Toastconcern--FrameStudio/docs/bundles.md

Bundles

A bundle (.fbundle) is several environments in one file: a collection to share, or to install on the headset in one go. Each environment in it stays its own environment. On the headset, a bundle is unpacked into the .fenv files it holds, and the Environments panel lists each one separately.

Making a bundle in Frame Studio

Everything is in File > Bundle and on the Bundle tab in Properties.

1. File > Bundle > New Bundle starts an empty one, and the Bundle tab opens.

2. Give it a Name. It's the bundle's own name; each environment keeps its name.

3. Add environments:

   • Add the Open Environment: the environment you have open, as it was last saved. Save first (Ctrl+S) to include your latest changes. A home that has never been saved can't be added yet.
   • My Environments ▾: anything you've saved.
   • Add .fenv...: any .fenv file. You can pick several at once.

   Each row shows the environment's picture, name and size. ▲ moves it up: the order is kept in the file. ✕ takes it out of the bundle; the .fenv file itself stays where it is. Double-click a row to open that environment.

4. Save Bundle... writes the .fbundle. The environments are stored as they are, not packed a second time, so saving is quick, and the bundle is about as big as its environments together.

Opening a bundle

File > Bundle > Open Bundle..., File > Open..., or dropping a .fbundle on the window opens the bundle on the Bundle tab. Its environments are listed in place; nothing is unpacked yet.

• Double-click an environment to open it. It is unpacked into a scratch folder first.
• Add, remove or reorder environments, then Save Bundle (the same file) or Save Bundle As... (a new one).
• Unpack into My Environments copies every environment out of the bundle into My Environments. An identical environment already there is skipped. A different one with the same name is kept, and the bundle's copy is added as "name 2".

Installing a bundle on the Steam Frame

• From Studio: with the bundle saved, choose Install on Steam Frame... on the Bundle tab or in the Bundle menu. The bundle is added to the Headset tab's install list. Then choose Install Frame Home there. The Headset tab's Add .fenv or .fbundle... button adds bundles too.

• Without Studio: give the bundle to the stand-alone installer like any environment (see install-frame-home.md):

  sh install-frame-home.sh --host steamos@frame my-collection.fbundle
  

  On Windows, drop it onto Install Frame Home.bat, or run powershell -ExecutionPolicy Bypass -File install-frame-home.ps1 my-collection.fbundle.

• By hand: copy the .fbundle into ~/frame-home/envs on the headset.

On the headset, Frame Home's Environments panel unpacks any bundle in ~/frame-home/envs in the background. Each environment becomes its own .fenv, and the bundle is then deleted to save space. An environment already there is kept, as above. A bundle that's damaged, or still being copied, is left alone and tried again once it changes.

A bundle never changes which environment is shown. When you install .fenv files and bundles together, the first .fenv is the one shown.

From the command line

fenv-tool (built with Frame Home, see building.md) makes and reads bundles:

fenv-tool bundle "My collection.fbundle" --name "My collection" calm.fenv beach.fenv night.fenv
fenv-tool info "My collection.fbundle"                 # each environment: name, size, picture, damaged or not
fenv-tool unbundle "My collection.fbundle" out-folder  # the .fenv files, one each

What's inside

A .fbundle is a ZIP archive:

my-collection.fbundle
├── bundle.json                 the bundle's name and its environments, in order
└── environments/
    ├── calm.fenv               each environment, stored as it is
    ├── beach.fenv
    └── night.fenv

{
  "format": "fbundle",
  "version": 1,
  "name": "My collection",
  "environments": [
    { "file": "environments/calm.fenv", "name": "Calm", "size": 94371840 }
  ]
}

• The .fenv files are stored, not compressed again: they're already compressed inside, so packing and unpacking are just copies, and each one can be read in place (Studio reads names and pictures without unpacking).
• Bundles over 4 GB use ZIP64. Any ZIP tool can open a bundle.
• Two environments with the same file name get "name 2"; names are compared without regard to case, so they unpack separately on Windows too.
• Every member's checksum is verified when it's unpacked: a damaged bundle stops without leaving half a file.

The format is in src/fenv_bundle.h; .fenv itself is described in environments-and-fenv.md.