@adatechnology/game-vehicles 0.5.0 → 0.6.0

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, 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 {
@@ -957,4 +1015,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 { 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 };