bacommon.workspace package

Functionality related to ballistica.net workspaces.

Submodules

bacommon.workspace.assetsv1 module

Public types for assets-v1 workspaces.

While this module is currently only used server-side, its source code can be useful as reference when setting workspace config data by hand or for use in client-side workspace modification tools. There may be advanced settings that are not accessible through the UI/etc.

class bacommon.workspace.assetsv1.AssetsV1GlobalVals(base_assets: str | None = None, base_assets_filter: str = '', docs: str = '')

Bases: object

Global values for an assets_v1 workspace.

base_assets: str | None = None

base_assets_filter: str = ''

docs: str = ''

Optional free-form workspace documentation, appended to the generated wrapper module’s docstring (after the auto-generated summary line). Empty string means none.

class bacommon.workspace.assetsv1.AssetsV1PathVals

Bases: IOMultiType[AssetsV1PathValsTypeID]

Top level class for path vals classes.

classmethod get_type(type_id: AssetsV1PathValsTypeID) → type[AssetsV1PathVals]

Return a specific subclass given a type-id.

Should be overridden by child classes. Generally, users of the class should call get_type_cached() instead of this, as it is more efficient.

classmethod get_type_id() → AssetsV1PathValsTypeID

Return the type-id for this subclass.

classmethod get_type_id_storage_name() → str

Return the key used to store type id in serialized data.

The default is a short obscure value so that it is unlikely to conflict with members of individual type attrs, but in some cases one might prefer to serialize it to something simpler like ‘type’ by overriding this call. One just needs to make sure that no encompassed types serialize anything to that same name themself (dataclassio will error if they do).

class bacommon.workspace.assetsv1.AssetsV1PathValsAudioV1(audio_role: AudioRole = AudioRole.DEFAULT, audio_quality: AudioQuality = AudioQuality.DEFAULT, docs: str = '')

Bases: AssetsV1PathVals

Path-specific values for an audio source in an assets_v1 workspace.

The per-sound authoring knobs (AudioRole, AudioQuality) are module-level types in this module.

audio_quality: AudioQuality = 'default'

audio_role: AudioRole = 'default'

docs: str = ''

Optional free-form documentation for this asset, surfaced as a comment above the asset in generated wrapper modules (and in the Sphinx docs). Empty string means no docs.

classmethod get_type_id() → AssetsV1PathValsTypeID

Return the type-id for this subclass.

class bacommon.workspace.assetsv1.AssetsV1PathValsCubeMapV1(docs: str = '')

Bases: AssetsV1PathVals

Path-specific values for a cube map (.cubemap dir) in a workspace.

