@adatechnology/game-vehicles 0.1.12 → 0.3.0

package/README.md

@@ -18,7 +18,7 @@ pnpm add @adatechnology/game-vehicles three
 Browser without a bundler (the global is `GameVehicles`):
 
 ```html
-<script src="https://unpkg.com/three@0.128.0/build/three.min.js"></script>
+<script src="https://unpkg.com/three@0.160.1/build/three.min.js"></script>
 <script src="https://unpkg.com/@adatechnology/game-vehicles/dist/index.global.js"></script>
 <script>
   const kit = GameVehicles.createVehicleKit({ THREE })
@@ -201,6 +201,13 @@ Plain DOM and SVG, no framework: `ui.damageMap(host, c, { selected, onSelect })`
 ones in a strip below); `ui.bandButtons`, `ui.legend`, `ui.healthBar({ text, bar }, c)`, `ui.scenarioButtons`. `ui.injectStyles()` adds minimal CSS
 (`--panel-2`, `--line` and `--muted` customise it).
 
+## Geometry
+
+The kit's three is `shapeGeometries(THREE)` of `@adatechnology/game-shapes-three`, thinned by the light mode: boxes, cylinders, cones, spheres,
+planes, circles, rings, tori, the tyre lathes and the straight-edged extrusions are made by game-shapes, bit-identical to three's
+(`tests/exact-golden.test.ts`, and the fleet's and `game-vehicles-three`'s) and cached by parameters across vehicles. Tubes, curved
+extrusions, the lofted bodies and the warps stay three's own or the kit's custom buffers. The IIFE build bundles game-shapes.
+
 ## Determinism and old seeds
 
 The random stream of a zone is seeded from the vehicle key, the zone id and the band. The first version of this engine used Portuguese ids, so ids
@@ -241,6 +248,12 @@ car.animations() // open/close clips for the doors, hood and trunk
 
 Fluids: the tank, the oil pan and the radiator hold fuel, oil and coolant; a hole below the level makes a `leak` event, a puddle and a falling level.
 
+Fuel tank: a bullet that goes through it **leaks and does not set it alight by itself**. The leak lights (event `ignite`, then the usual fire and, for a petrol tank, the explosion) with
+a spark of a hard round on the steel wall, an incendiary or tracer round, a burning part or burning fuel stain within `ignition.fireNear.radius`, or a blast. The chances of the round
+come in `Hit.ignition` (the weapons build them from the core and jacket of the ammunition) and are weighed by how full the tank is (`fuel`, 0 to 1, the starting level; a nearly empty tank lights
+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`.
+
 ## 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
@@ -266,3 +279,7 @@ scene.add(c.root)
 ### Contrato de destruição
 
 `createVehicleDestructible(kit, c, opções)` faz um veículo construído seguir o `DestructibleImpl` de `@adatechnology/game-contracts`: cada zona de dano vira uma peça com material, as peças mecânicas (bateria, alternador, câmbio, freios, direção, amortecedores, pneus, retrovisores, engate) são acrescentadas, as juntas (dobradiça, parafuso, solda) se desfazem por desgaste ou com a chave inglesa, e as peças saem do veículo e caem. `status()` diz o que a mecânica faz (freios, direção, bateria, câmbio). Os nomes em português estão em `locales/pt-BR.json` (`mechanics.*`).
+
+## Light mode and damageable parts
+
+`createVehicleKit({ lod })` takes the settings of the light mode (`defaultLodSettings`: every number can be overridden). `kit.build(key, state, zones, { lod: true })` builds the same vehicle with fewer triangles (rounded boxes with one ring, coarser lofts, grilles and generators, interiors tagged `userData.skipLite`) and puts the switch back; with it off nothing changes. `kit.damageables(c, matrix?)` lists the metal, glass, rubber and fuel parts of a built vehicle as `Box3` boxes (`kit.damageableKinds` maps zone types to parts and can be extended).

package/dist/index.d.ts

