@adatechnology/game-vehicles-three 0.7.0 → 0.8.1

package/dist/index.d.ts

@@ -1,9 +1,11 @@
-import { E as EngineProfile, V as VehicleSoundKeys, B as BuiltVehicle } from './testing-DI0_R8dH.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-DI0_R8dH.js';
+import { E as EngineProfile, V as VehicleSoundKeys, B as BuiltVehicle } from './testing-Cb10i9fm.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-Cb10i9fm.js';
 import { EffectSink, Vec3, AudioSink, AnimationClipSpec } from '@adatechnology/game-contracts';
-import { CabinSource } from '@adatechnology/game-vehicles';
+import { CabinSource, VehicleContext } from '@adatechnology/game-vehicles';
 import { LoopRecipe, Falloff, SampleAlias, SoundRecipe, SoundBank } from '@adatechnology/game-audio';
-import { Object3D, CanvasTexture, CircleGeometry, MeshBasicMaterial, Mesh, Vector3 } from 'three';
+import * as THREE_NS from 'three';
+import { Texture, Material, Color, Object3D, Matrix4, MeshStandardMaterial, MeshBasicMaterial, Mesh, CanvasTexture, CircleGeometry, Vector3, BufferGeometry, Side } from 'three';
+import '@adatechnology/game-vehicles-driving';
 import '@adatechnology/game-vehicles-proving';
 
 /**
@@ -43,6 +45,8 @@ declare const CAR_RECORDED_RPM: {
 };
 /** Where the start and the stop sit in the recording of a car starting, running and stopping (`engine_start_run_stop`), in seconds. */
 declare const CAR_START_RUN_STOP: {
+    /** The take the times below were measured on. */
+    readonly take: "_01.";
     /** The starter and the engine catching (at 0.58 s) and flaring; the loops take over at the crank time of the vehicle. */
     readonly start: {
         readonly offset: 0;
@@ -61,8 +65,32 @@ declare const CAR_START_RUN_STOP: {
  * recording yet.
  */
 declare const VEHICLE_SAMPLE_ALIASES: readonly SampleAlias[];
+/** The ids a host should decode as the vehicles load (`AudioSink.preload`): every aliased recording and the door's own file id. */
+declare const VEHICLE_PRELOAD_SOUNDS: readonly string[];
 declare const VEHICLE_SOUND_BANK: SoundBank;
 
+/** How many vehicles are heard at once: the nearest `max` to the listener keep their loops, the others are silent until they come closer. */
+type EngineBudget = {
+    /** Reports where a vehicle is this frame; true when it is among the nearest `max` (it may sound). */
+    admit(vehicle: object, position: Vec3): boolean;
+    /** Forgets a vehicle (it left the scene). */
+    release(vehicle: object): void;
+    /** Vehicles being tracked. */
+    readonly size: number;
+};
+type EngineBudgetOptions = {
+    /** Default 6: a street of idling cars is a hum, not a wall of a hundred engines. */
+    readonly max?: number;
+    /** Where the listener is (the camera or the player). */
+    readonly listener: () => Vec3;
+};
+/**
+ * A level of detail for vehicle sound, shared by every `createVehicleSound` of a scene (`VehicleSoundOptions.budget`): each vehicle reports its
+ * place every frame and only the nearest `max` keep their engine and tyre loops. A vehicle that falls out fades its loops to silence; its one-shots
+ * (a crash, the starter) still play, since they are rare and the engine's voice limiter already ranks them.
+ */
+declare function createEngineBudget(options: EngineBudgetOptions): EngineBudget;
+
 /** 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;
@@ -108,6 +136,12 @@ type VehicleSoundFrame = {
     readonly slip?: number;
     /** What the tyres are on: `dirt` for earth, gravel, sand or grass; anything else squeals as asphalt. */
     readonly surface?: 'asphalt' | 'dirt';
+    /** 0..1, how hard the brakes are pressed: the pads squeal as the car comes to a stop without skidding. */
+    readonly brake?: number;
+    /** An emergency vehicle's siren: `wail` sweeps 650–1500 Hz in ~4 s, `yelp` in a quarter second; absent or `off`, silent. */
+    readonly siren?: 'off' | 'wail' | 'yelp';
+    /** 0..1, how fast a helicopter's rotor turns (the blades spool up and down with it). */
+    readonly rotor?: number;
 };
 type VehicleSoundOptions = {
     readonly profile?: EngineProfile;
@@ -115,6 +149,8 @@ type VehicleSoundOptions = {
     readonly sounds?: Partial<VehicleSoundKeys>;
     /** Seconds the starter turns before the engine catches (the `engine_start` recipe catches at 0.75 s). */
     readonly crankSeconds?: number;
+    /** Shared by the vehicles of a scene: only the nearest few keep their loops (`createEngineBudget`). */
+    readonly budget?: EngineBudget;
 };
 /** What was asked of the sink, for the checks and the bench: the RPM in use and the level of each loop. */
 type VehicleSoundReading = {
@@ -131,6 +167,8 @@ type VehicleSound = {
     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';
+    /** A body hit at `speed` m/s (a person, an animal; `sound` names another id, a zombie in a game), louder with the speed. */
+    hit(speed: number, position: Vec3, sound?: string): void;
     update(frame: VehicleSoundFrame): void;
     readonly reading: VehicleSoundReading;
     dispose(): void;
@@ -146,11 +184,30 @@ declare function createVehicleSound(audio: AudioSink | undefined, options?: Vehi
  * 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.
  */
+
+type Three = typeof THREE_NS;
 /** 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;
+/** A material of the built vehicle as the fusion reads it (standard, basic or line materials alike). */
+type LiteSourceMaterial = Material & {
+    map?: Texture | null;
+    color: Color;
+    metalness?: number;
+    roughness?: number;
+    emissive?: Color;
+    emissiveIntensity?: number;
+    isMeshBasicMaterial?: boolean;
+};
+/** What the fusion reads of the built vehicle: its root and the paints (`c.paints`). */
+interface LiteSource {
+    vehicle: Object3D;
+    paints?: ReadonlySet<Material> | null;
+}
+/** A material of the fused vehicle (`liteMaterials`). */
+type LiteMaterial = MeshStandardMaterial | MeshBasicMaterial;
 interface Accumulator {
     P: number[];
     N: number[];
@@ -160,25 +217,25 @@ interface Accumulator {
     nv: number;
     alpha: boolean;
     uv: boolean;
-    map: any;
+    map: Texture | null | undefined;
 }
 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;
+declare function classify(mat: LiteSourceMaterial, mesh: Object3D, c: LiteSource): 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;
+declare function classColor(mat: LiteSourceMaterial, cls: LiteClass, primary: Material | null | undefined, paintColor: Color | null | undefined, out: Color): Color;
 /** 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>;
+declare function liteMaterials(THREE: Three, environment: Texture | null): Record<LiteClass, LiteMaterial>;
 /**
  * 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;
+declare function fuse(THREE: Three, c: LiteSource, pivot: Matrix4, paintColor: Color | null, primary: Material | null | undefined, hidden: ReadonlySet<Material>): LiteFusion;
 /** One mesh per class that has triangles. */
-declare function liteMeshes(THREE: any, fusion: LiteFusion, materials: Record<LiteClass, any>): any[];
+declare function liteMeshes(THREE: Three, fusion: LiteFusion, materials: Record<LiteClass, LiteMaterial>): Mesh[];
 
 /** 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;
@@ -192,8 +249,14 @@ type VehicleLod = {
     readonly fused: boolean;
     dispose(): void;
 };
+/** What the level of detail reads of the vehicle kit: its three.js, the materials nobody sees from outside and the studio environment. */
+type VehicleLodKit = {
+    readonly THREE: typeof THREE_NS;
+    lodHiddenMaterials(): ReadonlySet<Material>;
+    studioEnvironment(): Texture | null;
+};
 /** 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;
+declare function createVehicleLod(kit: VehicleLodKit, context: VehicleContext, root: Object3D, full: Object3D, options?: VehicleLodOptions): VehicleLod;
 
 type LampSwitch = {
     mode: 'off' | 'position' | 'low' | 'high';
@@ -204,6 +267,8 @@ type LampSwitch = {
     /** Indicator lamps lit this instant (the controls blink them). */
     left: boolean;
     right: boolean;
+    /** The beacon: the side lit this instant (0 or 1), null with it off. Default off. */
+    beacon?: 0 | 1 | null;
 };
 /** 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: {
@@ -227,6 +292,11 @@ declare const LAMP_RULES: {
             readonly off: 0.1;
             readonly on: 2.2;
         };
+        readonly beacon: {
+            readonly off: 0.35;
+            readonly dark: 0.12;
+            readonly lit: 2.8;
+        };
     };
     readonly low: {
         readonly color: 16773584;
@@ -275,6 +345,7 @@ interface VehicleLamps {
         tail: boolean;
         fog: boolean;
         indicators: boolean;
+        beacon: boolean;
     };
     set(lamps: LampSwitch): void;
     readonly state: LampSwitch;
@@ -474,4 +545,43 @@ declare const DASHBOARD_LOOK: {
 };
 declare function createVehicleDashboard(THREE: ThreeLib, built: BuiltVehicle, options: DashboardOptions): VehicleDashboard;
 
-export { type BodyEvent, type BodyThree, BuiltVehicle, CAR_RECORDED_RPM, CAR_START_RUN_STOP, 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_SAMPLE_ALIASES, VEHICLE_SOUNDS, VEHICLE_SOUND_BANK, type VehicleBody, type VehicleBodyOptions, type VehicleDashboard, type VehicleLamps, type VehicleLod, type VehicleSound, type VehicleSoundFrame, VehicleSoundKeys, type VehicleSoundOptions, type VehicleSoundReading, type WheelRoll, type WheelRollThree, type WindowId, classColor, classify, createCabinSmoke, createGearGuess, createVehicleBody, createVehicleDashboard, createVehicleLamps, createVehicleLod, createVehicleSound, createWheelRoll, engineMix, firingHz, fuse, layerWeight, liteMaterials, liteMeshes, rpmShare };
+/**
+ * The mist on the inside of a built vehicle's glass, drawn from the fog share of `createWindshieldFog` (`game-vehicles-driving`). Each pane the kit drew
+ * (`context.glass`) gets a thin pale film that follows it (a side window going down, a door swinging), on the pane's own geometry; the windshield shows
+ * the whole share and the other panes a little less, since the demister blows on the windshield first. The film is never hit by a shot (it has no
+ * raycast) and never writes depth. `dispose` takes the films away and frees their materials; the geometry is the pane's and stays.
+ */
+
+/** What the mist needs of three.js. */
+type MistThree = {
+    Mesh: new (geometry: BufferGeometry, material: Material) => Mesh;
+    MeshBasicMaterial: new (parameters: {
+        color: number;
+        transparent: boolean;
+        opacity: number;
+        depthWrite: boolean;
+        side: Side;
+        polygonOffset: boolean;
+        polygonOffsetFactor: number;
+        polygonOffsetUnits: number;
+    }) => Material & {
+        opacity: number;
+    };
+};
+/** How the mist looks: its colour, how opaque full fog is, and the share of it on the side and rear panes. */
+declare const MIST_RULES: {
+    readonly color: 15001836;
+    readonly opacity: 0.72;
+    readonly others: 0.8;
+};
+interface WindshieldMist {
+    /** Panes with a film. */
+    readonly panes: number;
+    /** Shows `fog` (0 clear to 1 misted over). */
+    set(fog: number): void;
+    readonly fog: number;
+    dispose(): void;
+}
+declare function createWindshieldMist(THREE: MistThree, built: BuiltVehicle): WindshieldMist;
+
+export { type BodyEvent, type BodyThree, BuiltVehicle, CAR_RECORDED_RPM, CAR_START_RUN_STOP, type CabinSmoke, DASHBOARD_LOOK, type DashboardOptions, type DashboardReading, type EngineBudget, type EngineBudgetOptions, type EngineLayerSetting, type EngineMixInput, EngineProfile, LAMP_RULES, LITE_CLASSES, type LampSwitch, type LiteClass, type LiteFusion, MIST_RULES, type MistThree, PRUNE_BELOW, VEHICLE_LOD_DISTANCE, VEHICLE_LOOPS, VEHICLE_LOOP_FALLOFF, VEHICLE_PRELOAD_SOUNDS, VEHICLE_SAMPLE_ALIASES, VEHICLE_SOUNDS, VEHICLE_SOUND_BANK, type VehicleBody, type VehicleBodyOptions, type VehicleDashboard, type VehicleLamps, type VehicleLod, type VehicleLodKit, type VehicleSound, type VehicleSoundFrame, VehicleSoundKeys, type VehicleSoundOptions, type VehicleSoundReading, type WheelRoll, type WheelRollThree, type WindowId, type WindshieldMist, classColor, classify, createCabinSmoke, createEngineBudget, createGearGuess, createVehicleBody, createVehicleDashboard, createVehicleLamps, createVehicleLod, createVehicleSound, createWheelRoll, createWindshieldMist, engineMix, firingHz, fuse, layerWeight, liteMaterials, liteMeshes, rpmShare };