@adatechnology/game-vehicles 0.2.0 → 0.4.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 })
@@ -64,6 +64,9 @@ scene.remove(c.root); kit.dispose(c)
 const hurt = kit.build('meteor', 'intact', state)
 scene.add(hurt.root)
 
+// ...or name a registered scenario and build it in one call (explicit health / flags given alongside win)
+const wreck = kit.build('meteor', 'intact', { scenario: 'burnt' })
+
 // 4. animate (particles, fluids, hood, rollover, explosions)
 kit.tick(hurt, dt)
 ```
@@ -89,7 +92,7 @@ and a band decided by the health:
 | 3 | `destroyed` | 1 to 25 | Heavy deformation, parts fall off |
 | 4 | `torn_off` | 0 | The part is gone |
 
-Bands only change the look when the band changes; `kit.build(key, state, zoneState)` rebuilds the vehicle and reapplies every zone.
+Bands only change the look when the band changes; `kit.build(key, state, zoneState)` rebuilds the vehicle and reapplies every zone. `zoneState` may also carry `scenario: 'id or name'`: the scenario is computed on the vehicle being built (no probe build) and any `health` / `flags` given with it are merged on top. An unknown scenario damages nothing, like `zoneScenario`.
 
 **Content packs.** A pack is a plugin: `{ name, configure, install(kit) }`. `configure` accepts everything in the configuration table below and
 `install` can call `kit.register(...)`, `kit.scenario(...)`, `kit.defineFluid(...)`, `kit.on(...)` and so on. The engine never imports a pack.
@@ -139,7 +142,7 @@ created with, so `kit.t('mypack.some.key')` reads from it, with English as the f
 | Area | Methods |
 |---|---|
 | Registry | `register(spec, build)`, `find(key)`, `fleet`, `configure`, `plugin`, `on`/`hook`, `scenario`, `defineFluid` |
-| Lifecycle | `build(key, state?, zoneState?)`, `dispose(c)`, `tick(c, dt)`, `settle(c, seconds)`, `defaultDamage(c)` |
+| Lifecycle | `build(key, state?, zoneState?)` (`zoneState.scenario` runs a scenario), `dispose(c)`, `tick(c, dt)`, `settle(c, seconds)`, `defaultDamage(c)` |
 | Zones | `bandOf(health)`, `zonesOf(c)`, `applyZones(c, state)`, `zoneScenario(c, id)`, `zoneOverall(c)`, `zoneAt(c, point)`, `zoneDamageAt(c, point, dir, force)`, `zonePoint(c, zone)`, `zoneEffect(zone, health?)`, `zoneOwner` |
 | Events | `impact(c, point, dir, force, options?)`, `zoneImpact(c, side, force)` (side: `front`, `rear`, `left`, `right` or `rolled`), `explode(c, options?)`, `blastDamage(c, amount)`, `roll(c, side?)`, `setHood(c, open)` |
 | Fluids and particles | `splat`, `puddle`, `wipe(c, mode)` (`wiper` or `rain`), `spawn`, `burst`, `addEmitter` |
@@ -175,6 +178,7 @@ kit.scenario({
 })
 const result = kit.zoneScenario(c, 'front') // { health, flags, scenario }
 const hurt = kit.build('meteor', 'intact', result)
+const same = kit.build('meteor', 'intact', { scenario: 'front' }) // the two steps in one call
 ```
 
 `x` has `c`, `meta`, `front`, `rear`, `length`, `width`, `clearance`, `top`, `rand()`, `set(zone, health)`, `flags`, `health`, `center` (of the zone
@@ -201,6 +205,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 +252,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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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
@@ -337,6 +337,8 @@ interface VehicleContext {
     meta: VehicleMeta;
     zones: DamageZone[];
     zoneState: ZoneState;
+    /** The scenario the vehicle was built in (`kit.build(key, state, { scenario })`), so a rebuild keeps it. */
+    scenario?: string;
     /** Deterministic random generator seeded from the vehicle key and state. */
     rand: () => number;
     parts: VehiclePart[];
@@ -418,6 +420,11 @@ interface ZoneState {
     health: Record<string, number>;
     flags: Record<string, boolean>;
 }
+/** The zone-state argument of `kit.build`: a `ZoneState` plus an optional scenario to compute on the vehicle being built. */
+interface BuildZoneState extends Partial<ZoneState> {
+    /** Id or name of a registered scenario (e.g. the fleet's `burnt`); explicit `health` / `flags` override its result. */
+    scenario?: string;
+}
 interface ScenarioResult {
     health: Record<string, number>;
     flags: Record<string, boolean>;
@@ -662,7 +669,7 @@ 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>, options?: BuildOptions): VehicleContext;
+    build(key: string, state?: BuildState, zoneState?: BuildZoneState, 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;
@@ -844,6 +851,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 {
@@ -885,6 +901,8 @@ 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;
+    /** A registered damage scenario (id or name, e.g. the fleet's `burnt`) built into the vehicle, through `kit.build(key, state, { scenario })`. */
+    scenario?: string;
 }
 interface VehicleItem {
     /** Add this to the scene: origin at the centre of the footprint on the floor, front facing +z. */
@@ -899,4 +917,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 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 };
+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 };