@adatechnology/game-urban-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/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @adatechnology/game-urban-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.
+Draws the scenes of `@adatechnology/game-urban` with three.js, the way the team's Galeria do Vale Cinzento does.
+
+```ts
+import * as THREE from 'three'
+import { createUrban } from '@adatechnology/game-urban'
+import { createUrbanThree } from '@adatechnology/game-urban-three'
+
+const urban = createUrban()
+const b = urban.builder({ seed: 7 })
+urban.streets.grid(b, { block: 36, count: 2, width: 10 })
+urban.poles.get('led_double').build(b, { x: 18, z: 5 })
+
+const three = createUrbanThree(THREE, { document })   // `document` only for signs and labels
+const drawn = three.draw(b.scene())
+scene.add(drawn.root)
+// each frame: drawn.animate(elapsedSeconds)            // flickering lamps, sweeping searchlights
+// when done:  drawn.dispose()
+```
+
+- Each part becomes a mesh in the order it was added: boxes with the team's rounded edge (a 4x4x4 grid per face, edge vertices on an arc), tapered cylinders, flat-shaded cones and prisms, planes that only receive shadows, crowns that only cast, canvas signs and labels.
+- The small boxes (road dashes, sandbags) are one instanced mesh, and the windows two (lit ones glow, dark ones are a dark pane). The instance matrices are the page's.
+- Lights are real `PointLight` and `SpotLight` objects; `drawn.lights` lists them. `animate(t)` flickers the failing lamps (`I * (sin(23t + x) > 0.3 || sin(3.1t) > 0.85 ? 0.15 : 1)`) and moves each searchlight target around its tower.
+- A `terrain` part becomes the square mesh with vertex colours (flat shaded, roughness 1, casts and receives shadows); the water is a plane part drawn after it.
+- A `placement` part (a vehicle of the fleet, a species of the pack) becomes a group at the spot, turned and scaled, holding the object a resolver made: `createUrbanThree(THREE, { resolvers: { vehicle: createVehicleResolver(vehiclesThree), plant: createPlantResolver(THREE) } })`. The vehicle resolver uses the `lite` build of `game-vehicles-three` (six fused meshes) and the plant resolver `generate` and `createPlantObject` of `game-vegetation`; each is built once for an id and paint (or seed) and cloned for every spot, sharing geometry and materials. An id the package does not know leaves the spot empty. `resolver.dispose()` frees them.
+- `draw(scene, { root })` draws into a group of yours. Works on three r128 and later.
+
+The scene hash, the lists of instances and the surface of each material (shadows, roughness, metalness, flat shading) of 34 cases are tested against the page.
+
+## Test area
+
+`createUrbanTestModule(options)` and `loadUrbanTestModule(room, options)` put the city in the shared test room (`?area=urban` in `examples/urban-test-area`; the module also loads in `examples/interactables-test-area`).
+
+- Items (17): the five poles of the kit in a row, a street grid with a filled block, a patch of terrain (a rolling plain with a river and a lake; `terrain` replaces it) and the ten neighbourhoods of the sample sheet in the Galeria's cells. Everything is drawn by the kit and this package, so a game that passes `urban: { packs, patch, remove }` sees its own catalogues in the area. Each item is scenery: one anchored slab of concrete as large as the sample.
+- Bench: the neighbourhood, the seed, the share of lamps on (the pattern's own, all, half, none), the budget of real lights and, when asked, the species of the region and the vehicles of the fleet (a game gives `vehicles: (THREE) => createVehiclesThree(...)`; without it the bench parks no cars). Actions draw and take away the neighbourhood in front of the player; changing a setting draws it again.
+- Layers: the reach of every real light and the box of each sample. Metrics: samples, draw calls, triangles, real lights, instances, objects of the bench and the light budget left.
+- Eight scenarios, with no object of the room: pole heights, the light budget (the counter goes below zero as the page's), the dash every 5 m, block heights, the seed, burnt-out lamps, the terrain (vertex height, river bed, lake level) and the providers (vehicles of the fleet, species of the region).
+- The room's camera sees 140 m and the sample sheet is 240 m wide, so the module lends the camera a 600 m view while it is loaded and gives the old one back when it detaches.

package/dist/index.d.ts

@@ -0,0 +1,170 @@
+import { PlacementPart, UrbanScene, UrbanOptions, TerrainOptions } from '@adatechnology/game-urban';
+import { Lod, Condition, Season } from '@adatechnology/game-vegetation';
+import { createVegetationMaterials } from '@adatechnology/game-vegetation/three';
+import { BuildVehicleOptions } from '@adatechnology/game-vehicles-three';
+import { TestableModule, ModuleScenario } from '@adatechnology/game-contracts';
+
+type Three$3 = any;
+/** What `document.createElement('canvas')` needs; a fake works in Node. */
+type CanvasFactory = {
+    createElement(tag: string): any;
+};
+type TextTextureOptions = {
+    width: number;
+    height: number;
+    background: string;
+    foreground: string;
+    font: string;
+};
+/** Canvas texture with centred lines of text, shrunk to fit 92 % of the width, on a filled background. */
+declare function createTextTexture(THREE: Three$3, document: CanvasFactory, lines: readonly string[], o: TextTextureOptions): any;
+
+type Three$2 = any;
+/** Makes the object of a placement; null when it cannot (an unknown id). The drawer clones it for each spot. */
+type PlacementResolver = ((part: PlacementPart) => any | null) & {
+    dispose?: () => void;
+};
+type VehicleResolverOptions = {
+    /** `lite` fuses a vehicle into six meshes, the right cost for a street of parked cars. Default `lite`. */
+    quality?: BuildVehicleOptions['quality'];
+};
+/** What the vehicle resolver needs of `createVehiclesThree`. */
+type VehicleBuilder = {
+    build(key: string, options?: BuildVehicleOptions): {
+        group: any;
+        dispose(): void;
+    };
+};
+/**
+ * Resolves vehicle placements with the vehicles of `game-vehicles-three`. A vehicle is built once for each id and paint and cloned
+ * (clones share geometry and materials) for each spot.
+ */
+declare function createVehicleResolver(vehicles: VehicleBuilder, options?: VehicleResolverOptions): PlacementResolver;
+type PlantResolverOptions = {
+    /** Level of detail of the plants of a street. Default 1. */
+    lod?: Lod;
+    condition?: Condition;
+    season?: Season;
+    /** Materials of the plants (wind included); default new ones. */
+    materials?: ReturnType<typeof createVegetationMaterials>;
+};
+/** Resolves plant placements with the species of `game-vegetation-species`, built with `game-vegetation`. One plant for each species and seed, cloned for each spot. */
+declare function createPlantResolver(THREE: Three$2, options?: PlantResolverOptions): PlacementResolver;
+
+type Three$1 = any;
+type UrbanThreeOptions = {
+    /** Where canvases come from (the page's `document`). Needed only for signs and labels. */
+    document?: CanvasFactory;
+    /** Who makes the objects of the vehicles and plants a scene places. A kind without a resolver is left empty. */
+    resolvers?: {
+        vehicle?: PlacementResolver;
+        plant?: PlacementResolver;
+    };
+};
+/** What a drawn scene gives back: the group to add to a scene, the per-frame animation and the cleanup. */
+type DrawnUrban = {
+    root: any;
+    /** Moves the animated parts to time `t` (seconds): flickering lamps and sweeping searchlights. */
+    animate(t: number): void;
+    /** Lights drawn, for a budget meter. */
+    readonly lights: any[];
+    dispose(): void;
+};
+type DrawOptions = {
+    /** Group the parts go into. Default a new `THREE.Group`. */
+    root?: any;
+};
+/**
+ * Draws urban scenes with three.js the way the team's page does: a mesh per part in the order they were added (boxes with the
+ * rounded edge, cylinders, flat-shaded cones and prisms, planes that only receive shadows, canvas signs), then one instanced mesh for
+ * the small boxes and one for each kind of window. Materials are shared by colour. The instance matrices are the page's.
+ */
+declare function createUrbanThree(THREE: Three$1, options?: UrbanThreeOptions): {
+    THREE: any;
+    draw: (scene: UrbanScene, drawOptions?: DrawOptions) => DrawnUrban;
+};
+type UrbanThree = ReturnType<typeof createUrbanThree>;
+
+type Three = any;
+/** The team's rounded box: a 4x4x4 grid per face with the edge vertices pushed onto an arc of the given radius (smooth normals). A radius of 0 is a plain box. */
+declare function createRoundedBox(THREE: Three, width: number, height: number, depth: number, radius: number): any;
+/** Triangle prism: the triangle `width` wide and `height` high, extruded `depth` long and centred on z. Base at y = 0. */
+declare function createPrism(THREE: Three, width: number, height: number, depth: number): any;
+
+type UrbanTestOptions = {
+    /** `en` or `pt-BR` (default). The room asks `items(locale)` and `scenarios(locale)` itself; this is the language of the bench and of the signs of the neighbourhoods. */
+    readonly locale?: string;
+    /** Seed of the fixed samples of the area (default 7, the Galeria's). */
+    readonly seed?: number;
+    /** Options of the urban kit the area draws with (packs, patches, removals): a game's own catalogues show up in the area. */
+    readonly urban?: UrbanOptions;
+    /** The terrain of the terrain patch (default a small rolling plain with a river and a lake). */
+    readonly terrain?: TerrainOptions;
+    /** Where canvases come from for the signs; default the page's `document`. */
+    readonly document?: CanvasFactory;
+    /** Builds the vehicles of the fleet for the `vehicle` provider of the bench (`createVehiclesThree` of `game-vehicles-three`). Without it the bench parks no cars. */
+    readonly vehicles?: (THREE: unknown) => VehicleBuilder;
+    /** Where the bench draws its neighbourhood in the room, `[x, z]` (default `[0, -60]`). */
+    readonly benchOrigin?: readonly [number, number];
+};
+/** What a scenario needs of the room: the pass/fail line and time. The checks of this area are on the kit's own numbers, so no object of the room is touched. */
+type UrbanContext = {
+    expect(condition: boolean, label: string, data?: Record<string, unknown>): void;
+    step(seconds: number): void;
+};
+
+declare const URBAN_AREA_ID = "urban";
+/** The default terrain patch of the area: a rolling plain 96 m wide with a river across it and a round lake. A game passes its own through `terrain`. */
+declare const DEFAULT_TEST_TERRAIN: TerrainOptions;
+/**
+ * The urban test area as a `TestableModule`: the five poles of the Galeria in a row, a street grid with a filled block, a patch of terrain and the ten neighbourhoods of the
+ * sample sheet in its cells, each drawn by the kit and `game-urban-three` (so a game that patches the catalogues sees its own). The bench draws any neighbourhood in front of the player with
+ * a seed, a share of lamps on, a light budget and, when asked, the vehicles of the fleet and the species of the region; its layers show the reach of the real lights and the box of each sample.
+ */
+declare function createUrbanTestModule(options?: UrbanTestOptions): TestableModule<UrbanContext> & {
+    readonly placed: ReadonlyMap<string, unknown>;
+    tick(t: number): void;
+    readonly itemIds: readonly string[];
+};
+/** What `loadUrbanTestModule` needs of a room: `TestRoom.loadModule` has it. */
+type ModuleRoomLike = {
+    loadModule(module: never): unknown;
+};
+/** Loads the urban module into a room. */
+declare function loadUrbanTestModule<Room extends ModuleRoomLike>(room: Room, options?: UrbanTestOptions): ReturnType<Room['loadModule']>;
+
+/** Words and sentences of the urban area, by locale. `{0}`, `{1}`... are filled in order. */
+type UrbanText = {
+    group: string;
+    name: string;
+    items: Record<string, string>;
+    controls: Record<'pattern' | 'seed' | 'lamps' | 'budget' | 'providers', string>;
+    hints: Record<'pattern' | 'seed' | 'lamps' | 'budget' | 'providers', string>;
+    options: {
+        lamps: Record<string, string>;
+        providers: Record<string, string>;
+    };
+    actions: Record<'compose' | 'clear', string>;
+    layers: Record<'light_radius' | 'bounds', string>;
+    metrics: Record<'samples' | 'draw_calls' | 'triangles' | 'real_lights' | 'instances' | 'bench_objects' | 'light_budget_left', string>;
+    log: Record<'composed' | 'cleared' | 'no_vehicles', string>;
+    scenarios: Record<string, string>;
+    checks: Record<string, string>;
+};
+declare const TEXT: Record<string, UrbanText>;
+
+/** The heights of the five poles of the Galeria (m), the tops measured on the page's scenes. A game's own poles are not checked. */
+declare const POLE_TOPS: Readonly<Record<string, number>>;
+type ScenarioDeps = {
+    readonly text: UrbanText;
+    readonly urban: UrbanOptions | undefined;
+    readonly terrain: TerrainOptions;
+};
+/**
+ * The scenarios of the urban area: checks on the numbers the kit promises (the poles' heights, the light budget, the dashes of a road,
+ * the heights of a block, the determinism of a neighbourhood, burnt-out lamps, the terrain, the providers). They need no object of the
+ * room, so a game that patches the catalogues sees at once what it changed.
+ */
+declare const createScenarios: (deps: ScenarioDeps) => ModuleScenario<UrbanContext>[];
+
+export { type CanvasFactory, DEFAULT_TEST_TERRAIN, type DrawOptions, type DrawnUrban, type ModuleRoomLike, POLE_TOPS, type PlacementResolver, type PlantResolverOptions, TEXT, type TextTextureOptions, URBAN_AREA_ID, type UrbanContext, type UrbanTestOptions, type UrbanText, type UrbanThree, type UrbanThreeOptions, type VehicleBuilder, type VehicleResolverOptions, createPlantResolver, createPrism, createRoundedBox, createScenarios, createTextTexture, createUrbanTestModule, createUrbanThree, createVehicleResolver, loadUrbanTestModule };