BundleManager¶

C++ type: BundleManager (static)

Description¶

A registry for reusable bundles — prefab-like groups of entities that can be spawned into any Scene at runtime. A bundle is authored in the editor and saved as a .bundle file (see Bundles).

Loading a bundle by API¶

There is no API that loads a .bundle file directly at runtime. Instead, each .bundle file is converted into a factory function during export, and the exporter emits a registerBundle call that wires that factory to a numeric ID and a name:

// Generated by export — you do not write this by hand
BundleManager::registerBundle(1, "enemies/EnemyShip", create_bundle_enemies_EnemyShip);

The bundle name is the .bundle file's path with the extension removed, using forward slashes (for example, bundles/enemies/EnemyShip.bundle registers as enemies/EnemyShip). At runtime you spawn an instance by that name (or ID) with createBundle, and remove it with destroyBundle:

local root = BundleManager.createBundle("enemies/EnemyShip", scene)
-- ... later ...
BundleManager.destroyBundle(scene, root)

Entity root = BundleManager::createBundle("enemies/EnemyShip", &scene);
// ... later ...
BundleManager::destroyBundle(&scene, root);

This makes bundles ideal for entities created on demand — enemies, projectiles, item drops, UI cards, and any pooled hierarchy.

Methods¶

Constants¶

Method details¶

registerBundle¶

• static void registerBundle(uint32_t id, const std::string& name, std::function factory, std::function destroyer = nullptr)

Registers a named bundle factory. The factory receives the target Scene* and a root Entity, and must create the bundle's entities and components as children of that root. The optional destroyer is called by destroyBundle instead of the default entity destruction; it receives (Scene*, Entity root) and returns true on success.

This call is generated by the export step for every .bundle file in the project, so you normally never write it yourself. It is C++-only and not exposed to Lua.

BundleManager::registerBundle(1, "enemies/EnemyShip",
    [](Scene* scene, Entity root) {
        // create child entities/components under root...
    });

createBundle¶

• static Entity createBundle(const std::string& name, Scene* scene)
• static Entity createBundle(uint32_t id, Scene* scene)
• static Entity createBundle(const std::string& name, Scene* scene, Entity root)
• static Entity createBundle(uint32_t id, Scene* scene, Entity root)

Spawns an instance of a registered bundle into scene and returns the root entity of the new hierarchy, or a null entity if the name/ID is not found.

• The two-argument overloads create a new root entity for the instance.
• The three-argument overloads attach the bundle under an existing root entity (which must already exist in the scene).

Each call tracks the instance internally so destroyBundle can later remove every entity it created. Note the argument order: the bundle name/ID comes first, then the scene.

-- New root
local root = BundleManager.createBundle("enemy_grunt", scene)

-- By ID
local r2 = BundleManager.createBundle(1, scene)

-- Under an existing root entity
BundleManager.createBundle("enemy_grunt", scene, existingRoot)

Entity root = BundleManager::createBundle("enemy_grunt", &scene);
Entity r2   = BundleManager::createBundle(1, &scene);
BundleManager::createBundle("enemy_grunt", &scene, existingRoot);

destroyBundle¶

• static bool destroyBundle(Scene* scene, Entity rootEntity)

Destroys a bundle instance by its root entity, removing all tracked entities (children first, then the root). If the bundle was registered with a custom destroyer, that is called instead of the default destruction. Returns false if rootEntity is not a tracked bundle root. Note the argument order: scene first, then the root entity.

BundleManager.destroyBundle(scene, root)

BundleManager::destroyBundle(&scene, root);

getBundleId / getBundleName¶

• static uint32_t getBundleId(const std::string& name)
• static std::string getBundleName(uint32_t id)

Look up a bundle's numeric ID by name, or its name by ID. Returns 0 / "" if not found.

getBundleNames¶

• static std::vector\<std::string> getBundleNames()

Returns all registered bundle names, in registration order. Use the bundleCount property (Lua) or getBundleCount() (C++) for the count.

destroyAllInstances¶

• static void destroyAllInstances(Scene* scene)

Destroys every tracked bundle instance belonging to scene, calling the appropriate destroyer for each. C++-only; useful when tearing a scene down manually.

clearAll¶

• static void clearAll()

Removes all registered bundles and all tracked instances. Used by the editor when resetting state.