@adatechnology/game-vehicles-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,26 @@
-# Temporary Holding Version
+# @adatechnology/game-vehicles-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.
+A vehicle of `@adatechnology/game-vehicles` in a game frame, at full detail or fused into six meshes. A literal port of the team's Frota Leve (`FrotaLeve.criar(...).construir`).
+
+```ts
+import { createVehicleKit } from '@adatechnology/game-vehicles'
+import { installFleet } from '@adatechnology/game-vehicles-fleet'
+import { createVehiclesThree } from '@adatechnology/game-vehicles-three'
+
+const kit = createVehicleKit({ THREE })
+installFleet(kit)
+const vehicles = createVehiclesThree(THREE, { kit })
+const car = vehicles.build('midsize_sedan', { quality: 'lite', seed: 42 })
+scene.add(car.group) // front on +z, right on -x, centred, wheels on y = 0
+car.triangles // 19286 · car.drawCalls // 6 · car.damageables // metal, glass, rubber, fuel boxes in the game frame
+```
+
+- `quality: 'high'` is the kit's vehicle (the context stays in `car.context` for damage), `'lite'` fuses it into `paint`, `trim`, `metal`, `glass`, `light` and `plate`, dropping interiors and pieces under 3 cm.
+- The colour comes from `color` or from `seed` through the palette of the vehicle's group (`colorFromSeed`).
+- Tested against the team's page on three r160 (triangles, draw calls, size, per-class vertices, damageable boxes) and against `DIMS` for the 69 vehicles.
+
+## Test area
+
+`createVehiclesTestModule({ locale, document?, three?, vehicles?, effects? })` is a `TestableModule` for the shared test room (`room.loadModule`, or `loadVehiclesTestModule(room)`, which learns the room's three.js to compute the door, hood and trunk clips). It lays the eight vehicles of the Frota test, each with its own `DestructibleImpl`, and brings 13 scenarios: the eleven of the team's test page, literal (`vehicles_9mm_windshield`, `vehicles_shotgun_door`, `vehicles_ram_front`, `vehicles_engine_fire`, `vehicles_fuel_tank`, `vehicles_unbolt_wheel`, `vehicles_tear_bumper`, `vehicles_break_mirror`, `vehicles_kill_battery`, `vehicles_rollover`, `vehicles_melt`; the page ids are in `PAGE_SCENARIO_ALIASES`), plus `vehicles_drive_arcade` and `vehicles_drive_semi` for `@adatechnology/game-vehicles-driving`.
+
+The bench sets the quality (full or light mode), the paint by seed and palette, the driving mode and the surface, and drives a car down a lane; its layers show the damageable boxes by material, the zones by type and the axes of the output frame; its metrics read triangles, draw calls, the size against `DIMS` and the boxes by material. The module draws no particles: fire, explosion, glass, sparks, leaks and exhaust are requested by id through `host.effects` when the host has one (`defaultEffectIds`, replaceable by option). A pierced tank asks for `leak` (`vehicle_leak`: the pool and the drips only); when the leak catches fire (a spark, an incendiary round, a fire near, a blast) the `ignite` event of the tank asks for `leakIgnited` (`vehicle_leak_ignited`: the Garagem's whole sequence, the fire along the pool and then the blast). `examples/vehicles-test-area` loads it.

package/dist/index.d.ts

@@ -0,0 +1,217 @@
+import { Damageable, VehicleContext, VehicleKit } from '@adatechnology/game-vehicles';
+import { FleetDims } from '@adatechnology/game-vehicles-fleet';
+import { EffectSink, Vec3, TestableModule } from '@adatechnology/game-contracts';
+
+type VehicleQuality = 'high' | 'lite';
+interface BuildVehicleOptions {
+    /** `high`: the kit's vehicle at full detail. `lite`: fused into six meshes. Default `high`. */
+    quality?: VehicleQuality;
+    /** Body colour as a CSS colour. Wins over `seed`. */
+    color?: string;
+    /** Picks the body colour from the palette of the vehicle's group. */
+    seed?: number | string;
+    /** State of the vehicle. Default `intact`. */
+    state?: 'intact' | 'damaged' | 'modified';
+}
+interface BuiltVehicle {
+    key: string;
+    quality: VehicleQuality;
+    /** The colour the body ended up with, or null when the vehicle keeps its own paint. */
+    color: string | null;
+    seed: number | string | null;
+    /** Group in the game frame: front on +z, right on -x, centred on x and z, wheels on y = 0. */
+    group: any;
+    /** Damageable boxes in the game frame. */
+    damageables: Damageable[];
+    triangles: number;
+    drawCalls: number;
+    /** Measured size of the group in metres: length along z, width along x, height along y. */
+    length: number;
+    width: number;
+    height: number;
+    /** Pieces dropped for being smaller than 3 cm (lite only). */
+    pruned: number;
+    /** The measured size the team recorded for this vehicle, when the fleet knows it. */
+    expected: FleetDims | undefined;
+    /** The kit's context, for damage and animation (full detail only). */
+    context: VehicleContext | null;
+    dispose(): void;
+}
+interface VehiclesThree {
+    readonly THREE: any;
+    readonly kit: VehicleKit;
+    build(key: string, options?: BuildVehicleOptions): BuiltVehicle;
+}
+interface VehiclesThreeOptions {
+    kit: VehicleKit;
+    /** Vehicle id to the group id whose palette paints it. Defaults to the fleet group of the vehicle (`military` for the military ones). */
+    groupOf?: (key: string) => string;
+}
+/**
+ * Builds vehicles in a game frame. Port of `FrotaLeve.criar(...).construir` (frota-leve.js 14311-14442): the kit builds with +x to the front
+ * and +z to the right; the game wants +z to the front and -x to the right, the vehicle centred on x and z and standing on y = 0.
+ */
+declare function createVehiclesThree(THREE: any, options: VehiclesThreeOptions): VehiclesThree;
+
+/**
+ * The light mode of the team's Frota Leve (frota-leve.js 14202-14310): a built vehicle fused into six meshes, one per class of material,
+ * with the meshes nobody sees from outside left out. A literal port: the classes, the thresholds (3 cm prune, 0.99 opacity, 0.5 metalness,
+ * 0.25 and 0.45 emissive) and the colours are the team's.
+ */
+/** The six classes of a fused vehicle, in the order they are added to the group. */
+declare const LITE_CLASSES: readonly ["paint", "trim", "metal", "glass", "light", "plate"];
+type LiteClass = (typeof LITE_CLASSES)[number];
+/** Smallest extent in metres a piece needs to survive the fusion (the plate is always kept). */
+declare const PRUNE_BELOW = 0.03;
+interface Accumulator {
+    P: number[];
+    N: number[];
+    C: number[];
+    U: number[];
+    I: number[];
+    nv: number;
+    alpha: boolean;
+    uv: boolean;
+    map: any;
+}
+interface LiteFusion {
+    acc: Record<LiteClass, Accumulator>;
+    pruned: number;
+}
+/** Which class a material belongs to, or `null` when it is left out. */
+declare function classify(mat: any, mesh: any, c: any): LiteClass | null;
+/** The vertex colour of a piece of a class. `paintColor` replaces the primary paint. */
+declare function classColor(mat: any, cls: LiteClass, primary: any, paintColor: any, out: any): any;
+/** The material of each class (vertex colours; glass blends; light is unlit; the plate keeps its canvas texture). */
+declare function liteMaterials(THREE: any, environment: any): Record<LiteClass, any>;
+/**
+ * Walks the built vehicle and collects every visible mesh, in the frame of `pivot`, into one set of arrays per class.
+ * `hidden` is the set of materials nobody sees from outside (`kit.lodHiddenMaterials()`).
+ */
+declare function fuse(THREE: any, c: any, pivot: any, paintColor: any, primary: any, hidden: ReadonlySet<any>): LiteFusion;
+/** One mesh per class that has triangles. */
+declare function liteMeshes(THREE: any, fusion: LiteFusion, materials: Record<LiteClass, any>): any[];
+
+/** What the module needs of a document (canvas textures of the kit): a real `document`, or a stub in Node. */
+type DocumentLike = {
+    createElement(tag: string): unknown;
+};
+/** The host's effects (`host.effects`, an `EffectSink` of the contracts: `game-vfx-three` is one): the module asks by id and writes no particle code. */
+type EffectsLike = EffectSink;
+/** The events the module turns into effect requests, and the effect id each one asks for. A game maps its own ids over these. */
+type VehicleEffectIds = {
+    readonly ignite: string;
+    readonly explode: string;
+    readonly glass: string;
+    readonly sparks: string;
+    readonly leak: string;
+    /** The leak of a pierced tank caught fire: the whole sequence (fire along the pool, then the blast). `leak` is only the pool and the drips. */
+    readonly leakIgnited: string;
+    readonly exhaust: string;
+};
+declare const defaultEffectIds: VehicleEffectIds;
+/** The sounds the module asks of `host.audio`, by id of the host's banks. `engine` is a loop (the game's saw through a 400 Hz low-pass), `horn` and `crash` one-shots. */
+type VehicleSoundIds = {
+    readonly engine: string;
+    readonly horn: string;
+    readonly crash: string;
+};
+declare const defaultSoundIds: VehicleSoundIds;
+type VehiclesTestOptions = {
+    /** `en` or `pt-BR` (default). */
+    readonly locale?: string;
+    /** The kit the vehicles are built with, per three.js namespace. Default: `createVehicleKit` with the fleet installed (`installFleet`). */
+    readonly createKit?: (THREE: unknown) => VehicleKit;
+    readonly document?: DocumentLike;
+    /** The three.js namespace the door, hood and trunk clips are computed with (they are plain numbers, so any copy works). Default: the global `THREE`; without either the items bring no clips. */
+    readonly three?: unknown;
+    /** The vehicles to lay out, as fleet ids (default the 8 of the Frota test: hatch, sedan, pickup, sport bike, box truck, city bus, battle tank, attack helicopter). */
+    readonly vehicles?: readonly string[];
+    /** Effect ids requested through `host.effects` (the defaults are ids of `game-vfx`: the Garagem's `car_fuel_tank` blast, the `vehicle_fire`, `vehicle_leak` (pool and drips only), `vehicle_leak_ignited` (the whole sequence) and `vehicle_exhaust` recipes written around a car from `engine_smoke` and `fuel_leak`, and the point-based `glass_burst` and `impact_metal`). */
+    readonly effects?: Partial<VehicleEffectIds>;
+    /** Sound ids requested through `host.audio` (the defaults are the `game-audio` ones: `engine_saw`, `horn`, `sfx_impact`). */
+    readonly sounds?: Partial<VehicleSoundIds>;
+};
+/** The part of the test room the scenarios use (the room's `ScenarioContext.room` has all of it). */
+type PartView = {
+    holes: {
+        through?: boolean;
+    }[];
+    cracks: unknown[];
+    dents: unknown[];
+    status: string;
+    hp: number;
+    maxHp: number;
+    temperature: number;
+    burning: boolean;
+    liters: number;
+    melt: number;
+};
+type SpawnedVehicle = {
+    objectId: string;
+    root: {
+        userData: Record<string, unknown>;
+    };
+};
+type VehiclesRoom = {
+    spawn(item: string, position?: Vec3, rotationY?: number): SpawnedVehicle;
+    setTool(weaponId: string): void;
+    /** Lets the tool in hand finish its draw time (the room's rule: a weapon cannot fire the moment it is taken). */
+    waitUntilReady(): void;
+    look(position: Vec3, target: Vec3): void;
+    use(hold?: number): void;
+    playAnimation(clipId: string, objectId?: string): boolean;
+    world: {
+        part(object: string, part: string): PartView;
+        hit(object: string, hit: Record<string, unknown>): unknown;
+        disassemble(object: string, joint: string, tool: string, dt: number): number;
+        state(object: string): {
+            joints: {
+                id: string;
+                open: boolean;
+            }[];
+            groups: unknown[][];
+        };
+    };
+    log: {
+        entries(filter: {
+            type?: string;
+            objectId?: string;
+        }): readonly unknown[];
+    };
+};
+/** What a scenario needs of the room: the pass/fail line, time, and the room for the ones that shoot and hit. */
+type VehiclesContext = {
+    room: VehiclesRoom;
+    expect(condition: boolean, label: string, data?: Record<string, unknown>): void;
+    step(seconds: number): void;
+};
+
+declare const VEHICLES_AREA_ID = "vehicles_area";
+/** The eight vehicles of the Frota test page, in its order, and the item id each one has in the area. */
+declare const DEFAULT_TEST_VEHICLES: readonly string[];
+/**
+ * The vehicles test area as a `TestableModule`: the vehicles of the Frota test (hatch, sedan, pickup, sport bike, box truck, city bus, battle tank, attack helicopter), each with its own
+ * `DestructibleImpl` and its door, hood and trunk clips, the eleven scenarios of that page (literal) and two for the drivers. The bench sets the quality (full or light mode), the paint
+ * by seed and palette, the driving mode and the surface, and shows the damageable boxes by material, the zones by type and the axes of the output frame. Effects (fire, glass, sparks,
+ * exhaust) are requested by id through `host.effects` when the host has it; this module draws none.
+ */
+declare function createVehiclesTestModule(options?: VehiclesTestOptions): TestableModule<VehiclesContext> & {
+    readonly placed: ReadonlyMap<string, unknown>;
+};
+/** What `loadVehiclesTestModule` needs of a room: `TestRoom.loadModule` has it. */
+type ModuleRoomLike = {
+    loadModule(module: never): unknown;
+};
+/**
+ * Loads the vehicles module into a room. The door, hood and trunk clips of the items are computed when the room reads the items, before the module is lent the room's three.js
+ * (`attach`), so this first lends an empty module to learn the namespace and then loads the real one with it. Pass `three` to skip that.
+ */
+declare function loadVehiclesTestModule<Room extends ModuleRoomLike>(room: Room, options?: VehiclesTestOptions): ReturnType<Room['loadModule']>;
+
+declare const VEHICLE_SCENARIO_IDS: readonly string[];
+/** The ids of the Frota test page, for whoever keeps a report or a link made against it. */
+declare const PAGE_SCENARIO_ALIASES: Readonly<Record<string, string>>;
+declare const PAGE_ITEM_ALIASES: Readonly<Record<string, string>>;
+
+export { type BuildVehicleOptions, type BuiltVehicle, DEFAULT_TEST_VEHICLES, type DocumentLike, type EffectsLike, LITE_CLASSES, type LiteClass, type LiteFusion, type ModuleRoomLike, PAGE_ITEM_ALIASES, PAGE_SCENARIO_ALIASES, PRUNE_BELOW, VEHICLES_AREA_ID, VEHICLE_SCENARIO_IDS, type VehicleEffectIds, type VehicleQuality, type VehicleSoundIds, type VehiclesContext, type VehiclesRoom, type VehiclesTestOptions, type VehiclesThree, type VehiclesThreeOptions, classColor, classify, createVehiclesTestModule, createVehiclesThree, defaultEffectIds, defaultSoundIds, fuse, liteMaterials, liteMeshes, loadVehiclesTestModule };