Using Bundle Mode to Test Bundles

Bundle mode is a process that lets you enable asset loading to prioritize bundles over loose cache assets. After you build the seed lists for packaging your game, you can use bundle mode and the sys_report_files_not_found_in_paks console variable to test your packaging rules. Bundle mode makes it easy for you to load and report on issues in all the bundles (game .pak files) from a location that you specify without creating a release build.

Using bundle mode involves two key tasks:

• Turning on missing asset reporting for assets not in bundles. This enables “bundle mode”.
• Mounting and loading bundles for your game.

When reporting is enabled, the sys_report_files_not_found_in_paks console variable reports when an asset loads that isn’t in any of your bundles. By selectively loading bundles and using the sys_report_files_not_found_in_paks command, you can find assets that need to be included in your bundles.

Enabling Bundle Mode

To enable bundle mode, use the sys_report_files_not_found_in_paks console variable and specify a value of 1,2, or 3. A value of 1 writes missing files as log entries without issuing warning messages.

The following list shows valid arguments for the sys_report_files_not_found_in_paks console variable.

0 = Disabled
1 = Log
2 = Warning
3 = Error
<Every other value> = Error

Log File Entries

Missing files are logged with entries similar to the following:

Missing from bundle: @assets@\levels\milestone2\auto_resourcelist.txt

If you use the sys_report_files_not_found_in_paks console variable with the launcher, the error messages are written to a log file.

Setting the Console Variable

Enabling the console variable before running the editor or launcher ensures that all missing assets are reported. To ensure that the console variable is always active when you run the editor or launcher, modify editor.cfg and autoexec.cfg in your project directory.

You can also enable the console variable at runtime by using the console (~) or remote console.

Bundle Mode Commands

Bundle mode has two commands:

• loadbundles <bundle_directory> - Loads all the bundles from the specified directory into the game. If no arguments are supplied, the directory defaults to Bundles and the extension to .pak.
• unloadbundles - Unload any bundle that was loaded through the loadbundles command.

Using Bundle Mode Example

The following procedure shows how bundle mode works. In the example, game mode is entered when a bundle is missing.

To test bundle mode

1. In the console window, enter the following command:

   sys_report_files_not_found_in_paks 1
   

   The 1 argument specifies that missing files are reported as log entries rather than warnings or errors.

2. Enter game mode. A list of Missing from bundle errors displays.

1. Enter the command loadbundles to load bundles for the level.

There are fewer errors, but some assets are still missing. The Asset Validation Gem seed-related commands can help find the missing assets.

1. Use the Asset Validation gem addseedpath command to add a likely missing bundle.

   addseedpath levels\milestone2\level.pak
   

2. Enter the listknownassets command.

1. Examine the output. In the following example, the output shows missing button assets.

In the case of the button assets, the bundle was packaged a while ago and must be repackaged. However, other assets are also still missing.

1. Add the missing assets to the seed list for the level.

2. Run the bundling commands for the level.

3. Drop the bundles into the Bundles directory.

4. Enter an assetbundlerbatch assetlists command, as shown in the following example. Use the --print argument to check the output. In the example, the single-line command has been formatted for readability.

   assetbundlerbatch assetlists
         --addseed levels\milestone2\level.pak
         --addseed levels\milestone2\milestonecutscene.scriptevents
         --addseed levels\milestone2\hardcodedassetreference.luac
         --print
   

5. Verify that the output displays as expected.

6. Enter the assetbundlerbatch assetlists command again to bundle the assets, but this time without the --print argument. The example command is single-line, but has been formatted for readability.

   assetbundlerbatch assetlists
         --addseed levels\milestone2\level.pak
         --addseed levels\milestone2\milestonecutscene.scriptevents
         --addseed levels\milestone2\hardcodedassetreference.luac
         --platform pc
         --assetlistfile DemoLevelList.assetlist
   

   Output:

   Saving Asset List file to ( G:\P4\dev\DemoLevelList_pc.assetlist )...
   Save successful! ( G:\P4\dev\DemoLevelList_pc.assetlist )
   

7. Enter an assetbundlerbatch bundles command, as shown in the following example.

   assetbundlerbatch bundles
         --assetlistfile DemoLevelList_pc.assetlist
         --platform pc
         --outputbundlepath G:\P4\dev\DemoProject\Bundles\milestone2.pak
   

   Output:

   Creating Bundle ( G:\P4\dev\DemoProject\Bundles\milestone2_pc.pak )...
   Bundle ( G:\P4\dev\DemoProject\Bundles\milestone2_pc.pak ) created successfully!
   

8. Enter the loadbundles command to reload the bundles, and then enter game mode.

All the assets loaded when game mode was entered are now in bundles.