@adatechnology/game-contracts 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Fernandes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# @adatechnology/game-contracts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The contracts every game module depends on, and nothing else. Types plus a few tiny pure checkers, **no runtime dependencies**, MIT.
+
+The idea: a vehicle, a chair, a pistol or a house is a *module*. It does not need the default destruction world, a renderer or the test room.
+It only needs to agree on a few shapes, and these are they. The destruction package, the weapons package, the fluids package and the test room all
+depend on this one and re-export what they used to define, so `import { Hit } from '@adatechnology/game-destruction'` keeps working.
+
+```text
+your module ──▶ game-contracts ◀── game-destruction / game-weapons / game-fluids / game-test-room
+```
+
+## Install
+
+```sh
+pnpm add @adatechnology/game-contracts
+```
+
+Browser without a bundler (the global is `GameContracts`):
+
+```html
+<script src="https://unpkg.com/@adatechnology/game-contracts/dist/index.global.js"></script>
+<script>
+  const problems = GameContracts.checkHit({ type: 'blunt', point: [0, 1, 0] })
+</script>
+```
+
+## What is in it
+
+| Contract | Exports | Used for |
+|---|---|---|
+| 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 |
+| 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 |
+
+### Destruction: a module owns its object
+
+```ts
+import type { DestructibleImpl } from '@adatechnology/game-contracts'
+import { checkDestructible } from '@adatechnology/game-contracts'
+
+const impl: DestructibleImpl = {
+  id: 'rental_car_1',
+  describe: () => ({ parts: [/* body, door_l, wheel_fl... in the impl's local space */] }),
+  hit: (hit) => [/* events: every one has object === id and names a part listed by describe() */],
+  state: () => ({ /* ObjectState */ }),
+}
+
+checkDestructible(impl, { materials: world.materials.keys() }) // { ok, problems }
+```
+
+Hits arrive in world space and events go out in world space. `checkDestructible` needs no world: it validates `describe()`, hits the impl with a
+500 J ballistic hit, and checks that `state()` matches `describe()`, hit points never go negative, `update(0.016)` returns an array and every event is
+well-formed and JSON-serializable. The contracts package does not know your materials: pass their ids (the world's `world.materials.keys()`) or
+leave `materials` out to skip that check.
+
+### Weapons
+
+```ts
+const hit = shotToHit(shot, point) // { type: 'ballistic', energy: shot.energyAt(distance), caliber, direction, ... }
+checkHit(hit)                       // [] when valid
+```
+
+### Animations
+
+A clip is plain data: keys with poses (offsets from the rest pose, Euler XYZ) for the item root and for named parts, plus events.
+`checkAnimation(clip, partIds)` verifies a snake_case id, a positive duration, ordered times inside the clip, finite vectors, that every moved part
+is one of `partIds`, and well-formed events.
+
+```ts
+const open: AnimationClipSpec = {
+  id: 'open',
+  duration: 1.2,
+  keys: [{ t: 0 }, { t: 1.2, parts: { door_l: { rotation: [0, 1.1, 0] } } }],
+  events: [{ t: 0.15, type: 'sound', data: { key: 'door_latch' } }],
+}
+checkAnimation(open, ['body', 'door_l']) // { ok: true, problems: [] }
+```
+
+### A module for the test room
+
+```ts
+import type { TestableModule } from '@adatechnology/game-contracts'
+
+export const RENTAL_CARS: TestableModule = {
+  id: 'rental_cars',
+  name: 'Rental cars',
+  group: 'Rental cars',
+  items: (locale) => [{ id: 'rental_car', name: 'Rental car', build: (THREE) => buildCar(THREE), impl: (root, id) => createCarImpl(root, id), animations: [open] }],
+  scenarios: (locale) => [/* { id, name, run(ctx) } */],
+}
+
+room.loadModule(RENTAL_CARS) // items join the catalogue, scenarios become buttons, contract checks write ✓ / ✗ lines to the log
+```
+
+`build` receives the host's three.js namespace and returns its `Object3D` (both are `unknown` here: this package has no dependency on three.js).
+`impl` receives the object id the host gives the item and `DestructibleImpl.id` must equal it.
+
+## API
+
+Everything is exported from the package root; see `src/*.ts` for the doc comments. Units: metres, seconds, joules, millimetres (calibre), degrees Celsius.
+
+## 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
+execução**. Um carro, uma cadeira, uma pistola ou uma casa é um *módulo*; ele não precisa do mundo de destruição padrão, de um renderizador nem da
+sala de testes, só concordar com estas formas. Os pacotes de destruição, armas, fluidos e a sala de testes dependem deste e reexportam os tipos que
+antes definiam, então `import { Hit } from '@adatechnology/game-destruction'` continua funcionando.
+
+- **Destruição própria**: `DestructibleImpl` (o módulo manda no seu objeto) e `checkDestructible(impl, { materiais })`, que valida `describe()`,
+  aplica um golpe de 500 J e confere eventos e estado sem precisar de mundo.
+- **Impacto**: `IMPACT_CONTRACT` e `checkHit(hit)` dizem quais campos cada tipo de dano exige.
+- **Armas**: `Shot`, `Use` e `shotToHit(shot, ponto)`.
+- **Fluidos**: `ContainerSpec`, `LiquidId` e `ItemUseDef`.
+- **Animações**: `AnimationClipSpec` e `checkAnimation(clipe, idsDasPeças)` (uma porta `open`, uma pistola `reload`).
+- **Módulo**: `TestableModule` entrega itens, animações e cenários à sala de testes; `room.loadModule(modulo)` roda as verificações e escreve linhas
+  ✓ / ✗ no log. Assim o módulo de um carro de aluguel já nasce com as suas animações e o seu jeito de quebrar.