IN THIS ARTICLE
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.
To enable bundle mode, use the
sys_report_files_not_found_in_paks console variable and specify a value of
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
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.
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
autoexec.cfg in your project directory.
You can also enable the console variable at runtime by using the console (~) or remote console.
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
Bundlesand the extension to
- unloadbundles - Unload any bundle that was loaded through the
The following procedure shows how bundle mode works. In the example, game mode is entered when a bundle is missing.
To test bundle mode
In the console window, enter the following command:
1argument specifies that missing files are reported as log entries rather than warnings or errors.
Enter game mode. A list of Missing from bundle errors displays.
- Enter the command
loadbundlesto 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.
Use the Asset Validation gem
addseedpathcommand to add a likely missing bundle.
- 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.
Add the missing assets to the seed list for the level.
Run the bundling commands for the level.
Drop the bundles into the
assetbundlerbatch assetlistscommand, as shown in the following example. Use the
assetbundlerbatch assetlists --addseed levels\milestone2\level.pak --addseed levels\milestone2\milestonecutscene.scriptevents --addseed levels\milestone2\hardcodedassetreference.luac --print
Verify that the output displays as expected.
assetbundlerbatch assetlistscommand again to bundle the assets, but this time without the
assetbundlerbatch assetlists --addseed levels\milestone2\level.pak --addseed levels\milestone2\milestonecutscene.scriptevents --addseed levels\milestone2\hardcodedassetreference.luac --platform pc --assetlistfile DemoLevelList.assetlist
Saving Asset List file to ( G:\P4\dev\DemoLevelList_pc.assetlist )... Save successful! ( G:\P4\dev\DemoLevelList_pc.assetlist )
assetbundlerbatch bundlescommand, as shown in the following example.
assetbundlerbatch bundles --assetlistfile DemoLevelList_pc.assetlist --platform pc --outputbundlepath G:\P4\dev\DemoProject\Bundles\milestone2.pak
Creating Bundle ( G:\P4\dev\DemoProject\Bundles\milestone2_pc.pak )... Bundle ( G:\P4\dev\DemoProject\Bundles\milestone2_pc.pak ) created successfully!
loadbundlescommand to reload the bundles, and then enter game mode.
All the assets loaded when game mode was entered are now in bundles.
Copyright © 2022 Open 3D Engine Contributors
Documentation Distributed under CC BY 4.0.
The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Policy page.