@adatechnology/game-floorplan-three 0.2.0 → 0.3.0

package/README.md

@@ -48,6 +48,23 @@ house.update(dt, performance.now(), camera.position) // doors, laundry, wind, di
 
 `house.group` is the root. Everything is merged to one mesh per group and material (a draw call each); only what moves stays apart.
 
+## Furniture as a destructible spec
+
+`furnitureSpec(THREE, type, { w?, d?, h?, seed?, options? })` runs the team's builder of `type` (`bookcase`, `shelf_unit`, `dining_table`, `coffee_table`... the keys of `renderer.types`) unchanged, with a recording stand-in for the drawing api, and returns `{ spec, build(THREE), top, size }`: one part per drawn box or cylinder (`wood_0`, `plain_17`: builder material key and drawing order), with the colour the builder gave it. Sizes default to the catalogue entry (`residentialItems`; `catalog` overrides it), `seed` drives the builder's random (the books), so the same seed gives the same piece.
+
+```ts
+import { furnitureSpec } from '@adatechnology/game-floorplan-three'
+const shelf = furnitureSpec(THREE, 'bookcase') // 1.2 x 0.35 x 2 m: uprights, back, boards and books
+world.add(shelf.spec, { id: 'shelf', position: [-3.5, 0, 0] })
+scene.add(shelf.build(THREE)) // meshes named by part id
+const table = furnitureSpec(THREE, 'dining_table', { w: 1.6, d: 0.8, h: 0.78, options: { chairs: false } })
+table.top // { part: 'wood_0', y: 0.78 }: what loose things rest on
+```
+
+`tapSpec(THREE, { kind: 'counter' | 'wall', reach? })` does the same for the team's tap (`counterTap` of the sink, `wallTap` of the laundry tub): the steel parts of the base, column, spout and lever, and `spout`, where the water thread starts (the thread itself is not drawn).
+
+Materials: `wood` is `wood_hard` (`wood_soft` under 3.5 cm: boards, panels), `metal` is `steel`, `plain` is `plastic` (`paper` on shelves and racks: the books), `fabric`, `glass` and `plant` keep their name; `options.materials` overrides any key. Parts that touch the floor are anchored. Joints come from `inferJoints` (screws between wood...), except that paper rests on what it lies on with a weak `resting` joint, so books fall when their board breaks, and is not joined to its neighbours. `options.chairs: false` drops what the builder draws in a frame of its own (a table's chairs). Planes and leaves have no volume and are left out.
+
 ## Bound to the destruction
 
 With `destruction` (a world of `game-destruction`) and `destructionRenderer` (`game-destruction-three`), the house registers itself in the world on first need
@@ -88,6 +105,14 @@ navigator.blocked(x, z, floor) // 1 blocked, 0 free, -1 use the ground grid
 
 Everything the house says to the player (prompts, messages) is in `locales` (`en`, `pt-BR`).
 
+## Geometry
+
+The kernel's three is `shapeGeometries(THREE)` of `@adatechnology/game-shapes-three`: the primitive templates the accumulator copies (box,
+cylinders of 12 and 6 sides, the open cone, sphere, plane), the breach units, the fragments, the mirrors and the test area's specimens are made
+by game-shapes, bit-identical to three's (`tests/exact-golden.test.ts`) and cached by parameters across renderers. The accumulator itself (one
+mesh per group and material) keeps its own arithmetic: its transform, normals and world-projected uvs are not three's matrix order, so moving
+it onto the core bake would change bytes (see the T9 design, §7.3).
+
 ## Build
 
 `dist/index.js` (ESM, three.js and the other packages external), `dist/index.d.ts`, and `dist/index.global.js` exposing `GameFloorplanThree` (three.js is the page's own `THREE`).

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ModuleScenario, TestableModule } from '@adatechnology/game-contracts';
+import { ModuleScenario, TestableModule, DestructibleSpec } from '@adatechnology/game-contracts';
 
 /** Texts the house shows to the player (interaction prompts, messages, outbuilding labels), by locale. */
 type Messages = Record<string, string>;
