@adatechnology/game-vehicles-three 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,57 +1,9 @@
-import { Damageable, VehicleContext, VehicleKit, CabinSource } 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;
+import { E as EngineProfile, V as VehicleSoundKeys } from './testing-gEnSqEF6.js';
+export { B as BIKE_ENGINE, a as BuildVehicleOptions, b as BuiltVehicle, C as CAR_ENGINE, c as CRASH_SPEEDS, D as DEFAULT_TEST_VEHICLES, d as DEFAULT_TEST_WRECKS, e as DEFAULT_VEHICLE_SOUND_KEYS, f as DocumentLike, g as ENGINE_PROFILES, h as EffectsLike, i as EngineLayer, j as EngineLoadLayer, F as FleetDims, 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, T as TRUCK_ENGINE, q as VEHICLES_AREA_ID, r as VEHICLE_SCENARIO_IDS, s as VehicleEffectIds, t as VehicleFleetContent, u as VehicleQuality, v as VehicleSoundIds, w as VehicleWreck, x as VehiclesContext, y as VehiclesRoom, z as VehiclesTestFleet, A as VehiclesTestOptions, G as VehiclesThree, H as VehiclesThreeOptions, I as createProvingModule, J as createVehiclesTestModule, K as createVehiclesThree, L as defaultEffectIds, N as defaultSoundIds, O as loadProvingModule, Q as loadVehiclesTestModule } from './testing-gEnSqEF6.js';
+import { EffectSink, Vec3, AudioSink } from '@adatechnology/game-contracts';
+import { CabinSource } from '@adatechnology/game-vehicles';
+import { LoopRecipe, Falloff, SoundRecipe, SoundBank } from '@adatechnology/game-audio';
+import '@adatechnology/game-vehicles-proving';
 
 /**
  * Keeps the host's effects told where the cabins of the vehicles are and how open they are (`EffectSink.enclose`), so the smoke, dust and steam
@@ -74,6 +26,92 @@ interface CabinSmoke {
 }
 declare function createCabinSmoke(): CabinSmoke;
 
+/** How a vehicle loop falls off: `1 / (1 + d² × 0.004)`, the game's one-shot curve, with the cutoff muffled by `1 + d × 0.01` (a car far away is dull). */
+declare const VEHICLE_LOOP_FALLOFF: Falloff;
+/** The engines (car, truck, bike) and the tyres, as loops. */
+declare const VEHICLE_LOOPS: readonly LoopRecipe[];
+/** The one-shots: the starter, the engine stopping, crashes by speed, and the doors, trunk and hood of a car. */
+declare const VEHICLE_SOUNDS: readonly SoundRecipe[];
+declare const VEHICLE_SOUND_BANK: SoundBank;
+
+/** What one engine loop is set to this frame. `frequency` is absent for the load layer (noise has no pitch). */
+type EngineLayerSetting = {
+    readonly sound: string;
+    readonly volume: number;
+    readonly frequency?: number;
+    readonly cutoff: number;
+};
+type EngineMixInput = {
+    readonly rpm: number;
+    /** 0..1, how open the throttle is (the engine's load). */
+    readonly throttle: number;
+};
+/** The firing frequency of a four-stroke engine, Hz: every cylinder fires once every two turns. */
+declare const firingHz: (profile: EngineProfile, rpm: number) => number;
+/** RPM as a share of the range: 0 at idle, 1 at the redline. */
+declare const rpmShare: (profile: EngineProfile, rpm: number) => number;
+/** Equal-power weight of a layer centred at `centre` with `width` at the normalised RPM `n`. */
+declare const layerWeight: (centre: number, width: number, n: number) => number;
+/**
+ * The engine's loops for an RPM and a throttle: every tone layer at the firing frequency times its harmonic, faded in and out across the RPM range so
+ * the sum stays even, louder and brighter under load; the load layer opens with the throttle. A stopped engine (`rpm` 0) is silent.
+ */
+declare function engineMix(profile: EngineProfile, input: EngineMixInput): EngineLayerSetting[];
+/**
+ * A guess of the RPM from the speed for a driver without an engine model: the gear is kept between calls (up above 85% of the redline, down below
+ * 40%), so the RPM climbs and drops at each shift as it does in a real car.
+ */
+declare function createGearGuess(profile: EngineProfile): {
+    rpm(speed: number, throttle: number): number;
+    readonly gear: number;
+};
+
+/** What the vehicle is doing this frame. Without `rpm` (a driver with no engine model) the RPM is guessed from the speed through the profile's gears. */
+type VehicleSoundFrame = {
+    readonly dt: number;
+    readonly position: Vec3;
+    /** m/s, signed or not. */
+    readonly speed: number;
+    /** 0..1. */
+    readonly throttle: number;
+    readonly rpm?: number;
+    /** 0..1: how much the tyres slide (the largest wheel slip; 1 = locked or spinning). */
+    readonly slip?: number;
+    /** What the tyres are on: `dirt` for earth, gravel, sand or grass; anything else squeals as asphalt. */
+    readonly surface?: 'asphalt' | 'dirt';
+};
+type VehicleSoundOptions = {
+    readonly profile?: EngineProfile;
+    /** Any of the one-shot and tyre ids, pointed at other sounds. */
+    readonly sounds?: Partial<VehicleSoundKeys>;
+    /** Seconds the starter turns before the engine catches (the `engine_start` recipe catches at 0.75 s). */
+    readonly crankSeconds?: number;
+};
+/** What was asked of the sink, for the checks and the bench: the RPM in use and the level of each loop. */
+type VehicleSoundReading = {
+    readonly running: boolean;
+    readonly rpm: number;
+    readonly levels: Readonly<Record<string, number>>;
+};
+type VehicleSound = {
+    /** Turns the key: the starter, then the engine catches with a flare of RPM. `fail` cranks without catching (no fuel, a dead engine). */
+    start(position: Vec3, options?: {
+        readonly fail?: boolean;
+    }): void;
+    /** Ignition off: the engine runs down. */
+    stop(position: Vec3): void;
+    /** A hit at `speed` m/s: light, medium or heavy by speed, louder with it. */
+    crash(speed: number, position: Vec3): 'light' | 'medium' | 'heavy';
+    update(frame: VehicleSoundFrame): void;
+    readonly reading: VehicleSoundReading;
+    dispose(): void;
+};
+/**
+ * The sounds of one vehicle on a host's sink (`ModuleHost.audio`): the engine loops by RPM and load, the starter, the tyres skidding and rolling,
+ * and crashes by speed. The loops are placed at the vehicle every frame (distance and side come from the sink). Works without a sink (silent).
+ */
+declare function createVehicleSound(audio: AudioSink | undefined, options?: VehicleSoundOptions): VehicleSound;
+
 /**
  * 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,
@@ -113,135 +151,19 @@ declare function fuse(THREE: any, c: any, pivot: any, paintColor: any, primary:
 /** 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;
-/** 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 = {
-    /** `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[];
-    /** 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 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>;
-    };
+/** Past this distance (m) an untouched vehicle draws fused: nobody sees a door seam from here, and the full model costs hundreds of draw calls. */
+declare const VEHICLE_LOD_DISTANCE = 14;
+type VehicleLodOptions = {
+    /** The clock (ms) the quiet time is read from (default `performance.now`). */
+    readonly now?: () => number;
 };
