@adatechnology/game-vehicles 0.5.0 → 0.6.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { MaterialId, Vec3, JointKind, ToolKind, DestructibleImpl, AnimationClipSpec, IgnitionRules, ObjectState, Enclosure } from '@adatechnology/game-contracts';
+import { MaterialId, Vec3, JointKind, ToolKind, DeferredQueue, DestructibleImpl, AnimationClipSpec, IgnitionRules, DestructionEvent, ObjectState, Enclosure } from '@adatechnology/game-contracts';
 
 /**
  * Light mode ("lite"): the same vehicles with fewer triangles, for a whole street of them. Port of the `[LOD]` hooks of the team's Frota Leve
@@ -39,6 +39,18 @@ declare function createLod(options?: Partial<LodSettings>): LodSettings;
  */
 declare function wrapThreeForLod(TH: any, lod: LodSettings): any;
 
+/** Smoke, fire and dust puffs handed to the host's effects world instead of the kit's own sprites. */
+/** What `EffectSink.play` of `game-contracts` takes, as a structural type: this package does not depend on the contracts layer. */
+interface ParticleEffectRequest {
+    readonly effect: string;
+    readonly point: [number, number, number];
+    readonly values: Readonly<Record<string, number>>;
+}
+/** The host's effects world as far as the puffs need it (`EffectSink` of `game-contracts` fits). */
+interface ParticleEffects {
+    play(request: ParticleEffectRequest): unknown;
+}
+
 /**
  * Damageable parts: what a bullet, a bat or a crash can hurt on a built vehicle, as boxes. Port of `coletarDanificaveis` and `tipoDaZona`
  * (frota-leve.js 14391-14405), driven by the zones the kit already derives, so it works for any vehicle of any pack.
@@ -571,8 +583,25 @@ interface VehicleKitOptions extends KitConfiguration {
     locale?: string | PartialLocaleStrings;
     /** Document used for canvas textures and the UI. Defaults to the global `document`. */
     document?: Document;
+    /**
+     * Where the material of every smoke, fire and dust puff comes from and goes back to: puffs change their own material every frame (opacity, rotation, dissolve), so each keeps one, but
+     * handing them to the host's pool keeps the shader program linked when the last puff dies. Without it each puff makes and disposes its own (deprecated, removed in the next major).
+     */
+    particleMaterials?: ParticleMaterials;
+    /**
+     * The host's effects world, read at each puff (the host attaches after the first build). With one, smoke, fire and dust go through it and its one budget; without one the kit draws its own
+     * sprites with their own cap (deprecated, removed in the next major).
+     */
+    effects?: () => ParticleEffects | undefined;
     plugins?: Plugin[];
 }