@@ -435,11 +435,13 @@ interface FloorplanEngineLike {
     generate(template: string, options?: {
         seed?: number;
         state?: string;
+        floors?: number;
     }): any;
     listTemplates(): Array<{
         id: string;
         name?: string;
         floors?: number;
+        floorRange?: number[] | null;
     }>;
     listStates(): string[];
     translate?(namespace: any, key: string, locale?: string, vars?: Record<string, string | number>): string;
@@ -460,6 +462,15 @@ interface SpecimenDef {
     state?: string;
     /** The bearing walls only close: a frame of pillars and beams carries the building. */
     portico?: boolean;
+    /**
+     * How the structure is sized (`toDestructibleSpec`): `safety` is the share of its capacity a pillar uses at rest, `redundancy` the most it uses after one other pillar is lost.
+     * A slab on four pillars is held by the sum of the four: with `safety` 0.72 and `redundancy` 0.97 it holds one loss (0.96) and falls with two.
+     */
+    sizing?: {
+        safety?: number;
+        redundancy?: number;
+        safetyOthers?: number;
+    };
     /** Name by locale; the text of the area when absent. */
     name?: Record<string, string>;
 }
@@ -511,7 +522,9 @@ declare function createFloorplanTestModule(options?: FloorplanTestOptions): Test
 
 /**
  * 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).
+ * 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). The frame house is a reinforced concrete frame (T10 §12): the slabs
+ * are cut into panels on real beams, the pillars are sized (`sizing`) to carry the load of the ones lost, and the beams to carry the span the lost pillar leaves: one pillar lost and the slab stays,
+ * the two ends of a side lost and that side comes down (owner, 2026-10-24: "4 pilares e a sustentação é a soma dos 4"; 2026-10-25: the real structure of the houses).
  */
 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. */
@@ -530,4 +543,88 @@ declare function specimenSpec(THREE: any, engine: FloorplanEngineLike, def: Spec
  */
 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 };
+/** What `furnitureSpec` reads of a catalogue entry (the items of `game-floorplan-residential` and the other packs have more). */
+interface FurnitureCatalogEntry {
+    type: string;
+    w: number;
+    d: number;
+    h: number;
+}
+interface FurnitureSpecOptions {
+    /** Size in metres (default: the catalogue entry of the type). */
+    w?: number;
+    d?: number;
+    h?: number;
+    /** Seed of the builder's random (the books of a shelf, the crates): same seed, same piece (default 1). */
+    seed?: number;
+    /** Builder-level choices. */
+    options?: {
+        /** Material of the destruction world per builder material key (`wood`, `metal`, `plain`, `fabric`, `glass`...), overriding the defaults. */
+        materials?: Record<string, string>;
+        /** Keep the chairs a table draws (default true). Chairs are drawn by the builder in a frame of their own, so this drops everything drawn in another frame than the piece's. */
+        chairs?: boolean;
+        /** Colour roles of the builder (`wood`, `fabric_main`, `fabric_accent`, `metal`...) as `0xRRGGBB`. */
+        palette?: Record<string, number>;
+    };
+    /** Catalogue the default size is read from (default `residentialItems`). */
+    catalog?: readonly FurnitureCatalogEntry[];
+    /** The `document` the house renderer makes its textures with (default the global one). */
+    document?: unknown;
+}
+interface FurnitureSpecResult {
+    /** One part per box or cylinder the builder drew, origin at the centre of the footprint on the floor. */
+    spec: DestructibleSpec;
+    /** Draws the piece: one mesh per part, named by the part id, coloured as the builder coloured it. */
+    build(THREE: any): any;
+    /** The widest high horizontal part and the height of its upper face (what loose things rest on), or null when the piece has none. */
+    top: {
+        part: string;
+        y: number;
+    } | null;
+    /** Size the piece was drawn at. */
+    size: {
+        w: number;
+        d: number;
+        h: number;
+    };
+    /** Where the water leaves the taps the builder drew (a sink, a tub), in the space of the spec; empty for furniture without a tap. */
+    spouts: Array<[number, number, number]>;
+}
+/**
+ * The team's furniture as a destructible spec. It runs the builder of `type` (`FURNITURE.shelf` for `bookcase`, `FURNITURE.table` for `dining_table`,
+ * mapped in `furniture/type-table.ts`) unchanged, with a recording stand-in for the drawing api instead of the house's accumulators: every box and
+ * cylinder it draws becomes a part, named `<material key>_<n>` in drawing order (`wood_0`, `plain_17`), with the colour the builder gave it.
+ * Planes and leaves (flat, no volume) and water are left out.
+ *
+ * Materials: `wood` is `wood_hard`, and `wood_soft` for thin boards and panels (under 3.5 cm); `metal` is `steel`; `fabric`, `glass` and `plant` keep
+ * their name; `plain` is `plastic`, or `paper` for shelves and racks (their books and boxes). Parts that touch the floor are anchored. Joints come from
+ * `inferJoints` (screws between wood, welds or bolts between metal...), except that paper rests on what it lies on with a `resting` joint (weak: it falls when
+ * the board breaks) and is not joined to its neighbours.
+ *
+ * @example
+ * const { spec, build, top } = furnitureSpec(THREE, 'bookcase') // 1.2 x 0.35 x 2 m, boards and books
+ */
+declare function furnitureSpec(THREE: any, type: string, opts?: FurnitureSpecOptions): FurnitureSpecResult;
+interface TapSpecOptions {
+    /** `counter` (default): the tap of a sink, standing on the counter; `wall`: the tap of a laundry tub or a garden, with its plate on the wall. */
+    kind?: 'counter' | 'wall';
+    /** How far the counter tap's spout reaches, metres (default 0.2: the kitchen sink's). */
+    reach?: number;
+    /** The `document` the house renderer makes its textures with (default the global one). */
+    document?: unknown;
+}
+interface TapSpecResult {
+    /** The tap as parts (base, column, spout, lever), origin on the counter under the column (`counter`) or on the wall plate's centre line at the floor (`wall`). */
+    spec: DestructibleSpec;
+    /** Draws the tap: one mesh per part, named by the part id. */
+    build(THREE: any): any;
+    /** Where the water leaves the spout, in the space of the spec. */
+    spout: [number, number, number];
+}
+/**
+ * The team's tap (`counterTap` of the sink, `wallTap` of the laundry tub: `furniture/taps.ts`) drawn by the same code into parts, with the lever at rest. `spout` is where its
+ * water thread starts, so a host can put a tap of the fluids world there; the water thread itself is not drawn.
+ */
+declare function tapSpec(THREE: any, opts?: TapSpecOptions): TapSpecResult;
+
+export { type AreaContext, type BuildOptions, DEFAULT_SPECIMENS, type Damageable, type DestructibleHouse, FLOORPLAN_AREA_ID, type FloorNavigator, type FloorplanEngineLike, type FloorplanTestOptions, type FurnitureCatalogEntry, type FurnitureSpecOptions, type FurnitureSpecResult, 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 TapSpecOptions, type TapSpecResult, type TemplateGroup, type Translate, VERSION, bindNavigator, buildSpecimenMeshes, create, createFloorNavigator, createFloorplanTestModule, create as createHouseRenderer, createHouseScenarios, createTranslator, en, furnitureSpec, isOpenArea, locales, navigationDefOf, planLod, ptBR, rectsOf, specimenSpec, tapSpec };