🗃️ Content

Intermediate data representation.

Base

Content representation containers.

class BaseContent

Base class for content representations.

kind: ClassVar[FileKind]

class ModelContent(meta=<factory>, scene=<factory>)

Bases: BaseContent

Content representation of 3D model.

kind: ClassVar[FileKind] = 'model'

meta: ModelMeta

scene: ModelScene

has(feature)

Return type:

bool

class TextureContent(width=0, height=0, meta=<factory>, texture=<factory>)

Bases: BaseContent

Content representation of texture.

kind: ClassVar[FileKind] = 'texture'

width: int = 0

height: int = 0

meta: TextureMeta

texture: Texture

property mipmap_count: Any

property format: Any

property path_hash: Any

property is_cubemap: bool

property is_compressed: bool

property fourcc: bytes

class ImageContent(image=<factory>)

Bases: BaseContent

Content representation of image.

kind: ClassVar[FileKind] = 'image'

image: bytes

class ArchiveContent(entries=<factory>)

Bases: BaseContent

Content representation of archive.

kind: ClassVar[FileKind] = 'archive'

entries: list[TypeAliasType]

class DocumentContent(value=None)

Bases: BaseContent

Content representation of structured document.

kind: ClassVar[FileKind] = 'document'

value: TypeAliasType = None

class RegionContent(x=0, z=0, offsets=<factory>, counts=<factory>, uuids=<factory>, chunks=<factory>)

Bases: BaseContent

Content representation of world region.

kind: ClassVar[FileKind] = 'region'

x: int = 0

z: int = 0

offsets: list[int]

counts: list[int]

uuids: list[bytes]

chunks: list[RegionChunk]

property rx: Any

property rz: Any

property sector_offsets: Any

property sector_counts: Any

type DocumentPrimitive

int | float | bytes | str

type DocumentValue

None | DocumentPrimitive | list[DocumentValue] | dict[str, DocumentValue]

type ArchiveEntry

tuple[str, bytes]

Models

3D scene representation.

Scene

Scene structures.

ROOT_BONE_ID = -1

Default parent ID for root bones.

class SkeletonBone(id=0, name='bone', parent_id=-1, position=<factory>, rotation=<factory>, tail=<factory>)

Bone with transform data.

id: int = 0

name: str = 'bone'

parent_id: int = -1

position: TypeAliasType

rotation: TypeAliasType

tail: TypeAliasType

property is_root: bool

property quaternion: Quaternion

property slug: str

class ModelSkeleton(bones=<factory>, space=SkeletonSpace.GLOBAL)

Skeleton bones container.

bones: list[SkeletonBone]

space: SkeletonSpace = 'global'

property roots: list[SkeletonBone]

class AnimationClip(name='clip', frames=0, rate=0.33, translations=<factory>, rotations=<factory>, morph_weights=<factory>)

Keyframed bone and morph animation clip.

name: str = 'clip'

frames: int = 0

rate: float = 0.33

translations: TypeAliasType

rotations: TypeAliasType

morph_weights: TypeAliasType

property times: AnimationTimes

class ModelAnimation(clips=<factory>, morph_channels=<factory>, translation=AnimationTranslation.DELTA, rotation=AnimationRotation.QUATERNION)

Animation clips container.

clips: list[AnimationClip]

morph_channels: list[str]

translation: AnimationTranslation = 'delta'

rotation: AnimationRotation = 'quaternion'

class SceneScales(position=1.0, uv=1.0, uv2=1.0)

Scale multipliers for scene data.

position: float = 1.0

uv: float = 1.0

uv2: float = 1.0

class ModelSkin(bind_matrices)

Bind matrices used by meshes in an assembled scene.

bind_matrices: TypeAliasType

class ModelScene(scale=<factory>, meshes=<factory>, skins=<factory>, skeleton=<factory>, animation=<factory>)

Container for meshes, skeleton, and animation.

scale: SceneScales

meshes: list[ModelMesh]

skins: list[ModelSkin]

skeleton: ModelSkeleton

animation: ModelAnimation

has(feature)

Return whether scene contains a feature.

Return type:

bool

property total_vertices: int

property total_polygons: int

Mesh

Mesh structures.

class MeshBounds(min=<factory>, max=<factory>, radius=0.0)

Mesh bounding box.

min: TypeAliasType

max: TypeAliasType

radius: float = 0.0

class BlendShape(name='name', deltas=<factory>, channel=None)

Mesh deformation target.

name: str = 'name'

deltas: TypeAliasType

channel: str | None = None

class ModelMesh(name='name', material='material', bounds=<factory>, polygon_quads=False, has_blend_shapes=False, mip_factor=0.1, bones=<factory>, skin=None, vertices=<factory>, uv1=<factory>, uv2=<factory>, normals=<factory>, tangents=<factory>, colors=<factory>, blend_vertex_map=<factory>, blend_shapes=<factory>, links_ids=<factory>, links_weights=<factory>, polygons=<factory>, link_space=LinkSpace.GLOBAL, uv_origin=UVOrigin.TOP_LEFT, uv_sign=UVSign.POSITIVE)

