@adatechnology/game-vehicles-three 0.4.0 → 0.6.0

package/dist/testing-gEnSqEF6.d.ts

@@ -0,0 +1,349 @@
+import { EffectSink, Vec3, TestableModule } from '@adatechnology/game-contracts';
+import { Damageable, VehicleContext, VehicleKit } from '@adatechnology/game-vehicles';
+import { ProvingSubject, ProvingTestRegistry, ProvingCertificate } from '@adatechnology/game-vehicles-proving';
+
+type VehicleQuality = 'high' | 'lite';
+/** The measured size of a fleet vehicle in metres (the shape of `FleetDims` of `game-vehicles-fleet`). */
+interface FleetDims {
+    length: number;
+    width: number;
+    height: number;
+}
+/**
+ * The fleet content the builder reads: the paint palettes, the size the team measured and the colour a seed picks. It is the shape of what
+ * `game-vehicles-fleet` exports (`defaultVehicleFleet()` of `game-kit-defaults` hands it over), so this adapter imports no content.
+ */
+interface VehicleFleetContent {
+    readonly paintPalettes: {
+        readonly civil: unknown;
+        readonly military: unknown;
+    };
+    paletteOf(group: string): unknown;
+    colorFromSeed(seed: number | string, palette: unknown): string;
+    fleetDims(id: string): FleetDims | undefined;
+}
+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;
+    /**
+     * The fleet's palettes and measured sizes (`defaultVehicleFleet()` of `game-kit-defaults`, or the game's own). Default the ones of `game-vehicles-fleet`.
+     * @deprecated pass `fleet`; the default is removed in the next major.
+     */
+    fleet?: VehicleFleetContent;
+    /** 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;
+
+/**
+ * How a vehicle sounds, as data. An engine is a few loops crossfaded by RPM (idle, low/mid, high) plus a load layer (intake and exhaust roar) that
+ * follows the throttle, the way a sampled engine is mixed: when recorded loops arrive they take the same ids and the same crossfade. The pitch of
+ * each tone layer is the firing frequency of the engine (`rpm / 60 × cylinders / 2` for a four-stroke) times its harmonic.
+ */
+/** One tone layer of the engine: the loop id, where in the RPM range it is loudest (0 idle … 1 redline), and its level and cutoff. */
+type EngineLayer = {
+    readonly sound: string;
+    /** Normalised RPM (0 at idle, 1 at the redline) where the layer is loudest. */
+    readonly centre: number;
+    /** How far from `centre` the layer fades out (equal-power crossfade). */
+    readonly width: number;
+    /** Multiple of the firing frequency the oscillator plays at. */
+    readonly harmonic: number;
+    /** Level at full load. */
+    readonly gain: number;
+    /** Low-pass cutoff, Hz, from no load at idle to full load at the redline. */
+    readonly cutoff: readonly [min: number, max: number];
+};
+/** The roar of the intake and exhaust: a noise loop that opens with the throttle and the RPM. */
+type EngineLoadLayer = {
+    readonly sound: string;
+    readonly gain: number;
+    readonly cutoff: readonly [min: number, max: number];
+};
+type EngineProfile = {
+    readonly id: string;
+    readonly cylinders: number;
+    readonly idleRpm: number;
+    readonly redlineRpm: number;
+    /** Gear ratios times final drive per m/s, to guess the RPM from the speed when the driver has no engine model (the arcade driver). */
+    readonly rpmPerMps: readonly number[];
+    readonly layers: readonly EngineLayer[];
+    readonly load: EngineLoadLayer;
+    /** Level with the throttle closed, as a share of full load (engine braking is quieter and darker). */
+    readonly closedThrottle: number;
+};
+/** The sound ids a vehicle plays besides its engine. Every one is a key of `VEHICLE_SOUND_BANK`, and a game can point any of them elsewhere. */
+type VehicleSoundKeys = {
+    readonly start: string;
+    readonly stop: string;
+    readonly fail: string;
+    readonly crashLight: string;
+    readonly crashMedium: string;
+    readonly crashHeavy: string;
+    readonly skidAsphalt: string;
+    readonly skidDirt: string;
+    readonly roll: string;
+};
+declare const DEFAULT_VEHICLE_SOUND_KEYS: VehicleSoundKeys;
+/** The speed of the hit, m/s, where a crash stops being light (≈ 22 km/h: dents and plastic) and where it turns heavy (≈ 50 km/h: metal folds, glass goes). */
+declare const CRASH_SPEEDS: {
+    readonly medium: 6;
+    readonly heavy: 14;
+};
+/** A four-cylinder petrol car: 800 to 6 500 rpm. */
+declare const CAR_ENGINE: EngineProfile;
+/** A six-cylinder diesel truck or bus: 650 to 2 600 rpm, low and clattering. */
+declare const TRUCK_ENGINE: EngineProfile;
+/** A four-cylinder sport bike: 1 300 to 12 000 rpm, bright and fast to rev. */
+declare const BIKE_ENGINE: EngineProfile;
+declare const ENGINE_PROFILES: Readonly<Record<string, EngineProfile>>;
+
+/** The fleet the area runs on: its palettes and sizes, and how it is installed in a kit (`defaultVehicleFleet()` of `game-kit-defaults`). */
+type VehiclesTestFleet = VehicleFleetContent & {
+    installFleet(kit: VehicleKit): void;
+};
+/** 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: the horn (placed at the car), and the vehicle's own sounds (`createVehicleSound`: the starter, the
+ * crashes by speed, the tyres). The engine loops come from the engine profile.
+ */
+type VehicleSoundIds = {
+    readonly horn: string;
+} & VehicleSoundKeys;
+declare const defaultSoundIds: VehicleSoundIds;
+/** A damaged vehicle of the area: the item id, the fleet vehicle it is built from and the scenario of the kit applied while building. */
+type VehicleWreck = {
+    readonly key: string;
+    readonly vehicle: string;
+    readonly scenario: string;
+};
+declare const DEFAULT_TEST_WRECKS: readonly VehicleWreck[];
+type VehiclesTestOptions = {
+    /**
+     * The fleet content: paint palettes, measured sizes and the install into the default kit (`defaultVehicleFleet()` of `game-kit-defaults`). Default the ones of `game-vehicles-fleet`.
+     * @deprecated pass `fleet`; the default is removed in the next major.
+     */
+    readonly fleet?: VehiclesTestFleet;
+    /** `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 (`fleet.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[];
+    /** Wrecks laid out after the vehicles: item `key` is the fleet vehicle `vehicle` built with the registered damage `scenario` (default `sedan_burnt` and `hatch_burnt`, the fleet's `burnt`; an empty list lays none). */
+    readonly wrecks?: readonly VehicleWreck[];
+    /** 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: the vehicle bank of this package). */
+    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>>;
+
+declare const PROVING_AREA_ID = "vehicles_proving";
+type Three = any;
+/** Content comes in by option (the adapter does not import a content pack): the example wires the kit's fleet, a game its own catalogue. */
+interface ProvingModuleOptions {
+    locale?: string;
+    /** Vehicles offered on the bench, by catalogue id. */
+    vehicles: readonly string[];
+    /** The proving subject of a vehicle (`fleetProvingSubject` of game-vehicles-fleet); `mass` is the kit's own when it has one. Null hides the vehicle. */
+    subject(id: string, mass: number | undefined): ProvingSubject | null;
+    /** The vehicle's name on the bench and the board (default: the id). */
+    nameOf?(id: string): string | undefined;
+    /** The tests (default: the kit's, see `createProvingTests`). */
+    tests?: ProvingTestRegistry;
+    /** Builds the vehicle kit, with the catalogue installed, for a three.js namespace. */
+    createKit(THREE: Three): VehicleKit;
+    sounds?: Partial<VehicleSoundIds>;
+    /** Called whenever a certificate changes (a result in, a sign-off), so a page can keep or show them. */
+    onCertificate?(certificate: ProvingCertificate): void;
+}
+/**
+ * The proving ground as a `TestableModule`: a track where a fleet vehicle runs the measured tests of `game-vehicles-proving` live (0-100, top speed, braking, turning circle, wet braking, mud)
+ * on the same semi-simulation driver the headless runner uses, with the vehicle cameras of `game-camera` (chase, cockpit, hood) taking over the room's view, the rear-view and side mirrors
+ * and the reversing camera with its guide lines as extra views of the host, a board by the track with the vehicle's certificate, and the sign-off of the visual checks.
+ */
+declare function createProvingModule(options: ProvingModuleOptions): TestableModule & {
+    certificates(): ProvingCertificate[];
+    certificate(id: string): ProvingCertificate | undefined;
+};
+/** What `loadProvingModule` needs of a room: `TestRoom.loadModule` has it. */
+type ProvingRoomLike = {
+    loadModule(module: never): unknown;
+    openArea?(id: string): unknown;
+};
+declare function loadProvingModule<Room extends ProvingRoomLike>(room: Room, options: ProvingModuleOptions): ReturnType<Room['loadModule']>;
+
+/** Texts of the proving ground, in Brazilian Portuguese and English. */
+type ProvingText = {
+    name: string;
+    controls: Record<'vehicle' | 'test' | 'camera' | 'time_scale' | 'visual_check', string>;
+    hints: Record<'vehicle' | 'test' | 'camera' | 'time_scale' | 'visual_check', string>;
+    actions: Record<'run_test' | 'run_all' | 'certify_now' | 'reverse_park' | 'sign_ok' | 'sign_fail' | 'reset', string>;
+    layers: Record<'mirrors' | 'reverse_camera' | 'scoreboard', string>;
+    metrics: Record<'speed' | 'time' | 'value' | 'passed' | 'failed' | 'pending' | 'status', string>;
+    cameras: Record<'room' | 'chase' | 'cockpit' | 'hood', string>;
+    tests: Record<string, string>;
+    status: Record<'approved' | 'rejected' | 'pending', string>;
+    verdict: Record<'pass' | 'fail' | 'pending', string>;
+    board: {
+        title: string;
+        test: string;
+        value: string;
+        range: string;
+        verdict: string;
+        notRun: string;
+        running: string;
+    };
+    log: {
+        start: string;
+        result: string;
+        signed: string;
+        certified: string;
+    };
+};
+declare const PROVING_TEXT: Record<string, ProvingText>;
+
+export { type VehiclesTestOptions as A, BIKE_ENGINE as B, CAR_ENGINE as C, DEFAULT_TEST_VEHICLES as D, type EngineProfile as E, type FleetDims as F, type VehiclesThree as G, type VehiclesThreeOptions as H, createProvingModule as I, createVehiclesTestModule as J, createVehiclesThree as K, defaultEffectIds as L, type ModuleRoomLike as M, defaultSoundIds as N, loadProvingModule as O, PAGE_ITEM_ALIASES as P, loadVehiclesTestModule as Q, TRUCK_ENGINE as T, type VehicleSoundKeys as V, type BuildVehicleOptions as a, type BuiltVehicle as b, CRASH_SPEEDS as c, DEFAULT_TEST_WRECKS as d, DEFAULT_VEHICLE_SOUND_KEYS as e, type DocumentLike as f, ENGINE_PROFILES as g, type EffectsLike as h, type EngineLayer as i, type EngineLoadLayer as j, PAGE_SCENARIO_ALIASES as k, PROVING_AREA_ID as l, PROVING_TEXT as m, type ProvingModuleOptions as n, type ProvingRoomLike as o, type ProvingText as p, VEHICLES_AREA_ID as q, VEHICLE_SCENARIO_IDS as r, type VehicleEffectIds as s, type VehicleFleetContent as t, type VehicleQuality as u, type VehicleSoundIds as v, type VehicleWreck as w, type VehiclesContext as x, type VehiclesRoom as y, type VehiclesTestFleet as z };

package/dist/testing.d.ts

@@ -0,0 +1,4 @@
+export { D as DEFAULT_TEST_VEHICLES, d as DEFAULT_TEST_WRECKS, f as DocumentLike, h as EffectsLike, M as ModuleRoomLike, P as PAGE_ITEM_ALIASES, k as PAGE_SCENARIO_ALIASES, l as PROVING_AREA_ID, m as PROVING_TEXT, n as ProvingModuleOptions, o as ProvingRoomLike, p as ProvingText, q as VEHICLES_AREA_ID, r as VEHICLE_SCENARIO_IDS, s as VehicleEffectIds, v as VehicleSoundIds, w as VehicleWreck, x as VehiclesContext, y as VehiclesRoom, z as VehiclesTestFleet, A as VehiclesTestOptions, I as createProvingModule, J as createVehiclesTestModule, L as defaultEffectIds, N as defaultSoundIds, O as loadProvingModule, Q as loadVehiclesTestModule } from './testing-gEnSqEF6.js';
+import '@adatechnology/game-contracts';
+import '@adatechnology/game-vehicles';
+import '@adatechnology/game-vehicles-proving';

package/dist/testing.js

@@ -0,0 +1,33 @@
+import {
+  DEFAULT_TEST_VEHICLES,
+  DEFAULT_TEST_WRECKS,
+  PAGE_ITEM_ALIASES,
+  PAGE_SCENARIO_ALIASES,
+  PROVING_AREA_ID,
+  PROVING_TEXT,
+  VEHICLES_AREA_ID,
+  VEHICLE_SCENARIO_IDS,
+  createProvingModule,
+  createVehiclesTestModule,
+  defaultEffectIds,
+  defaultSoundIds,
+  loadProvingModule,
+  loadVehiclesTestModule
+} from "./chunk-4SUQMRS3.js";
+export {
+  DEFAULT_TEST_VEHICLES,
+  DEFAULT_TEST_WRECKS,
+  PAGE_ITEM_ALIASES,
+  PAGE_SCENARIO_ALIASES,
+  PROVING_AREA_ID,
+  PROVING_TEXT,
+  VEHICLES_AREA_ID,
+  VEHICLE_SCENARIO_IDS,
+  createProvingModule,
+  createVehiclesTestModule,
+  defaultEffectIds,
+  defaultSoundIds,
+  loadProvingModule,
+  loadVehiclesTestModule
+};
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adatechnology/game-vehicles-three",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "license": "MIT",
   "description": "three.js output of the vehicles of @adatechnology/game-vehicles: a vehicle in a game frame (front on +z, centred, on the ground) at full detail or fused into six meshes (the team's Frota Leve light mode), coloured by seed, with its damageable boxes; and the vehicles test module.",
   "keywords": [
@@ -31,18 +31,25 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
     "./global": "./dist/index.global.js"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@adatechnology/game-audio": "^0.3.6",
-    "@adatechnology/game-contracts": "^0.21.0",
-    "@adatechnology/game-shapes-three": "^0.2.0",
-    "@adatechnology/game-vehicles": "^0.5.0",
-    "@adatechnology/game-vehicles-driving": "^0.2.8",
-    "@adatechnology/game-vehicles-fleet": "^5.0.0"
+    "@adatechnology/game-audio": "^0.5.0",
+    "@adatechnology/game-camera": "^0.2.0",
+    "@adatechnology/game-contracts": "^0.23.0",
+    "@adatechnology/game-render-three": "^0.1.0",
+    "@adatechnology/game-shapes-three": "^0.3.1",
+    "@adatechnology/game-vehicles": "^0.6.1",
+    "@adatechnology/game-vehicles-driving": "^0.2.10",
+    "@adatechnology/game-vehicles-fleet": "^6.0.0",
+    "@adatechnology/game-vehicles-proving": "^0.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.10.7",
@@ -52,7 +59,8 @@
     "tsup": "^8.5.1",
     "typescript": "^5.7.3",
     "vitest": "^3.2.4",
-    "@adatechnology/game-test-room": "^0.20.0",
+    "@adatechnology/game-kit-defaults": "^0.2.0",
+    "@adatechnology/game-test-room": "^0.22.0",
     "@adatechnology/golden-tool": "^0.0.0"
   },
   "peerDependencies": {