@jgengine/core 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -11,6 +11,53 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
+## 0.8.0
+
+Transport-agnostic multiplayer (socket.io, WebRTC p2p, LAN/Fly adapters) plus grid/voxel
+and puzzle primitives, HUD-only presentation, cumulative leveling, and a round of
+controller/camera/sensor additions. **Breaking:** the `gameui` component kit moved out of
+`@jgengine/react` onto the shadcn registry.
+
+### Migrate
+
+- Bump every `@jgengine/*` dependency to `^0.8.0` (the eight packages version in lockstep).
+- Additive only, except for `gameui` — every other 0.7.0 API is unchanged; opt into any of the below by importing it directly.
+- **Breaking:** replace any `@jgengine/react/gameui` import with the equivalent registry component (`npx shadcn@latest add https://jgengine.com/r/<name>.json`), and swap `GameUiThemeProvider` for `--jg-*` CSS variables on a wrapper element. `GameIcon` and friends moved to `@jgengine/react/gameIcons`.
+- `leveling({ thresholdMode: 'cumulative' })` is opt-in; the default `perLevel` behavior is unchanged.
+- `defineGame.physics.gravity`/`jumpVelocity` are now read by the built-in kinematics controller every frame — if a game already set them expecting a no-op, jump/fall now actually reflects them; omit both to keep the previous defaults.
+
+### Added
+
+- Cumulative leveling — `leveling({ thresholdMode: 'cumulative' })` tracks xp as a lifetime total that resolves upward across levels and clamps at the max-level threshold once capped (#12).
+- Direction-aware pool depletion — `EffectSystem.canReceive(instanceId, effect, magnitude?)` takes an optional signed magnitude; negative checks the opposite direction and returns `pools-depleted` only when every stat in the receive order is already at max, so heals reach fully-depleted targets (#168).
+- Puzzle primitives — `puzzle/cellGrid` (uniform-cell boards: line-clear, match-3 cascade, run detection) and `puzzle/fallingPiece` (rotation-state shapes, ghost drop, lock delay, classic gravity/level/score curves) for Tetris/match-3 games (#166).
+- Voxel field — `world/voxelField` (`createVoxelField`, chunked block lattice, neighbors/exposedFaces, 3D DDA raycast, dirty-tracked `chunkVersion`) for voxel games and instanced renderers; assert on `field.summary()` the way environment worlds assert on `summarizeEnvironment` (#166).
+- `defineGame` games may omit `assets` (an empty catalog is injected); `PlayableGame.presentation: 'hud'` mounts no 3D canvas/camera/pointer for board/card/menu games; an `environment()` world auto-renders as the shell's backdrop when `PlayableGame.environment` is unset (#166).
+- Declared-action intent board — `turn/intent` `createIntentBoard` for one-turn-ahead intents (Slay-the-Spire style): declare/peek/all/consume/clear (#168).
+- `turnLoop` lifecycle hooks — `config.onTurnStart`/`onTurnEnd` fire on every `advanceTurn()`; `ctx.game.turn.loop(id, config)` lazily creates/returns a notify-wrapped `TurnLoop` so every mutation (`advanceTurn`/`advancePhase`/`advanceRound`/`spend`/`gain`/`refill`/`setOrder`/...) auto-bumps `ctx.version()` with no manual wiring (#163/#168).
+- `ctx.game.store` — a reactive per-game keyed store (`set`/`delete`/`get`/`has`/`subscribe`/`mapSnapshot`/`arraySnapshot`) plus `@jgengine/react`'s `useGameStore` selector hook, replacing hand-rolled module-level stores for ad-hoc reactive game state; `ctx.game.cards.pile(id, config?)` lazily creates/returns a notify-wrapped `CardPile` the same way; `createCardPile` gained an `onChange` hook for headless use; `CommandDefinition.apply` may return void for side-effect-only commands (#163).
+- Camera — `sideScroll` rig (fixed lateral follow for 2.5D platformers/beat-'em-ups), a `none` rig (no camera mounted; pairs with `PlayableGame.presentation: 'hud'`), `rts.pan: false` (static backdrop camera: no pan/edge-scroll/rotate/zoom, still re-centers on the follow target), and the `observer` rig now defaults to the local player when `bind` is unset (#167).
+- Sensors + session — `sensor/concealment` (`colorDistance`/`concealmentScore`/`createConcealmentSensor`), `sensor/freezeMonitor` (`createFreezeMonitor`), `session/roles` (`assignRoles`); `createRoundState`'s `RoundConfig.teams` accepts per-team roles and an optional `winCondition` that `evaluate()` checks each tick, and takes an optional `phaseOrder` for arbitrary named phase cycles (`concludeRound`/`evaluate` settle only while the current phase is neither the first nor the last entry) (#151).
+- Appearance replication — presence rows carry an optional per-slot appearance channel (cosmetic ids, hex tints, model keys) alongside pose, riding the existing pose message with no protocol bump; wire `ctx.player.cosmetics.get(userId)` into the outgoing pose (#151).
+- `ctx.input` — a per-frame held-action snapshot (`publish(held)`/`isDown(action)`/`held()`) without bumping `ctx.version()`; action bindings gained `repeatMs` (repeat-fire while held); every command resolved from a bound action now carries `aim`; `pointer.secondaryCommand` runs a command on right-click off the same raycast as move/ping (#164).
+- Object spatial queries + entity patching — `ctx.scene.object.at`/`inBox`/`raycast`/`raycastAll` over unit-box objects; `ctx.scene.entity.update(id, patch)` for name/position/rotation/role/movement/behaviors/meta; per-instance `renderObject`/`objectStyles` overrides; `pointerService.worldHitCenter()` + pointer-lock center-ray aiming (#165).
+- Controller movement config — `PlayerMovementConfig` (`mode`: free/axis/grid, `axis`, `cellSize`, `collideObjects`, `beforeCommit` pre-commit hook) for the shell-driven walk controller; `defineGame.physics.gravity`/`jumpVelocity` are honored by the built-in walk controller (distinct from the standalone `physics/physicsWorld` rigid-body sim); `ctx.player.motion.impulse`/`setVerticalVelocity`/`setY`/`takePending` (`MotionIntents`); `entity.spawnPoseOf`/`resetToSpawn`/`resetAllToSpawn` (#162).
+- Model material/animation + paint — `ModelConfig.tint`/`metalness`/`roughness`/`animation` (GLTF clip playback, paused pose holds); `PointerHit.uv` + `pointerService.sampleSurface()` for material-aware picking; `ctx.scene.entity.paint` runtime paint layer, auto-rendered via a per-instance canvas texture with no per-game wiring; remote-player appearance tint recolors the shell's default capsule (#151).
+- **Transport pipe seam** (`@jgengine/ws/pipe`) — `createWsBackend` runs over any bidirectional string channel, not just a raw `WebSocket`: `TransportPipe`/`TransportPipeHandlers`/`TransportPipeFactory`, with `webSocketPipe(url, webSocketFactory?)` as the default. `createWsBackend({ userId, url?, pipe? })` — `url` stays the common case, `pipe` opens the seam to socket.io, WebRTC, and in-process loopback below.
+- **Browser-safe authoritative host** — `createGameHost` and `memoryPersistence` moved from `@jgengine/node` to `@jgengine/ws/host` (zero Node dependencies; `@jgengine/node` re-exports both unchanged from `@jgengine/node/host` / `@jgengine/node/persistence`, so existing imports keep working). `@jgengine/ws/hostRouter`'s `createHostRouter({ host, authenticate?, poseRules?, positionHistoryMs?, chatRateLimit?, chatHistoryLimit?, chatMaxBodyLength?, now? })` extracts the ws wire-protocol session logic out of `createGameWsServer` into a transport-agnostic `HostRouter` (`connect(transport) → { handleRaw, close }`, `rewind`, `close`); `@jgengine/node`'s `createGameWsServer` is now a thin binding of this router onto the `ws` npm package, same public API. `loopbackPipe(router): TransportPipeFactory` connects a `createWsBackend` straight into an in-process router.
+- **Socket.IO transport** — `@jgengine/ws/socketIoPipe` (`SocketIoLikeSocket` structural type, `socketIoPipe(socket)`, `createSocketIoBackend({ socket, userId, … })`) and `@jgengine/node/socketIoServer` (`attachGameSocketIoServer({ io, host, …router options }): { rewind, close }`, structural `SocketIoLikeServer`/`SocketIoLikeServerSocket`) ride the existing ws JSON protocol over socket.io's `send`/`message` frames — no socket.io dependency in either package's types. New `socketIo({ topology?, url? })` adapter in `@jgengine/core/runtime/adapter`.
+- **WebRTC peer-to-peer** (`@jgengine/ws/peer`) — one browser tab hosts, authoritatively, with no server process. `createPeerHost({ userId, host?, runtimes?, persistence?, tickMs?, router?, rtc? })` runs a `GameHost` + `HostRouter` in the host tab (`backend` is the host player's own loopback connection, `accept(offerCode) → Promise<answerCode>` per guest); `createPeerGuest({ userId, token?, rtc? })` offers/connects from the joining side. `encodePeerSignal`/`decodePeerSignal` turn SDP into copy-pasteable base64url codes for manual cross-machine signaling; `broadcastChannelSignaling(room)` automates it for same-origin multi-tab play, with `announcePeerHost`/`joinPeerSession` wiring host/guest to a `PeerSignaling` in one call. New `p2p({ topology?, room? })` adapter (topology defaults `"private"`).
+- **LAN adapter + Fly sugar** — `lan({ topology?, port?, path? })` in `@jgengine/core/runtime/adapter` resolves through `@jgengine/shell/multiplayer`'s `resolveShellMultiplayer` to `ws(s)://<page hostname>:<port ?? 8080><path ?? /ws>` derived from `window.location`, so any browser on the LAN auto-connects to whichever machine served the page — no URL configuration. `fly({ app, topology?, path? })` is `ws` sugar for a Fly.io deploy: resolves to `wss://<app>.fly.dev<path ?? "/ws">`. `apps/dev`'s Vite server now listens on the network (`server: { host: true }`) and exposes `?p2p=host` / `?p2p=join` query params wired through the new `resolvePeerShellMultiplayer({ gameId, role, room?, userId?, feedActions? })`.
+- `ws()` (`@jgengine/core/runtime/adapter`) gained an optional `url` field, carried through by `resolveShellMultiplayer` (`args.url ?? adapter.url ?? default`).
+
+### Removed
+
+- **The `gameui` component kit** (`@jgengine/react/gameui`) — the themed HUD kit (bars, slots, feedback, meters, panels, screens, reticles, icons) and its `GameUiThemeProvider`/`useGameUiTheme` theming have been removed. **Breaking** for anyone importing `@jgengine/react/gameui` (or its subpaths/barrel). The components now ship as installable shadcn registry items at `https://jgengine.com/r/<name>.json` (`npx shadcn@latest add https://jgengine.com/r/<name>.json`), styled with Tailwind + `--jg-*` CSS variables instead of a theme object. The icon catalog (`GameIcon`, `iconForAction`, `iconForItemId`, `isGameIconName`, `GameIconName`) moved to `@jgengine/react/gameIcons`. To theme, set the `--jg-*` variables on a wrapper element (the registry's `jg-theme` presets mirror the old `ember`/`synthwave`/`fieldkit` palettes) instead of wrapping in `GameUiThemeProvider`.
+
+### Docs
+
+- Added [CREDITS.md](CREDITS.md) crediting [achrefelouafi](https://github.com/achrefelouafi) for the MIT Three.js reference projects behind the procedural building, water, rain, and snow renderers, with links from the root, `@jgengine/core`, and `@jgengine/shell` READMEs.
+
 ## 0.7.0
 
 The engine-gaps release — 22 system-level additions across turn/tactics, cards & boards,

package/README.md

@@ -8,4 +8,6 @@ Import modules by path:
 import { createGameRuntime } from "@jgengine/core/runtime/gameRuntime";
 ```
 
+The renderer-free world layer includes a Gerstner `waterSurface` (`world/water`) and a seeded `generateBuilding` kit (`world/buildings`), whose wave math and building component vocabulary were shaped from **[achrefelouafi](https://github.com/achrefelouafi)**'s MIT [OceanThreejs](https://github.com/achrefelouafi/OceanThreejs) and [BuildingGeneratorThreeJS](https://github.com/achrefelouafi/BuildingGeneratorThreeJS) — see [CREDITS.md](../../CREDITS.md).
+
 Part of [JGengine](https://github.com/Noisemaker111/jgengine). AGPL-3.0-only.

package/dist/ai/spawnDirector.d.ts

@@ -21,6 +21,8 @@ export interface SpawnDirectorConfig {
     maxSpawnsPerTick?: number;
     loop?: boolean;
     seed?: number;
+    spawnPoints?: readonly NavPoint[];
+    spawnPointBias?: number;
 }
 export interface SpawnDirectorState {
     wave: number;
@@ -36,11 +38,14 @@ export interface SpawnDirectorState {
 export interface DirectorContext {
     alive: number;
     players?: number;
+    playerPositions?: readonly NavPoint[];
 }
 export interface SpawnRequest {
     entryId: string;
     cost: number;
     wave: number;
+    point?: NavPoint;
+    laneId?: number;
 }
 export interface DirectorStep {
     state: SpawnDirectorState;

package/dist/ai/spawnDirector.js

@@ -106,13 +106,25 @@ export function advanceSpawnDirector(config, state, dt, ctx) {
     let spawnedTotal = state.spawnedTotal;
     let alive = ctx.alive;
     const entries = config.waves[wave]?.entries ?? [];
+    const spawnPoints = config.spawnPoints;
+    const playerPositions = ctx.playerPositions ?? [];
     while (spawns.length < maxSpawns && alive < maxAlive) {
         const picked = pickEntry(entries, wave, budget, rng);
         if (picked === null)
             break;
         rng = picked.rng;
         budget -= picked.entry.cost;
-        spawns.push({ entryId: picked.entry.id, cost: picked.entry.cost, wave });
+        const spawn = { entryId: picked.entry.id, cost: picked.entry.cost, wave };
+        if (spawnPoints !== undefined && spawnPoints.length > 0) {
+            const [roll, nextRng] = nextRandom(rng);
+            rng = nextRng;
+            const point = pickSpawnPoint(spawnPoints, playerPositions, { roll, bias: config.spawnPointBias });
+            if (point !== null) {
+                spawn.point = point;
+                spawn.laneId = spawnPoints.indexOf(point);
+            }
+        }
+        spawns.push(spawn);
         spawnedThisWave += 1;
         spawnedTotal += 1;
         alive += 1;

package/dist/anim/easing.d.ts

@@ -0,0 +1,14 @@
+export type Easing = (t: number) => number;
+export declare function lerp(from: number, to: number, t: number): number;
+export declare function clamp01(t: number): number;
+export declare function smoothstep(t: number): number;
+export declare function easeInQuad(t: number): number;
+export declare function easeOutQuad(t: number): number;
+export declare function easeInOutQuad(t: number): number;
+export declare function easeInCubic(t: number): number;
+export declare function easeOutCubic(t: number): number;
+export declare function easeInOutCubic(t: number): number;
+export declare function easeOutBack(t: number): number;
+export declare function easeOutElastic(t: number): number;
+export declare function tween(from: number, to: number, t: number, easing?: Easing): number;
+export declare function timedProgress(startedAt: number, now: number, durationMs: number): number;

package/dist/anim/easing.js

@@ -0,0 +1,55 @@
+export function lerp(from, to, t) {
+    return from + (to - from) * t;
+}
+export function clamp01(t) {
+    return t < 0 ? 0 : t > 1 ? 1 : t;
+}
+export function smoothstep(t) {
+    const c = clamp01(t);
+    return c * c * (3 - 2 * c);
+}
+export function easeInQuad(t) {
+    const c = clamp01(t);
+    return c * c;
+}
+export function easeOutQuad(t) {
+    const c = clamp01(t);
+    return 1 - (1 - c) * (1 - c);
+}
+export function easeInOutQuad(t) {
+    const c = clamp01(t);
+    return c < 0.5 ? 2 * c * c : 1 - ((-2 * c + 2) ** 2) / 2;
+}
+export function easeInCubic(t) {
+    const c = clamp01(t);
+    return c * c * c;
+}
+export function easeOutCubic(t) {
+    const c = clamp01(t);
+    return 1 - (1 - c) ** 3;
+}
+export function easeInOutCubic(t) {
+    const c = clamp01(t);
+    return c < 0.5 ? 4 * c * c * c : 1 - ((-2 * c + 2) ** 3) / 2;
+}
+const BACK_OVERSHOOT = 1.70158;
+export function easeOutBack(t) {
+    const c = clamp01(t);
+    const s = BACK_OVERSHOOT + 1;
+    return 1 + s * (c - 1) ** 3 + BACK_OVERSHOOT * (c - 1) ** 2;
+}
+const ELASTIC_PERIOD = (2 * Math.PI) / 3;
+export function easeOutElastic(t) {
+    const c = clamp01(t);
+    if (c === 0 || c === 1)
+        return c;
+    return 2 ** (-10 * c) * Math.sin((c * 10 - 0.75) * ELASTIC_PERIOD) + 1;
+}
+export function tween(from, to, t, easing = smoothstep) {
+    return lerp(from, to, easing(clamp01(t)));
+}
+export function timedProgress(startedAt, now, durationMs) {
+    if (durationMs <= 0)
+        return now >= startedAt ? 1 : 0;
+    return clamp01((now - startedAt) / durationMs);
+}

package/dist/behaviour/behaviour.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Unity-style behaviour lifecycle over a headless id-keyed node tree, ported from
+ * vladkrutenyuk/three-start (MIT) and adapted to run without three.js: nodes are plain
+ * string ids (use entity instance ids to pair with `entityStore`), and the shell binds
+ * render-side hooks separately.
+ *
+ * Lifecycle per behaviour: `onAwake` (once, first activation) → `onEnable` (every
+ * inactive→active transition) → `onStart` (once, after the first `onEnable`) →
+ * `onUpdate` (per `world.update` while active) → `onDisable` (every active→inactive
+ * transition) → `onDestroy` (once, always — even if never activated).
+ *
+ * `world.start()` bootstraps in passes: modules awake → modules start → modules join
+ * update dispatch → ALL behaviours on effectively-active nodes awake (even disabled
+ * ones) → enable/start/subscribe. Behaviours attached during the module pass are
+ * deferred to the behaviour passes, so module `onUpdate` always dispatches before any
+ * behaviour `onUpdate`.
+ */
+/**
+ * Declaration-merging registry games and adapters augment for typed access to
+ * world modules:
+ *
+ * ```ts
+ * declare module "@jgengine/core/behaviour/behaviour" {
+ *   interface JGEngineRegister {
+ *     modules: { physics: PhysicsModule; director: DirectorModule };
+ *   }
+ * }
+ * ```
+ */
+export interface JGEngineRegister {
+}
+export type RegisterField<TKey extends string, TFallback = unknown> = TKey extends keyof JGEngineRegister ? JGEngineRegister[TKey] : TFallback;
+/** Resolves to the augmented module map when `JGEngineRegister` declares one. */
+export type BehaviourModules = RegisterField<"modules", Record<string, BehaviourModule>>;
+interface UpdateSubscriber {
+    onUpdate(dt: number): void;
+}
+interface BehaviourWorldInternal extends BehaviourWorld {
+    _subscribeUpdate(subscriber: UpdateSubscriber): void;
+    _unsubscribeUpdate(subscriber: UpdateSubscriber): void;
+    _isEffectivelyActive(nodeId: string): boolean;
+    _detachBehaviour(behaviour: Behaviour): void;
+}
+/**
+ * Subclass and override the lifecycle hooks. A behaviour only joins the per-frame
+ * update dispatch if it actually overrides `onUpdate` (prototype-identity check at
+ * each activation), so hook-only behaviours cost nothing per frame.
+ */
+export declare class Behaviour {
+    /** @internal */ _world: BehaviourWorldInternal | null;
+    /** @internal */ _nodeId: string | null;
+    /** @internal */ _awoken: boolean;
+    /** @internal */ _startedOnce: boolean;
+    /** @internal */ _isActive: boolean;
+    private _enabled;
+    private _destroyed;
+    /** The node this behaviour is attached to; available from `onAwake` onward, never in the constructor. */
+    get nodeId(): string;
+    get world(): BehaviourWorld;
+    get modules(): BehaviourModules;
+    /** Own enabled flag; effective activity also requires the node's hierarchy to be active. */
+    get enabled(): boolean;
+    /** Whether the lifecycle is currently in the active span (`onEnable` fired, `onDisable` not yet). */
+    get isActive(): boolean;
+    onAwake(): void;
+    onEnable(): void;
+    onStart(): void;
+    onUpdate(_dt: number): void;
+    onDisable(): void;
+    onDestroy(): void;
+    enable(): void;
+    disable(): void;
+    /** Flips the flag only when the node is hierarchy-inactive or the world hasn't started; lifecycle catches up on the next activation. */
+    setEnabled(enabled: boolean): void;
+    /** Detaches from the node and fires `onDisable` (if active) then `onDestroy`. */
+    destroy(): void;
+    /** @internal */
+    _activate(): void;
+    /** @internal */
+    _deactivate(): void;
+    /** @internal */
+    _destroy(): void;
+}
+/**
+ * A world-lifetime service with typed sibling access via `this.modules`. Modules awake
+ * and start before any behaviour during `world.start()`, subscribe to update dispatch
+ * first (their `onUpdate` fires before every behaviour's), and have no disable/destroy —
+ * they live as long as the world.
+ */
+export declare class BehaviourModule {
+    /** @internal */ _world: BehaviourWorldInternal | null;
+    get world(): BehaviourWorld;
+    get modules(): BehaviourModules;
+    onAwake(): void;
+    onStart(): void;
+    onUpdate(_dt: number): void;
+    /** @internal */
+    _subscribe(): void;
+}
+export interface BehaviourWorld {
+    /** Creates the node if missing (parented under `parentId` when given, else a root); reparents an existing node when `parentId` differs. */
+    add(id: string, parentId?: string): void;
+    has(id: string): boolean;
+    parentOf(id: string): string | null;
+    childrenOf(id: string): readonly string[];
+    /** Moves `id` (and subtree) under `parentId` (`null` = root), firing enable/disable cascades when effective activity changes. Throws on cycles. */
+    setParent(id: string, parentId: string | null): void;
+    /** Attaches and immediately activates when the world has started, the node is effectively active, and the behaviour is enabled (deferred during bootstrap). */
+    attach<T extends Behaviour>(nodeId: string, behaviour: T): T;
+    behavioursOf(nodeId: string): readonly Behaviour[];
+    /**
+     * Sets the node's own flag and cascades activation/deactivation through the subtree,
+     * pruning at descendants whose own flag is false — so reactivating a parent restores
+     * exactly the per-child stored flags. A flip under an inactive ancestor changes only
+     * the flag.
+     */
+    setActive(id: string, active: boolean): void;
+    /** The node's own flag; unknown ids count active. */
+    isActiveSelf(id: string): boolean;
+    /** Own flag AND every ancestor's; unknown ids count active. */
+    isActive(id: string): boolean;
+    /** Registers modules by key. Throws on duplicate keys or after `start()`. */
+    addModules(modules: Partial<BehaviourModules>): void;
+    readonly modules: BehaviourModules;
+    /** Bootstraps: modules awake/start/subscribe, then all behaviours on effectively-active nodes awake, then enable+start+subscribe. Idempotent. */
+    start(): void;
+    started(): boolean;
+    /** Dispatches `onUpdate(dt)` to modules then behaviours, over a snapshot — subscribers added mid-dispatch first fire next update. */
+    update(dt: number): void;
+    /** Destroys every behaviour in the subtree (parent-first) and removes the nodes. */
+    destroyNode(id: string): boolean;
+    /** Destroys all nodes and behaviours and clears update dispatch. */
+    destroy(): void;
+}
+export declare function createBehaviourWorld(): BehaviourWorld;
+export {};