@adatechnology/game-contracts 0.13.0 → 0.15.0

package/README.md

@@ -32,7 +32,7 @@ Browser without a bundler (the global is `GameContracts`):
 | Destruction | `DestructibleSpec`, `PartSpec`, `Hit`, `DestructionEvent`, `ObjectState`, `PartState`, `JointSpec`... | the vocabulary of parts, joints, hits, events and state |
 | Impact | `IMPACT_CONTRACT`, `checkHit(hit)` | the fields a weapon or hazard must put in a `Hit`, per damage type |
 | Own destruction | `DestructibleImpl`, `checkDestructible(impl, { materials })` | a module that owns its destruction (a car with its own panel rule) |
-| Weapons | `Shot`, `Use`, `shotToHit(shot, point, normal?)` | what a weapon produces, and the `Hit` a shot makes at a point |
+| Weapons | `Shot`, `Use`, `shotToHit(shot, point, normal?)`, `shotExtras(shot, distance?)` | what a weapon produces, and the `Hit` a shot makes at a point |
 | Fluids | `ContainerSpec`, `LiquidId`, `ItemUseDef` | what an item says about the liquid it holds and how it is used |
 | Animation | `AnimationClipSpec`, `ItemAnimationContract`, `checkAnimation(clip, partIds)` | use animations an item brings (a door `open`, a pistol `reload`) |
 | Module | `TestableModule`, `TestableItem`, `ModuleScenario` | what a module hands the test room |
@@ -129,6 +129,7 @@ metrics: () => [{ id: 'particles', name: 'Particles', max: 400, read: () => fx.p
 Tool events are named after a tool's cycle, not a firearm: `mode`, `fault`, `clear` (start / end) and `safety`, and `shot` carries `rounds`
 (cartridges spent) next to `shots` (projectiles, always 1 or more) and the `mode`; a dud round is its own `misfire` event, not a `shot` of zero. `HostTool` may report `mode`, `fault`, `safety` and `heat` (0..1).
 `host.configureTool(settings)` takes a `Record<string, string>` keyed by the id of the module's own control; the test room applies `condition` and `ammo_quality` and ignores other ids.
+`host.player()` returns the `PlayerState` (`position`, `yaw`, `pitch`, `crouching`, `speed` in m/s, `running`, `cameraMode`); a `{ type: 'player' }` event tells when crouching or the camera mode changes.
 
 ### Sound and weather the host lends
 
@@ -141,6 +142,20 @@ store that implements the bus, and `DEFAULT_ENVIRONMENT` is the calm dry day.
 
 Everything is exported from the package root; see `src/*.ts` for the doc comments. Units: metres, seconds, joules, millimetres (calibre), degrees Celsius.
 
+## Ignition of a leak
+
+`Hit.ignition` (`{ spark, flame }`), `Hit.incendiary` and `Hit.tracer` say what a round brings to a leak of flammable fluid; `IgnitionRules` / `DEFAULT_IGNITION_RULES` are the numbers
+of the container side (the `fillCurve`, the `sparkTarget` of the wall, `fireNear`), `ignitionChance(hit, { sparkTarget, fill, fluid? }, rules?)` is the chance that one round that went through
+lights the leak, `fillFactor(fill, curve?)` the curve and `sparkTargetFactor(materialId, isMetal, rules?)` the wall. `game-destruction` and `game-vehicles` use them; a plain bullet only leaks.
+
+## Categories (kinds with inheritance)
+
+`defineCategories(defs, { extra, patches, remove })` builds a `CategoryRegistry`: each `CategoryDef` has an `id`, an optional `extends` (any depth), `defaults`, `requires` (contract ids) and `abstract`.
+`defaults(id)` deep-merges along the chain (root first, arrays replace), `requires(id)` is the deduped union, `chain(id)`, `isA(id, ancestor)` and `check()` (unknown parent, cycle, duplicate id) complete it.
+`resolveEntry(registry, entry)` puts the category defaults under an entry (the entry wins); `checkCategorized(entries, registry, checkers, { allow })` runs the `ContractChecker` of every required contract on the resolved entry and
+reports `"<id>" (<kind>): <problem>, required by <category>`; `allow` lists known gaps that go to `allowed` instead of `problems`.
+Items only name their `kind`, so a game can insert a new parent above existing types (`patches: { canned_food: { extends: 'preserved' } }` with `preserved` extending the old parent) or add a child under any type, and every item keeps resolving, now with the extra defaults and requirements, without being edited.
+
 ## Português
 
 Os contratos de que todo módulo de jogo depende, e só isso: tipos mais alguns verificadores pequenos e puros, **sem dependências em tempo de