@adatechnology/game-vehicles-three 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -1,6 +1,9 @@
-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 } 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
@@ -23,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,
@@ -64,6 +153,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 +164,6 @@ 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;
 
-export { type CabinSmoke, LITE_CLASSES, type LiteClass, type LiteFusion, PRUNE_BELOW, VEHICLE_LOD_DISTANCE, type VehicleLod, classColor, classify, createCabinSmoke, createVehicleLod, fuse, liteMaterials, liteMeshes };
+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 };