@adatechnology/game-vegetation-three 0.0.0-stage → 0.2.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,40 @@
-# Temporary Holding Version
+# @adatechnology/game-vegetation-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 vegetation test module for the shared test room: the 18 plants of the Viveiro as destructible items, their 13 scenarios and the nursery lot. A literal port of the team's `vegetation-module.js`.
+
+```ts
+import { loadVegetationTestModule } from '@adatechnology/game-vegetation-three'
+
+loadVegetationTestModule(room, { locale: 'en' }) // or room.loadModule(createVegetationTestModule(options))
+room.openArea('vegetation')
+```
+
+Without options the module uses `@adatechnology/game-vegetation` (with its three.js adapter) and `@adatechnology/game-vegetation-species`; a game that brings its own build passes `GameVegetation` and `GameVegetationSpecies`.
+
+## Items
+
+`mango_tree`, `mango_young_15`, `mango_young_30`, `yellow_ipe`, `coconut_palm`, `banana_with_bunch`, `araucaria`, `dead_tree`, `hibiscus_shrub`, `boxwood_hedge`, `rose_bush_red`, `sunflower`, `mandacaru`, `prickly_pear`, `crown_cactus`, `potted_fern`, `potted_cactus`, `lawn_tuft`. Each piece of a plant (trunk, branch, crown, fruit, arm, pad, spines, pot, soil) is one mesh named after the piece, with its destruction spec: the shape from the real thickness of the wood (`radius`, `length` and `axis` that `generate` gives each wood piece), the joints (`stem` between a branch and the trunk, `tie` for leaves, flowers and spines, `resting` for the soil in a pot), the fixed root piece, tags, mass and `fill`, and a `sway` clip for the wind. The young mango trees are the 15 and 30 cm trunks on which the SDK documents the number of axe swings; the terracotta pot has 25 hp, so 1 to 3 shots of 9 mm break it.
+
+## Scenarios
+
+The 13 of the page, with its ids: `veg_axe_fells_crown`, `veg_axe_fells_30cm`, `veg_axe_cuts_branch_joint`, `veg_shot_cannot_fell`, `veg_saw_cuts_branch`, `veg_lighter_ignites_foliage`, `veg_shot_strips_leaves`, `veg_shot_breaks_pot`, `veg_machete_arm`, `veg_pad_pulled`, `veg_dead_burns_faster`, `veg_hedge_cut_pieces`, `veg_walk_on_grass`. The room gives every tool a draw time that the team's page did not know, so each scenario waits for the tool to be ready.
+
+## Bench
+
+- Controls: the seed, quality (high or game), detail (LOD 0 to 2), condition and season of the nursery lot, the wind and the gusts. Actions: plant the lot, remove it, start or stop the walker. Changing a lot control plants the lot again.
+- The nursery is the 12 x 20 m plot of the Viveiro's lot demo (house, walls, street, sidewalk, path), planted by `scatterRulesFor` of `@adatechnology/game-vegetation-species` over the front yard, the backyard, the side strips and the sidewalk tree, and built by `buildLot`. The walker crosses it along `WAY`, stays out of the house and the trunks, and bends the plants through the wind shader's actors.
+- Layers: `colliders` (the trunks and cactus bodies as wire cylinders), `piece_boxes` (the box of every piece) and `wood_axes` (a line along the centreline of each wood piece).
+- Metrics: plants, pieces, triangles and draw calls of the items, and the triangles, plants, colliders, plants by LOD and build time of the lot.
+
+The module draws no particles and asks for no effects: leaves, sap and fire come from the events of the default destruction world, which the room shows.
+
+## Tests
+
+`tests/team-golden-module.test.ts` runs the module of the Viveiro artifact against the kit's room and compares it with this one: the 18 items (names in both languages, meshes, specs, clips) and the 13 scenarios (the same checks and the same count of every log line). `tests/team-golden-nursery.test.ts` cuts `buildLotVeg` from the page and compares the placements, triangles, plants, colliders and species for 8 seeds. `examples/vegetation-test-area` loads the module, and so does `examples/interactables-test-area`.
+
+## Geometry
+
+The nursery's scenery (ground, street, walls, house and roof), its colliders and walker, and the colliders layer are made through
+`shapeGeometries(THREE)` of `@adatechnology/game-shapes-three`: the same bytes as three's constructors
+(`tests/exact-golden.test.ts`), cached by parameters. The plants themselves are `@adatechnology/game-vegetation`'s own buffers (`PlantMesh`,
+with the per-vertex `sway` of the wind), drawn by its adapter.

