@adatechnology/game-vehicles 0.4.7 → 0.6.0

package/README.md

@@ -258,6 +258,12 @@ come in `Hit.ignition` (the weapons build them from the core and jacket of the a
 easiest, a full one mostly leaks); diesel takes a spark far worse than petrol. `createVehicleDestructible(kit, vehicle, { fuel: 0.1, ignition: { fillCurve, fireNear, sparkTarget } })`;
 the defaults and every number are `IgnitionRules` of `@adatechnology/game-contracts`.
 
+Cabin and smoke: `cabinEnclosure(car, { frame })` is the cabin (`meta.cabin`, from `kit.interior`) as an `Enclosure` in world space, for the host's
+`EffectSink.enclose`: a shut car keeps the smoke out and seeps only at `CABIN_LEAK` (2 % per second), more with cracked glass. It is open where a door
+or lid stands open (past 6 % of its swing), where a window shattered and where a door, glass, roof or panel was torn off or burnt away; a bullet hole
+lets smoke in at the hole at a rate that grows with its area (a 9 mm hole about 0.2 a second). `null` for a vehicle with no cabin (a bike) or one
+destroyed. `createCabinSmoke()` of `game-vehicles-three` keeps a host told every frame.
+
 ## Português
 
 Motor genérico de veículos procedurais para three.js: carrocerias, vidros, faróis, rodas, interiores, capô e compartimento do motor, **zonas de dano

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ToolKind, JointKind, Vec3, MaterialId, DestructibleImpl, AnimationClipSpec, IgnitionRules } from '@adatechnology/game-contracts';
+import { MaterialId, Vec3, JointKind, ToolKind, DeferredQueue, DestructibleImpl, AnimationClipSpec, IgnitionRules, 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;
@@ -782,6 +811,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;
@@ -827,9 +858,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 +913,11 @@ interface VehicleDestructibleOptions {
      * Defaults and meaning of every number: `IgnitionRules` of `@adatechnology/game-contracts`.
      */
     ignition?: Partial<IgnitionRules>;
+    /**
+     * 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 {
@@ -917,4 +975,49 @@ interface VehicleItem {
  */
 declare function buildVehicleItem(kit: VehicleKit, key: string, options?: VehicleItemOptions): VehicleItem;
 
-export { type Band, type BandId, type BandIndex, type BandOverride, type BuildFunction, type BuildOptions, type BuildState, type BuildZoneState, 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, clamp, createLod, createTranslate, createVehicleDestructible, createVehicleKit, defaultDamageableKinds, defaultLodSettings, format, hash, legacyGlassId, legacyLightId, legacyZoneId, listLocales, registerLegacySeeds, registerLocale, resolveStrings, rng, smooth, strHash, wrapThreeForLod };
+/**
+ * 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
+ * away; a bullet hole lets a little in at a rate that grows with its size, and the gaps of a shut door let a trace in.
+ */
+
+/** The cabin box a vehicle with an interior records (`kit.interior`), in the vehicle's own space: x along it, `z` the inner half width. */
+interface CabinBox {
+    readonly x0: number;
+    readonly x1: number;
+    readonly y0: number;
+    readonly y1: number;
+    readonly z: number;
+}
+/** What the cabin enclosure reads of a vehicle: its parts and their state (any `DestructibleImpl` of a vehicle has these). */
+interface CabinSource {
+    readonly vehicle: VehicleContext;
+    readonly model: VehicleModel;
+    state(): ObjectState;
+}
+interface CabinEnclosureOptions {
+    /** The object the destructible answers in (its `frame` option, where the host placed the vehicle): the holes of `state()` are in its space. Default `vehicle.root`. */
+    readonly frame?: any;
+    /** Gaps of the shut doors and vents, share per second of the smoke pressing on the closed shell (default {@link CABIN_LEAK}). */
+    readonly leak?: number;
+    /** How open a door or lid has to be (share of its full swing) to count as open (default 0.06: ajar). */
+    readonly ajar?: number;
+}
+/** The gaps of a shut car (door seals, the vents, the dash): about 2 % per second of what presses on it seeps in. */
+declare const CABIN_LEAK = 0.02;
+/** The cabin box of a vehicle, or `null` when it has none (a bike, a vehicle with no interior). */
+declare function cabinBoxOf(vehicle: VehicleContext): CabinBox | null;
+/** How far a door or lid stands open, 0 shut to 1 at the end of its clip: the turn of its drawn hinge from rest (the room poses it by the part id). */
+declare function swingOf(vehicle: VehicleContext, partId: string): number;
+/**
+ * The cabin of `source` as an `Enclosure` in world space, or `null` when there is no closed cabin (no interior, the vehicle exploded, every shell
+ * part gone). Call it each frame, or when the vehicle moves or changes, and hand it to `EffectSink.enclose`.
+ */
+declare function cabinEnclosure(source: CabinSource, options?: CabinEnclosureOptions): Enclosure | null;
+
+/** 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 { 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 };