bacommon.assetspec package

Asset specs: authoring-level references to asset-package assets.

A spec is a minimal claim about an asset – an apverid plus a logical name – carrying no asset data and no guarantee the package is locally present (or still exists). Per the D28 semantic split (see strings-asset-migration.md in ballistica-internal), assets ladder through three tiers: TextureSpec (this claim form; wire/model currency) -> client bauiv1.TextureVerifiedSpec (a verified-local subclass adding .get(); its wrapper pin resolved before use) -> bauiv1.Texture (the loaded engine asset). Servers hold only specs; consuming clients verify/resolve before display. Each kind gets a distinct type (TextureSpec, MeshSpec) so a consumer schema can enforce where each kind may go.

Type-safe, ergonomic access to a package’s references comes from a generated wrapper module (emitted server-side; the codegen lives in baserver.assetwrappergen), whose per-kind roots (textures, meshes) are driven at runtime by AssetGroup – mirroring the client-side asset-package wrappers.

class bacommon.assetspec.AssetGroup(apverid: str, node: AssetGroupTree, prefix: str)

Bases: object

Dynamic accessor for one subdirectory of an asset-package’s refs.

Attribute access resolves against the wrapper’s nested kind-code tree: a subdirectory yields another AssetGroup; a leaf yields the reference for its kind. All real type information lives in the wrapper’s if TYPE_CHECKING: shadow, so callers never type-check through this class.

type bacommon.assetspec.AssetGroupTree = dict[str, str | AssetGroupTree]

class bacommon.assetspec.CollisionMeshSpec(apverid: str, name: str)

Bases: object

A language-independent reference to a collision-mesh in a package.

name is the collision-mesh’s logical path within the package (e.g. meshes/courtyard_level_collide). The engine resolves the qualified form <apverid>:<name>.

Collision meshes are a scene-only kind (physics; they ride the flavor-invariant constant bucket – asset-packages decision #26), so nothing server-side emits one. The type exists so the scene wrapper’s verified-spec leaves stay kind-distinct like every other kind.

apverid: str

name: str

class bacommon.assetspec.MeshSpec(apverid: str, name: str)

Bases: object

A language-independent reference to a mesh in an asset-package.

name is the mesh’s logical path within the package (e.g. meshes/box). The engine resolves the qualified form <apverid>:<name>.

apverid: str

name: str

class bacommon.assetspec.SoundSpec(apverid: str, name: str)

Bases: object

A language-independent reference to a sound in an asset-package.

name is the sound’s logical path within the package (e.g. audio/swish). The engine resolves the qualified form <apverid>:<name>.

apverid: str

name: str

class bacommon.assetspec.TextureSpec(apverid: str, name: str)

Bases: object

A language-independent reference to a texture in an asset-package.

name is the texture’s logical path within the package (e.g. textures/zoe_icon). The engine resolves the qualified form <apverid>:<name>.

apverid: str

name: str