-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;
+type VehicleLod = {
+    /** `touched`: hit or driven, from now on it always draws in full (its damage only exists there); `posed`: a door, hood or lid is open now (fused only while all are shut). */
+    update(distance: number, touched: boolean, posed?: boolean): void;
+    readonly fused: boolean;
+    dispose(): void;
 };
-/**
- * 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>>;
+/** Shows `full` near and the kit's fused light mode (one mesh per class of material) far, in `root`'s own space. Hit tests read the full model, visible or not. */
+declare function createVehicleLod(kit: any, context: any, root: any, full: any, options?: VehicleLodOptions): VehicleLod;
 
-export { type BuildVehicleOptions, type BuiltVehicle, type CabinSmoke, DEFAULT_TEST_VEHICLES, DEFAULT_TEST_WRECKS, 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 VehicleWreck, type VehiclesContext, type VehiclesRoom, type VehiclesTestOptions, type VehiclesThree, type VehiclesThreeOptions, classColor, classify, createCabinSmoke, createVehiclesTestModule, createVehiclesThree, defaultEffectIds, defaultSoundIds, fuse, liteMaterials, liteMeshes, loadVehiclesTestModule };
+export { type CabinSmoke, type EngineLayerSetting, type EngineMixInput, EngineProfile, LITE_CLASSES, type LiteClass, type LiteFusion, PRUNE_BELOW, VEHICLE_LOD_DISTANCE, VEHICLE_LOOPS, VEHICLE_LOOP_FALLOFF, VEHICLE_SOUNDS, VEHICLE_SOUND_BANK, type VehicleLod, type VehicleSound, type VehicleSoundFrame, VehicleSoundKeys, type VehicleSoundOptions, type VehicleSoundReading, classColor, classify, createCabinSmoke, createGearGuess, createVehicleLod, createVehicleSound, engineMix, firingHz, fuse, layerWeight, liteMaterials, liteMeshes, rpmShare };