@adatechnology/game-vehicles 0.6.0 → 0.6.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { MaterialId, Vec3, JointKind, ToolKind, DeferredQueue, 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
@@ -784,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
@@ -822,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;
@@ -851,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', {
@@ -913,6 +940,10 @@ 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.
@@ -952,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 {
@@ -975,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
@@ -1020,4 +1122,4 @@ declare function cabinEnclosure(source: CabinSource, options?: CabinEnclosureOpt
 /** 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 { 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 CreaseQueue, type CreaseWork, 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 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, buildVehicleItem, buildVehicleModel, cabinBoxOf, cabinEnclosure, clamp, crackedGlassMaterial, createCreaseQueue, createLod, createTranslate, createVehicleDestructible, createVehicleKit, defaultDamageableKinds, defaultLodSettings, format, hash, legacyGlassId, legacyLightId, legacyZoneId, listLocales, registerLegacySeeds, registerLocale, resolveStrings, rng, smooth, strHash, swingOf, wrapThreeForLod };
+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 };