package/dist/index.d.ts

@@ -0,0 +1,237 @@
+import { Vec3, TestableModule, DestructibleSpec, AnimationClipSpec, TestableItem } from '@adatechnology/game-contracts';
+import * as GameVegetationMain from '@adatechnology/game-vegetation';
+import { Condition, PlantSpec, PlantMesh, Lod, Season, Placement } from '@adatechnology/game-vegetation';
+import * as GameVegetationAdapter from '@adatechnology/game-vegetation/three';
+import * as GameVegetationSpeciesMain from '@adatechnology/game-vegetation-species';
+import { ScatterRulesOptions } from '@adatechnology/game-vegetation-species';
+
+/** The vegetation engine with its three.js adapter, as the `GameVegetation` global of the IIFE build has it. */
+type VegetationSdk = typeof GameVegetationMain & typeof GameVegetationAdapter;
+/** The species pack. */
+type SpeciesSdk = typeof GameVegetationSpeciesMain;
+/** The shared materials of the plants (wind and the actors that bend them). */
+type MaterialsLike = GameVegetationAdapter.VegetationMaterials;
+type VegetationTestOptions = {
+    /** `en` or `pt-BR` (default). The room asks `items(locale)` and `scenarios(locale)` itself; this is the language of the bench and of the lines the module writes. */
+    readonly locale?: string;
+    /** The vegetation engine (default: `@adatechnology/game-vegetation` with its three adapter). A game that brings its own build of it passes it here. */
+    readonly GameVegetation?: VegetationSdk;
+    /** The species pack (default: `@adatechnology/game-vegetation-species`). */
+    readonly GameVegetationSpecies?: SpeciesSdk;
+    /** The materials of the plants, when the game already has them (default: made from the first three.js namespace the module is built with). */
+    readonly materials?: MaterialsLike;
+    /** Seed of the plants (the Viveiro's module uses 3, so the items are the same in every run). */
+    readonly seed?: number;
+    /** Where the nursery lot stands in the room, the corner of its 12 x 20 m plot: `[x, z]` (default `[-6, 14]`). */
+    readonly nurseryOrigin?: readonly [number, number];
+};
+/** The part of the test room the scenarios use (the room's `ScenarioContext.room` has all of it). */
+type VegetationRoom = {
+    spawn(item: string, position?: Vec3, rotationY?: number): {
+        objectId: string;
+        root: {
+            userData: Record<string, any>;
+        };
+    };
+    setTool(weaponId: string): void;
+    /** Lets the tool in hand finish its draw time (the room's rule: a tool cannot be used the moment it is taken). */
+    waitUntilReady(): void;
+    look(position: Vec3, target: Vec3): void;
+    use(hold?: number): void;
+    walk(to: Vec3, seconds: number): void;
+    camera: {
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    };
+    world: {
+        raycast(origin: Vec3, direction: Vec3, max: number): {
+            object: string;
+            part?: string;
+            point: Vec3;
+        } | null;
+        nearestJoint(object: string, point: Vec3, range: number, tool?: string): {
+            id: string;
+        } | null;
+        snapshot(object: string): any;
+        state(object: string): any;
+        part(object: string, part: string): any;
+        ids(): string[];
+    };
+    log: {
+        entries(filter: {
+            type?: string;
+            objectId?: string;
+        }): readonly any[];
+    };
+};
+/** What a scenario needs of the room: the pass/fail line, time, and the room for the ones that shoot, cut and burn. */
+type VegetationContext = {
+    room: VegetationRoom;
+    expect(condition: boolean, label: string, data?: Record<string, unknown>): void;
+    step(seconds: number): void;
+};
+
+declare const VEGETATION_AREA_ID = "vegetation";
+/** The 18 item ids of the Viveiro's module, in its order. */
+declare const VEGETATION_ITEM_IDS: readonly string[];
+/** The ids of the 13 scenarios (the ids of the Viveiro's page, `veg_*`). */
+declare const VEGETATION_SCENARIO_IDS: readonly string[];
+/**
+ * The vegetation test area as a `TestableModule`: the 18 plants of the Viveiro (mango trees of three sizes, ipe, palm, banana, araucaria, dead tree, hibiscus, hedge, rose, sunflower, three
+ * cacti, two pots, a lawn tuft) as items of the default destruction world, each piece a mesh with its spec (shape from the real wood thickness, joints, anchors, tags, sway clip), and the 13
+ * scenarios of that page (literal). The bench plants the nursery lot (12 x 20 m, with house, walls and path, by `scatterRulesFor`) with its seed, quality, detail, condition and season, sets
+ * the wind and starts the walker that bends the plants; its layers show the colliders, the boxes of the pieces and the axes of the wood; its metrics read triangles, pieces and draw calls.
+ */
+declare function createVegetationTestModule(options?: VegetationTestOptions): TestableModule<VegetationContext> & {
+    readonly placed: ReadonlyMap<string, unknown>;
+    materials(THREE?: unknown): MaterialsLike;
+    tick(t: number): void;
+    readonly itemIds: readonly string[];
+};
+/** What `loadVegetationTestModule` needs of a room: `TestRoom.loadModule` has it. */
+type ModuleRoomLike = {
+    loadModule(module: never): unknown;
+};
+/** Loads the vegetation module into a room. */
+declare function loadVegetationTestModule<Room extends ModuleRoomLike>(room: Room, options?: VegetationTestOptions): ReturnType<Room['loadModule']>;
+
+/** The seed of every plant of the area (the Viveiro's module fixes it, so the plants are the same in every run). */
+declare const PLANT_SEED = 3;
+type PlantDefKind = 'tree' | 'shrub' | 'hedge' | 'flower' | 'cactus' | 'pot' | 'tuft';
+/** One item of the area: a species of the pack (or a variant of it) and how it is built. */
+type PlantDef = {
+    readonly id: string;
+    /** The species the plant is generated from (default: `id`). */
+    readonly base?: string;
+    readonly kind: PlantDefKind;
+    readonly sway: boolean;
+    /** Fields of the species spec replaced for this item. */
+    readonly over?: Readonly<Record<string, number>>;
+    /** The name, `[pt-BR, en]`, when the species name does not fit the variant. */
+    readonly name?: readonly [string, string];
+    readonly condition?: Condition;
+    /** Plants side by side (a hedge is 4 sections joined by their stems). */
+    readonly segments?: number;
+    readonly movable?: boolean;
+};
+/** The 18 items of the Viveiro's module, in its order. */
+declare const PLANT_DEFS: readonly PlantDef[];
+/** The id of a mesh or a joint: lower case, runs of other characters turned into one `_` (`crown:flowers` becomes `crown_flowers`). */
+declare const sanitize: (s: string) => string;
+/** What `buildObject` records in `userData.veg` of each piece mesh. */
+type PieceMeta = {
+    id: string;
+    piece: string;
+    kind: string;
+    sub: string | null;
+    base: string;
+    parent: string | null;
+    seg: number;
+    materialKey: string;
+    radius?: number;
+    length?: number;
+    axis?: [number, number, number];
+    /** Where the plant of this section stands along x in the object (sections of a hedge are side by side). */
+    dx: number;
+};
+type Three$1 = any;
+declare function createPlants(sdk: VegetationSdk, species: SpeciesSdk, materials: (THREE: Three$1) => MaterialsLike, seed?: number): {
+    defs: Map<string, PlantDef>;
+    specFor: (def: PlantDef) => PlantSpec;
+    plantFor: (def: PlantDef, segment: number) => PlantMesh;
+    buildObject: (THREE: Three$1, def: PlantDef) => any;
+    buildSpec: (root: any, def: PlantDef) => DestructibleSpec;
+    swayClip: (def: PlantDef) => AnimationClipSpec;
+    items: (locale: string, defsToUse?: readonly PlantDef[]) => TestableItem[];
+};
+type Plants = ReturnType<typeof createPlants>;
+
+type Three = any;
+/** The plot of the Viveiro's lot demo, in metres: the corner at (0, 0), the street on the negative z side. */
+declare const LOT: {
+    readonly W: 12;
+    readonly D: 20;
+};
+declare const HOUSE: {
+    readonly x0: 2.5;
+    readonly x1: 9.5;
+    readonly z0: 6.5;
+    readonly z1: 13;
+};
+/** The walker's route (x, z). */
+declare const WAY: readonly (readonly [number, number])[];
+type Rect = {
+    rect: {
+        x: number;
+        z: number;
+        w: number;
+        d: number;
+    };
+};
+declare const EX_HOUSE: Rect;
+declare const EX_PATH: Rect;
+/** Where each kind of planting goes. */
+declare const AREAS: Readonly<Record<'front_yard' | 'backyard' | 'sides' | 'sidewalk_tree', Rect[]>>;
+/** The four plantings of the lot: the context of the regional table, where, how many of each group, and the tag of the scatter seed. */
+type Planting = {
+    context: string;
+    areas: Rect[];
+    options: ScatterRulesOptions & {
+        n: number;
+    };
+    tag: string;
+};
+declare const PLANTINGS: readonly Planting[];
+type NurserySettings = {
+    seed: number;
+    quality: 'high' | 'game';
+    lod: Lod;
+    condition: Condition;
+    season: Season;
+};
+type LotStats = {
+    triangles: number;
+    plants: number;
+    colliders: number;
+    meshes: number;
+    lod: [number, number, number];
+    buildMs: number;
+    species: number;
+};
+/**
+ * The scatter of the lot: the same picks, rules and placements as the Viveiro's `buildLotVeg`. Every planting draws its species from the regional table of its context, splits
+ * them into trees, hedges, middle layer and ground cover, and scatters each group over the areas of the plot without touching the house or the path.
+ */
+declare function scatterLot(sdk: VegetationSdk, species: SpeciesSdk, seedNumber: number, plantings?: readonly Planting[]): {
+    placements: Placement[];
+    used: Set<string>;
+};
+/**
+ * The nursery: the 12 x 20 m plot of the Viveiro's lot demo (house, walls, street, path) planted by `scatterRulesFor` + `scatter` + `buildLot`, and the walker that crosses it and bends
+ * the plants (the wind shader's actors). The module owns it; `plant` builds it, `clear` takes it away.
+ */
+declare function createNursery(sdk: VegetationSdk, species: SpeciesSdk, THREE: Three, materials: MaterialsLike, parent: any, origin: readonly [number, number]): {
+    group: any;
+    readonly stats: LotStats | null;
+    readonly planted: boolean;
+    readonly walking: boolean;
+    readonly position: {
+        x: number;
+        z: number;
+    };
+    /** Plants the lot with the settings (replaces the one standing). */
+    plant(settings: NurserySettings): LotStats;
+    /** The colliders of the lot as wire cylinders. */
+    showColliders(on: boolean): void;
+    /** Starts or stops the walker that crosses the lot along `WAY`, bending the plants. */
+    setWalker(on: boolean): void;
+    step(dt: number): void;
+    /** Takes the lot, the walker and the scenery away. */
+    clear(): void;
+};
+type Nursery = ReturnType<typeof createNursery>;
+
+export { AREAS, EX_HOUSE, EX_PATH, HOUSE, LOT, type LotStats, type MaterialsLike, type ModuleRoomLike, type Nursery, type NurserySettings, PLANTINGS, PLANT_DEFS, PLANT_SEED, type PieceMeta, type PlantDef, type PlantDefKind, type Planting, type Plants, type SpeciesSdk, VEGETATION_AREA_ID, VEGETATION_ITEM_IDS, VEGETATION_SCENARIO_IDS, type VegetationContext, type VegetationRoom, type VegetationSdk, type VegetationTestOptions, WAY, createNursery, createPlants, createVegetationTestModule, loadVegetationTestModule, sanitize, scatterLot };