@adatechnology/game-floorplan-three 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,533 @@
+import { ModuleScenario, TestableModule } from '@adatechnology/game-contracts';
+
+/** Texts the house shows to the player (interaction prompts, messages, outbuilding labels), by locale. */
+type Messages = Record<string, string>;
+declare const en: Messages;
+declare const ptBR: Messages;
+declare const locales: Record<string, Messages>;
+type Translate = (key: string, params?: Record<string, string | number>) => string;
+/**
+ * Translator for a locale id ('en', 'pt-BR'), or for a partial table that overrides the English one.
+ * A missing key falls back to English and then to the key itself.
+ */
+declare function createTranslator(locale?: string | Partial<Messages>): Translate;
+
+/** A part of the house a hit can damage (door, window, glass, tank...): the game reads `hp`. */
+interface Damageable {
+    type: string;
+    hp: number;
+    hpMax: number;
+}
+/** What `create(THREE, options)` reads. Everything is optional; the three.js namespace is the first argument. */
+interface HouseRendererOptions {
+    /** Document used to draw the procedural textures on a canvas (default: the page's). */
+    document?: any;
+    /** `'game'` merges more and draws less than `'high'`. */
+    quality?: 'high' | 'game';
+    /** Locale of the texts the house shows (`en`, `pt-BR`) or a table of messages. */
+    locale?: string | Partial<Messages>;
+    /** `@adatechnology/game-props3d` (default: the package's own dependency). */
+    props?: any;
+    /** `THREE.Reflector` (three/examples/jsm/objects/Reflector.js); without it the mirrors use only the environment map. */
+    reflector?: any;
+    /** Cars of the lot and garage: `build(kind, { quality, seed })` -> `{ group, damageable, release() }`. Without it there are no cars. */
+    fleet?: {
+        build(kind: string, options: {
+            quality: string;
+            seed: number;
+        }): any;
+    } | null;
+    /** Car kinds (fleet ids) per lot style (`budget`, `mid`, `high`); replaces the list of a style. */
+    carKinds?: Record<string, string[]>;
+    /** Hit points per damage class (glass, wood, water, metal, masonry, rubber, fuel, gas). */
+    hp?: Record<string, number>;
+    /** Textures from the app that replace the procedural ones. */
+    textures?: Record<string, any>;
+    atlas?: Record<string, any>;
+    /** Materials the game swaps (a material or a function of the default one). */
+    materials?: Record<string, any>;
+    /** The world of `@adatechnology/game-destruction`; the house registers itself in it on first need. */
+    destruction?: any;
+    /** `createDestructionRenderer(THREE, { scene, world })` of `@adatechnology/game-destruction-three`: draws fracture, collapse, fragments, spalls and the rebar cage on the house's meshes. */
+    destructionRenderer?: any;
+    /** The interactables kit, injected: `{ GameInteractables, GameInteractablesHousehold, GameInteractablesThree, adapter, locale, region, items, effects, camera, onEvent, onSeat }`. */
+    interactives?: any;
+    /** The vegetation packages, injected: `{ GameVegetation, GameVegetationSpecies }`. */
+    vegetation?: any;
+    /** Maps an id of the plan to the key its seeded random draws use, to reproduce a scene drawn with other ids (golden tests). */
+    seedKey?: (id: string) => string | null | undefined;
+    /** Distance (m) beyond which the interior (`interior`) and the house (`hide`) are drawn no more, or `false` to switch distance LOD off. */
+    lod?: false | {
+        interior?: number;
+        hide?: number;
+    };
+    drawCallBudget?: number;
+    onChange?: (change: {
+        shadow: boolean;
+    }) => void;
+    onCollider?: (collider: any) => void;
+    onDamage?: (part: any, point: {
+        x: number;
+        y: number;
+        z: number;
+    } | null, type: string) => void;
+    onWreck?: (event: any, house: any) => void;
+    onInteract?: (target: any, action: any) => boolean | void;
+    onLight?: (light: any) => void;
+    onMessage?: (text: string) => void;
+}
+interface BuildOptions {
+    /** `'high'` (default) or `'game'`. */
+    quality?: 'high' | 'game';
+    /** Night: lit windows and room lamps. */
+    night?: boolean;
+    /** Roof cut off and floors above hidden, to look into the plan. */
+    cut?: boolean;
+    /** A state returned by `newState()`: pass the same one to rebuild without closing every door. */
+    state?: any;
+    /** `false`: the app already has ground, street and lawn. */
+    terrain?: boolean;
+    /** `true`: no lot wall, fence or gates (the game has its own). */
+    noPerimeter?: boolean;
+    /** `'meshes'`: one mesh per structural piece instead of one per group and material. */
+    pieces?: 'meshes';
+    drawCallBudget?: number;
+    building?: {
+        floors?: number;
+        floor?: number;
+        unit?: number;
+        showBuilding?: boolean;
+    };
+}
+/** The house the renderer built. The three.js groups are ready to add to a scene. */
+interface House {
+    version: string;
+    r: any;
+    name: string;
+    quality: string;
+    group: any;
+    house: any;
+    groups: Record<string, any>;
+    floors: any[];
+    ceilings: any[];
+    roof: any;
+    lot: any;
+    ground: any;
+    building: any;
+    /** Public colliders: walls, doors, lot walls and gates (aabb) and furniture (obb). */
+    colliders: any[];
+    /** Parts that move or take damage: id -> `{ group, type, opens(t), damageable }`. */
+    parts: Record<string, any>;
+    doors: any[];
+    stairs: any[];
+    labels: any[];
+    /** The real lights the builders asked for (at night) in `list`, and the same grouped by room id in `byRoom`. */
+    lights: {
+        list: any[];
+        byRoom: Record<string, any[]>;
+    };
+    stats: any;
+    structure: any;
+    destruction: any;
+    interactives: any;
+    update(dt: number, time?: number, focus?: {
+        x: number;
+        y: number;
+        z: number;
+    }): void;
+    show(options: {
+        floor?: number;
+        cut?: boolean;
+        lot?: boolean;
+    }): void;
+    target(eye: any, options?: any): any;
+    interact(target: any): any;
+    toggleDoor(id: string): any;
+    toggleLight(room?: string): any;
+    lightOn(room: string): boolean;
+    collide(x: number, z: number, floor: number, options?: any): any;
+    roomAt(floor: number, x: number, z: number): any;
+    setLod(level: number): void;
+    readonly lod: number;
+    damage(id: string, point?: any, type?: string, amount?: number): void;
+    colliderDamage(collider: any, point?: any, type?: string, amount?: number): void;
+    /** The part (door, window, furniture piece...) an object belongs to, found by going up its parents. */
+    partOf(object: any): any | null;
+    /** The first part whose box holds the point (with a tolerance, default 5 cm). */
+    partAt(point: {
+        x: number;
+        y: number;
+        z: number;
+    }, tolerance?: number): any | null;
+    dispose(): void;
+    [extra: string]: any;
+}
+/** The renderer `create(THREE, options)` returns. */
+interface HouseRenderer {
+    version: string;
+    build(result: any, options?: BuildOptions): House;
+    newState(): any;
+    types: Record<string, any>;
+    mv: any;
+    applyPart(group: any, t: number): void;
+    materials: Record<string, any>;
+    roomLightMask(material: any): void;
+    lighting(options?: any): any;
+    setNight(night: boolean): void;
+    cars: {
+        model(kind: string, seed?: number): any;
+        group(...args: any[]): any;
+        info(kind: string, seed?: number): any;
+    };
+    dispose(): void;
+}
+
+declare const OPEN_ROOM_TYPES: Set<string>;
+declare const rectsOf: (c: any) => any;
+declare const isOpenArea: (c: any) => boolean;
+declare function planLod(houses: any, focus: any, budget: any): {
+    total: any;
+    levels: any;
+    houses: any;
+};
+
+declare const VERSION = "1.0.0";
+
+/**
+ * Creates a house renderer: `create(THREE, options).build(result, { quality, night })` turns the result of `@adatechnology/game-floorplan`
+ * (plus the structure of `@adatechnology/game-floorplan-structure`) into a three.js group. Port of the team's Casa3DSDK.
+ */
+declare function create(THREE: any, options?: HouseRendererOptions): HouseRenderer;
+
+/** A rectangle `[x0, z0, x1, z1]` in the house's coordinates. */
+type NavRect = [number, number, number, number];
+/** `[x0, z0, x1, z1, from, to, axis]`: a flight from floor `from` to floor `to` along `axis`. */
+type NavStair = [number, number, number, number, number, number, 'x' | 'z'];
+interface NavFloor {
+    /** Absolute height of the floor level. */
+    y: number;
+    /** Height of the storey. */
+    h: number;
+    solids?: NavRect[];
+}
+interface NavHouseDef {
+    id: string;
+    floors: NavFloor[];
+    stairs?: NavStair[];
+    groups?: unknown[];
+    roof?: unknown;
+    /** The fine grid also rules the ground floor inside the house (default: the ground floor uses the game's grid, except stairs and banisters). */
+    own?: boolean;
+    /** The house's rectangle (default: the union of its solids and stairs). */
+    rect?: NavRect;
+}
+/** A shape on the plan: a rectangle `[x0, z0, x1, z1]` or a circle `[cx, cz, radius]`. */
+type NavShape = {
+    rect: NavRect;
+} | {
+    circle: [number, number, number];
+};
+interface NavResult {
+    y: number;
+    floor: number;
+    dx: number;
+    dz: number;
+    t: number;
+    stair: NavFlight | null;
+}
+interface NavFlight {
+    x0: number;
+    z0: number;
+    x1: number;
+    z1: number;
+    axis: 0 | 1;
+    from: number;
+    to: number;
+    group: any;
+    yFrom: number;
+    yTo: number;
+    dir: number;
+    lo: number;
+    len: number;
+    e: number;
+}
+interface NavHouse {
+    id: string;
+    own: boolean;
+    floors: NavFloor[];
+    groups: unknown[];
+    roof: unknown;
+    flights: NavFlight[];
+    grids: Uint8Array[];
+    fields: any[];
+    /** Triples (floor, cell, previous value) of the run-time changes of the grid. */
+    journal: number[];
+    shown: number;
+    x0: number;
+    z0: number;
+    x1: number;
+    z1: number;
+    ox: number;
+    oz: number;
+    nx: number;
+    nz: number;
+    n: number;
+}
+declare function createFloorNavigator(): FloorNavigator;
+interface FloorNavigator {
+    houses: NavHouse[];
+    /** Frame time in seconds; the path field is recomputed at most every 0.15 s of it. */
+    time: number;
+    currentHouse: NavHouse | null;
+    currentFloor: number;
+    /** Result of the last `level` and `heading` call (no allocation per query). */
+    result: NavResult;
+    register(def: NavHouseDef): NavHouse;
+    houseAt(x: number, z: number): NavHouse | null;
+    blocked(x: number, z: number, floor: number): number;
+    level(x: number, z: number, floor: number): boolean;
+    landing(flight: NavFlight, top: boolean, inside: number, out: number[]): number[];
+    stairTo(house: NavHouse, from: number, to: number): NavFlight | null;
+    heading(house: NavHouse, floor: number, x: number, z: number, tx: number, tz: number): boolean;
+    ray(house: NavHouse, floor: number, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, max: number): number;
+    ceilingOf(house: NavHouse, floor: number): number;
+    occlude(x: number, z: number, floor: number): NavHouse | null;
+    cell(house: NavHouse, floor: number, x: number, z: number): number;
+    apply(house: NavHouse, floor: number): void;
+    houseOf(id: string): NavHouse | null;
+    openCells(houseId: string, floor: number, shape: NavShape): number;
+    closeCells(houseId: string, floor: number, shape: NavShape): number;
+    undoChanges(houseId: string): void;
+}
+
+/** The parts of a built house (`create(THREE, options).build(...)`) the navigator reads. */
+interface NavigableHouse {
+    name?: string;
+    r: {
+        floors: {
+            index: number;
+            y0: number;
+            ceiling: number;
+        }[];
+    };
+    colliders: {
+        type: string;
+        f: number;
+        x0: number;
+        z0: number;
+        x1: number;
+        z1: number;
+    }[];
+    stairs: {
+        m: {
+            ry: number;
+        };
+        f: number;
+        to: number;
+        rect: NavRect;
+    }[];
+    floors: unknown[];
+    roof: unknown;
+}
+interface NavigationDefOptions {
+    /** Id the house registers with (default: the house's name). */
+    id?: string;
+    /** Collider types that make a cell solid (default: walls and the boards of a barricade; the gaps of the doors stay free). */
+    solids?: string[];
+    /** The fine grid also rules the ground floor inside the house. */
+    own?: boolean;
+}
+/**
+ * The registration of a built house in a floor navigator: heights from the plan's floors, solids from the house's wall colliders, one flight per
+ * stair (its footprint, from the floor it leaves to the floor it reaches, along the axis the flight runs on) and the floor groups and roof to hide
+ * by occlusion.
+ */
+declare function navigationDefOf(house: NavigableHouse, options?: NavigationDefOptions): NavHouseDef;
+
+/** The parts of a built house the binding reads: its structure (parts by id), its floors and its destruction adapter. */
+interface DestructibleHouse {
+    r: {
+        floors: {
+            index: number;
+            y0: number;
+        }[];
+    };
+    structure: {
+        byId: Map<string, {
+            role: string;
+            floor: number;
+            aabb: NavRect;
+            y1: number;
+        }>;
+    };
+    destruction: {
+        onEvent(listener: (event: any) => void): () => void;
+        restore?: () => void;
+    };
+}
+interface NavigatorBinding {
+    /** Stops listening. */
+    off(): void;
+    /** Puts the grid back (after a world reset). */
+    reset(): void;
+}
+/**
+ * Connects a floor navigator to the destruction of a house, so the people walking in it follow what the world did to it:
+ *  - a wall that reaches stage 2 opens the cells inside its opening (a circle on its floor);
+ *  - a wall that fractures or collapses opens all the cells of its footprint;
+ *  - a slab that supports a floor and fractures or collapses removes the cells of that floor under it (they become blocked).
+ * The house has to be registered in the navigator under `houseId` (`navigationDefOf`). Events arrive once the house's destruction is active.
+ * Returns the binding; `reset()` undoes the changes.
+ */
+declare function bindNavigator(navigator: FloorNavigator, houseId: string, house: DestructibleHouse): NavigatorBinding;
+
+type AreaText = {
+    group: string;
+    name: string;
+    controls: Record<'package' | 'template' | 'state' | 'seed' | 'quality' | 'lod' | 'houses' | 'budget' | 'floor_view' | 'hit', string>;
+    hints: Record<'template' | 'houses' | 'budget' | 'lod' | 'floor_view' | 'hit', string>;
+    actions: Record<'build' | 'enter' | 'up' | 'down' | 'door' | 'strike' | 'reset' | 'clear', string>;
+    options: {
+        quality: Record<string, string>;
+        lod: Record<string, string>;
+        floor_view: Record<string, string>;
+        hit: Record<string, string>;
+        state: Record<string, string>;
+    };
+    layers: Record<'roof' | 'lot' | 'night', string>;
+    metrics: Record<'houses' | 'parts' | 'standing' | 'broken' | 'holes' | 'draw_calls' | 'triangles' | 'lod' | 'floor' | 'doors_open' | 'target' | 'planned', string>;
+    sheet: {
+        kicker: string;
+        title: string;
+        template: string;
+        seed: string;
+        state: string;
+        floors: string;
+        size: string;
+        parts: string;
+        look: string;
+        none: string;
+        no_engine: string;
+    };
+    specimens: Record<string, string>;
+    scenarios: Record<string, string>;
+    steps: Record<'built' | 'no_engine' | 'entered' | 'floor' | 'no_floor' | 'door' | 'no_door' | 'strike' | 'no_aim' | 'cleared' | 'reset' | 'one_pillar_broke' | 'slabs_whole' | 'no_slab_fell' | 'two_slab_fell' | 'two_roof_fell' | 'partition_broke' | 'slab_stayed' | 'glass_hole' | 'glass_broke' | 'walls_whole' | 'tank_hole' | 'tank_leaked' | 'gas_exploded' | 'gas_damaged', string>;
+};
+
+/** What the room hands a scenario (`ScenarioContext` of game-test-room), narrowed to what these use. */
+interface AreaContext {
+    room: any;
+    step(seconds: number): void;
+    expect(condition: boolean, label: string, data?: Record<string, unknown>): void;
+}
+type Vec3 = readonly [number, number, number];
+/** Where the team's page lays its specimens (the arena has 14 m of half width). */
+declare const SPECIMEN_AT: Vec3;
+/**
+ * The six structural scenarios of the team's house area (sala-de-testes/area-casas, L3833-3868), same ids and same checks, on the specimens the area builds: destroy a pillar, two pillars, a partition,
+ * shoot a window, puncture the water tank, set the gas bottle on fire. The hits are the team's (3 MJ blunt on a pillar, 600 J 9 mm on the glass and the tank, 900 C fire on the bottle). A scenario
+ * passes when every check holds; the names of the checks are in `text.steps`.
+ */
+declare function createHouseScenarios(text: AreaText, at?: Vec3): Array<ModuleScenario<AreaContext>>;
+
+/** The part of the floorplan engine (`engine` of `@adatechnology/game-floorplan`, with the content packs the page registered) the test area reads. */
+interface FloorplanEngineLike {
+    generate(template: string, options?: {
+        seed?: number;
+        state?: string;
+    }): any;
+    listTemplates(): Array<{
+        id: string;
+        name?: string;
+        floors?: number;
+    }>;
+    listStates(): string[];
+    translate?(namespace: any, key: string, locale?: string, vars?: Record<string, string | number>): string;
+}
+/** A pack of templates the bench lists together (residential, commercial, rural, post-apocalyptic). Ids the engine does not know are left out. */
+interface TemplateGroup {
+    id: string;
+    /** Name by locale (`en`, `pt-BR`); the id when absent. */
+    name?: Record<string, string>;
+    templates: readonly string[];
+}
+/** A small house the area lays out for the structural scenarios: the structure spec of a template, drawn as boxes named by part (the team's HouseArea items). */
+interface SpecimenDef {
+    /** Item id (`house_casa_portico`): the scenarios and the golden name them. */
+    id: string;
+    template: string;
+    seed?: number;
+    state?: string;
+    /** The bearing walls only close: a frame of pillars and beams carries the building. */
+    portico?: boolean;
+    /** Name by locale; the text of the area when absent. */
+    name?: Record<string, string>;
+}
+interface FloorplanTestOptions {
+    locale?: string;
+    /** The engine with the packs registered. Without it the module has no houses to build. */
+    engine?: FloorplanEngineLike;
+    /** The packs the bench lists, in order. Default: every template of the engine in one group. */
+    groups?: readonly TemplateGroup[];
+    /** The states the bench offers (`normal`, `fortified`, `abandoned`). Default: the engine's. */
+    states?: readonly string[];
+    /** The room's destruction world and renderer (`room.world`, `room.renderer`): the houses built here register in them, so every shot, blast and fire of the room reaches the walls. */
+    world?: any;
+    renderer?: any;
+    /** Passed to the house renderer: `fleet`, `reflector`, `interactives`, `vegetation`, `props`, `textures`... */
+    house?: Partial<HouseRendererOptions>;
+    /** Template and seed the bench starts with. */
+    template?: string;
+    seed?: number;
+    /** Specimens of the structural scenarios; default the five of the team's house area, those whose template the engine has. */
+    specimens?: readonly SpecimenDef[];
+    /** Half size of the room's arena (`createTestRoom({ arenaSize })`), 14 by default: where the houses are laid. */
+    arenaSize?: number;
+    /** Where the specimens stand for the scenarios (the team's page: `[-5, 0, -11]`). */
+    specimenAt?: readonly [number, number, number];
+}
+
+declare const FLOORPLAN_AREA_ID = "floorplan_area";
+type Placed = {
+    house: any;
+    plan: any;
+    seed: number;
+    width: number;
+    depth: number;
+};
+/**
+ * The houses test area as a `TestableModule`: any typology of the content packs the page registered (residential, commercial, rural, post-apocalyptic) built with game-floorplan-three from a seed, laid
+ * in the room, with the player able to walk in (walls and closed doors stop the walk), use the doors (E), go up and down the floors, see the level of detail (manual, by distance, or shared among a row
+ * of houses by a draw-call budget), and hit the walls with what the room throws (its tools, or the bench's hit): the houses register in the room's destruction world, so shots, blows, blasts and fire
+ * reach the structure and the room's renderer draws the fracture, the brick courses and the collapse. Dust and sparks are the room's own effects: this module draws no particles.
+ * Everything that is a pack of content comes in by option: this package knows no game.
+ */
+declare function createFloorplanTestModule(options?: FloorplanTestOptions): TestableModule<AreaContext> & {
+    readonly houses: readonly Placed[];
+    build(): void;
+    clear(): void;
+    groups(): readonly TemplateGroup[];
+};
+
+/**
+ * The five items of the team's house area (sala-de-testes/area-casas): a frame house, a whole house, a wood-frame house, a log cabin and a tent. The team's frame house is its single-storey house A; here it is the
+ * two-storey townhouse, because the ceiling slab of the single-storey plan keeps standing on its bearing partitions when two pillars go (see evidence, T2.6).
+ */
+declare const DEFAULT_SPECIMENS: readonly SpecimenDef[];
+/** What the area keeps of a built specimen: the structure spec the house draws (what the destruction world is given) and the plan it came from. */
+interface SpecimenSpec {
+    readonly spec: any;
+    readonly plan: any;
+}
+/**
+ * The structure spec of a specimen: the engine draws the plan, the house renderer draws the house, and the house describes its structure (`house.structure.spec`) with what the water tank holds and
+ * what makes the gas bottle explode. The spec is cached per three.js namespace and specimen; each call hands out a copy.
+ */
+declare function specimenSpec(THREE: any, engine: FloorplanEngineLike, def: SpecimenDef, houseOptions?: Partial<HouseRendererOptions>): SpecimenSpec;
+/**
+ * One box (or cylinder, sphere) per part, named by the part id and coloured by its material, in the space of the house (the origin at the corner of the plan): what the team's house area draws, so the
+ * room binds each mesh to the part of the same name. The anchored terrain slab is left out (the room has a floor).
+ */
+declare function buildSpecimenMeshes(THREE: any, spec: any): any;
+
+export { type AreaContext, type BuildOptions, DEFAULT_SPECIMENS, type Damageable, type DestructibleHouse, FLOORPLAN_AREA_ID, type FloorNavigator, type FloorplanEngineLike, type FloorplanTestOptions, type House, type HouseRenderer, type HouseRendererOptions, type Messages, type NavFlight, type NavFloor, type NavHouse, type NavHouseDef, type NavRect, type NavResult, type NavShape, type NavStair, type NavigableHouse, type NavigationDefOptions, type NavigatorBinding, OPEN_ROOM_TYPES, SPECIMEN_AT, type SpecimenDef, type TemplateGroup, type Translate, VERSION, bindNavigator, buildSpecimenMeshes, create, createFloorNavigator, createFloorplanTestModule, create as createHouseRenderer, createHouseScenarios, createTranslator, en, isOpenArea, locales, navigationDefOf, planLod, ptBR, rectsOf, specimenSpec };