bard-legends-framework 1.5.0 → 1.5.2

package/AGENTS.md

@@ -0,0 +1,351 @@
+# bard-legends-framework — AI Agent Guide
+
+> **Audience**: AI coding agents working in games built on `bard-legends-framework`.
+> This file is self-contained. Read it **instead of** the library source in
+> `node_modules/bard-legends-framework`. Everything you need to use the framework correctly is here.
+>
+> **Hard dependency**: the framework is built on `actions-lib` (every observable, stream and
+> lifecycle rule comes from it). You MUST also know that library — read its `AGENTS.md`. In
+> particular: every subscription/stream must be `.attach(owner)`-ed, idle streams self-destruct,
+> pipelines are linear, delivery is synchronous. Those rules are assumed below and not repeated.
+
+`bard-legends-framework` is a TypeScript 2D game framework over **PixiJS** (rendering) and **p2**
+(physics). It gives the game a strict, decorator-driven **layered architecture** with dependency
+injection, so gameplay code is organized into self-contained **modules** that talk to each other
+only through narrow public APIs. Lifecycle is `actions-lib` attachment all the way down: every
+entity, view, scene and subscription is owned by a parent and dies when the parent dies.
+
+---
+
+## Core mental model (read this first)
+
+1. **The game is a tree of `actions-lib` attachables.** `Scene` → `Entity` → subscriptions/child
+   entities; `Entity` → its `View` → Pixi containers. Destroying any node cascades. You rarely
+   call `destroy()` directly — you destroy the owner (close a scene, destroy an entity) and the
+   rest follows.
+
+2. **Six roles, each with a decorator.** Every gameplay file is exactly one of these:
+
+   | Role | Decorator | Extends | Responsibility |
+   | --- | --- | --- | --- |
+   | **Entity** | `@EntityDecorator()` | `Entity` family | Holds **state** (`Variable`/`Action`/`Reducer`/`Reference`). No rendering, no orchestration. |
+   | **View** | `@ViewDecorator({ entity })` | `View` | Renders one entity with Pixi. Auto-created/destroyed with its entity. |
+   | **Service** | `@ServiceDecorator()` | (plain class) | Business logic / orchestration. Singleton, injectable. |
+   | **Gateway** | `@ServiceDecorator()` | (plain class) | A module's **public API**. The only thing other modules import. |
+   | **Controller** | `@ControllerDecorator({ controllerLink })` | (plain class) | Receives gateway calls, forwards to the Service. Hidden from other modules. |
+   | **Scene** | `@SceneDecorator()` | `Scene<In, Out>` | A top-level game state (title, battle, map…). Owns its entities; has an update loop. |
+
+3. **Modules are folders; cross-module calls go through Gateways only.** A module
+   (`HUD`, `PLAYER_SHIP`, `CAMPAIGN`…) groups one feature's entities/views/services/gateway.
+   **Never import another module's Service, Entity or View.** Import its `Gateway` (from the
+   module's `⚜️gateways` barrel) and call methods on it. This is what keeps modules decoupled and
+   import cycles impossible. (See [Why Gateway + Controller](#why-gateway--controller).)
+
+4. **Dependency injection by constructor type.** Services, Gateways and Controllers receive their
+   dependencies as typed constructor parameters — the framework resolves and caches singletons
+   (reflect-metadata). Get one outside a constructor with `Service.get(SomeService)`. Do **not**
+   `new` a Service/Gateway/Controller yourself.
+
+5. **Two registration mechanisms, both wired at boot by an eager glob.** Controllers (`@Controller`)
+   register to their `ControllerLink`; Views (`@View`) register against their entity class. The app
+   entry eagerly imports every `*.controller.ts` and `*.view.ts` so those side effects run before
+   gameplay starts (see [Bootstrap](#bootstrap)). A new controller/view file does nothing until it
+   matches that glob — keep the `.controller.ts` / `.view.ts` suffix.
+
+6. **`actions-lib` is the nervous system.** Entity state is `Variable`/`Action`/`Reducer`. Async
+   flows (scene open, animations, `onClose`, gateway results) are `IdleSingleEvent`/`IdleSequence`.
+   Attach everything; return idle streams from functions callers may ignore.
+
+---
+
+## Folder convention (one module)
+
+Emoji-prefixed folders are load-order / category markers. A typical module:
+
+```
+SOME_MODULE/
+  ⚜️gateways/                  ← public surface
+    some.gateway.ts            ← @ServiceDecorator class + `export const XLink = new ControllerLink()`
+    controllers/some.controller.ts  ← @ControllerDecorator({ controllerLink: XLink })
+    dtos/shared.dto.ts         ← interfaces crossing the module boundary (DTOs)
+    index.ts                   ← barrel: re-exports the Gateway + DTOs ONLY (never the Service)
+  📐services/some.service.ts   ← @ServiceDecorator, real logic (module-private)
+  🧊entities/some.entity.ts    ← @EntityDecorator, state (module-private)
+  🧩views/some.view.ts         ← @ViewDecorator, rendering (module-private)
+```
+
+Top-level: `🏹scenes/` (Scene classes, may nest their own sub-modules), `⚗️libraries/` (shared UI
+widgets/helpers), `☄️assets/` (generated sprite/definition data). Other modules import from the
+`⚜️gateways/index.ts` barrel — never reach past it.
+
+---
+
+## The roles in detail
+
+### Entity — state only
+
+```ts
+import { Variable, Reducer } from 'actions-lib';
+import { EntityDecorator, SingletonEntity } from 'bard-legends-framework';
+
+@EntityDecorator()
+export class HudEntity extends SingletonEntity {
+  readonly barState = new Variable<StatusBarState>(DEFAULT);
+  readonly isTransitioning = Reducer.createOr();
+  constructor(public readonly pilotThumbnail: SpriteID) { super(); }
+}
+```
+
+- An Entity is an `IDAttachable`: it has `.id`, `onDestroy()`, and must be attached to a scope
+  (`new HudEntity(...).attach(Scene.getActiveSceneOrFail())`). When the scope dies, the entity and
+  all state subscriptions die.
+- **Put only state here.** No Pixi, no orchestration, no cross-module calls. Logic lives in the
+  Service; rendering in the View.
+- Static lookups: `MyEntity.getInstanceByID(id)`, `getInstanceByIDOrFail(id)`, `getEntities()`.
+
+**Entity base classes** — pick the narrowest that fits:
+
+| Base | Use for |
+| --- | --- |
+| `Entity` | Plain stateful object, many instances. |
+| `SingletonEntity` | At most one alive at a time. Adds `getInstance()/getInstanceOrFail()`, `getInstanceAsync(): IdleSingleEvent`, `continuesSubscription()` (open/close stream). |
+| `MovableEntity` | Has `position`/`rotation`/`velocity`/`rotationalSpeed` as `Variable`s, no physics body. |
+| `MovablePhysicsEntity` | A **dynamic** p2 body; the framework drives its `position`/`rotation`/`velocity` Variables from the simulation. Has `onCollision`, `mass`, `area`. |
+| `ImmovablePhysicsEntity` | A **static** p2 body (walls, platforms). |
+
+### View — render one entity
+
+```ts
+import { Container, Game, Service, Sprite, View, ViewDecorator } from 'bard-legends-framework';
+
+@ViewDecorator({ entity: HudEntity })
+export class HUDView extends View {
+  private hudService = Service.get(HudService);
+  constructor(private entity: HudEntity, private someGateway: SomeGateway) {  // DI: entity first, then injectables
+    super();
+    let container = new Container().displayParent(Game.camera.layers.foregroundScreen).attach(this);
+    this.entity.barState.subscribe(v => bar.setState(v)).attach(this);          // attach to the view
+  }
+}
+```
+
+- **Auto-lifecycle**: when an entity of the decorated class is created, its View is instantiated
+  automatically (constructor args = the entity, then DI-resolved services/gateways). When the
+  entity is destroyed, the View is destroyed. **You never `new` or attach a View yourself.**
+- The View is the owner for all its Pixi objects and subscriptions: end every chain with
+  `.attach(this)`.
+- A View **reads** entity state and reflects it; it should not mutate game state. User input →
+  call a `Service` method (often `Service.get(...)`), which mutates the entity.
+- `View.update(time, delta)` exists if you need per-frame work; static `View.getInstance(entityID)`.
+
+### Service — logic & orchestration
+
+```ts
+@ServiceDecorator()
+export class HudService {
+  constructor(private playerShipGateway: PlayerShipGateway, private optionsMenuGateway: OptionsMenuGateway) {}
+  createUI(options: CreateHudOptionsDTO): void {
+    let hud = new HudEntity(/*…*/).attach(Scene.getActiveSceneOrFail());
+    this.playerShipGateway.subscribeToShipResourceStates()
+      .tap(s => { hud.barState.value = toBarState(s); })
+      .attach(hud);
+  }
+}
+```
+
+- Singleton, constructor-injected. The only role allowed to **create entities** and run async
+  orchestration. Owns subscriptions by attaching them to a relevant entity/scene.
+- It may depend on other modules — **but only via their Gateways** (injected). It may use its own
+  module's Service/Entity/View directly.
+
+### Why Gateway + Controller
+
+These two together let module B call module A without B importing A's internals (no cycles, no
+leaked private classes):
+
+```ts
+// A/⚜️gateways/a.gateway.ts  — imported by other modules
+export const ALink = new ControllerLink();
+@ServiceDecorator()
+export class AGateway {
+  doThing(x: number): void { return ALink.trigger('doThing', x); }   // public, thin, type-safe
+}
+
+// A/⚜️gateways/controllers/a.controller.ts — module-private, registered by eager glob
+@ControllerDecorator({ controllerLink: ALink })
+export class AController {
+  constructor(private aService: AService) {}
+  doThing(x: number): void { this.aService.doThing(x); }             // forwards to real logic
+}
+```
+
+- The **Gateway** is a tiny, dependency-free facade other modules import. It holds no logic — each
+  method just `link.trigger('methodName', ...args)` and returns the result.
+- The **Controller** binds to the same `ControllerLink` and dispatches the trigger to the real
+  `Service`. It lives behind the module boundary and is loaded via the eager `*.controller.ts` glob.
+- Net effect: importing `AGateway` pulls in **none** of A's services/entities. The link is resolved
+  at runtime, breaking the static import graph. Gateway method signatures and DTOs (in `dtos/`) are
+  the module's contract.
+- **Rule**: keep Gateways logic-free passthroughs; keep their method/DTO names stable; never expose
+  an Entity/Service instance across the boundary — cross with plain DTOs.
+
+### Scene — a top-level game state with an update loop
+
+```ts
+@SceneDecorator()
+export class TitleScene extends Scene<void, TitleSceneOutputDTO> {  // <Input, Output>
+  constructor(private cameraGateway: CameraGateway, private cockpitGateway: CockpitGateway) { super(); }
+  protected init(): IdleSingleEvent {                 // build the scene; return when ready
+    this.cockpitGateway.create().tap(out => this.close(out)).attach(this);
+    return Game.camera.appear(true, 'pureBlack');
+  }
+  protected update(time: number, delta: number): void { /* per-frame */ }
+  protected prepareToClose(): IdleSingleEvent { return Game.camera.appear(false, 'pureBlack'); }
+}
+```
+
+- `Scene<InputType, OutputType>`: typed input passed to `open`, typed result delivered via `close`.
+- **Lifecycle hooks (abstract, you implement):** `init(input)` build & return readiness;
+  `update(time, delta)` called every frame while active; `prepareToClose()` run an exit transition.
+- **Open / close (callers):**
+  ```ts
+  BattleScene.open({ battle })                  // static; IdleSingleEvent<BattleScene>
+    .asyncMap(scene => scene.onClose)           // resolves with OutputType when the scene closes itself
+    .tap(result => /* route to next scene */)
+    .attach(owner);
+  ```
+  Inside the scene, `this.close(output)` triggers `prepareToClose()` then resolves `onClose`.
+- Only one scene is active at a time. Statics: `Scene.activeScene`, `Scene.getActiveSceneOrFail()`,
+  `Scene.isTransitioning`, `Scene.cancelActiveScene()`, `MyScene.getInstanceOrFail()`,
+  `MyScene.isActive()`.
+- A scene is the natural **owner** for the entities it spawns: `new XEntity().attach(scene)`.
+- `Scene.destroy()` is `@deprecated` — drive lifecycle with `open`/`close`/`cancelActiveScene`.
+
+---
+
+## Bootstrap
+
+```ts
+import { Game, Service } from 'bard-legends-framework';
+
+// MANDATORY: register every controller and view via side-effecting import (Vite glob).
+import.meta.glob('./**/*.controller.ts', { eager: true });
+import.meta.glob('./**/*.view.ts', { eager: true });
+
+let game = new Game({ devMode, resolution: 2, maxScreenResolution });
+await game.setup({ assetDefinitions: [...SpriteAssets, ...FontAssets], spriteDefinitions: SpriteDefinitions });
+Service.get(GameCycleGateway).startGame();   // kick off the first scene via a gateway
+```
+
+- `Game` is the global singleton: `Game.instance`, `Game.camera`, `Game.time`, `Game.pause`
+  (a `Reducer<boolean>` — open an effect to pause), `Game.instance.screenSize`/`screenSizeCenter`
+  (`PersistentNotifier<Vector>`), `setResolution`, `screenPositonToStagePosition`.
+- `setup` loads assets and must be awaited before any scene opens.
+- If you add a module, no manual registration is needed **as long as** files keep the
+  `*.controller.ts` / `*.view.ts` suffixes so the globs pick them up.
+
+---
+
+## Rendering (Pixi wrappers)
+
+All display objects extend `Container` (itself `ContainerAttributes`). They are chainable and are
+`actions-lib` attachables — **attach every one you create**.
+
+```ts
+new Sprite(def)                 // or Sprite.createByName('spriteId')
+  .setPosition(pos, { holdFrom: Vector.half })   // anchor-aware placement; round defaults true
+  .setScale(0.75)
+  .setZIndex(10)
+  .displayParent(parent)        // parent: a Container OR a Game.camera.layers.* id
+  .attach(owner);               // lifecycle owner (usually `this` in a View)
+```
+
+- **Containers**: `Container`, `Sprite`, `Graphics` (factory shapes: `createRectangle`,
+  `createCircle`, `createPolygon`, `createArrow`, `createDashedLine`…), `Text`, `RichText`,
+  `Placeholder`, plus layout helpers `DisplayObjectArray<T>` (diffs a list via `trackBy`),
+  `ScrollAreaUI`, menus (`MenuUI`/`MenuEntity`/`MenuView`).
+- **Attributes** (on every container): `position/x/y`, `size`, `rotation`/`rotationValue`,
+  `zIndex`, `scale`, `alpha`, `skewX/Y`, `mirror`, `flip`, `aspectRatio`, `interactive`, `cursor`,
+  `setMask`, `boundingBox`, `hitTest`. Setters come in fluent `setX()` and property forms.
+- **Display tree vs. ownership are separate**: `displayParent()` controls where it renders (and
+  camera layer); `attach()` controls when it's destroyed. Set both.
+- **Camera layers** (`Game.camera.layers[...]`): `backgroundScreen`, `background`, `main`,
+  `foreground`, `foregroundScreen`. `*Screen` layers are fixed to the screen (HUD/menus); the
+  others move with the camera (world). `Game.camera` also has `setPosition`, `setTransition`,
+  `appear(on, type)`.
+- **Input**: `container.on(ContainerEventType.Click)` returns a `Sequence` (attach it); UI widgets
+  expose `onClick`. Global input via injected `KeyboardService` / `MouseService`.
+
+---
+
+## Animation
+
+- `Animator(target, 'propName' | ['a','b'], options)` — tween numeric properties; `.animate({...})`
+  returns a `SingleEvent<void>`, plus `.set(...)`, `.completeAnimation()`, `.value` notifier.
+- `Animations.{lineer,easeIn,easeOut,easeInOut,easeInOutCubic,blink}` and
+  `AnimationInterpolationFunctions` for easing curves.
+- State-driven helpers: `StateAnimation<T>`, `FadeInStateAnimation<T>`, `SlideStateAnimation`,
+  `FadeInContent<T>`, `SlideInContent<T>` — drive enter/leave transitions by `setState`/`setIndex`.
+- `UpdateCycle` is the frame clock: `sceneUpdateAction` (+`before`/`after`), `wait(duration)`,
+  `lastDelta`, `registerUpdateModifier` (e.g. time-scale). Prefer the scene's `update()` hook over
+  subscribing directly unless you need global timing.
+
+---
+
+## Physics (p2)
+
+- Bodies are entities: extend `MovablePhysicsEntity` (dynamic) or `ImmovablePhysicsEntity` (static).
+  Construct with a `physicsWorldID` and a `PhysicsEntityDefinition` (`shapeDefinition` =
+  material/group/shapeType/shapeData, plus `position`, `rotation`, `addInEmptySpace`,
+  `includeOnPathfinding`). The framework keeps the entity's `position`/`rotation`/`velocity`
+  Variables in sync with the simulation.
+- Collisions: subscribe to `entity.onCollision` (`CollisionReport[]` with `self`/`target` details:
+  normal, mass, area, contact position).
+- World & queries via injected `PhysicsGateway`: `createPhysicsWorld`, `hitTest`, `findPath` /
+  `findPathDirection`, `applyImpulse`, `createExplosion` / `createElipticExplosion` (return
+  `ExplosionHit[]`), `getMapSize`, `setPaused`.
+- Bodies belong to `PhysicsBodyGroup`s; which groups interact is set per-world via
+  `interactingBodyGroups`. Pathfinding helpers: `PathFinder`, `VectorFieldPathFinder`,
+  `ClosestAvailableSpaceHelper`.
+
+---
+
+## Services you inject (built-ins)
+
+Resolve via constructor injection or `Service.get(X)`:
+
+- `KeyboardService` — `keyPressed`/`keyReleased` notifiers, `isKeyDown(code, { onlyPressedThisFrame })`.
+- `MouseService` — `stagePosition`/`screenPosition` (world vs. screen), `mainButtonState`,
+  `secondaryButtonState`, `initialMouseMovementHappened`.
+- `MouseTargetFocusService` — “did the user click-to-focus a world point” events.
+- `CameraGateway` / `PhysicsGateway` — camera & physics façades shown above.
+
+---
+
+## Testing
+
+- Call `BardLegendsHardReset.hardReset()` in `beforeEach` (alongside `actions-lib`'s
+  `ActionLib.hardReset()`) to clear entity/singleton/DI registries between tests.
+- Drive frames with `UpdateCycle.triggerUpdateTick(delta)`; use fake timers for `wait`/animations.
+- Because delivery is synchronous (`actions-lib`), most assertions need no awaiting.
+
+---
+
+## Do / Don't
+
+```ts
+// DO: keep state in the Entity, logic in the Service, pixels in the View.
+// DO: cross module boundaries only through an injected Gateway + DTOs.
+// DO: attach every container, subscription and stream to a clear owner (usually `this`/the entity/the scene).
+// DO: create entities in Services; let Views appear automatically; own entities with the Scene.
+// DO: return IdleSingleEvent/IdleSequence from async functions; route scenes via open().asyncMap(s => s.onClose).
+// DO: keep Gateways as thin link.trigger(...) passthroughs; keep DTO/method names stable.
+
+// DON'T: import another module's Service/Entity/View — import its Gateway.
+// DON'T: new or attach a View yourself, or new a Service/Gateway/Controller — use DI / Service.get / let entities spawn views.
+// DON'T: put logic in a Gateway, or Pixi/orchestration in an Entity.
+// DON'T: rename a *.controller.ts / *.view.ts file off-suffix — it silently stops registering.
+// DON'T: call scene.destroy() (deprecated) — use close()/cancelActiveScene().
+// DON'T: mutate game state from a View — call a Service method instead.
+// DON'T: forget actions-lib rules (attach-or-throw, linear pipelines, no raw Promises) — see its AGENTS.md.
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bard-legends-framework",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Bard Legends Framework",
   "main": "dist/index.js",
   "publishConfig": {
@@ -15,7 +15,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "AGENTS.md"
   ],
   "repository": {
     "type": "git",