@@ -1,4 +1,58 @@
-import { ToolKind, JointKind, Vec3, MaterialId, DestructibleImpl, AnimationClipSpec } from '@adatechnology/game-contracts';
+import { ToolKind, JointKind, Vec3, MaterialId, DestructibleImpl, AnimationClipSpec, IgnitionRules } 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
+ * (frota-leve.js lines 21-65, 232-257, 1205-1221, 14155-14170). Every number is a setting; with `on` false nothing changes, so every golden
+ * of the full-detail build stays byte for byte the same.
+ */
+
+interface LodSettings {
+    /** Light mode is active for the builds that run now. Set by `kit.build(key, state, zones, { lod: true })`. */
+    on: boolean;
+    /** Fraction of the segments three's own generators keep (cylinders, spheres, tori, lathes, tubes, extrusions, circles, rings). */
+    segmentFraction: number;
+    /** Rounding rings of a rounded box (the full build uses 3). */
+    roundingRings: number;
+    /** Multiplier of the maximum edge length when subdividing a mesh (bigger triangles). */
+    subdivisionFactor: number;
+    /** A box with an edge under this, or a rounding radius under 1.2 cm, is drawn as a plain 12-triangle box. */
+    flatBoxEdge: number;
+    /** Fewest segments of a superellipse loft. */
+    minLoftSegments: number;
+    /** Fraction of a loft's segments. */
+    loftSegmentFraction: number;
+    /** Fewest stations of a resampled loft. */
+    minStations: number;
+    /** Fraction of the stations of a resampled loft. */
+    stationFraction: number;
+    /** Multiplier of the grid cell size of grilles and side grilles. */
+    gridFactor: number;
+    /** Materials (by name in `kit.materials`) whose meshes are never seen from outside and are left out in light mode. */
+    hiddenMaterials: readonly string[];
+}
+declare const defaultLodSettings: LodSettings;
+/** The settings the kit starts with: the defaults, overridden by the options. */
+declare function createLod(options?: Partial<LodSettings>): LodSettings;
+/**
+ * A copy of the three.js namespace whose geometry generators take fewer segments while `lod.on` is true (and whose canvas textures come out in
+ * sRGB when three has colour management). With `lod.on` false every generator passes its arguments through untouched.
+ */
+declare function wrapThreeForLod(TH: any, lod: LodSettings): any;
+
+/**
+ * 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.
+ */
+
+type DamageableMaterial = 'metal' | 'glass' | 'rubber' | 'fuel';
+type DamageableSide = 'center' | 'left' | 'right';
+/** What a zone is, by type: the material it is made of and the part name a game shows. */
+interface DamageableKind {
+    material: DamageableMaterial;
+    part: string;
+}
+/** Zone type (and, for some, `fxKey` or `sub`) to material and part. A game replaces or adds entries with `kit.damageableKinds`. */
+declare const defaultDamageableKinds: Record<string, DamageableKind>;
 
 var plate = {
 	band: "BRAZIL"
@@ -487,9 +541,25 @@ interface Plugin {
     configure?: KitConfiguration;
     install?(kit: VehicleKit): void;
 }
+interface BuildOptions {
+    /** Build this vehicle in light mode (fewer triangles; interiors tagged `skipLite`). */
+    lod?: boolean;
+}
+interface Damageable {
+    material: DamageableMaterial;
+    /** Id of the zone. */
+    zone: string;
+    /** `door`, `hood`, `lid`, `bumper`, `window`, `windshield`, `headlight`, `taillight`, `wheel`, `fuel_tank`. */
+    part: string;
+    side: DamageableSide;
+    /** A `THREE.Box3`. */
+    box: ThreeObject;
+}
 interface VehicleKitOptions extends KitConfiguration {
     /** The three.js namespace (`import * as THREE from 'three'` or `window.THREE`). */
     THREE: any;
+    /** Light mode settings (every number of `defaultLodSettings` can be overridden). */
+    lod?: Partial<LodSettings>;
     /** 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`. */
@@ -552,6 +622,10 @@ interface KitInternals {
 type Builder = (...args: any[]) => any;
 interface VehicleKit {
     readonly THREE: any;
+    /** The light mode settings (live: change a number and the next build uses it). */
+    readonly lod: LodSettings;
+    /** Zone type to material and part of `damageables`; add or replace entries. */
+    readonly damageableKinds: Record<string, DamageableKind>;
     /** Translated strings in use. */
     readonly strings: LocaleStrings;
     /** Looks up a locale key (`'zones.hood'`) and fills variables. */
@@ -588,7 +662,9 @@ interface VehicleKit {
     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;
+    build(key: string, state?: BuildState, zoneState?: Partial<ZoneState>, options?: BuildOptions): VehicleContext;
+    /** The damageable parts of a built vehicle as boxes (optionally in the frame of `matrix`). */
+    damageables(c: VehicleContext, matrix?: ThreeObject): Damageable[];
     dispose(c: VehicleContext): void;
     /** Advances particles, fluids, hood, blast and rollover animations by `dt` seconds. */
     tick(c: VehicleContext, dt: number): void;
@@ -768,6 +844,15 @@ interface VehicleDestructibleOptions {
     headless?: boolean;
     /** Extra seed for the choices that are random in the real world (which way a broken steering pulls). */
     seed?: number;
+    /** How full the fuel tank starts, 0 to 1 (default 1). A nearly empty tank leaks little and lights easily (see `ignition`). */
+    fuel?: number;
+    /**
+     * What lights the fuel that leaks from a pierced tank: a plain bullet only leaks; a spark of a hard round on steel, an incendiary or tracer
+     * round, a fire within `fireNear.radius` (a burning part or a burning fuel stain) or a blast lights it, and then the usual fire and explosion
+     * follow. The chance of the round is in `Hit.ignition`; this is the target side (how full the tank is, what the wall is, the fire near).
+     * Defaults and meaning of every number: `IgnitionRules` of `@adatechnology/game-contracts`.
+     */
+    ignition?: Partial<IgnitionRules>;
 }
 /** What the vehicle can do now, from the state of its hidden mechanics. */
 interface VehicleStatus {
@@ -807,6 +892,8 @@ declare function createVehicleDestructible(kit: VehicleKit, vehicleCtx: VehicleC
 
 interface VehicleItemOptions {
     state?: BuildState;
+    /** Build in the light mode of the kit (`kit.lod`): fewer segments and no interior, for crowds and for budgets. Default off. */
+    lod?: boolean;
 }
 interface VehicleItem {
     /** Add this to the scene: origin at the centre of the footprint on the floor, front facing +z. */
@@ -821,4 +908,4 @@ interface VehicleItem {
  */
 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 };
+export { type Band, type BandId, type BandIndex, type BandOverride, type BuildFunction, type BuildOptions, type BuildState, 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 };