Mesh geometry container.

name: str = 'name'

material: str = 'material'

bounds: MeshBounds

polygon_quads: bool = False

has_blend_shapes: bool = False

mip_factor: float = 0.1

bones: TypeAliasType

skin: int | None = None

vertices: TypeAliasType

uv1: TypeAliasType

uv2: TypeAliasType

normals: TypeAliasType

tangents: TypeAliasType

colors: TypeAliasType

blend_vertex_map: TypeAliasType

blend_shapes: list[BlendShape]

links_ids: TypeAliasType

links_weights: TypeAliasType

polygons: TypeAliasType

link_space: LinkSpace = 'global'

uv_origin: UVOrigin = 'top_left'

uv_sign: UVSign = 'positive'

property max_influences: int

Meta

Model source metadata.

class ModelCounts(meshes=0, bones=0, channels=0, clips=0)

Declared model counts.

meshes: int = 0

bones: int = 0

channels: int = 0

clips: int = 0

class MeshCounts(vertices=0, polygons=0, max_influences=0, local_bones=0, blend_shapes=0)

Declared mesh counts.

vertices: int = 0

polygons: int = 0

max_influences: int = 0

local_bones: int = 0

blend_shapes: int = 0

class ModelMeta(version=0.0, flags=<factory>, counts=<factory>)

Model source metadata.

version: float = 0.0

flags: TypeAliasType

counts: ModelCounts

declares(feature)

Return whether the source declares a model feature.

Return type:

bool

Matrices

Matrix transformations.

create_rotation_matrix(rotation)

Convert euler angles (XYZ) to 3×3 rotation matrix.

Return type:

TypeAliasType

create_transform_matrix(translation, rotation)

Convert translation and rotation (R * T) to 4×4 transform matrix.

Return type:

TypeAliasType

euler_to_quat(rotation)

Convert euler angles (XYZ) to quaternion (XYZW).

Return type:

TypeAliasType

quaternions_to_euler(rotations)

Convert quaternion keyframes (XYZW) to continuous XYZ euler angles.

Return type:

TypeAliasType

Transforms

Scene transformation functions.

scene_transforms(*transforms)

Adapt scene transformations to model content.

Return type:

tuple[TypeAliasType, ...]

unique_names(scene)

Ensure all meshes have unique names.

Return type:

ModelScene

flip_uv(scene)

Flip V axis (TOP_LEFT → BOTTOM_LEFT).

Return type:

ModelScene

invert_uv(scene)

Invert V axis sign (POSITIVE → NEGATIVE).

Return type:

ModelScene

global_transforms(skeleton)

Compute global transformation matrices for a valid skeleton.

Return type:

TypeAliasType

inverse_bind_matrices(skeleton, *, transpose=False)

Compute inverse bind matrices for a valid skeleton.

Return type:

TypeAliasType

skeleton_to_local(scene)

Convert bone positions (GLOBAL → LOCAL).

Return type:

ModelScene

animation_to_absolute(scene)

Add rest pose positions to animation deltas (DELTA → ABSOLUTE).

Return type:

ModelScene

apply_fp_animation(animation, *models)

Combine model geometry with animation rig.

Return type:

ModelScene

extend_fp_skeleton(animation, *models)

Add model bones missing from a first-person animation skeleton.

Return type:

ModelScene

apply_skins(scene, animation, *models)

Apply source bind poses to the assembled scene.

Return type:

ModelScene

apply_fp_models(animation, *models)

Apply first-person models to the animation scene.

Return type:

ModelScene

apply_skeletal_animation(animation, model)

Apply index-mapped skeletal animation clips to model.

Return type:

ModelScene

apply_morph_animation(animation, model)

Apply morph animation clips to compatible model blend shapes.

Return type:

ModelScene

type SceneTransform

Callable[[ModelScene], ModelScene]

type ModelTransform

Callable[['ModelContent'], 'ModelContent']

type AnimationTransform

Callable[[ModelScene, ModelScene], ModelScene]

Enums

Model enumerations.

class Feature(*values)

Bases: StrEnum

Optional model feature.

UV = 'uv'

UV2 = 'uv2'

NORMALS = 'normals'

TANGENTS = 'tangents'

COLORS = 'colors'

SKELETON = 'skeleton'

BLEND_SHAPES = 'blend_shapes'

ANIMATION = 'animation'

BONE_ANIMATION = 'bone_animation'

MORPH_ANIMATION = 'morph_animation'

property members: tuple[Feature, ...]

Concrete features represented by this feature.

property requires: tuple[Feature, ...]

Features required to serialize this feature.

property parent: Feature

Parent feature used for shared behavior.

class ModelUnits(*values)

Bases: IntEnum

Model structure element counts.

POSITIONS = 4

TEXTURES = 2

NORMALS = 4

TANGENTS = 4

TRIANGLES = 3

QUADS = 4

LINKS = 4

BONES = 6

FRAMES = 7

class UVOrigin(*values)

Bases: StrEnum

UV coordinate origin.

TOP_LEFT = 'top_left'

BOTTOM_LEFT = 'bottom_left'

class UVSign(*values)

Bases: StrEnum

