@adatechnology/game-vehicles 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,824 @@
+import { ToolKind, JointKind, Vec3, MaterialId, DestructibleImpl, AnimationClipSpec } from '@adatechnology/game-contracts';
+
+var plate = {
+	band: "BRAZIL"
+};
+var parts = {
+	tire_front: "Front {side} tire",
+	tire_rear: "Rear {side} tire",
+	bike_tire_front: "Front tire",
+	bike_tire_rear: "Rear tire",
+	headlight: "{Side} headlight",
+	taillight: "{Side} taillight",
+	led_bar: "LED bar",
+	taillight_bar: "Taillight bar",
+	hood: "Hood",
+	engine: "Engine",
+	engine_electric: "Electric motor and inverter",
+	radiator: "Radiator",
+	bumper_front: "Front bumper",
+	bumper_rear: "Rear bumper",
+	fuel_tank: "Fuel tank",
+	diesel_tank: "Diesel tank",
+	windshield: "Windshield",
+	rear_window: "Rear window",
+	window_front: "Front window",
+	window_rear: "Rear window",
+	quarter_glass: "Rear quarter glass",
+	cab_window: "Cab window",
+	window: "Window",
+	glass: "Glass",
+	glass_side: "{label} ({side})",
+	glass_side_m: "{label} ({side})",
+	track: "{Side} track"
+};
+var texts = {
+	high_voltage: "HIGH VOLTAGE",
+	who: "whoever is on that side",
+	no_effect: ""
+};
+var blast = {
+	lethal: "Lethal radius {m} m",
+	injury: "Injuries up to {m} m",
+	tank_explosion: "Tank explosion",
+	explosion: "Explosion"
+};
+var zones = {
+	windshield: "Windshield",
+	glass_left: "Left side glass",
+	glass_right: "Right side glass",
+	rear_window: "Rear window",
+	light_bar_front: "Front light bar",
+	taillight: "Taillight",
+	light_bar_rear: "Taillight bar",
+	headlight: "{Side} headlight",
+	taillight_side: "{Side} taillight",
+	wheels: "Wheels",
+	wheels_axle_front: "Front axle wheels",
+	wheels_axle_rear: "Rear axle wheels",
+	wheels_axle_n: "Axle {n} wheels",
+	wheel_front_side: "Front {side} wheel",
+	wheel_rear_side: "Rear {side} wheel",
+	wheel_front: "Front wheel",
+	wheel_rear: "Rear wheel",
+	bumper_front: "Front bumper",
+	bumper_rear: "Rear bumper",
+	hood: "Hood",
+	fender_front: "Front {side} fender",
+	door_front: "Front {side} door",
+	door: "{Side} door",
+	door_rear: "Rear {side} door",
+	side_rear: "Rear {side} side panel",
+	roof: "Pillars and roof",
+	cargo_bed: "Cargo bed",
+	trunk_lid: "Trunk lid",
+	tail_lid: "Rear lid",
+	underbody: "Underbody and suspension",
+	engine: "Engine",
+	engine_electric: "Electric motor",
+	radiator: "Radiator",
+	fuel_tank: "Fuel tank",
+	battery: "Battery",
+	diesel_tank: "Diesel tank",
+	fairing: "Fairing and headlight",
+	handlebar_levers: "Handlebar and levers",
+	tank: "Tank",
+	seat_rack: "Seat and rack",
+	handlebar: "Handlebar",
+	frame: "Frame",
+	seat_tail: "Seat and tail",
+	exhaust: "Exhaust",
+	grille_front: "Grille and front",
+	engine_hood: "Engine hood",
+	fender_rear: "Rear {side} fender",
+	operator_station: "Operator station",
+	bus_front: "Bus front",
+	cab_front: "Cab (front)",
+	bus_front_side: "Front, {side} side",
+	cab_side: "Cab, {side} side",
+	body_saloon: "Saloon",
+	body_tank: "Tank",
+	body_body: "Body",
+	body_box: "Box",
+	body_side: "{label} ({side} side)",
+	body_rear: "{label} (rear)",
+	chassis: "Chassis",
+	armor_front: "Front armor",
+	armor_side: "{Side} armor",
+	armor_rear: "Rear armor",
+	cannon: "Cannon",
+	weapon: "Weapon",
+	turret: "Roof and turret",
+	track: "{Side} track",
+	wheels_side: "{Side} side wheels",
+	bow: "Bow",
+	port_side: "Port side",
+	starboard_side: "Starboard side",
+	stern: "Stern",
+	deck: "Deck and cabin",
+	outboard_engine: "Outboard engine",
+	nose_propeller: "Nose and propeller",
+	nose_engine: "Nose and engine",
+	cabin_glass: "Cabin and glass",
+	wing: "{Side} wing",
+	rear_fuselage: "Rear fuselage",
+	tail: "Tail",
+	landing_gear: "Landing gear",
+	wing_tanks: "Tanks (in the wings)",
+	nose_bubble: "Nose and bubble",
+	cabin: "Cabin",
+	tail_cone: "Tail cone",
+	main_rotor: "Main rotor",
+	tail_rotor: "Tail rotor",
+	skids: "Skids",
+	engine_transmission: "Engine and transmission",
+	front: "Front",
+	side: "{Side} side",
+	rear: "Rear",
+	top: "Roof"
+};
+var who = {
+	front_seats: "whoever rides in front",
+	rear_seats: "whoever rides in the back",
+	driver: "the driver",
+	passenger: "the front passenger",
+	rear_left: "whoever rides in the back on the left",
+	rear_right: "whoever rides in the back on the right",
+	left_side: "whoever is on the left side",
+	right_side: "whoever is on the right side",
+	cargo: "the cargo",
+	tractor_driver: "the tractor driver",
+	boarding_door: "the boarding door",
+	helper: "the helper",
+	seated_side: "whoever is seated on that side",
+	back_seats: "whoever rides at the back",
+	crew_side: "the crew on that side",
+	boat_side: "whoever is on that side of the boat",
+	pilot: "the pilot",
+	passengers: "the passengers"
+};
+var bands = {
+	intact: "Intact",
+	scratched: "Scratched",
+	dented: "Dented",
+	destroyed: "Destroyed",
+	torn_off: "Torn off"
+};
+var groups = {
+	"default": "Vehicles"
+};
+var sides = {
+	left: "left",
+	right: "right",
+	leftM: "left",
+	rightM: "right"
+};
+var matchers = {
+	windshield: "windshield",
+	rear: "rear",
+	side: "left|right",
+	tank: "tank|tanker",
+	diesel: "diesel",
+	fuel: "gasoline|petrol|ethanol|alcohol|fuel",
+	glass_id: "glass|window|windshield|rear_window"
+};
+var ui = {
+	front: "▲ FRONT",
+	inside: "Inside",
+	aria: "Damage map seen from above, front up",
+	noZones: "This vehicle has no zones.",
+	health: "Overall health"
+};
+var mechanics = {
+	chassis: "Chassis frame",
+	battery: "Battery",
+	alternator: "Alternator",
+	gearbox: "Gearbox",
+	brakes: "Brakes",
+	steering: "Steering",
+	shock_absorbers: "Shock absorbers",
+	tow_hitch: "Tow hitch",
+	oil_pan: "Oil pan",
+	mirror: "{Side} mirror",
+	tyre: "{zone} tyre",
+	pillar_a: "{Side} A pillar",
+	pillar_c: "{Side} C pillar",
+	engine: "Engine",
+	radiator: "Radiator",
+	fuel_tank: "Fuel tank"
+};
+var en = {
+	plate: plate,
+	parts: parts,
+	texts: texts,
+	blast: blast,
+	zones: zones,
+	who: who,
+	bands: bands,
+	groups: groups,
+	sides: sides,
+	matchers: matchers,
+	ui: ui,
+	mechanics: mechanics
+};
+
+/** Every user-visible string of the engine, grouped by area. Missing keys of a locale fall back to English. */
+type LocaleStrings = typeof en;
+/** A locale given by the caller: any subset of {@link LocaleStrings}. */
+type PartialLocaleStrings = {
+    [K in keyof LocaleStrings]?: Partial<LocaleStrings[K]>;
+};
+/** Registers (or extends) a locale under a code such as `es` or `pt-BR`. Missing keys fall back to English. */
+declare function registerLocale(code: string, strings: PartialLocaleStrings | Record<string, any>): void;
+/** Codes of the registered locales. */
+declare function listLocales(): string[];
+/**
+ * Resolves a locale to a complete string table.
+ * Accepts a registered code (`'pt-BR'`; `'pt'` finds `'pt-BR'`, `'en-US'` finds `'en'`), or a partial table that overrides English.
+ */
+declare function resolveStrings(locale?: string | PartialLocaleStrings): LocaleStrings;
+/** Replaces `{name}` in a template. `{Name}` (capital first letter) capitalises the value of `name`. Unknown names stay as written. */
+declare function format(template: string, vars?: Record<string, unknown>): string;
+/** A function that looks up a dotted key (`'zones.hood'`) and fills in its variables. */
+type Translate = (key: string, vars?: Record<string, unknown>) => string;
+/**
+ * Builds the translate function of a string table. The variable `s` (-1 left, +1 right) is expanded to
+ * `{side}` (feminine word) and `{sideM}` (masculine word), so one template reads right in languages with grammatical gender.
+ */
+declare function createTranslate(strings: LocaleStrings): Translate;
+
+/**
+ * Public types of `@adatechnology/game-vehicles`.
+ * three.js objects are typed `any` on purpose: the host passes its own `THREE` namespace at runtime, so the package does not bind to one version.
+ */
+
+/** A three.js `Vector3`, `Object3D`, `Mesh`, ... of the host's `THREE`. */
+type ThreeObject = any;
+/** A three.js `Vector3` of the host's `THREE`. */
+type ThreeVector = any;
+type BuildState = 'intact' | 'damaged' | 'modified';
+/** Index of a damage band: 0 intact, 1 scratched, 2 dented, 3 destroyed, 4 torn off. */
+type BandIndex = 0 | 1 | 2 | 3 | 4;
+type BandId = 'intact' | 'scratched' | 'dented' | 'destroyed' | 'torn_off';
+interface Band {
+    id: BandId;
+    /** Display name (from the locale). */
+    name: string;
+    /** Lowest health that still belongs to the band. */
+    min: number;
+    /** Health a button/scenario uses to put a zone in this band. */
+    health: number;
+    /** CSS colour used by the UI widgets. */
+    color: string;
+}
+/** Where a vehicle is built: the context returned by {@link VehicleKit.build}. */
+interface VehicleContext {
+    /** Add this to the scene. */
+    root: ThreeObject;
+    /** The vehicle itself (a child of `root`); zones, parts and meshes live here. */
+    vehicle: ThreeObject;
+    key: string;
+    state: BuildState;
+    spec: VehicleSpec;
+    meta: VehicleMeta;
+    zones: DamageZone[];
+    zoneState: ZoneState;
+    /** Deterministic random generator seeded from the vehicle key and state. */
+    rand: () => number;
+    parts: VehiclePart[];
+    log: unknown[];
+    zoneErrors?: string[];
+    [key: string]: any;
+}
+interface VehicleMeta {
+    kind?: 'car' | 'bike' | 'truck' | 'bus' | 'tank' | 'boat' | 'plane' | 'heli' | string;
+    /** x of the front / rear of the bounding body (+x is forward). */
+    front?: number;
+    rear?: number;
+    length?: number;
+    width?: number;
+    /** Ground clearance and height of the body above it. */
+    clearance?: number;
+    bodyHeight?: number;
+    belt?: number;
+    top?: number;
+    /** Optional text for the body zone label; `bodyKind: 'box'` makes the single body zone a box. */
+    bodyLabel?: string;
+    bodyKind?: 'box' | 'body';
+    exhaust?: ThreeVector | false;
+    exhaustDir?: ThreeVector;
+    /** Replaces the default armour (state `modified`). */
+    armor?: (c: VehicleContext, kit: VehicleKit) => void;
+    [key: string]: any;
+}
+interface VehicleSpec {
+    /** Unique id of the vehicle. */
+    key: string;
+    /** Seeds the random streams (look and damage) instead of `key`. Lets a vehicle be renamed without changing how it looks. */
+    seedKey?: string;
+    /** Display name. */
+    name?: string;
+    /** Fleet group (see `configure({ groups })`). */
+    group?: string;
+    /** Fuel id (a key of `configure({ fuels })`) or `'electric'` / `'none'`. */
+    fuel?: string;
+    build?: BuildFunction;
+    [key: string]: any;
+}
+/** Builds the geometry of a vehicle into the context. */
+type BuildFunction = (c: VehicleContext, kit: VehicleKit) => void;
+interface VehiclePart {
+    kind: string;
+    label: string;
+    key?: string;
+    pos: ThreeVector;
+    [key: string]: any;
+}
+/** A part label: a plain string, or a locale key (`parts.<key>`) with an optional text override. */
+type PartLabel = string | {
+    key: string;
+    label?: string;
+};
+/** A damage zone of a built vehicle. */
+interface DamageZone {
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Relative weight in the overall health. */
+    weight: number;
+    /** Health (0..100) when the zone is untouched. */
+    health: number;
+    band: number;
+    internal?: boolean;
+    owned?: boolean;
+    tags: string[];
+    /** `[xMin, xMax, zMin, zMax]` rectangle on the top-down damage map. */
+    map: [number, number, number, number];
+    box: ThreeObject;
+    /** Overrides the id used to seed the random damage (keeps the output of an earlier pack identical). */
+    seedId?: string;
+    [key: string]: any;
+}
+/** Health per zone id (0..100) and scenario flags. */
+interface ZoneState {
+    health: Record<string, number>;
+    flags: Record<string, boolean>;
+}
+interface ScenarioResult {
+    health: Record<string, number>;
+    flags: Record<string, boolean>;
+    scenario: string;
+}
+/** The object a scenario's `zone` / `init` callbacks receive. */
+interface ScenarioContext {
+    c: VehicleContext;
+    meta: VehicleMeta;
+    front: number;
+    rear: number;
+    length: number;
+    width: number;
+    clearance: number;
+    top: number;
+    /** Deterministic random in [0, 1). */
+    rand: () => number;
+    /** Stores the health (0..100, rounded) of a zone. */
+    set(zone: DamageZone, health: number): void;
+    flags: Record<string, boolean>;
+    health: Record<string, number>;
+    /** Body types that count as bodywork (`panel`, `door`, `roof`, `lid`, `hood`, `bumper`). */
+    bodyTypes: Record<string, number>;
+    clamp(v: number, lo: number, hi: number): number;
+    /** Centre of the zone being visited. */
+    center: ThreeVector | null;
+    /** True when the zone being visited is a windshield. */
+    isWindshield: boolean;
+    /** Scratch space: `init` can store values here for `zone` to read. */
+    [key: string]: any;
+}
+interface ScenarioDefinition {
+    id: string;
+    /** Seeds the random stream of the scenario instead of `id`. Lets a scenario be renamed without changing its result. */
+    seedId?: string;
+    /** Display name. */
+    name: string;
+    init?(x: ScenarioContext): void;
+    zone(zone: DamageZone, x: ScenarioContext): void;
+}
+/** Visual effect of a scenario flag (`flipped`, `burnt`, `abandoned` or a plugin's own). */
+interface FlagEffect {
+    /** Lower runs first (default 50). */
+    order?: number;
+    /** Run the settle step after applying (default true). */
+    settle?: boolean;
+    apply(c: VehicleContext, flags: Record<string, boolean>, kit: VehicleKit): void;
+}
+interface FluidDefinition {
+    fresh?: string;
+    dry?: string;
+    /** Seconds until dry. */
+    dryTime?: number;
+    roughFresh?: number;
+    roughDry?: number;
+    metalFresh?: number;
+    metalDry?: number;
+    /** Wipers and rain remove it while fresh. */
+    wipeable?: boolean;
+    /** Fully custom fluid: return `true` to remove it. */
+    update?(c: VehicleContext, fluid: any, dt: number, index: number): boolean | void;
+    [key: string]: any;
+}
+interface ZoneEffect {
+    [key: string]: any;
+}
+interface BandOverride {
+    name?: string;
+    color?: string;
+    min?: number;
+    health?: number;
+}
+/** Text overrides. Anything left out comes from the locale. */
+interface KitTexts {
+    /** Placeholder for the party that caused a damage (`{who}` in zone texts). */
+    who?: string;
+    /** Text when a zone has no visible effect. */
+    noEffect?: string;
+    plate?: string;
+    /** Overrides of the `ui.*` locale strings. */
+    ui?: Record<string, string>;
+}
+/** Everything a content pack can set; also accepted by `createVehicleKit`. */
+interface KitConfiguration {
+    bands?: BandOverride[];
+    zoneEffects?: Record<string, ZoneEffect | ((z: DamageZone, health: number) => unknown)>;
+    partEffects?: Record<string, string>;
+    scenarios?: ScenarioDefinition[];
+    flagEffects?: Record<string, FlagEffect>;
+    fluids?: Record<string, FluidDefinition>;
+    /** Fuel id to its definition (flammability, colour, label, ...). */
+    fuels?: Record<string, any>;
+    groups?: string[];
+    waterGroups?: Record<string, any>;
+    palette?: {
+        rust?: string | number;
+    };
+    plate?: string;
+    texts?: KitTexts;
+    /** Fluid type of the stain an impact leaves (null: none). */
+    impactStain?: string | null;
+    defaultSplat?: string;
+    defaultGroup?: string;
+    /** Scenario applied to a `'damaged'` build when no zone state is given. */
+    damagedScenario?: string | null;
+}
+/** The live configuration of a kit (what `configure` has set so far). */
+interface ResolvedConfiguration {
+    defaultGroup: string;
+    plate: string;
+    defaultSplat: string;
+    impactStain: string | null;
+    damagedScenario: string | null;
+    texts: KitTexts & {
+        who: string;
+        noEffect: string;
+    };
+}
+interface Plugin {
+    name?: string;
+    configure?: KitConfiguration;
+    install?(kit: VehicleKit): void;
+}
+interface VehicleKitOptions extends KitConfiguration {
+    /** The three.js namespace (`import * as THREE from 'three'` or `window.THREE`). */
+    THREE: any;
+    /** A registered locale code (`'en'`, `'pt-BR'`), or a partial string table overriding English. Default `'en'`. */
+    locale?: string | PartialLocaleStrings;
+    /** Document used for canvas textures and the UI. Defaults to the global `document`. */
+    document?: Document;
+    plugins?: Plugin[];
+}
+interface ImpactOptions {
+    /** Do not leave a stain. */
+    noStain?: boolean;
+    [key: string]: any;
+}
+interface SplatOptions {
+    fluid?: string;
+    glass?: boolean;
+    obj?: ThreeObject;
+}
+interface ExplodeOptions {
+    /** Explode immediately. */
+    now?: boolean;
+    /** Seconds of fire before the blast (default 3..8 at random). */
+    delay?: number;
+}
+interface OverallHealth {
+    health: number;
+    band: number;
+    name: string;
+}
+interface ZoneDamageEntry {
+    id: string;
+    name: string;
+    damage: number;
+}
+interface DamageMapOptions {
+    /** Id of the selected zone. */
+    selected?: string;
+    onSelect?(zoneId: string): void;
+}
+interface UiHelpers {
+    damageMap(host: HTMLElement, c: VehicleContext, o?: DamageMapOptions): SVGElement | null;
+    bandButtons(host: HTMLElement, onPick?: (health: number, band: number) => void): HTMLButtonElement[];
+    legend(host: HTMLElement): void;
+    healthBar(els: {
+        text?: HTMLElement;
+        bar?: HTMLElement;
+    }, c: VehicleContext): OverallHealth;
+    scenarioButtons(host: HTMLElement, onRun: (id: string) => void): HTMLButtonElement[];
+    zoneLabel(z: DamageZone): string;
+    bandRange(i: number): string;
+    css(): string;
+    injectStyles(): void;
+}
+/** Helpers for plugins that implement their own flag effects. */
+interface KitInternals {
+    rng(seed: number): () => number;
+    strHash(text: string): number;
+    zonesOf(c: VehicleContext): DamageZone[];
+    [key: string]: any;
+}
+/** Low-level builders of the engine; see the JSDoc of each. They take and return three.js objects. */
+type Builder = (...args: any[]) => any;
+interface VehicleKit {
+    readonly THREE: any;
+    /** Translated strings in use. */
+    readonly strings: LocaleStrings;
+    /** Looks up a locale key (`'zones.hood'`) and fills variables. */
+    readonly t: Translate;
+    readonly bands: Band[];
+    readonly fleet: VehicleSpec[];
+    readonly scenarios: ScenarioDefinition[];
+    readonly plugins: string[];
+    readonly fluidTypes: Record<string, FluidDefinition>;
+    readonly flagEffects: Record<string, FlagEffect>;
+    readonly fuels: Record<string, any>;
+    readonly groups: string[];
+    readonly config: ResolvedConfiguration;
+    readonly internals: KitInternals;
+    readonly ui: UiHelpers;
+    register(spec: VehicleSpec, build: BuildFunction): VehicleSpec;
+    find(key: string): VehicleSpec | null;
+    configure(options: KitConfiguration): VehicleKit;
+    /**
+     * Registers a locale table (any top-level key, so a content pack can add its own) and refreshes the strings of this kit,
+     * which keeps the locale it was created with. English is the fallback for every locale.
+     */
+    registerLocale(code: string, strings: Record<string, any>): VehicleKit;
+    /**
+     * Registers the original (pre-rename) text of zone ids and glass labels, which keeps the random damage of a renamed zone or
+     * pane unchanged. `zones`: new zone id to original id; `glassLabels`: glass part key to original label. Shared by every kit.
+     */
+    registerLegacySeeds(tables: {
+        zones?: Record<string, string>;
+        glassLabels?: Record<string, string>;
+    }): void;
+    plugin(plugin: Plugin): VehicleKit;
+    scenario(def: ScenarioDefinition): ScenarioDefinition;
+    defineFluid(key: string, def: FluidDefinition): FluidDefinition;
+    on(event: string, fn: (...args: any[]) => void): VehicleKit;
+    hook(event: string, ...args: any[]): void;
+    build(key: string, state?: BuildState, zoneState?: Partial<ZoneState>): VehicleContext;
+    dispose(c: VehicleContext): void;
+    /** Advances particles, fluids, hood, blast and rollover animations by `dt` seconds. */
+    tick(c: VehicleContext, dt: number): void;
+    /** Runs `sec` seconds of `tick` in one go. */
+    settle(c: VehicleContext, sec: number): void;
+    defaultDamage(c: VehicleContext): void;
+    bandOf(health: number): BandIndex;
+    zonesOf(c: VehicleContext): DamageZone[];
+    applyZones(c: VehicleContext, state: Partial<ZoneState>): void;
+    zoneScenario(c: VehicleContext, idOrName: string): ScenarioResult;
+    zoneOverall(c: VehicleContext): OverallHealth;
+    zoneAt(c: VehicleContext, point: ThreeVector, object?: ThreeObject): DamageZone | null;
+    zoneDamageAt(c: VehicleContext, point: ThreeVector, dir: ThreeVector, force: number, object?: ThreeObject): ZoneDamageEntry[];
+    zonePoint(c: VehicleContext, zone: DamageZone): ThreeVector;
+    zoneImpact(c: VehicleContext, side: 'front' | 'rear' | 'left' | 'right' | string, force: number): unknown;
+    impact(c: VehicleContext, point: ThreeVector, dir: ThreeVector, force: number, options?: ImpactOptions): unknown[];
+    splat(c: VehicleContext, point: ThreeVector, normal: ThreeVector, radius: number, options?: SplatOptions): {
+        grp: ThreeObject;
+        [key: string]: any;
+    };
+    explode(c: VehicleContext, options?: ExplodeOptions): number | false;
+    blastDamage(c: VehicleContext, amount: number): 'fire' | 'explosion' | null;
+    roll(c: VehicleContext, side?: number): boolean;
+    applyArmor(c: VehicleContext): void;
+    spawn: Builder;
+    burst: Builder;
+    addEmitter: Builder;
+    readonly geo: Record<string, Builder>;
+    readonly materials: Record<string, any>;
+    [builder: string]: any;
+}
+
+/**
+ * Creates a vehicle kit bound to a three.js namespace and a locale.
+ * The returned object is the public API; every call creates an independent kit (its own registry, caches and configuration).
+ */
+declare function createVehicleKit(options: VehicleKitOptions): VehicleKit;
+
+/** Build states: new English name -> original seed text. */
+declare const LEGACY_STATES: Record<string, string>;
+/** Salts mixed into the seed of each phase of `applyZones`. */
+declare const SEED_SALTS: {
+    rust: string;
+    scenario: string;
+    settle: string;
+    rollover: string;
+};
+/** Auto-derived zone ids: new id -> original id. Ids that did not change are not listed. */
+declare const LEGACY_ZONE_IDS: Record<string, string>;
+/**
+ * Lets a content pack add its own legacy seeds: `zones` maps a new zone id to the original id and `glassLabels` maps the key of a
+ * glass part to its original label. The tables are shared by every kit of the process; an id keeps one meaning, so a different
+ * text for an id that is already known is an error.
+ */
+declare function registerLegacySeeds(tables: {
+    zones?: Record<string, string>;
+    glassLabels?: Record<string, string>;
+}): void;
+/** The text a zone contributes to its seed: an explicit `seedId`, the legacy id, or the id itself. */
+declare function legacyZoneId(z: {
+    id: string;
+    seedId?: string;
+}): string;
+/**
+ * Original zone id of a glass pane. `key` is the part key (null for free-text labels), `label` the current label,
+ * `side` -1/1 for panes made by `sideWindows`, `appended` 'left'/'right' when the zone added a side word itself and
+ * `fallback` the new id, used when the label was free text (then the id never changed).
+ */
+declare function legacyGlassId(key: string | null, label: string, side: number, appended: string | null, fallback: string): string;
+/** Original id of a light zone: `farol_e`, `lanterna_c`, `farol_d_2`... */
+declare function legacyLightId(kind: string, side: string, index: number): string;
+
+/** Pure helpers shared by every module. They never touch three.js. */
+/** Deterministic hash of three numbers to [0, 1). */
+declare function hash(a: number, b: number, c: number): number;
+declare function clamp(v: number, a: number, b: number): number;
+/** Smoothstep on [0, 1]. */
+declare function smooth(t: number): number;
+/** Mulberry32 pseudo random generator. The same seed always gives the same sequence. */
+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;
+
+/**
+ * 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
+ * vehicle meta, and the joints (hinge, bolt, weld, glue, clip) say how each one is held.
+ *
+ * Everything here is pure data derived from the built vehicle: no meshes are created or touched.
+ */
+
+/** What a part is, which decides its material, its joint and what happens when it comes off. */
+type PartRole = 'frame' | 'panel' | 'fender' | 'door' | 'hood' | 'lid' | 'roof' | 'bumper' | 'glass' | 'light' | 'rim' | 'tyre' | 'mirror' | 'pillar' | 'engine' | 'radiator' | 'fuel_tank' | 'oil_pan' | 'battery' | 'alternator' | 'gearbox' | 'brakes' | 'steering' | 'shocks' | 'hitch' | 'other';
+/** An axis-aligned box in `c.vehicle` coordinates (+x front, +y up, +z right). */
+interface LocalBox {
+    center: Vec3;
+    size: Vec3;
+}
+interface PartDef {
+    id: string;
+    role: PartRole;
+    /** Display name from the locale. */
+    name: string;
+    material: MaterialId;
+    box: LocalBox;
+    mass: number;
+    /** Energy in joules that wrecks the part. */
+    hp: number;
+    /** The damage zone this part is, when it is one. */
+    zoneId?: string;
+    /** Fluid held, in litres. */
+    contains?: {
+        fluid: string;
+        liters: number;
+        pressurized?: boolean;
+    };
+    explodes?: {
+        energy: number;
+        radius: number;
+        atC: number;
+    };
+    /** Temperature in Celsius at which the part catches fire (none: it does not burn). */
+    ignitionC?: number;
+    /** Parts that can be seen coming off the vehicle (the others are logical: they keep state and effects only). */
+    visual: boolean;
+    /** The part is one of the new mechanical parts (the ones the damage zones do not cover). */
+    mechanical: boolean;
+    tags: string[];
+}
+interface JointDef {
+    id: string;
+    a: string;
+    b: string;
+    kind: JointKind;
+    strength: number;
+    tools: ToolKind[];
+    seconds: number;
+}
+interface VehicleModel {
+    parts: PartDef[];
+    joints: JointDef[];
+    /** The part every other part hangs from. */
+    hub: string;
+    hitch: boolean;
+}
+interface ModelOptions {
+    /** Fit a tow hitch. Default: the spec flag `hitch`, else a seeded choice by vehicle kind. */
+    hitch?: boolean;
+}
+/** 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', {
+    strength: number;
+    tools: ToolKind[];
+    seconds: number;
+}>;
+/** Builds the part and joint model of a built vehicle. */
+declare function buildVehicleModel(kit: VehicleKit, c: VehicleContext, options?: ModelOptions): VehicleModel;
+
+/**
+ * `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,
+ * melt, explode), joints come apart by wear, by a wrench or by breaking, and the hidden mechanics change how the vehicle drives.
+ *
+ * It depends on the contracts only (types) and on the kit it is given: not on the default destruction world.
+ */
+
+interface VehicleDestructibleOptions {
+    /** Object id the host gives (`DestructibleImpl.id`). Default: the vehicle key. */
+    id?: string;
+    /** Display name. Default: the vehicle name. */
+    name?: string;
+    /** Object whose space `describe()` answers in (the wrapper the host placed the vehicle in). Default: `c.root`. */
+    frame?: any;
+    /** Tow hitch: the option wins over the spec flag, the spec flag over the seeded choice. */
+    hitch?: boolean;
+    /** Do not create or move any mesh (logic only, for servers and tests that need no scene). */
+    headless?: boolean;
+    /** Extra seed for the choices that are random in the real world (which way a broken steering pulls). */
+    seed?: number;
+}
+/** What the vehicle can do now, from the state of its hidden mechanics. */
+interface VehicleStatus {
+    /** Battery, alternator, engine and fuel are in order. */
+    canStart: boolean;
+    /** Headlights and taillights are powered (battery and alternator in order). */
+    lightsOn: boolean;
+    /** Engine runs and the gearbox transmits. */
+    canDrive: boolean;
+    /** 1 is normal; worn or missing brakes make the stopping distance this many times longer. */
+    brakeFactor: number;
+    /** -1..1: the sideways pull of a damaged steering or flat tyres (negative is left). */
+    steerPull: number;
+    flatTyres: string[];
+    detached: string[];
+    leaking: string[];
+    burning: string[];
+    exploded: boolean;
+    fuelLiters: number;
+}
+interface VehicleDestructible extends DestructibleImpl {
+    readonly vehicle: VehicleContext;
+    readonly model: VehicleModel;
+    /** Display name of a part (from the kit locale). */
+    partName(partId: string): string;
+    status(): VehicleStatus;
+    /** Open and close clips for the doors, the hood and the trunk lid the vehicle has. */
+    animations(): AnimationClipSpec[];
+    /** World position of a part's centre. */
+    partWorldCenter(partId: string): Vec3;
+    /** Rolls the vehicle over (the roof, the glass and the fluids are hurt when it lands). */
+    rollover(side?: number): void;
+    /** Part ids that are no longer attached to the main body. */
+    detachedParts(): string[];
+}
+declare function createVehicleDestructible(kit: VehicleKit, vehicleCtx: VehicleContext, options?: VehicleDestructibleOptions): VehicleDestructible;
+
+interface VehicleItemOptions {
+    state?: BuildState;
+}
+interface VehicleItem {
+    /** Add this to the scene: origin at the centre of the footprint on the floor, front facing +z. */
+    root: any;
+    /** The built vehicle inside it. */
+    vehicle: VehicleContext;
+}
+/**
+ * Builds vehicle `key` as an item for a viewer that expects the origin at the centre of the footprint on the floor and the front facing +z
+ * (the test room). The vehicle itself keeps the kit axes (+x front) inside a turned, centred group. Pass `root` as `frame` to
+ * `createVehicleDestructible` so `describe()` answers in the item's space.
+ */
+declare function buildVehicleItem(kit: VehicleKit, key: string, options?: VehicleItemOptions): VehicleItem;
+
+export { type Band, type BandId, type BandIndex, type BandOverride, type BuildFunction, type BuildState, type DamageMapOptions, type DamageZone, 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 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, clamp, createTranslate, createVehicleDestructible, createVehicleKit, format, hash, legacyGlassId, legacyLightId, legacyZoneId, listLocales, registerLegacySeeds, registerLocale, resolveStrings, rng, smooth, strHash };