bundle_update

Pure-Luau wrapper that adds bundle.update(entityId, bundleRef?) to the engine's existing bundle namespace. The prelude grafts it on at boot via M.installInto(bundle). After install, callers use the grafted method on the bundle global — they shouldn't require this module directly.

bundle.update re-composes the bundle from an entity's current hierarchy and writes the new template to the bundle's on-disk path. The VFS write fires the engine's generic asset hot-reload pipeline, which dispatches onAssetReload(field) on every component instance whose declared asset field references this bundle's guid. There is no opt-in subscription API — declaring an asset field IS the subscription.

Exports

• M.update(entityId: string, bundleRef: BundleRef?) -> any — re-compose and write back. Errors if entityId is empty, if no ref can be inferred, or if the ref cannot be resolved to an on-disk path.
• M.installInto(bundleNamespace: BundleNamespace) — graft update onto the supplied namespace. No-op when given a non-table.

Types:

• BundleRef = { guid?: string, __ref?: string, identity?: string, path?: string, name?: string }
• BundleNamespace = { update?: ((string, BundleRef?) -> any) }

Usage

-- The prelude installs the wrapper at boot:
require("@builtin::modules.bundle_update").installInto(bundle)

-- After install, callers use the grafted method:
bundle.update(entityId)                      -- infer ref from Asset/PlayerTemplate
bundle.update(entityId, { guid = "abc..." })  -- explicit ref

Notes

• Ref resolution order: guid, __ref, identity, path, name — first non-empty key wins.
• Path resolution probes both the bundle and player asset categories. PlayerTemplate.asset is an AssetRef<player> and lives under the player registry — same container shape as a bundle.
• installInto is idempotent — calling it more than once just overwrites the field.
• This module owns no state. Hot-reloading it just re-installs update next time the prelude runs.