UV coordinate sign.

POSITIVE = 'positive'

NEGATIVE = 'negative'

class LinkSpace(*values)

Bases: StrEnum

Vertex link coordinate space.

GLOBAL = 'global'

LOCAL = 'local'

class SkeletonSpace(*values)

Bases: StrEnum

Skeleton bones coordinate space.

GLOBAL = 'global'

LOCAL = 'local'

class AnimationTranslation(*values)

Bases: StrEnum

Animation translation mode.

DELTA = 'delta'

ABSOLUTE = 'absolute'

class AnimationRotation(*values)

Bases: StrEnum

Animation rotation format.

QUATERNION = 'quaternion'

EULER = 'euler'

Types

Model data types.

class LocalBoneId

Bone index within mesh.

alias of int

class SkeletonBoneId

Bone index within skeleton.

alias of int

type Features

tuple[Feature, ...]

Model feature collection.

type FeatureFlags

dict[Feature, bool]

Feature flags declared by source model.

type BonesMapping

dict[LocalBoneId, SkeletonBoneId]

Mapping from mesh local to skeleton bone indices.

type Vector2D

Annotated[NDArray[np.float32], (..., 2)]

2D float32 vector.

type Vector3D

Annotated[NDArray[np.float32], (..., 3)]

3D float32 vector.

type Vector4D

Annotated[NDArray[np.float32], (..., 4)]

4D float32 vector.

type LinksIds

Annotated[NDArray[np.uint8], (..., 4)]

Bone indices per vertex.

type LinksWeights

Annotated[NDArray[np.float32], (..., 4)]

Bone weights per vertex.

type Links

tuple[LinksIds, LinksWeights]

Bone indices and weights pair.

type Polygons

Annotated[NDArray[np.uint32], (..., 3)]

Triangle indices.

type BlendVertexMap

Annotated[NDArray[np.uint16], (...,)]

Blend shape base vertex index per mesh vertex.

type Colors

Annotated[NDArray[np.uint8], (..., 4)]

RGBA vertex colors.

type EulerAngles

Annotated[NDArray[np.float32], (..., 3)]

Euler angles in degrees (XYZ intrinsic).

type Quaternion

Annotated[NDArray[np.float32], (..., 4)]

Quaternion rotation (XYZW).

type RotationMatrix

Annotated[NDArray[np.float32], (3, 3)]

3x3 rotation matrix.

type TransformMatrix

Annotated[NDArray[np.float32], (4, 4)]

4×4 transformation matrix.

type BindPose

list[TransformMatrix]

Global transform per bone.

type InverseBindMatrices

Annotated[NDArray[np.float32], (..., 4, 4)]

Inverse bind matrices per bone.

type AnimationTranslations

Annotated[NDArray[np.float32], (..., 3)]

Animation translations per frame.

type AnimationRotations

Annotated[NDArray[np.float32], (..., 4)]

Animation rotations per frame.

type AnimationTimes

Annotated[NDArray[np.float32], ...]

Animation times per frame.

type MorphWeights

NDArray[np.float32]

Morph channel weights per frame.

Regions

World region structures.

class ChunkHeader(record_size=0, section_mask=0, add_mask=0, terrain_size=0, compressed_size=0)

Header of compressed world chunk.

record_size: int = 0

section_mask: int = 0

add_mask: int = 0

terrain_size: int = 0

compressed_size: int = 0

class ChunkSection(y=0, blocks=<factory>, metadata=<factory>, additions=<factory>)

Vertical section of world chunk.

y: int = 0

blocks: memoryview

metadata: memoryview

additions: memoryview

class RegionChunk(index=0, header=<factory>, payload=<factory>, sections=(), lighting=<factory>, biomes=<factory>, records=<factory>)

Decompressed world chunk.

index: int = 0

header: ChunkHeader

payload: bytes

sections: tuple[ChunkSection, ...] = ()

lighting: memoryview

biomes: memoryview

records: memoryview

Textures

Texture structures.

CUBEMAP_FACES = ('+x', '-x', '+y', '-y', '+z', '-z')

Cubemap face order.

CUBEMAP_FACE_COUNT = 6

Number of faces in a cubemap.

class TextureMeta(mipmap_count=0, format=<factory>, path_hash=<factory>)

Texture source metadata.

mipmap_count: int = 0

format: bytes

path_hash: bytes

class Texture

Bases: ABC

Base class for texture data.

abstract property mipmap_count: int

abstract property image: bytes

abstract property linear_size: int

class DefaultTexture(uncompressed=<factory>, compressed=<factory>, mipmaps=<factory>)

Bases: Texture

Standard 2D texture with mipmaps.

uncompressed: list[int]

compressed: list[int]

mipmaps: list[bytes]

property mipmap_count: int

property image: bytes

property linear_size: int

class CubemapTexture(uncompressed=<factory>, compressed=<factory>, faces=<factory>)

Bases: Texture

Cubemap texture with face separated mipmaps.

uncompressed: list[list[int]]

compressed: list[list[int]]

faces: list[list[bytes]]

property mipmap_count: int

property image: bytes

property linear_size: int