@igneosoft/forge 0.1.1 → 0.1.2

package/dist/index.d.cts

@@ -1,18 +1,321 @@
 import * as THREE from 'three';
 export { THREE };
+export { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+export { FBXLoader } from 'three/addons/loaders/FBXLoader.js';
+
+interface CameraController {
+    readonly camera: THREE.Camera;
+    /** Whether the engine should rotate the character mesh to face movement direction */
+    readonly rotateCharacter: boolean;
+    /** Whether the character mesh should be hidden (e.g. first-person view) */
+    readonly hideCharacter: boolean;
+    /** Bind event listeners (mouse, scroll, pointer lock) to the canvas */
+    attach(canvas: HTMLCanvasElement): void;
+    /** Remove all event listeners */
+    detach(): void;
+    /** Per-frame update — positions/orients the camera relative to the target */
+    update(delta: number, target: THREE.Vector3): void;
+    /**
+     * Returns movement basis vectors from the camera's perspective.
+     * forward: direction "up on screen" maps to in world space (Y=0, normalized)
+     * right: direction "right on screen" maps to in world space (Y=0, normalized)
+     */
+    getMovementBasis(): {
+        forward: THREE.Vector3;
+        right: THREE.Vector3;
+    };
+    /** Handle viewport resize */
+    resize(width: number, height: number): void;
+}
+
+interface IsometricCameraOptions {
+    viewSize?: number;
+    minZoom?: number;
+    maxZoom?: number;
+    zoomSpeed?: number;
+}
+declare class IsometricCameraController implements CameraController {
+    readonly camera: THREE.OrthographicCamera;
+    readonly rotateCharacter = true;
+    readonly hideCharacter = false;
+    private viewSize;
+    private minZoom;
+    private maxZoom;
+    private zoomSpeed;
+    private canvas;
+    constructor(options?: IsometricCameraOptions);
+    attach(canvas: HTMLCanvasElement): void;
+    detach(): void;
+    update(_delta: number, target: THREE.Vector3): void;
+    getMovementBasis(): {
+        forward: THREE.Vector3;
+        right: THREE.Vector3;
+    };
+    resize(width: number, height: number): void;
+    private onWheel;
+}
+
+interface ThirdPersonCameraOptions {
+    distance?: number;
+    minDistance?: number;
+    maxDistance?: number;
+    pitchMin?: number;
+    pitchMax?: number;
+    initialYaw?: number;
+    initialPitch?: number;
+    followLerp?: number;
+    rotationSensitivity?: number;
+    zoomSpeed?: number;
+    autoReturnSpeed?: number;
+    autoReturnDelay?: number;
+}
+declare class ThirdPersonCameraController implements CameraController {
+    readonly camera: THREE.PerspectiveCamera;
+    readonly rotateCharacter = true;
+    readonly hideCharacter = false;
+    private yaw;
+    private pitch;
+    private distance;
+    private minDistance;
+    private maxDistance;
+    private pitchMin;
+    private pitchMax;
+    private followLerp;
+    private rotationSensitivity;
+    private zoomSpeed;
+    private autoReturnSpeed;
+    private autoReturnDelay;
+    private isOrbiting;
+    private lastOrbitTime;
+    private currentPosition;
+    private canvas;
+    constructor(options?: ThirdPersonCameraOptions);
+    attach(canvas: HTMLCanvasElement): void;
+    detach(): void;
+    update(delta: number, target: THREE.Vector3): void;
+    getMovementBasis(): {
+        forward: THREE.Vector3;
+        right: THREE.Vector3;
+    };
+    resize(width: number, height: number): void;
+    private onContextMenu;
+    private onMouseDown;
+    private onMouseUp;
+    private onMouseMove;
+    private onWheel;
+}
+
+interface FirstPersonCameraOptions {
+    pitchMin?: number;
+    pitchMax?: number;
+    sensitivity?: number;
+    headOffset?: THREE.Vector3;
+}
+declare class FirstPersonCameraController implements CameraController {
+    readonly camera: THREE.PerspectiveCamera;
+    readonly rotateCharacter = false;
+    readonly hideCharacter = true;
+    private yaw;
+    private pitch;
+    private pitchMin;
+    private pitchMax;
+    private sensitivity;
+    private headOffset;
+    private isLocked;
+    private canvas;
+    constructor(options?: FirstPersonCameraOptions);
+    attach(canvas: HTMLCanvasElement): void;
+    detach(): void;
+    update(_delta: number, target: THREE.Vector3): void;
+    getMovementBasis(): {
+        forward: THREE.Vector3;
+        right: THREE.Vector3;
+    };
+    resize(width: number, height: number): void;
+    private onClick;
+    private onPointerLockChange;
+    private onMouseMove;
+}
+
+interface VertexHeights {
+    nw: number;
+    ne: number;
+    sw: number;
+    se: number;
+}
+interface LinkedEdges {
+    north: boolean;
+    south: boolean;
+    east: boolean;
+    west: boolean;
+}
+interface TileData {
+    color: string;
+    walkable: boolean;
+    height: number;
+    vertexHeights?: VertexHeights;
+    linkedEdges?: LinkedEdges;
+    materialId?: string;
+}
+declare function getEffectiveVertexHeights(tile: TileData): VertexHeights;
+declare function isTileFlat(tile: TileData): boolean;
+declare function getLinkedEdges(tile: TileData): LinkedEdges;
+/** Get tile base height in tile units (elevation) */
+declare function getTileBaseElevation(mapData: MapData, x: number, z: number): number;
+interface WallOpening {
+    id: string;
+    type: 'window' | 'door' | 'arch';
+    offsetAlongWall: number;
+    baseHeight: number;
+    width: number;
+    height: number;
+}
+interface ColumnPiece {
+    id: string;
+    type: 'column';
+    x: number;
+    z: number;
+    baseElevation: number;
+    topElevation: number;
+    material: string;
+    materialId?: string;
+    constructionId?: string;
+}
+interface WallPiece {
+    id: string;
+    type: 'wall';
+    columnIds: [string, string];
+    material: string;
+    materialId?: string;
+    openings: WallOpening[];
+    constructionId?: string;
+}
+interface FloorPiece {
+    id: string;
+    type: 'floor';
+    columnIds: string[];
+    material: string;
+    materialId?: string;
+    constructionId?: string;
+}
+type StructuralPiece = ColumnPiece | WallPiece | FloorPiece;
+interface Construction {
+    id: string;
+    templateName: string;
+    instanceNumber: number;
+    pieceIds: string[];
+}
+interface MapEntity {
+    id: string;
+    characterId: string;
+    x: number;
+    z: number;
+}
+interface MapObject {
+    id: string;
+    type: string;
+    x: number;
+    z: number;
+    color: string;
+    height: number;
+    solid: boolean;
+}
+interface Portal {
+    x: number;
+    z: number;
+    targetScene: string;
+    targetSpawn: string;
+}
+interface SpawnPoint$1 {
+    x: number;
+    z: number;
+}
+interface MapData {
+    id: string;
+    name: string;
+    width: number;
+    height: number;
+    tileSize: number;
+    tiles: TileData[][];
+    objects: MapObject[];
+    portals: Portal[];
+    spawns: Record<string, SpawnPoint$1>;
+    structures: StructuralPiece[];
+    constructions: Construction[];
+    entities: MapEntity[];
+    colorFavorites?: string[];
+}
+declare function createEmptyMap(id: string, width: number, height: number, name?: string, baseColor?: string): MapData;
+
+declare class CollisionMap {
+    private walkable;
+    private heights;
+    private vertexHeights;
+    private solidObjects;
+    private solidStructures;
+    private floorSurfaces;
+    private allStructures;
+    private playerHeight;
+    private width;
+    private height;
+    private tileSize;
+    constructor(mapData: MapData, playerHeight?: number);
+    /** Push an AABB for a wall segment defined along the wall axis */
+    private pushWallSegment;
+    canWalk(worldX: number, worldZ: number, fromWorldX?: number, fromWorldZ?: number, currentFeetY?: number): boolean;
+    /** Get floor elevation at world position using N-column polygon + fan interpolation */
+    private getFloorElevationAt;
+    /** Get effective height at position. If currentY is provided, only considers
+     *  surfaces reachable from that height (below + step tolerance). */
+    getTileHeight(worldX: number, worldZ: number, currentY?: number): number;
+    isWater(worldX: number, worldZ: number, feetY?: number): boolean;
+}
+
+interface CharacterEntityLike {
+    readonly root: THREE.Group;
+    play(name: string, crossFadeDuration?: number): void;
+    update(delta: number): void;
+    dispose?(): void;
+}
+declare class Player {
+    readonly entity: CharacterEntityLike;
+    readonly mesh: THREE.Group;
+    /** Y offset set by the entity (morphology baseHeight) — preserved during movement */
+    private readonly baseY;
+    private targetPosition;
+    private collisionMap;
+    private wasMoving;
+    private targetFacingAngle;
+    constructor(entity: CharacterEntityLike);
+    get position(): THREE.Vector3;
+    setPosition(x: number, z: number): void;
+    getHeight(): number;
+    setCollisionMap(collisionMap: CollisionMap | null): void;
+    setFacingAngle(angle: number): void;
+    update(delta: number, direction: {
+        x: number;
+        z: number;
+    }): void;
+    dispose(): void;
+}
 
+interface EngineOptions {
+    cameraController?: CameraController;
+    player?: Player;
+}
 declare class Engine {
     private renderer;
     private scene;
-    private camera;
+    private cameraController;
     private player;
     private input;
     private sceneManager;
     private animationFrameId;
     private clock;
-    constructor(canvas: HTMLCanvasElement);
+    constructor(canvas: HTMLCanvasElement, options?: EngineOptions);
     start(): void;
     stop(): void;
+    setCameraController(controller: CameraController): void;
     private loop;
     private handleResize;
 }
@@ -37,7 +340,7 @@ interface SceneStateData {
     visited: boolean;
 }
 
-interface SpawnPoint$1 {
+interface SpawnPoint {
     x: number;
     z: number;
 }
@@ -48,7 +351,7 @@ declare abstract class GameScene {
     abstract buildInitialState(): SceneStateData;
     abstract populate(threeScene: THREE.Scene, state: SceneStateData): void;
     abstract update(delta: number): void;
-    abstract getSpawnPoint(fromSceneId?: string): SpawnPoint$1;
+    abstract getSpawnPoint(fromSceneId?: string): SpawnPoint;
     saveState(): SceneStateData | null;
     clear(threeScene: THREE.Scene): void;
 }
@@ -61,87 +364,162 @@ declare class SceneManager {
     constructor(threeScene: THREE.Scene);
     get current(): GameScene | null;
     register(scene: GameScene): void;
-    load(sceneId: string, fromSceneId?: string): SpawnPoint$1;
+    load(sceneId: string, fromSceneId?: string): SpawnPoint;
     getState(sceneId: string): SceneStateData | undefined;
     getAllStates(): Record<string, SceneStateData>;
 }
 
-interface TileData {
-    color: string;
-    walkable: boolean;
-    height: number;
-}
-interface MapObject {
+interface MaterialVariantData {
     id: string;
-    type: string;
-    x: number;
-    z: number;
-    color: string;
-    height: number;
-    solid: boolean;
-}
-interface Portal {
-    x: number;
-    z: number;
-    targetScene: string;
-    targetSpawn: string;
-}
-interface SpawnPoint {
-    x: number;
-    z: number;
+    sizeTiles: {
+        w: number;
+        h: number;
+    };
+    depth: number;
+    palette: string[];
+    data: string;
 }
-interface MapData {
-    id: string;
+interface MaterialDefData {
+    _id: string;
     name: string;
-    width: number;
-    height: number;
-    tileSize: number;
-    tiles: TileData[][];
-    objects: MapObject[];
-    portals: Portal[];
-    spawns: Record<string, SpawnPoint>;
+    backgroundColor?: string;
+    variants: MaterialVariantData[];
+}
+declare class StructureRenderer {
+    private group;
+    private materialDefs;
+    private highlightedId;
+    private allStructures;
+    getGroup(): THREE.Group;
+    setMaterialDefs(defs: MaterialDefData[]): void;
+    getMaterialDefs(): Map<string, MaterialDefData>;
+    setHighlighted(structureId: string | null): void;
+    private applyHighlight;
+    render(mapData: MapData): THREE.Group;
+    /** Get floor elevation at world position — uses the same pushed geometry as renderFloor
+     *  so interpolated values match exactly what the GPU renders. */
+    private getFloorElevAtWorld;
+    /** Get the 4 clipped top-Y values for a column's corners: [NW, NE, SW, SE] */
+    private getColumnTopCorners;
+    private renderColumn;
+    /** Build voxel-textured relief caps on visible column faces (faces without walls) */
+    private buildVoxelColumnMesh;
+    private renderWall;
+    private renderFloor;
+    /** Build voxel-textured mesh for a floor surface (8x8x1 materials on the XZ plane) */
+    private buildVoxelFloorMesh;
+    /** Pick the column corner height closest to a given direction from the column center */
+    private pickCornerHeight;
+    /** Build a voxel-textured mesh for a wall surface.
+     *  Tiles material variants across the wall and returns a mesh, or null if no material. */
+    private buildVoxelWallMesh;
+    /** Simple seeded random for deterministic tiling per wall */
+    private seededRandom;
+    /** Fill a surface grid with material variants, avoiding opening areas */
+    private tileSurface;
+    applyHeightCutoff(cutoffWorld: number): void;
+    dispose(): void;
 }
-declare function createEmptyMap(id: string, width: number, height: number, name?: string, baseColor?: string): MapData;
 
 declare class MapRenderer {
     private group;
-    private tileMeshes;
+    private terrainMesh;
+    private terrainVoxelMesh;
+    private wallMesh;
+    private waterMesh;
     private gridLines;
     private currentWidth;
     private currentHeight;
+    private heightSnapshot;
+    private spawnMarker;
+    private structureRenderer;
+    private entityMeshes;
     getGroup(): THREE.Group;
+    setMaterialDefs(defs: MaterialDefData[]): void;
+    private getMaterialBgColors;
     render(mapData: MapData): THREE.Group;
+    setGridVisible(visible: boolean): void;
     syncTiles(mapData: MapData): void;
-    needsFullRebuildForHeight(mapData: MapData): boolean;
+    syncStructures(mapData: MapData): void;
+    applyHeightCutoff(cutoff: number | null, tileSize: number): void;
+    setHighlightedStructure(structureId: string | null): void;
     needsFullRebuild(mapData: MapData): boolean;
     needsGeometryUpdate(mapData: MapData): boolean;
+    private saveHeightSnapshot;
+    private renderStructures;
+    private renderSpawn;
     private renderObjects;
-    private buildHeightWalls;
     private buildGrid;
+    private buildTerrainVoxels;
+    addEntity(id: string, mesh: THREE.Group, tileX: number, tileZ: number, updater: (delta: number) => void, mapData: MapData): void;
+    removeEntity(id: string): void;
+    updateEntities(delta: number): void;
     dispose(): void;
 }
 
-declare class CollisionMap {
-    private walkable;
-    private heights;
-    private solidObjects;
-    private width;
-    private height;
-    private tileSize;
-    constructor(mapData: MapData);
-    canWalk(worldX: number, worldZ: number, fromWorldX?: number, fromWorldZ?: number): boolean;
-    getTileHeight(worldX: number, worldZ: number): number;
-    isWater(worldX: number, worldZ: number): boolean;
+declare function createWorldGrid(cols: number, rows: number, tileSize?: number): THREE.Group;
+
+/**
+ * Compact voxel encoding: 8-bit indexed palette + RLE compression.
+ *
+ * Storage format:
+ *   palette: string[]   — up to 255 hex colors
+ *   data: string         — base64-encoded RLE byte pairs [count, paletteIndex]
+ *
+ * Traversal order: for z in [0,depth), for y in [0,height), for x in [0,width)
+ * Palette index 0 = empty (no voxel), 1..255 = palette[0..254]
+ */
+interface CompactVoxelData {
+    palette: string[];
+    data: string;
 }
+interface Voxel$1 {
+    x: number;
+    y: number;
+    z: number;
+    color: string;
+}
+/** Encode sparse voxels into palette + RLE base64. */
+declare function encodeVoxels(voxels: Voxel$1[], width: number, height: number, depth: number): CompactVoxelData;
+/** Decode palette + RLE to sparse voxel array. */
+declare function decodeVoxels(compact: CompactVoxelData, width: number, height: number, depth: number): Voxel$1[];
 
-declare function createWorldGrid(cols: number, rows: number, tileSize?: number): THREE.Group;
+/**
+ * Map serialization codec — compact tile format.
+ *
+ * Instead of storing each tile as a JSON object with repeated field names,
+ * uses flat arrays and sparse maps:
+ *
+ *   palette: string[]           — unique colors
+ *   tileGrid.colors: string     — base64 RLE palette indices (row-major)
+ *   tileGrid.heights: number[]  — flat height array (row-major)
+ *   tileGrid.notWalkable: number[]      — indices of non-walkable tiles (sparse)
+ *   tileGrid.vertexHeights: Record<string, VertexHeights>  — sparse "idx" → VH
+ *   tileGrid.linkedEdges: Record<string, LinkedEdges>      — sparse "idx" → LE
+ *
+ * Runtime MapData keeps TileData[][] with string colors.
+ * Backward-compatible: decodeMapData handles legacy format (tiles as objects).
+ */
+
+/** Encode MapData for compact serialization. */
+declare function encodeMapData(map: MapData): Record<string, unknown>;
+/** Decode serialized JSON back to MapData. Handles compact tileGrid and legacy tile-object formats. */
+declare function decodeMapData(json: Record<string, any>): MapData;
 
 declare class FieldScene extends GameScene {
     constructor();
     buildInitialState(): SceneStateData;
     populate(threeScene: THREE.Scene, _state: SceneStateData): void;
     update(_delta: number): void;
-    getSpawnPoint(_fromSceneId?: string): SpawnPoint$1;
+    getSpawnPoint(_fromSceneId?: string): SpawnPoint;
+}
+
+interface ColorPalette {
+    skin: string;
+    eyes: string;
+    hair: string;
+    primary: string;
+    secondary: string;
 }
 
 declare class InputManager {
@@ -156,156 +534,135 @@ declare class InputManager {
     };
 }
 
-interface ColorPalette {
-    skin: string;
-    primary: string;
-    secondary: string;
-    accent: string;
-}
-type PartFactory = (palette: ColorPalette) => THREE.Mesh;
-type SlotName = 'head' | 'torso' | 'armL' | 'armR' | 'forearmL' | 'forearmR' | 'legL' | 'legR' | 'shinL' | 'shinR' | 'weapon';
-interface CharacterConfig {
-    id: string;
-    palette: ColorPalette;
-    head: PartFactory;
-    torso: PartFactory;
-    armL: PartFactory;
-    armR: PartFactory;
-    forearmL: PartFactory;
-    forearmR: PartFactory;
-    legL: PartFactory;
-    legR: PartFactory;
-    shinL: PartFactory;
-    shinR: PartFactory;
-    weapon?: PartFactory;
-}
-
-declare class CharacterEntity {
-    readonly root: THREE.Group;
-    private bones;
-    private mixer;
-    private actions;
-    private currentAction;
-    private parts;
-    private palette;
-    constructor(config: CharacterConfig);
-    /** Play an animation by name. Crossfades from current. */
-    play(name: string, crossFadeDuration?: number): void;
-    /** Swap a body part at runtime (e.g., equip new armor) */
-    swapPart(slot: SlotName, factory: PartFactory): void;
-    /** Must be called every frame with delta time */
-    update(delta: number): void;
-    /** Cleanup GPU resources */
-    dispose(): void;
-}
-
-declare class Player {
-    readonly entity: CharacterEntity;
-    readonly mesh: THREE.Group;
-    private targetPosition;
-    private collisionMap;
-    private wasMoving;
-    constructor(config?: CharacterConfig);
-    get position(): THREE.Vector3;
-    setPosition(x: number, z: number): void;
-    setCollisionMap(collisionMap: CollisionMap | null): void;
-    update(delta: number, direction: {
-        x: number;
-        z: number;
-    }): void;
-    dispose(): void;
-}
-
 interface Vec3 {
     x: number;
     y: number;
     z: number;
 }
-interface PivotAxes {
-    x: boolean;
-    y: boolean;
-    z: boolean;
-}
-interface RotationConstraints {
-    axes: PivotAxes;
-    min: Vec3;
-    max: Vec3;
-}
-interface InternalPivot {
+interface Section {
     name: string;
-    position: Vec3;
-    constraints: RotationConstraints;
+    size: Vec3;
 }
-interface Connector {
-    name: string;
-    position: Vec3;
+interface AxisLimits {
+    min: number;
+    max: number;
+    initial: number;
 }
-interface BoneDefinition {
-    start: Vec3;
-    end: Vec3;
-    pivots: InternalPivot[];
-    connectors: Connector[];
+interface LinkRotation {
+    x: AxisLimits;
+    y: AxisLimits;
+    z: AxisLimits;
 }
-interface Attachment {
-    parentPart: string;
-    parentConnector: string;
-    constraints: RotationConstraints;
+interface LinkTranslation {
+    x: AxisLimits;
+    y: AxisLimits;
+    z: AxisLimits;
 }
-interface BodyPartDefinition {
+interface Link {
     name: string;
-    size: Vec3;
-    bone: BoneDefinition;
-    attachment: Attachment | null;
+    parent: string;
+    child: string;
+    insert: Vec3;
+    eje: Vec3;
+    rotation: LinkRotation;
+    translation?: LinkTranslation;
+}
+interface MorphologyConfig {
+    baseSpeed?: number;
+    canWalk?: boolean;
+    canFly?: boolean;
 }
 interface MorphologyData {
     _id?: string;
     name: string;
-    bodyParts: BodyPartDefinition[];
+    root: string;
+    baseHeight: number;
+    sections: Section[];
+    links: Link[];
+    config?: MorphologyConfig;
+}
+
+/**
+ * Serializable animation format for data-driven animations.
+ * Stored in MongoDB, exported via .igneokit, editable in the animation editor.
+ */
+interface BonePose {
+    boneName: string;
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    translation?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+interface Keyframe {
+    time: number;
+    poses: BonePose[];
+}
+interface AnimationData {
+    _id?: string;
+    name: string;
+    duration: number;
+    loop: boolean;
+    morphologyId: string;
+    keyframes: Keyframe[];
+}
+
+interface VoxelPartInput {
+    slot: string;
+    voxels: {
+        x: number;
+        y: number;
+        z: number;
+        color: string;
+    }[];
+    size: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    voxelSize: number;
+    paletteMapping?: Record<string, 'skin' | 'eyes' | 'hair' | 'primary' | 'secondary'>;
+}
+interface DataDrivenCharacterConfig {
+    morphology: MorphologyData;
+    parts: VoxelPartInput[];
+    palette?: Record<string, string>;
+    animations: AnimationData[];
+}
+/**
+ * Character entity built from data (morphology + voxel parts + animations).
+ * Everything comes from the database — morphology defines the skeleton,
+ * voxel parts provide the visual content, animations drive movement.
+ */
+declare class DataDrivenCharacterEntity {
+    readonly root: THREE.Group;
+    private mixer;
+    private actions;
+    private currentAction;
+    constructor(config: DataDrivenCharacterConfig);
+    /** Play an animation by name. Crossfades from current. */
+    play(name: string, crossFadeDuration?: number): void;
+    /** Must be called every frame with delta time */
+    update(delta: number): void;
+    /** Cleanup GPU resources */
+    dispose(): void;
 }
-declare const humanoidMorphology: MorphologyData;
 
 type MorphologyScene = {
     root: THREE.Group;
     groups: Record<string, THREE.Group>;
 };
 /**
- * Builds a THREE.Group hierarchy from the new bodyParts-based MorphologyData.
- * Each bodyPart becomes a group. Internal pivots become sub-groups.
- * Returns the root group + a map of all groups by name.
+ * Builds a THREE.Group hierarchy from sections + links MorphologyData.
+ * Each section becomes a group. Links define parent-child relationships.
+ * Child position = insert (position of child relative to parent).
  */
 declare function buildFromMorphology(data: MorphologyData): MorphologyScene;
-interface BoneRefs {
-    root: THREE.Group;
-    hips: THREE.Group;
-    spine: THREE.Group;
-    neck: THREE.Group;
-    shoulderL: THREE.Group;
-    armL: THREE.Group;
-    forearmL: THREE.Group;
-    shoulderR: THREE.Group;
-    armR: THREE.Group;
-    forearmR: THREE.Group;
-    weaponMount: THREE.Group;
-    hipL: THREE.Group;
-    legL: THREE.Group;
-    shinL: THREE.Group;
-    hipR: THREE.Group;
-    legR: THREE.Group;
-    shinR: THREE.Group;
-}
-/**
- * Manual skeleton builder — maintains exact same hierarchy as the original.
- * Used by CharacterEntity, CharacterAssembler, Player, and animations.
- * Does NOT depend on MorphologyData.
- */
-declare function createSkeleton(): BoneRefs;
-
-declare class CharacterAssembler {
-    /** Attach all parts from config to bones. Returns map of slot -> mesh for tracking. */
-    static assemble(bones: BoneRefs, config: CharacterConfig, parts: Map<SlotName, THREE.Object3D>): void;
-    /** Swap a single part. Disposes the old mesh. */
-    static swapPart(bones: BoneRefs, parts: Map<SlotName, THREE.Object3D>, slot: SlotName, factory: PartFactory, palette: ColorPalette): void;
-}
 
 /**
  * Data-driven character definition.
@@ -344,7 +701,7 @@ interface VoxelPartData {
         z: number;
     };
     voxels: Voxel[];
-    paletteMapping?: Record<string, 'skin' | 'primary' | 'secondary' | 'accent'>;
+    paletteMapping?: Record<string, 'skin' | 'eyes' | 'hair' | 'primary' | 'secondary'>;
 }
 interface VoxelEditorMesh {
     mesh: THREE.InstancedMesh;
@@ -353,7 +710,9 @@ interface VoxelEditorMesh {
     /** Maps "x,y,z" → instanceId */
     positionToInstance: Map<string, number>;
 }
-declare function buildEditorMesh(data: VoxelPartData): VoxelEditorMesh;
+/** Resolve a voxel color: '@skin' → palette lookup, '#ff8800' → as-is */
+declare function resolveVoxelColor(color: string, palette?: Record<string, string>, paletteMapping?: Record<string, string>): string;
+declare function buildEditorMesh(data: VoxelPartData, palette?: Record<string, string>): VoxelEditorMesh;
 declare function buildRuntimeMesh(data: VoxelPartData, palette?: Record<string, string>): THREE.Mesh;
 /** Get the face normal and adjacent position for placing a new voxel */
 declare function getAdjacentPosition(_face: THREE.Face | null, intersect: THREE.Intersection, voxelSize: number, origin: {
@@ -396,108 +755,11 @@ interface ArmorSetData {
     pieceIds: string[];
 }
 
-/** Standard humanoid head */
-declare const humanHead: PartFactory;
-/** Skull */
-declare const skullHead: PartFactory;
-/** Helmet */
-declare const helmetHead: PartFactory;
-/** Hood */
-declare const hoodHead: PartFactory;
-
-/** Basic tunic/shirt */
-declare const tunicTorso: PartFactory;
-/** Skeleton ribcage */
-declare const ribcageTorso: PartFactory;
-/** Armored torso */
-declare const armorTorso: PartFactory;
-/** Rags */
-declare const ragsTorso: PartFactory;
-/** Robe with skirt */
-declare const robeTorso: PartFactory;
-
-declare const humanArm: PartFactory;
-declare const boneArm: PartFactory;
-declare const armorArm: PartFactory;
-declare const robeArm: PartFactory;
-declare const humanForearm: PartFactory;
-declare const boneForearm: PartFactory;
-declare const armorForearm: PartFactory;
-declare const robeForearm: PartFactory;
-
-declare const humanLeg: PartFactory;
-declare const boneLeg: PartFactory;
-declare const armorLeg: PartFactory;
-declare const robeLeg: PartFactory;
-declare const humanShin: PartFactory;
-declare const boneShin: PartFactory;
-declare const armorShin: PartFactory;
-declare const robeShin: PartFactory;
-
-/** Short sword */
-declare const sword: PartFactory;
-/** Battle axe */
-declare const axe: PartFactory;
-/** Staff */
-declare const staff: PartFactory;
-
-declare const playerConfig: CharacterConfig;
-declare const skeletonConfig: CharacterConfig;
-declare const zombieConfig: CharacterConfig;
-declare const warriorConfig: CharacterConfig;
-declare const mageConfig: CharacterConfig;
-
-declare function register(clip: THREE.AnimationClip): void;
-declare const AnimationLibrary: {
-    get(name: string): THREE.AnimationClip;
-    getAll(): THREE.AnimationClip[];
-    register: typeof register;
-};
-
-/**
- * Serializable animation format for data-driven animations.
- * Stored in MongoDB, exported via .igneokit, editable in the animation editor.
- */
-interface BonePose {
-    boneName: string;
-    rotation: {
-        x: number;
-        y: number;
-        z: number;
-    };
-}
-interface Keyframe {
-    time: number;
-    poses: BonePose[];
-}
-interface AnimationData {
-    _id?: string;
-    name: string;
-    duration: number;
-    loop: boolean;
-    morphologyId: string;
-    keyframes: Keyframe[];
-}
-
 /**
  * Builds a THREE.AnimationClip from serializable AnimationData.
- * Uses the morphology's bone hierarchy to build dot-notation track paths
- * compatible with THREE's property binding system.
+ * Track names use flat `pivot_linkName.rotation[axis]` format,
+ * compatible with THREE's property binding system via findNode().
  */
 declare function buildAnimationClip(data: AnimationData, morphology?: MorphologyData): THREE.AnimationClip;
-/**
- * Converts an existing hardcoded AnimationClip to AnimationData format.
- * Useful for migrating existing animations.
- */
-declare function clipToAnimationData(clip: THREE.AnimationClip, morphologyId: string, loop?: boolean): AnimationData;
-
-/** Subtle breathing/bobbing animation */
-declare function createIdleClip(): THREE.AnimationClip;
-
-/** Walk cycle - arms and legs swing opposite */
-declare function createWalkClip(): THREE.AnimationClip;
-
-/** Single attack swing with right arm */
-declare function createAttackClip(): THREE.AnimationClip;
 
-export { type AnimationData, AnimationLibrary, type ArmorPieceData, type ArmorSetData, type Attachment, type BodyPartDefinition, type BoneDefinition, type BonePose, type BoneRefs, CharacterAssembler, type CharacterConfig, type CharacterDefinition, CharacterEntity, CollisionMap, type ColorPalette, type Connector, Engine, type EntityState, FieldScene, GameScene, InputManager, type InternalPivot, type Keyframe, type MapData, type MapObject, MapRenderer, type MorphologyData, type MorphologyScene, type PartFactory, type PivotAxes, Player, type Portal, type RotationConstraints, SceneManager, type SceneStateData, type SlotName, type SpawnPoint$1 as SpawnPoint, type TileData, type Vec3, type Voxel, type VoxelEditorMesh, type VoxelPartData, armorArm, armorForearm, armorLeg, armorShin, armorTorso, axe, boneArm, boneForearm, boneLeg, boneShin, buildAnimationClip, buildEditorMesh, buildFromMorphology, buildRuntimeMesh, clipToAnimationData, createAttackClip, createEmptyMap, createIdleClip, createIsometricCamera, createSkeleton, createWalkClip, createWorldGrid, getAdjacentPosition, getClickedVoxelPosition, helmetHead, hoodHead, humanArm, humanForearm, humanHead, humanLeg, humanShin, humanoidMorphology, mageConfig, playerConfig, ragsTorso, ribcageTorso, robeArm, robeForearm, robeLeg, robeShin, robeTorso, skeletonConfig, skullHead, staff, sword, tunicTorso, updateCameraTarget, warriorConfig, zombieConfig };
+export { type AnimationData, type ArmorPieceData, type ArmorSetData, type AxisLimits, type BonePose, type CameraController, type CharacterDefinition, type CharacterEntityLike, CollisionMap, type ColorPalette, type ColumnPiece, type CompactVoxelData, type Construction, type DataDrivenCharacterConfig, DataDrivenCharacterEntity, Engine, type EngineOptions, type EntityState, FieldScene, FirstPersonCameraController, type FirstPersonCameraOptions, type FloorPiece, GameScene, InputManager, IsometricCameraController, type IsometricCameraOptions, type Keyframe, type Link, type LinkRotation, type LinkTranslation, type LinkedEdges, type MapData, type MapEntity, type MapObject, MapRenderer, type MaterialDefData, type MaterialVariantData, type MorphologyConfig, type MorphologyData, type MorphologyScene, Player, type Portal, SceneManager, type SceneStateData, type Section, type SpawnPoint, type StructuralPiece, StructureRenderer, ThirdPersonCameraController, type ThirdPersonCameraOptions, type TileData, type Vec3, type VertexHeights, type Voxel, type VoxelEditorMesh, type VoxelPartData, type VoxelPartInput, type WallOpening, type WallPiece, buildAnimationClip, buildEditorMesh, buildFromMorphology, buildRuntimeMesh, createEmptyMap, createIsometricCamera, createWorldGrid, decodeMapData, decodeVoxels, encodeMapData, encodeVoxels, getAdjacentPosition, getClickedVoxelPosition, getEffectiveVertexHeights, getLinkedEdges, getTileBaseElevation, isTileFlat, resolveVoxelColor, updateCameraTarget };