Cube maps are reflection textures with no Python API (decision #24), so they aren’t wrapper-visible. This currently carries only optional docs – stored for completeness/consistency with other asset kinds, but not yet consumed by anything (it’ll have a home if/when cube maps gain a Python surface). Keyed in workspace.json’s path dict by the .cubemap directory path.

docs: str = ''

Optional free-form documentation for this cube map. Stored but not yet surfaced anywhere (cube maps have no wrapper entry). Empty string means no docs.

classmethod get_type_id() → AssetsV1PathValsTypeID

Return the type-id for this subclass.

class bacommon.workspace.assetsv1.AssetsV1PathValsGroupV1(docs: str = '')

Bases: AssetsV1PathVals

Path-specific values for a group (directory) in a workspace.

A group builds no asset of its own; this exists purely to carry optional docs (decision #28) that become the generated wrapper group class’s docstring. Keyed in workspace.json’s path dict by the directory path (e.g. textures or mydir/subdir).

docs: str = ''

Optional free-form documentation for this group, used as the generated wrapper group class’s docstring (a trailing “See source for the full asset list.” is always appended). Empty string means fall back to the auto-generated docstring.

classmethod get_type_id() → AssetsV1PathValsTypeID

Return the type-id for this subclass.

class bacommon.workspace.assetsv1.AssetsV1PathValsMeshV1(mesh_role: MeshRole = MeshRole.DEFAULT, docs: str = '')

Bases: AssetsV1PathVals

Path-specific values for a mesh source in an assets_v1 workspace.

The per-mesh authoring knob (MeshRole) is a module-level type in this module.

docs: str = ''

Optional free-form documentation for this asset, surfaced as a comment above the asset in generated wrapper modules (and in the Sphinx docs). Empty string means no docs.

classmethod get_type_id() → AssetsV1PathValsTypeID

Return the type-id for this subclass.

mesh_role: MeshRole = 'default'

class bacommon.workspace.assetsv1.AssetsV1PathValsStrV1(up_to_date_state: str | None = None)

Bases: AssetsV1PathVals

Path-specific values for an assets_v1 workspace path.

classmethod get_type_id() → AssetsV1PathValsTypeID

Return the type-id for this subclass.

up_to_date_state: str | None = None

Hash generated when all translations for this entry are complete. Used as a fast-out for checking whether updates are needed.

class bacommon.workspace.assetsv1.AssetsV1PathValsTexV1(texture_quality: TextureQuality = TextureQuality.DEFAULT, texture_role: Role = Role.DEFAULT, astc_settings: AstcSettings = <factory>, bc7_settings: Bc7Settings = <factory>, docs: str = '')

Bases: AssetsV1PathVals

Path-specific values for an assets_v1 workspace path.

The per-texture quality knobs (TextureQuality, Role, AstcSettings, Bc7Settings) are module-level types in this module.

astc_settings: AstcSettings

Per-format encode settings, consulted only when texture_quality is CUSTOM. Fully defaulted so a texture never has to store them explicitly.

bc7_settings: Bc7Settings

docs: str = ''

Optional free-form documentation for this asset, surfaced as a comment above the asset in generated wrapper modules (and in the Sphinx docs). Empty string means no docs.

classmethod get_type_id() → AssetsV1PathValsTypeID

Return the type-id for this subclass.

normalize() → None

Reset redundant/unused settings to defaults, in place.

A pure tidiness pass to run before storing: it never changes the resolved result, only drops dead data so store_default=False can strip it from workspace.json. Resolution consults the per-format settings only when the top-level texture_quality is CUSTOM, and a format’s explicit block_size/rdo only when that format’s own texture_quality is CUSTOM – so anything outside those paths is unused and gets cleared here.

texture_quality: TextureQuality = 'default'

texture_role: Role = 'default'

class bacommon.workspace.assetsv1.AssetsV1PathValsTypeID(*values)

Bases: Enum

Types of vals we can store for paths.

AUDIO_V1 = 'audio_v1'

CUBE_MAP_V1 = 'cube_map_v1'

GROUP_V1 = 'group_v1'

MESH_V1 = 'mesh_v1'

STR_V1 = 'str_v1'

TEX_V1 = 'tex_v1'

class bacommon.workspace.assetsv1.AssetsV1StringFile

Bases: IOMultiType[AssetsV1StringFileTypeID]

Top level class for our multitype.

classmethod get_type(type_id: AssetsV1StringFileTypeID) → type[AssetsV1StringFile]

Return the subclass for each of our type-ids.

classmethod get_type_id() → AssetsV1StringFileTypeID

Return the type-id for this subclass.

classmethod get_type_id_storage_name() → str

Return the key used to store type id in serialized data.

The default is a short obscure value so that it is unlikely to conflict with members of individual type attrs, but in some cases one might prefer to serialize it to something simpler like ‘type’ by overriding this call. One just needs to make sure that no encompassed types serialize anything to that same name themself (dataclassio will error if they do).

class bacommon.workspace.assetsv1.AssetsV1StringFileTypeID(*values)

Bases: Enum

Type ID for each of our subclasses.

V1 = 'v1'

class bacommon.workspace.assetsv1.AssetsV1StringFileV1(input: str, input_modtime: datetime.datetime, style_preset: StylePreset = StylePreset.NONE, outputs: dict[Locale, Output]=<factory>)

Bases: AssetsV1StringFile

Our initial version of string file data.

class Output(modtime: datetime, value: str = '', selector: StringSelector | None = None)

Bases: object

Represents a single localized output.

modtime: datetime

When this output was last changed.

selector: StringSelector | None = None

Optional render-time selector (plural/select); set instead of value for an entry whose value is chosen at render time.

value: str = ''

The plain-string output. Set for plain entries; empty (and omitted from the wire) when selector is set – the selector is then the authoritative value, with no separate fallback.

class StylePreset(*values)

Bases: Enum

Preset for general styling in translated strings.

LOUD = 'loud'

NONE = 'none'

SOFT = 'soft'

TITLE = 'title'

classmethod get_type_id() → AssetsV1StringFileTypeID

Return the type-id for this subclass.

input: str

input_modtime: datetime.datetime

outputs: dict[Locale, Output]

style_preset: StylePreset = 'none'

class bacommon.workspace.assetsv1.AstcBlockSize(*values)

Bases: Enum

ASTC square block size — the mobile bitrate lever.

Smaller block = more bits per texel = higher quality + larger output. Consulted only when an AstcSettings has its texture_quality set to CUSTOM; otherwise the blanket LOW/DEFAULT/HIGH map to a value in this range (LOW = TWELVE_BY_TWELVE, HIGH = FOUR_BY_FOUR).

EIGHT_BY_EIGHT = '8x8'

FIVE_BY_FIVE = '5x5'

FOUR_BY_FOUR = '4x4'

SIX_BY_SIX = '6x6'

TEN_BY_TEN = '10x10'

TWELVE_BY_TWELVE = '12x12'

class bacommon.workspace.assetsv1.AstcSettings(texture_quality: TextureQuality = TextureQuality.DEFAULT, block_size: AstcBlockSize = AstcBlockSize.SIX_BY_SIX)

Bases: object

Per-texture ASTC (mobile) encode settings.

Consulted only when the texture’s top-level texture_quality is CUSTOM. Its own texture_quality may in turn be CUSTOM to use the explicit block_size; otherwise LOW/DEFAULT/ HIGH map to the encoder’s block-size range. Fully defaulted so a texture never has to store it explicitly.

block_size: AstcBlockSize = '6x6'

texture_quality: TextureQuality = 'default'

class bacommon.workspace.assetsv1.AudioQuality(*values)

Bases: Enum

Per-sound authoring quality knob (asset-packages decision #25).

Mirrors the texture knob’s LOW/DEFAULT/HIGH pattern. Defined from day one as the escape hatch for content whose default encode budget doesn’t fit (e.g. a short pre-mixed UI sound sharing music’s bitrate), but nothing consumes it yet — the recipe carries it in its cache key only, so wiring it up later rebuilds correctly.

DEFAULT = 'default'

HIGH = 'high'

LOW = 'low'

class bacommon.workspace.assetsv1.AudioRole(*values)

Bases: Enum

A sound’s channel/encode contract (asset-packages decision #25).

Names the technical contract, not a content category — “music” deliberately does not exist as a build-time concept (volume routing stays a runtime play-flag; streaming is a length-derived engine policy).

• DEFAULT — spatialization-ready: downmixed to mono at encode (OpenAL only spatializes mono; a hard requirement, not a size optimization). The vast majority of sounds.

• PRE_MIXED — an authored mix: channels preserved (≤2) and the sound always plays listener-space. The recipe stamps a BA_ROLE=pre_mixed vorbis comment tag so the engine knows at load time (channel count alone can’t carry the bit — a mono pre-mixed source stays mono). Music, plus any intentionally stereo (or otherwise authored-mix) sound.

DEFAULT = 'default'

PRE_MIXED = 'pre_mixed'

class bacommon.workspace.assetsv1.Bc7Rdo(*values)

Bases: Enum

BC7 RDO (rate-distortion optimization) lambda — the desktop lever.

BC7 is a fixed 8bpp block format, so its size lever is RDO: higher lambda steers the encoder toward more zlib/LZ-compressible output (smaller on-disk) at the cost of quality. OFF disables RDO (best quality, largest). Consulted only when a Bc7Settings has its texture_quality set to CUSTOM; otherwise the blanket LOW/DEFAULT/HIGH map to a value in this range (LOW = FOUR, HIGH = OFF).

FOUR = '4'

OFF = 'off'

ONE = '1'

TWO = '2'

ZERO_POINT_FIVE = '0.5'

ZERO_POINT_ONE_TWO_FIVE = '0.125'

ZERO_POINT_TWO_FIVE = '0.25'

class bacommon.workspace.assetsv1.Bc7Settings(texture_quality: TextureQuality = TextureQuality.DEFAULT, rdo: Bc7Rdo = Bc7Rdo.ONE)

Bases: object

Per-texture BC7 (desktop) encode settings.

Consulted only when the texture’s top-level texture_quality is CUSTOM. Its own texture_quality may in turn be CUSTOM to use the explicit rdo lambda; otherwise LOW/DEFAULT/ HIGH map to the encoder’s RDO range. Fully defaulted so a texture never has to store it explicitly.

rdo: Bc7Rdo = '1'

texture_quality: TextureQuality = 'default'

class bacommon.workspace.assetsv1.MeshRole(*values)

Bases: Enum

What a mesh .obj source builds (asset-packages decision #26).

• DEFAULT — a display mesh: compiled to the engine’s binary .bob format (welded/quantized verts, vertex-cache-optimized index order) and served from the flavor-varying meshes bucket (headless builds get none).

• COLLISION — a collision mesh: compiled to the engine’s binary .cob format (positions + indices for the physics trimesh) and served from the flavor-invariant constant bucket — every build including headless gets it, and the bytes are identical across all flavors (networked sims/replays must agree on collision geometry).

COLLISION = 'collision'

DEFAULT = 'default'

class bacommon.workspace.assetsv1.Role(*values)

Bases: Enum

What a texture is for (its authoring intent).

Drives mip-filtering math and encoder flags (asset-packages initiative decisions #19/#23). Intent-based rather than a bundle of low-level mechanical flags — the recipe maps each role to a concrete filtering/encoding behavior. normal_map / data are reserved slots for when such content (and the compressed- profile recipes) land.

DEFAULT = 'default'

sRGB color with straight opacity alpha. The pipeline premultiplies it by its alpha for storage (decision #23): premult-weighted, halo-free mip filtering in the requested render_space, premult output bytes, ALPHA_PREMULTIPLIED DFD flag set. The common case for color sprites. Renders correctly only with premult-blend (the renderer wiring lands in a later step; until then DEFAULT output shows darkened edges under the legacy straight-blend path).

SOURCE_PREMULTIPLIED = 'source_premultiplied'

sRGB color whose SOURCE RGB is already premultiplied by its alpha (e.g. glow sprites — they carry additive RGB > alpha values that straight alpha cannot represent). The pipeline does NOT re-multiply; mips filter the premultiplied RGB directly (in the requested render_space) and the flag is set. Renders identically to DEFAULT (both premult-blend); they differ only in whether the pipeline applies the multiply.

STRAIGHT_ALPHA = 'straight_alpha'

sRGB color with straight alpha whose RGB channels carry meaningful color even in transparent regions, so they must be preserved (decision #23). The pipeline does NOT premultiply: mips filter RGB and alpha INDEPENDENTLY (color still filtered in the requested render_space, but with no premult round-trip, which would zero — and fail to recover — the transparent-region color). Straight output bytes; ALPHA_PREMULTIPLIED flag clear. Renders with ordinary straight-alpha blending.

class bacommon.workspace.assetsv1.TextureQuality(*values)

Bases: Enum

Per-texture authoring quality knob (decision #19).

DEFAULT is the normal case (the vast majority of textures); LOW and HIGH are deliberate per-texture overrides for special cases (e.g. HIGH for a hero texture that must stay crisp, LOW for one that can afford to be cheap). Named DEFAULT rather than MEDIUM to communicate that — it’s the baseline, not a middle setting you’d routinely reach past.

LOW/DEFAULT/HIGH are blanket settings that map to a sensible value for whichever encoder a profile uses (ASTC block size on mobile, BC7 RDO lambda on desktop). CUSTOM instead defers to the per-format AstcSettings / Bc7Settings so a texture can be tuned independently per encoder (e.g. ASTC HIGH while BC7 DEFAULT). Distinct from the bucket-level TextureTier.

CUSTOM = 'custom'

DEFAULT = 'default'

HIGH = 'high'

LOW = 'low'

class bacommon.workspace.assetsv1.WrapperType(*values)

Bases: Enum

Python wrapper-module flavor for an asset-package version.

Selects which feature-set’s loader API the generated wrapper delegates to. Members today correspond 1:1 with feature-sets, but the type is deliberately named WrapperType (not WrapperFeatureset) to leave room for non-featureset-shaped variants (e.g. tooling-only or future loader APIs) without a rename.

BABASE = 'babase'

Strings-only wrapper (asset-packages strings phase). Strings resolve via _babase.get_resource (a base-level concept, not a scene/UI loader), so they live in their own babase-rooted wrapper whose leaves are call-time-resolved str accessors.

BASCENEV1 = 'bascenev1'

BAUIV1 = 'bauiv1'

bacommon.workspace.assetsv1.complete_locale_values(string_files: dict[str, AssetsV1StringFileV1], locale: Locale) → dict[str, str | StringSelector]

English-completed per-locale values for a set of string files.

Maps each string’s logical name to its value for locale: the locale’s own output, else the English output, else the raw English brief input. So every locale’s map carries the complete key set with graceful English fallback – untranslated strings still render (in English) rather than failing, and every locale’s key set is identical.

The shared value-selection both the asset-build string recipe and the langstr vendor command route through (paired with serialize_language_blob()) so the built and vendored blobs can’t drift.