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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Fernandes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION.md

@@ -0,0 +1,118 @@
+# Migration: Casa3DSDK and AndaresSDK (Visor de casas 3D) to `@adatechnology/game-floorplan-three`
+
+The port is literal: the geometry, the draws and the seeded random of `Casa3DSDK.construir` are the team's. Only names changed (English API, texts in `locales`), and
+what the page injected through globals is now an option. The scene equals the page's, node by node, for six plans (`tests/golden-scene.test.ts`, which maps the new ids to the
+legacy ones through `seedKey`), and the level of detail planner gives the same levels in 25 situations.
+
+## Entry point
+
+| Visor de casas 3D | SDK |
+|---|---|
+| `Casa3DSDK.criar(THREE, cfg)` | `create(THREE, options)` (alias `createHouseRenderer`) |
+| `sdk.construir(res, opts)` | `renderer.build(plan, options)` |
+| `sdk.novoEstado()` | `renderer.newState()` |
+| `sdk.tipos`, `sdk.mv` | `renderer.types` (type to `{ f, source }`), `renderer.mv` (the props module) |
+| `sdk.aplicaParte(grupo, t)` | `renderer.applyPart(group, t)` |
+| `sdk.materiais`, `sdk.mascaraLuz`, `sdk.iluminacao` | `renderer.materials`, `renderer.roomLightMask`, `renderer.lighting` |
+| `sdk.definirNoite(n)` | `renderer.setNight(night)` |
+| `sdk.carros.{modelo,grupo,info}` | `renderer.cars.{model,group,info}` (`info` returns `{ parts, tris, L, W, H }`) |
+| `Casa3DSDK.planejaLOD(casas, foco, orcamento)` | `planLod(houses, focus, budget)` returns `{ total, levels, houses }` |
+
+## Options (`cfg` of `criar`)
+
+| VC3 | SDK |
+|---|---|
+| `document` | `document` |
+| `qualidade` `'alta'` / `'jogo'` | `quality` `'high'` / `'game'` |
+| `Moveis3DSDK` | `props` (default: `@adatechnology/game-props3d`) |
+| `Reflector` | `reflector` |
+| `frota` | `fleet` |
+| (fixed lists of car models per lot style) | `carKinds` (`budget`, `mid`, `high`; ids of `game-vehicles-fleet`) |
+| `hp` | `hp` |
+| `texturas`, `atlas`, `materiais` | `textures`, `atlas`, `materials` |
+| `destruicao` (world) | `destruction` (world of `game-destruction`) |
+| (the page's own fragment drawing) | `destructionRenderer` (`game-destruction-three`) draws fracture, fragments, spalls and the rebar cage |
+| `interativos` | `interactives` |
+| `vegetacao` | `vegetation` |
+| `lod` `{ interior, ocultar }` | `lod` `{ interior, hide }`, or `false` |
+| `orcamentoDrawCalls` | `drawCallBudget` |
+| `onMudou`, `onColisor`, `onDano`, `onEstrago`, `onInteragir`, `onLuz`, `onMensagem` | `onChange`, `onCollider`, `onDamage`, `onWreck`, `onInteract`, `onLight`, `onMessage` |
+| (ids of the page's plan feed the seeded random) | `seedKey(id)` |
+| (texts in Portuguese in the code) | `locale` (`'en'`, `'pt-BR'` or a table) |
+
+## Build options (`opts` of `construir`)
+
+| VC3 | SDK |
+|---|---|
+| `qualidade` | `quality` |
+| `noite` | `night` |
+| `corte` | `cut` |
+| `estado` | `state` |
+| `terreno: false` | `terrain: false` |
+| `semPerimetro` | `noPerimeter` |
+| `pecas: 'malhas'` | `pieces: 'meshes'` |
+| `predio` `{ andares, andar, unidade, mostrarPredio }` | `building` `{ floors, floor, unit, showBuilding }` |
+| `orcamentoDrawCalls` | `drawCallBudget` |
+
+## The house (result of `construir`)
+
+| VC3 | SDK | VC3 | SDK |
+|---|---|---|---|
+| `versao` | `version` | `grupo` | `group` |
+| `casa` | `house` | `grupos` | `groups` (`f0`, `f1`, `t1`, `roof`, `lot`...) |
+| `andares` | `floors` | `forros` | `ceilings` |
+| `telhado` | `roof` | `lote` | `lot` |
+| `chao` | `ground` | `predio` | `building` |
+| `caixaDagua` `{ parte, grupo, pos, planta }` | `waterTank` `{ part, group, pos, plant }` | `colisores` | `colliders` |
+| `partes` | `parts` | `carros` | `cars` |
+| `interagiveis` | `interactables` | `portas` | `doors` |
+| `escadas` | `stairs` | `rotulos` | `labels` |
+| `semModelo` | `noModel` | `luzes` `{ lista, porComodo }` | `lights` `{ list, byRoom }` |
+| `limites` | `limits` | `apt` | `apartment` |
+| `mostraPredio` | `showBuilding` | `predioCfg` `{ andares, andar, unidade }` | `buildingConfig` `{ floors, floor, unit }` |
+| `unidadeRy` | `unitRy` | `noite`, `corte` | `night`, `cut` |
+| `interativos` | `interactives` | `estado` | `state` |
+| `vegetacao`, `solar`, `agua`, `eletrica`, `calhas` | `vegetation`, `solar`, `water`, `electrical`, `gutters` | `estrutura` | `structure` |
+| `destruicao` | `destruction` | `interno` | `internal` |
+
+Methods: `atualiza(dt, tempo, foco)` is `update(dt, time, focus)`; `mostra({ andar, corte, lote })` is `show({ floor, cut, lot })`; `alvo` is `target`; `interage` is `interact`;
+`mensagem` is `message`; `alternaPorta` is `toggleDoor`; `luzLigada` is `lightOn`; `alternaLuz` is `toggleLight`; `colide` is `collide`; `comodoEm` is `roomAt`;
+`escolheEspelho` is `chooseMirror`; `definirLOD` is `setLod`; `centro` is `center`; `distancia` is `distance`; `dano` is `damage`; `danoColisor` is `colliderDamage`;
+`parteDe(obj)` is `partOf(object)`; `parteEm(p, tol)` is `partAt(point, tolerance)`; `descartar` is `dispose`.
+
+A door of `house.doors`: `{ id, andar, tipo ('aco' or 'giro'), aberta, t, bloq, trancada, macNomes, hT, cx, cz, visH, grupos, col }` is `{ id, floor, type ('steel' or 'swing'), open, t, blockedFlag, locked, handleNames, hT, cx, cz, visH, groups, col }`.
+
+## Names of parts, groups and lights
+
+| VC3 | SDK | VC3 | SDK |
+|---|---|---|---|
+| `porta:<id>` | `door:<id>` | `janela:<id>` | `window:<id>` |
+| `espelho:<n>` | `mirror:<n>` | `carro:<n>:<zone>:<n>` | `car:<n>:<zone>:<n>` |
+| `torn_<seed>_<n>` (tap) | `tap_<seed>_<n>` | `chuv_<seed>` (shower) | `shower_<seed>` |
+| `correio_<seed>` | `mailbox_<seed>` | `roupas_<seed>` | `laundry_<seed>` |
+| `botijao_<seed>` | `gas_cylinder_<seed>` | `caixa_<seed>` | `tank_<seed>` |
+| `tabuas:<id>` | `boards:<id>` | `disjuntor_<n>` | `breaker_<n>` |
+| light type `externa` | `outdoor` | `ix:`, `lamp_`, `lp_`, `sw_`, `lamp_ab_`, `lamp_ar_`, `lamp_ext_`, `lamp_pe_` | the same (they feed the seeded random) |
+| mesh groups `chapisco`, `reboco`, `calcada`, `madeira`, `vidro`, `telha`, `liso`, `lote/...` | `roughcast`, `plaster`, `sidewalk`, `wood`, `glass`, `tile`, `plain`, `lot/...` | `fonte` of a type (`moveis3d`, `jogo`) | `source` (`props3d`, `game`) |
+
+The salts of the seeded random (`'|varal'`, `'|luz'`, `'|temp'`, `'|veg'`...) are kept as the team wrote them: changing one changes the scene.
+
+## Messages
+
+All the texts the house shows are in `locales` (`en`, `pt-BR`): `prompt.*` (E: abrir a porta...), `what.*`, `message.*`, `outbuilding.*`, `warn.interactablesIncomplete`.
+
+## AndaresSDK
+
+| AndaresSDK | SDK |
+|---|---|
+| `AndaresSDK.criar()` | `createFloorNavigator()` |
+| `registra({ id, andares: [{ y, h, solidos }], escadas, grupos, telhado, proprio })` | `register({ id, floors: [{ y, h, solids }], stairs, groups, roof, own })` |
+| `casaEm`, `bloqueio(x, z, andar)`, `nivel`, `ponta`, `escadaPara`, `rumo`, `raio`, `tetoDe`, `oclui`, `cel` | `houseAt`, `blocked`, `level`, `landing`, `stairTo`, `heading`, `ray`, `ceilingOf`, `occlude`, `cell` |
+| `aplica(casa, andar)` (internal) | `apply(house, floor)` |
+| (new, T2.4d) | `openCells`, `closeCells`, `undoChanges`, `houseOf` |
+| (new, T2.4d) | `navigationDefOf(house, options)`: the registration of a built house; `bindNavigator(navigator, id, house)`: follows the destruction |
+
+## What is not here
+
+- `AdaptadorInterativos` (plan to objects of the interactables kit) is game code by its own header. The `interactives` option takes the adapter from the game.
+- The globals of the page (`Moveis3DSDK`, `FrotaLeve`, `Reflector`...) are options now.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# @adatechnology/game-floorplan-three
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The three.js renderer of `@adatechnology/game-floorplan`: it draws a generated plan as a house (walls, doors, windows, floors, slabs, stairs, roofs, gutters, lot,
+furniture, lights, mirrors, cars, utilities) and binds it to the destruction of its structure. It is the port of the team's `Casa3DSDK` (Visor de casas 3D) and
+`AndaresSDK` (floor navigator), literally: same geometry, same draws, same seeded random, so a plan looks the same as on the team's page
+(`tests/golden-scene.test.ts` compares the scene node by node with the page's, for six plans).
+
+```ts
+import * as THREE from 'three'
+import { engine } from '@adatechnology/game-floorplan'
+import { register as residential } from '@adatechnology/game-floorplan-residential'
+import { register as structure } from '@adatechnology/game-floorplan-structure'
+import { createDestruction } from '@adatechnology/game-destruction'
+import { createDestructionRenderer } from '@adatechnology/game-destruction-three'
+import { create } from '@adatechnology/game-floorplan-three'
+
+residential(engine, { region: 'br' })
+structure(engine)
+const plan = engine.generate('townhouse', { seed: 7, state: 'normal' })
+
+const world = createDestruction({ seed: 1 })
+const scene = new THREE.Scene()
+const renderer = create(THREE, {
+  destruction: world,
+  destructionRenderer: createDestructionRenderer(THREE, { scene, world }),
+  fleet, // optional: { build(kind, { quality, seed }) } of game-vehicles-fleet
+  locale: 'en', // or 'pt-BR', or a table of messages
+})
+const house = renderer.build(plan, { quality: 'high', night: false })
+scene.add(house.group)
+
+// every frame
+house.update(dt, performance.now(), camera.position) // doors, laundry, wind, distance LOD
+```
+
+## What it draws
+
+| Part | Where |
+|---|---|
+| walls, doors, windows, floors, slabs, stairs, baseboards, outbuildings, building shell | `house.floors[i]` (one group per floor), `house.doors`, `house.stairs` |
+| lot: ground, street, sidewalk, lot wall, gates, zones, fence | `house.lot` |
+| roof, tiles, gutters | `house.roof`, `house.gutters` |
+| furniture (`game-props3d` plus the house's own builders) | in the floor groups, merged by material; `renderer.types` is the map |
+| lamps, switches, room lights | `house.lights`, `house.toggleLight(room)` |
+| mirrors (the nearest one reflects when the camera is in its room) | `house.chooseMirror(camera)` |
+| cars (needs a `fleet`) | `house.cars`, `renderer.cars` |
+| solar panels, water, electrical, pipes | `house.solar`, `house.water`, `house.electrical` |
+
+`house.group` is the root. Everything is merged to one mesh per group and material (a draw call each); only what moves stays apart.
+
+## 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
+(`house.destruction.activate()`, or the first hit through `house.damage`):
+
+- **One part per wall**, with the assembly of its masonry (units, breach, layers) and **the rebar of reinforced concrete on slabs, beams, pillars and stairs**.
+- **A vertex range per piece.** Every wall, slab, window, door... knows its range in the merged mesh (`house.structure.meshesOf(id)`); the renderer's `bind` gets them,
+  so fracture and collapse hide the range and the renderer lets the fragments fall. `house.destruction.reset()` puts everything back.
+- **Brick courses at LOD 0.** A masonry wall that reaches stage 2 stops being a box: its range collapses and it is drawn again as instanced units (running bond,
+  one instance per unit) without the ones inside the opening; the units around the edge show the bare brick. At LOD 1 and 2 the box comes back.
+- **Spall decal and rebar cage** come from the destruction renderer (decals on hits, instanced bars when the concrete is exposed).
+- `house.damage(id, point, type, amount)` keeps the legacy behaviour (hp of the part, `onDamage`) and becomes a hit in the world.
+
+## Floor navigator
+
+`createFloorNavigator()` is the team's AndaresSDK: a 10 cm grid per floor, stairs with banisters and U-turns, path fields, occlusion of the floors above.
+
+```ts
+import { createFloorNavigator, navigationDefOf, bindNavigator } from '@adatechnology/game-floorplan-three'
+
+const navigator = createFloorNavigator()
+navigator.register(navigationDefOf(house, { id: 'home', own: true })) // heights, wall colliders, flights, floor groups
+const binding = bindNavigator(navigator, 'home', house) // wall stage 2 opens cells; a wall or slab that falls changes the grid
+navigator.blocked(x, z, floor) // 1 blocked, 0 free, -1 use the ground grid
+```
+
+## Injected, never read from globals
+
+| Option | What |
+|---|---|
+| `fleet` | cars (`game-vehicles-fleet`) |
+| `reflector` | `THREE.Reflector` for the mirrors |
+| `props` | `game-props3d` (default: the package's dependency) |
+| `interactives` | `{ GameInteractables, GameInteractablesHousehold, GameInteractablesThree, adapter }`: the interactable kit in place of the static furniture. The adapter (plan to kit objects) is game code, not part of this package. |
+| `vegetation` | `{ GameVegetation: { ...core, ...three }, GameVegetationSpecies }` |
+| `textures`, `atlas`, `materials` | the app's replacements |
+| `seedKey` | maps an id of the plan to the key its seeded draws use (to reproduce a scene drawn with other ids) |
+
+Everything the house says to the player (prompts, messages) is in `locales` (`en`, `pt-BR`).
+
+## 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`).
+
+See `.claude/skills/game-floorplan-three/SKILL.md` for the API and `MIGRATION.md` for the Portuguese names the Visor de casas 3D used.
+
+## Em português
+
+Desenho em three.js das plantas do `game-floorplan`: porte literal do `Casa3DSDK` (Visor de casas 3D) e do `AndaresSDK` (navegação por andares). Paredes, portas, janelas,
+pisos, lajes, escadas, telhado, calhas, lote, móveis, luzes, espelhos e carros; cada peça sabe a faixa de vértices que ocupa na malha fundida para a destruição
+(fratura, colapso, fileiras de tijolo no LOD 0, decalque de lascamento e armadura aparente). Os pacotes (frota, interativos, vegetação, espelho) são injetados. Os
+textos vêm de `locales` (`en`, `pt-BR`).