+/** What the host's material pool (`MaterialPool` of `@adatechnology/game-render-three`) lends the particles: a structural type, because this package does not depend on the render layer. */
+interface ParticleMaterials {
+    /** Makes (with `build`) a material the caller owns and changes per frame. */
+    own<TMaterial>(build: () => TMaterial): TMaterial;
+    /** Gives it back: the first of its program family is kept alive, the others are disposed. */
+    release(material: unknown): void;
+}
 interface ImpactOptions {
     /** Do not leave a stain. */
     noStain?: boolean;
@@ -755,6 +784,30 @@ declare function rng(seed: number): () => number;
 /** FNV-1a hash of a string, used to derive seeds from vehicle keys and zone ids. */
 declare function strHash(s: string): number;
 
+/**
+ * Armour levels of a vehicle, after NIJ 0108: the level says which rounds the glass and the steel stop, and how many hits they take
+ * before they give. Every number is configurable: a game passes its own table in `VehicleDestructibleOptions.armourLevels`.
+ */
+type ArmourLevelId = 'IIIA' | 'III';
+type ArmourLevel = {
+    /** Energy in joules a round needs to go through the armoured glass. */
+    readonly glassStops: number;
+    /** Joules of hits the armoured glass takes before it gives way. */
+    readonly glassHp: number;
+    /** Share of a stopped round's energy the glass takes as damage (it cracks round the hit and holds). */
+    readonly glassTakes: number;
+    /** How much harder the steel skin is than a plain car's. */
+    readonly steel: number;
+};
+/** IIIA: civilian armour, stops handguns up to .44 Magnum, a rifle goes through. III: armour against rifles up to 7.62x51 (cash in transit, military). */
+declare const ARMOUR_LEVELS: Readonly<Record<ArmourLevelId, ArmourLevel>>;
+/** The level a vehicle has: the host's option, else its spec (`armor`), else III for the old `armored`/`bullet` flags, else none. */
+declare function armourLevelOf(meta: {
+    armor?: string;
+    armored?: boolean;
+    bullet?: boolean;
+}, option?: ArmourLevelId | null): ArmourLevelId | null;
+
 /**
  * Part and joint model of a vehicle for the destruction contract: every damage zone becomes a part with a material, the mechanical parts the
  * zones do not cover (battery, alternator, gearbox, brakes, steering, shock absorbers, tow hitch, tyres, mirrors, pillars...) are added from the
@@ -782,6 +835,8 @@ interface PartDef {
     hp: number;
     /** The damage zone this part is, when it is one. */
     zoneId?: string;
+    /** The panes of a glass part no damage zone claims. */
+    panes?: any[];
     /** Fluid held, in litres. */
     contains?: {
         fluid: string;
@@ -791,7 +846,8 @@ interface PartDef {
     explodes?: {
         energy: number;
         radius: number;
-        atC: number;
+        atC: number; /** The named explosion of game-vfx it plays (its fireball and its sound). */
+        effect?: string;
     };
     /** Temperature in Celsius at which the part catches fire (none: it does not burn). */
     ignitionC?: number;
@@ -820,6 +876,8 @@ interface VehicleModel {
 interface ModelOptions {
     /** Fit a tow hitch. Default: the spec flag `hitch`, else a seeded choice by vehicle kind. */
     hitch?: boolean;
+    /** Armour of the vehicle: its glass is laminated and as strong as the level says. */
+    armour?: ArmourLevel | null;
 }
 /** Joint kinds as the vehicle uses them: strength in joules of wear, the tools that undo them and the seconds of work. */
 declare const JOINT_RULES: Record<'hinge' | 'bolt' | 'weld' | 'glue' | 'clip', {
@@ -827,9 +885,31 @@ declare const JOINT_RULES: Record<'hinge' | 'bolt' | 'weld' | 'glue' | 'clip', {
     tools: ToolKind[];
     seconds: number;
 }>;
-/** Builds the part and joint model of a built vehicle. */
 declare function buildVehicleModel(kit: VehicleKit, c: VehicleContext, options?: ModelOptions): VehicleModel;
 
+/** What one vehicle's visuals give the shared crease queue: the normal smoothing and the triangle indexes still to finish. */
+interface CreaseWork {
+    /** Units waiting; 0 in the frame a panel was torn (that frame already paid for the cut). `frame` is the budget's frame counter. */
+    pendingUnits(frame?: number): number;
+    /** Runs one slice of the work (a smoothing step or a piece of the index warm-up) until `deadline` on `performance.now()`; false when there was nothing to run. */
+    runStep(deadline: number): boolean;
+    /** Finishes everything now. */
+    finishAll(): void;
+    /** While true the vehicle's own update leaves the work to the queue. */
+    setQueued(isQueued: boolean): void;
+}
+interface CreaseQueue {
+    /** The queue for a frame budget (id `vehicles.crease`, `DEFERRED_PRIORITY['vehicles.crease']`); asking for it changes nothing. */
+    deferredQueue(): DeferredQueue;
+    /** A vehicle's visuals join the queue; returns the function that takes them out (a rebuilt vehicle, a vehicle that goes away). */
+    track(work: CreaseWork): () => void;
+}
+/**
+ * One queue for every vehicle of a scene, run round robin over the vehicles with work, so that the first vehicle does not take the whole budget.
+ * Until a budget attaches it, each vehicle keeps smoothing in its own `update`.
+ */
+declare function createCreaseQueue(): CreaseQueue;
+
 /**
  * `createVehicleDestructible`: a vehicle that follows the destruction contract of `@adatechnology/game-contracts` and brings its own rules.
  * Every damage zone and mechanical part is a part with a material, hits become events (dent, hole, crack, fracture, detach, leak, ignite,
@@ -860,6 +940,15 @@ interface VehicleDestructibleOptions {
      * Defaults and meaning of every number: `IgnitionRules` of `@adatechnology/game-contracts`.
      */
     ignition?: Partial<IgnitionRules>;
+    /** Armour level of this vehicle (`IIIA` civilian, `III` against rifles), or null for none. Default: its spec. */
+    armour?: ArmourLevelId | null;
+    /** Replaces or extends the armour table. */
+    armourLevels?: Partial<Record<ArmourLevelId, ArmourLevel>>;
+    /**
+     * One queue that smooths the normals of cut panels for every vehicle that shares it (`createCreaseQueue()`), run by a frame budget. Without it, or while
+     * nobody registered the queue with a budget, each vehicle smooths in its own `update` (2.5 ms a frame), as always.
+     */
+    creaseQueue?: CreaseQueue;
 }
 /** What the vehicle can do now, from the state of its hidden mechanics. */
 interface VehicleStatus {
@@ -894,7 +983,31 @@ interface VehicleDestructible extends DestructibleImpl {
     rollover(side?: number): void;
     /** Part ids that are no longer attached to the main body. */
     detachedParts(): string[];
+    /** What the damage leaves for driving: each tyre's health where it stands, the brakes, the engine and the shocks (0 gone .. 1 whole). */
+    driveReport(): DriveReport;
+    /**
+     * The engine ran for `seconds` at `load` (0 idle .. 1 full throttle): without coolant it heats up, steams and seizes in a few minutes;
+     * without oil it wears and seizes. Call it while the vehicle is driven. Answers the engine temperature, °C.
+     */
+    runEngine(seconds: number, load: number): number;
+    /**
+     * The vehicle rolled `meters` at `speed` m/s: a flat tyre wears through and tears off (a run-flat insert on an armoured vehicle carries it far
+     * at up to 80 km/h), then the bare rim grinds on the road throwing sparks. Answers how many rims are on the road.
+     */
+    rollFlat(meters: number, speed: number): number;
+    /** Pushes the drawn body in by `depth` metres around `point` (world), along `direction`: the crumple of a crash. Drawing only. */
+    crumple(point: Vec3, direction: Vec3, depth: number): void;
 }
+type DriveReport = {
+    readonly tyres: ReadonlyArray<{
+        readonly x: number;
+        readonly z: number;
+        readonly health: number;
+    }>;
+    readonly brakes: number;
+    readonly engine: number;
+    readonly suspension: number;
+};
 declare function createVehicleDestructible(kit: VehicleKit, vehicleCtx: VehicleContext, options?: VehicleDestructibleOptions): VehicleDestructible;
 
 interface VehicleItemOptions {
@@ -917,6 +1030,53 @@ interface VehicleItem {
  */
 declare function buildVehicleItem(kit: VehicleKit, key: string, options?: VehicleItemOptions): VehicleItem;
 
+/**
+ * A vehicle running into something: the energy of the crash, from the masses and the closing speed, becomes blunt hits spread over the
+ * contact. A wide wall crushes the whole front evenly; a pillar or a post goes deep into a narrow strip; a lighter object takes most of
+ * the change of speed and the vehicle little. Every number is configurable through `CrashRules`.
+ */
+
+type CrashRules = {
+    /** Share of the deformation energy each blunt hit carries into the parts (the rest is the crumple of the structure itself). */
+    readonly energyToDamage: number;
+    /** Width one blunt hit stands for, metres. */
+    readonly hitSpacing: number;
+    /** Below this closing speed nothing deforms (a nudge), m/s. */
+    readonly minSpeed: number;
+    /** Heights over the contact point the blow also lands at, metres: the bumper takes it first, the front above it (hood, lights, grille) after. */
+    readonly rows: readonly number[];
+    /** How far the front crushes per m/s of change of speed, metres (a car into a wall at 50 km/h folds about half a metre), and at most. */
+    readonly crushPerMs: number;
+    readonly maxCrush: number;
+};
+declare const CRASH_RULES: CrashRules;
+type CrashOptions = {
+    /** Where the vehicle touched the obstacle, world space. */
+    readonly point: Vec3;
+    /** The way the vehicle was moving into the obstacle, world space. */
+    readonly direction: Vec3;
+    /** Closing speed, m/s. */
+    readonly speed: number;
+    /** Mass of this vehicle, kg. */
+    readonly massKg: number;
+    /** Mass of what it hit, kg (`Infinity` for a wall, a pillar or anything anchored). */
+    readonly otherMassKg: number;
+    /** How wide the contact is, metres (a post 0.2, a wall the whole front). */
+    readonly contactWidth: number;
+    readonly source?: string;
+    readonly rules?: Partial<CrashRules>;
+};
+type CrashResult = {
+    /** Change of speed this vehicle takes, m/s. */
+    readonly deltaV: number;
+    /** Deformation energy this vehicle takes, joules. */
+    readonly energy: number;
+    readonly events: DestructionEvent[];
+};
+/** Change of speed of each body in a plastic collision: the lighter one takes more. */
+declare function crashDeltaV(speed: number, massKg: number, otherMassKg: number): number;
+declare function crashVehicle(d: VehicleDestructible, crash: CrashOptions): CrashResult;
+
 /**
  * The cabin of a vehicle as a closed space for the smoke, dust and steam of the host's effects (`EffectSink.enclose` of the contracts): a shut car
  * keeps the smoke out. It is open where it is in the real world: a door standing open, a window shattered, a door, glass or roof torn off or burnt
@@ -957,4 +1117,9 @@ declare function swingOf(vehicle: VehicleContext, partId: string): number;
  */
 declare function cabinEnclosure(source: CabinSource, options?: CabinEnclosureOptions): Enclosure | null;
 
-export { type Band, type BandId, type BandIndex, type BandOverride, type BuildFunction, type BuildOptions, type BuildState, type BuildZoneState, CABIN_LEAK, type CabinBox, type CabinEnclosureOptions, type CabinSource, type DamageMapOptions, type DamageZone, type Damageable, type DamageableKind, type DamageableMaterial, type DamageableSide, type ExplodeOptions, type FlagEffect, type FluidDefinition, type ImpactOptions, JOINT_RULES, type JointDef, type KitConfiguration, type KitInternals, type KitTexts, LEGACY_STATES, LEGACY_ZONE_IDS, type LocalBox, type LocaleStrings, type LodSettings, type OverallHealth, type PartDef, type PartLabel, type PartRole, type PartialLocaleStrings, type Plugin, type ResolvedConfiguration, SEED_SALTS, type ScenarioContext, type ScenarioDefinition, type ScenarioResult, type SplatOptions, type ThreeObject, type ThreeVector, type Translate, type UiHelpers, type VehicleContext, type VehicleDestructible, type VehicleDestructibleOptions, type VehicleItem, type VehicleItemOptions, type VehicleKit, type VehicleKitOptions, type VehicleMeta, type VehicleModel, type VehiclePart, type VehicleSpec, type VehicleStatus, type ZoneDamageEntry, type ZoneEffect, type ZoneState, buildVehicleItem, buildVehicleModel, cabinBoxOf, cabinEnclosure, clamp, createLod, createTranslate, createVehicleDestructible, createVehicleKit, defaultDamageableKinds, defaultLodSettings, format, hash, legacyGlassId, legacyLightId, legacyZoneId, listLocales, registerLegacySeeds, registerLocale, resolveStrings, rng, smooth, strHash, swingOf, wrapThreeForLod };
+/** Glass cracks, shattering and tempered or laminated breakage textures. */
+
+/** The material of a pane with cracks drawn on it. A host warms its program at load with any texture: the first crack is in the middle of a blast. */
+declare function crackedGlassMaterial(THREE: any, texture: unknown): any;
+
+export { ARMOUR_LEVELS, type ArmourLevel, type ArmourLevelId, type Band, type BandId, type BandIndex, type BandOverride, type BuildFunction, type BuildOptions, type BuildState, type BuildZoneState, CABIN_LEAK, CRASH_RULES, type CabinBox, type CabinEnclosureOptions, type CabinSource, type CrashOptions, type CrashResult, type CrashRules, type CreaseQueue, type CreaseWork, type DamageMapOptions, type DamageZone, type Damageable, type DamageableKind, type DamageableMaterial, type DamageableSide, type DriveReport, type ExplodeOptions, type FlagEffect, type FluidDefinition, type ImpactOptions, JOINT_RULES, type JointDef, type KitConfiguration, type KitInternals, type KitTexts, LEGACY_STATES, LEGACY_ZONE_IDS, type LocalBox, type LocaleStrings, type LodSettings, type OverallHealth, type PartDef, type PartLabel, type PartRole, type PartialLocaleStrings, type ParticleEffectRequest, type ParticleEffects, type ParticleMaterials, type Plugin, type ResolvedConfiguration, SEED_SALTS, type ScenarioContext, type ScenarioDefinition, type ScenarioResult, type SplatOptions, type ThreeObject, type ThreeVector, type Translate, type UiHelpers, type VehicleContext, type VehicleDestructible, type VehicleDestructibleOptions, type VehicleItem, type VehicleItemOptions, type VehicleKit, type VehicleKitOptions, type VehicleMeta, type VehicleModel, type VehiclePart, type VehicleSpec, type VehicleStatus, type ZoneDamageEntry, type ZoneEffect, type ZoneState, armourLevelOf, buildVehicleItem, buildVehicleModel, cabinBoxOf, cabinEnclosure, clamp, crackedGlassMaterial, crashDeltaV, crashVehicle, createCreaseQueue, createLod, createTranslate, createVehicleDestructible, createVehicleKit, defaultDamageableKinds, defaultLodSettings, format, hash, legacyGlassId, legacyLightId, legacyZoneId, listLocales, registerLegacySeeds, registerLocale, resolveStrings, rng, smooth, strHash, swingOf, wrapThreeForLod };