@adatechnology/game-vehicles-three 0.5.0 → 0.6.1

package/dist/index.d.ts

@@ -1,6 +1,10 @@
-export { B as BuildVehicleOptions, a as BuiltVehicle, D as DEFAULT_TEST_VEHICLES, b as DEFAULT_TEST_WRECKS, c as DocumentLike, E as EffectsLike, F as FleetDims, M as ModuleRoomLike, P as PAGE_ITEM_ALIASES, d as PAGE_SCENARIO_ALIASES, V as VEHICLES_AREA_ID, e as VEHICLE_SCENARIO_IDS, f as VehicleEffectIds, g as VehicleFleetContent, h as VehicleQuality, i as VehicleSoundIds, j as VehicleWreck, k as VehiclesContext, l as VehiclesRoom, m as VehiclesTestFleet, n as VehiclesTestOptions, o as VehiclesThree, p as VehiclesThreeOptions, q as createVehiclesTestModule, r as createVehiclesThree, s as defaultEffectIds, t as defaultSoundIds, u as loadVehiclesTestModule } from './testing-DmGv7Gpb.js';
-import { EffectSink } from '@adatechnology/game-contracts';
+import { E as EngineProfile, V as VehicleSoundKeys, B as BuiltVehicle } from './testing-C-BgV7gj.js';
+export { a as BIKE_ENGINE, b as BuildVehicleOptions, 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-C-BgV7gj.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 { Object3D, CanvasTexture, CircleGeometry, MeshBasicMaterial, Mesh, Vector3 } from 'three';
+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
@@ -23,6 +27,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,
@@ -64,6 +154,10 @@ declare function liteMeshes(THREE: any, fusion: LiteFusion, materials: Record<Li
 
 /** 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 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;
@@ -71,6 +165,170 @@ type VehicleLod = {
     dispose(): void;
 };
 /** 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): VehicleLod;
+declare function createVehicleLod(kit: any, context: any, root: any, full: any, options?: VehicleLodOptions): VehicleLod;
+
+type LampSwitch = {
+    mode: 'off' | 'position' | 'low' | 'high';
+    fog: boolean;
+    interior: boolean;
+    brake: boolean;
+    reverse: boolean;
+    /** Indicator lamps lit this instant (the controls blink them). */
+    left: boolean;
+    right: boolean;
+};
+/** Glow of the lamp glass by switch, as a share of what the kit drew (the kit draws them lit), and the beams. */
+declare const LAMP_RULES: {
+    readonly glow: {
+        readonly head: {
+            readonly off: 0.04;
+            readonly position: 0.3;
+            readonly low: 1;
+            readonly high: 1.35;
+        };
+        readonly tail: {
+            readonly off: 0.15;
+            readonly on: 0.7;
+            readonly brake: 1.6;
+        };
+        readonly fog: {
+            readonly off: 0.04;
+            readonly on: 1.1;
+        };
+        readonly amber: {
+            readonly off: 0.1;
+            readonly on: 2.2;
+        };
+    };
+    readonly low: {
+        readonly color: 16773584;
+        readonly intensity: 2.4;
+        readonly distance: 32;
+        readonly angle: 0.42;
+        readonly penumbra: 0.55;
+        readonly decay: 1.6;
+        readonly drop: 0.09;
+    };
+    readonly high: {
+        readonly color: 16774882;
+        readonly intensity: 3.6;
+        readonly distance: 70;
+        readonly angle: 0.3;
+        readonly penumbra: 0.45;
+        readonly decay: 1.4;
+        readonly drop: 0.015;
+    };
+    readonly fog: {
+        readonly color: 16773320;
+        readonly intensity: 1.6;
+        readonly distance: 16;
+        readonly angle: 0.75;
+        readonly penumbra: 0.7;
+        readonly decay: 1.8;
+        readonly drop: 0.12;
+    };
+    readonly reverse: {
+        readonly color: 16054015;
+        readonly intensity: 0.9;
+        readonly distance: 7;
+        readonly decay: 2;
+    };
+    readonly interior: {
+        readonly color: 16769712;
+        readonly intensity: 0.5;
+        readonly distance: 2.4;
+        readonly decay: 2;
+    };
+};
+interface VehicleLamps {
+    /** What this vehicle has: fog lamps only when the kit drew them. */
+    readonly has: {
+        head: boolean;
+        tail: boolean;
+        fog: boolean;
+        indicators: boolean;
+    };
+    set(lamps: LampSwitch): void;
+    readonly state: LampSwitch;
+    dispose(): void;
+}
+declare function createVehicleLamps(THREE: {
+    Object3D: new () => Object3D;
+}, built: BuiltVehicle, options?: {
+    lights?: unknown;
+    owner?: string;
+}): VehicleLamps;
+
+/** What the cluster shows this instant. */
+type DashboardReading = {
+    kmh: number;
+    rpm: number;
+    /** -1 reverse, 0 neutral, 1.. forward. */
+    gear: number;
+    ignition: boolean;
+    engineOn: boolean;
+    left: boolean;
+    right: boolean;
+    highBeam: boolean;
+    lowBeam: boolean;
+    fog: boolean;
+    parkingBrake: boolean;
+    seatbelt: boolean;
+    fourWheel: boolean;
+    /** Engine temperature, 0 (cold) to 1 (overheating); leave out while the engine has no heat model. */
+    temperature?: number;
+    /** Fuel, 0 (empty) to 1 (full); leave out while the vehicle has no fuel model. */
+    fuel?: number;
+};
+/** The scale of the dials and how often the faces are redrawn. */
+type DashboardOptions = {
+    /** The kit's dial material (`kit.materials.gauge`): the dials are found by it. */
+    gauge: unknown;
+    /** The kit's needle material (`kit.materials.amber`): the fixed needles drawn on the dials hide while the live face shows. */
+    needle?: unknown;
+    /** Top of the speedometer, km/h. Default 220. */
+    maxKmh?: number;
+    /** Red line of the rev counter. Default 6500. */
+    redlineRpm?: number;
+    /** Redraws per second at most. Default 15. */
+    fps?: number;
+    /** Where the canvases come from (tests pass a fake one). Default the page's. */
+    document?: {
+        createElement(tag: 'canvas'): HTMLCanvasElement;
+    };
+};
+interface VehicleDashboard {
+    /** How many dials were found (0: a vehicle without a cluster drawn, nothing to show). */
+    readonly dials: number;
+    update(reading: DashboardReading, dt: number): void;
+    dispose(): void;
+}
+type ThreeLib = {
+    CanvasTexture: new (canvas: HTMLCanvasElement) => CanvasTexture;
+    CircleGeometry: new (radius: number, segments: number) => CircleGeometry;
+    MeshBasicMaterial: new (p: {
+        map: CanvasTexture;
+        transparent: boolean;
+        toneMapped: boolean;
+        depthWrite: boolean;
+    }) => MeshBasicMaterial;
+    Mesh: new (g: CircleGeometry, m: MeshBasicMaterial) => Mesh;
+    Vector3: new (x?: number, y?: number, z?: number) => Vector3;
+};
+/** The colours of the cluster: the warning lights by the usual code (red stop, amber caution, green and blue information). */
+declare const DASHBOARD_LOOK: {
+    readonly face: "#0b1110";
+    readonly ring: "#2f3a36";
+    readonly marks: "#cfe8dc";
+    readonly needle: "#ff6a2a";
+    readonly red: "#e2402f";
+    readonly amber: "#f2a630";
+    readonly green: "#46d16f";
+    readonly blue: "#3f8cff";
+    readonly dim: "rgba(207,232,220,0.12)";
+    /** How far in front of the kit's dial the face sits, metres (the kit's needle sticks out 6 mm). */
+    readonly lift: 0.011;
+};
+declare function createVehicleDashboard(THREE: ThreeLib, built: BuiltVehicle, options: DashboardOptions): VehicleDashboard;
 
-export { type CabinSmoke, LITE_CLASSES, type LiteClass, type LiteFusion, PRUNE_BELOW, VEHICLE_LOD_DISTANCE, type VehicleLod, classColor, classify, createCabinSmoke, createVehicleLod, fuse, liteMaterials, liteMeshes };
+export { BuiltVehicle, type CabinSmoke, DASHBOARD_LOOK, type DashboardOptions, type DashboardReading, type EngineLayerSetting, type EngineMixInput, EngineProfile, LAMP_RULES, LITE_CLASSES, type LampSwitch, type LiteClass, type LiteFusion, PRUNE_BELOW, VEHICLE_LOD_DISTANCE, VEHICLE_LOOPS, VEHICLE_LOOP_FALLOFF, VEHICLE_SOUNDS, VEHICLE_SOUND_BANK, type VehicleDashboard, type VehicleLamps, type VehicleLod, type VehicleSound, type VehicleSoundFrame, VehicleSoundKeys, type VehicleSoundOptions, type VehicleSoundReading, classColor, classify, createCabinSmoke, createGearGuess, createVehicleDashboard, createVehicleLamps, createVehicleLod, createVehicleSound, engineMix, firingHz, fuse, layerWeight, liteMaterials, liteMeshes, rpmShare };