goudengine 0.0.828 → 0.0.830

package/README.md

@@ -40,6 +40,116 @@ const game = await GoudGame.create(800, 600, "My Game");
 // same API as Node
 ```
 
+## Networking
+
+Networking wrappers are available in both the Node and web builds.
+
+- `goudengine/node`: host + client
+- `goudengine/web`: WebSocket client only
+
+Use `new NetworkManager(gameOrContext)` with `GoudGame` or `GoudContext`. `host()` and `connect()` return `NetworkEndpoint`. `connect()` stores the default peer ID, so clients can call `send(...)`. Host endpoints reply with `sendTo(...)`.
+
+```typescript
+import { GoudContext, NetworkManager, NetworkProtocol } from "goudengine/node";
+
+const hostContext = new GoudContext();
+const clientContext = new GoudContext();
+
+const host = new NetworkManager(hostContext).host(NetworkProtocol.Tcp, 9000);
+const client = new NetworkManager(clientContext).connect(
+  NetworkProtocol.Tcp,
+  "127.0.0.1",
+  9000,
+);
+
+client.send(Buffer.from("ping"));
+
+while (true) {
+  host.poll();
+  client.poll();
+
+  const packet = host.receive();
+  if (!packet) {
+    continue;
+  }
+
+  host.sendTo(packet.peerId, Buffer.from("pong"));
+  break;
+}
+```
+
+Browser note:
+
+- On `goudengine/web`, use `NetworkProtocol.WebSocket`.
+- Browser hosting is not supported.
+- `connect()` returns before the socket is fully open, so poll until `peerCount() > 0` before sending.
+
+Example:
+
+```typescript
+import { GoudGame, NetworkManager, NetworkProtocol } from "goudengine/web";
+
+const game = await GoudGame.create({ width: 800, height: 600, title: "Web Net" });
+const endpoint = new NetworkManager(game).connect(
+  NetworkProtocol.WebSocket,
+  "ws://127.0.0.1:9001",
+  9001,
+);
+```
+
+Browser-specific limitations and workarounds are documented in the Web Platform Gotchas guide:
+[`docs/src/guides/web-platform-gotchas.md`](../../docs/src/guides/web-platform-gotchas.md).
+
+## Debugger Runtime
+
+The debugger runtime is available on the desktop Node target. Enable it through `GoudContext` config, then use the raw JSON accessors or the thin parsed helpers from `goudengine/node`.
+
+```typescript
+import {
+  GoudContext,
+  parseDebuggerSnapshot,
+} from "goudengine/node";
+
+const ctx = new GoudContext({
+  debugger: {
+    enabled: true,
+    publishLocalAttach: true,
+    routeLabel: "ts-demo",
+  },
+});
+
+ctx.setDebuggerProfilingEnabled(true);
+
+const snapshot = parseDebuggerSnapshot(ctx);
+const manifestJson = ctx.getDebuggerManifestJson();
+const memory = ctx.getMemorySummary();
+
+ctx.setDebuggerSelectedEntity(42);
+ctx.clearDebuggerSelectedEntity();
+ctx.destroy();
+```
+
+The Node target also exposes pause, step, time-scale, debug-draw, input injection, capture, replay, and metrics methods on `GoudGame` and `GoudContext`. Capture, replay, and metrics stay Rust-owned and come back as raw artifact envelopes instead of TypeScript-specific debugger models.
+
+`goudengine/web` does not expose the debugger runtime in this batch. The browser build throws an explicit unsupported error for these methods instead of silently no-oping.
+
+See [`docs/src/guides/debugger-runtime.md`](../../docs/src/guides/debugger-runtime.md) for desktop-only scope, determinism limits, and the `goudengine-mcp` bridge workflow.
+
+## Features
+
+- 2D and 3D rendering with runtime renderer selection
+- Entity Component System (ECS) with Transform2D, Sprite, and more
+- Physics simulation (Rapier2D/3D): rigid bodies, colliders, raycasting, collision events
+- Audio playback with per-channel volume (Music, SFX, Ambience, UI, Voice) and spatial audio
+- Text rendering with TrueType/bitmap fonts, alignment, and word-wrapping
+- Sprite animation with state machine controller, multi-layer blending, and tweening
+- Scene management with transitions (instant, fade, custom)
+- UI component system with hierarchical node tree
+- Tiled map support for 2D worlds
+- Input handling (keyboard, mouse)
+- Dual targets: Node.js desktop (napi-rs) and web browser (wasm-bindgen)
+- Structured error diagnostics with error codes and recovery hints
+
 ## Flappy Bird Example
 
 A condensed Node.js version showing the core patterns — game loop, physics, sprite rendering,
@@ -153,6 +263,8 @@ A few things to keep in mind when targeting the browser:
   browser tab is hidden. No extra handling is needed.
 - **Touch input** -- Touch events are automatically mapped to mouse button 0.
   `touchstart` maps to `press_mouse_button(0)`, `touchend` maps to `release_mouse_button(0)`.
+- **More browser caveats** -- See the Web Platform Gotchas guide for async loop rules,
+  asset-loading caveats, and the current networking limitation on `goudengine/web`.
 
 ## Node vs Web Targets
 
@@ -204,9 +316,13 @@ npm run build:all       # Node + Web
 ```bash
 cd sdks/typescript
 npm test                # node --test test/*.test.mjs
+npx c8 --reporter=text-summary npm test
 npm run typecheck       # tsc --noEmit for both targets
 ```
 
+The TypeScript SDK CI gate expects at least `80%` line coverage across the
+public SDK surface and publishes a Cobertura report from `c8`.
+
 ## Codegen
 
 Most source files under `native/src/` and `src/generated/` are auto-generated

package/dist/generated/diagnostic.g.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Diagnostic mode controls backtrace capture on errors (debug builds only).
+ *
+ * In web/WASM builds these are no-ops.
+ */
+export declare class DiagnosticMode {
+    private static _enabled;
+    /** Enable or disable diagnostic mode. */
+    static setEnabled(enabled: boolean): void;
+    /** Returns whether diagnostic mode is currently enabled. */
+    static get isEnabled(): boolean;
+    /** Returns the backtrace captured from the most recent error, or empty string if none. */
+    static get lastBacktrace(): string;
+}
+//# sourceMappingURL=diagnostic.g.d.ts.map

package/dist/generated/diagnostic.g.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic.g.d.ts","sourceRoot":"","sources":["../../src/generated/diagnostic.g.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAS;IAEhC,yCAAyC;IACzC,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAWzC,4DAA4D;IAC5D,MAAM,KAAK,SAAS,IAAI,OAAO,CAS9B;IAED,0FAA0F;IAC1F,MAAM,KAAK,aAAa,IAAI,MAAM,CASjC;CAEF"}

package/dist/generated/diagnostic.g.js

@@ -0,0 +1,50 @@
+"use strict";
+// This file is AUTO-GENERATED by GoudEngine codegen. DO NOT EDIT.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiagnosticMode = void 0;
+/**
+ * Diagnostic mode controls backtrace capture on errors (debug builds only).
+ *
+ * In web/WASM builds these are no-ops.
+ */
+class DiagnosticMode {
+    /** Enable or disable diagnostic mode. */
+    static setEnabled(enabled) {
+        try {
+            const native = require('../node/index.g.js');
+            if (typeof native.goud_diagnostic_set_enabled === 'function') {
+                native.goud_diagnostic_set_enabled(enabled);
+            }
+        }
+        catch {
+        }
+        DiagnosticMode._enabled = enabled;
+    }
+    /** Returns whether diagnostic mode is currently enabled. */
+    static get isEnabled() {
+        try {
+            const native = require('../node/index.g.js');
+            if (typeof native.goud_diagnostic_is_enabled === 'function') {
+                return native.goud_diagnostic_is_enabled();
+            }
+        }
+        catch {
+        }
+        return DiagnosticMode._enabled;
+    }
+    /** Returns the backtrace captured from the most recent error, or empty string if none. */
+    static get lastBacktrace() {
+        try {
+            const native = require('../node/index.g.js');
+            if (typeof native.goud_diagnostic_last_backtrace === 'function') {
+                return native.goud_diagnostic_last_backtrace() ?? "";
+            }
+        }
+        catch {
+        }
+        return "";
+    }
+}
+exports.DiagnosticMode = DiagnosticMode;
+DiagnosticMode._enabled = false;
+//# sourceMappingURL=diagnostic.g.js.map

package/dist/generated/diagnostic.g.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic.g.js","sourceRoot":"","sources":["../../src/generated/diagnostic.g.ts"],"names":[],"mappings":";AAAA,kEAAkE;;;AAElE;;;;GAIG;AACH,MAAa,cAAc;IAGzB,yCAAyC;IACzC,MAAM,CAAC,UAAU,CAAC,OAAgB;QAChC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;YAC7C,IAAI,OAAO,MAAM,CAAC,2BAA2B,KAAK,UAAU,EAAE,CAAC;gBAC7D,MAAM,CAAC,2BAA2B,CAAC,OAAO,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;QACT,CAAC;QACD,cAAc,CAAC,QAAQ,GAAG,OAAO,CAAC;IACpC,CAAC;IAED,4DAA4D;IAC5D,MAAM,KAAK,SAAS;QAClB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;YAC7C,IAAI,OAAO,MAAM,CAAC,0BAA0B,KAAK,UAAU,EAAE,CAAC;gBAC5D,OAAO,MAAM,CAAC,0BAA0B,EAAE,CAAC;YAC7C,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;QACT,CAAC;QACD,OAAO,cAAc,CAAC,QAAQ,CAAC;IACjC,CAAC;IAED,0FAA0F;IAC1F,MAAM,KAAK,aAAa;QACtB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;YAC7C,IAAI,OAAO,MAAM,CAAC,8BAA8B,KAAK,UAAU,EAAE,CAAC;gBAChE,OAAO,MAAM,CAAC,8BAA8B,EAAE,IAAI,EAAE,CAAC;YACvD,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;QACT,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;;AArCH,wCAuCC;AAtCgB,uBAAQ,GAAG,KAAK,CAAC"}

package/dist/generated/index.g.d.ts

@@ -1,5 +1,7 @@
-export { GoudGame, EngineConfig, Color, Vec2, Vec3, Key, MouseButton } from './node/index.g.js';
-export type { IGoudGame, IEngineConfig, IEntity, IColor, IVec2, ITransform2DData, ISpriteData, IRenderStats, IContact, IFpsStats } from './types/engine.g.js';
+export { GoudGame, GoudContext, EngineConfig, UiManager, PhysicsWorld2D, PhysicsWorld3D, Color, Vec2, Vec3, Key, MouseButton, PhysicsBackend2D } from './node/index.g.js';
+export type { IGoudGame, IEngineConfig, IUiManager, IUiStyle, IUiEvent, UiNodeId, IPhysicsWorld2D, IPhysicsWorld3D, IEntity, IColor, IVec2, ITransform2DData, ISpriteData, IRenderStats, IContact, IFpsStats, IDebuggerConfig, IContextConfig, IMemoryCategoryStats, IMemorySummary, IPhysicsRaycastHit2D, IPhysicsCollisionEvent2D, IAnimationEventData, IRenderCapabilities, IPhysicsCapabilities, IAudioCapabilities, IInputCapabilities, INetworkCapabilities, INetworkStats, INetworkSimulationConfig } from './types/engine.g.js';
+export type { IGoudContext, INetworkConnectResult, INetworkPacket } from './node/index.g.js';
 export type { Rect } from './types/math.g.js';
 export { GoudError, GoudContextError, GoudResourceError, GoudGraphicsError, GoudEntityError, GoudInputError, GoudSystemError, GoudProviderError, GoudInternalError, RecoveryClass } from './errors.g.js';
+export { DiagnosticMode } from './diagnostic.g.js';
 //# sourceMappingURL=index.g.d.ts.map

package/dist/generated/index.g.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.g.d.ts","sourceRoot":"","sources":["../../src/generated/index.g.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChG,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC9J,YAAY,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,eAAe,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.g.d.ts","sourceRoot":"","sources":["../../src/generated/index.g.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1K,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,oBAAoB,EAAE,cAAc,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AACxgB,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC7F,YAAY,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,eAAe,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACzM,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/generated/index.g.js

@@ -1,15 +1,20 @@
 "use strict";
 // This file is AUTO-GENERATED by GoudEngine codegen. DO NOT EDIT.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RecoveryClass = exports.GoudInternalError = exports.GoudProviderError = exports.GoudSystemError = exports.GoudInputError = exports.GoudEntityError = exports.GoudGraphicsError = exports.GoudResourceError = exports.GoudContextError = exports.GoudError = exports.MouseButton = exports.Key = exports.Vec3 = exports.Vec2 = exports.Color = exports.EngineConfig = exports.GoudGame = void 0;
+exports.DiagnosticMode = exports.RecoveryClass = exports.GoudInternalError = exports.GoudProviderError = exports.GoudSystemError = exports.GoudInputError = exports.GoudEntityError = exports.GoudGraphicsError = exports.GoudResourceError = exports.GoudContextError = exports.GoudError = exports.PhysicsBackend2D = exports.MouseButton = exports.Key = exports.Vec3 = exports.Vec2 = exports.Color = exports.PhysicsWorld3D = exports.PhysicsWorld2D = exports.UiManager = exports.EngineConfig = exports.GoudContext = exports.GoudGame = void 0;
 var index_g_js_1 = require("./node/index.g.js");
 Object.defineProperty(exports, "GoudGame", { enumerable: true, get: function () { return index_g_js_1.GoudGame; } });
+Object.defineProperty(exports, "GoudContext", { enumerable: true, get: function () { return index_g_js_1.GoudContext; } });
 Object.defineProperty(exports, "EngineConfig", { enumerable: true, get: function () { return index_g_js_1.EngineConfig; } });
+Object.defineProperty(exports, "UiManager", { enumerable: true, get: function () { return index_g_js_1.UiManager; } });
+Object.defineProperty(exports, "PhysicsWorld2D", { enumerable: true, get: function () { return index_g_js_1.PhysicsWorld2D; } });
+Object.defineProperty(exports, "PhysicsWorld3D", { enumerable: true, get: function () { return index_g_js_1.PhysicsWorld3D; } });
 Object.defineProperty(exports, "Color", { enumerable: true, get: function () { return index_g_js_1.Color; } });
 Object.defineProperty(exports, "Vec2", { enumerable: true, get: function () { return index_g_js_1.Vec2; } });
 Object.defineProperty(exports, "Vec3", { enumerable: true, get: function () { return index_g_js_1.Vec3; } });
 Object.defineProperty(exports, "Key", { enumerable: true, get: function () { return index_g_js_1.Key; } });
 Object.defineProperty(exports, "MouseButton", { enumerable: true, get: function () { return index_g_js_1.MouseButton; } });
+Object.defineProperty(exports, "PhysicsBackend2D", { enumerable: true, get: function () { return index_g_js_1.PhysicsBackend2D; } });
 var errors_g_js_1 = require("./errors.g.js");
 Object.defineProperty(exports, "GoudError", { enumerable: true, get: function () { return errors_g_js_1.GoudError; } });
 Object.defineProperty(exports, "GoudContextError", { enumerable: true, get: function () { return errors_g_js_1.GoudContextError; } });
@@ -21,4 +26,6 @@ Object.defineProperty(exports, "GoudSystemError", { enumerable: true, get: funct
 Object.defineProperty(exports, "GoudProviderError", { enumerable: true, get: function () { return errors_g_js_1.GoudProviderError; } });
 Object.defineProperty(exports, "GoudInternalError", { enumerable: true, get: function () { return errors_g_js_1.GoudInternalError; } });
 Object.defineProperty(exports, "RecoveryClass", { enumerable: true, get: function () { return errors_g_js_1.RecoveryClass; } });
+var diagnostic_g_js_1 = require("./diagnostic.g.js");
+Object.defineProperty(exports, "DiagnosticMode", { enumerable: true, get: function () { return diagnostic_g_js_1.DiagnosticMode; } });
 //# sourceMappingURL=index.g.js.map

package/dist/generated/index.g.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.g.js","sourceRoot":"","sources":["../../src/generated/index.g.ts"],"names":[],"mappings":";AAAA,kEAAkE;;;AAElE,gDAAgG;AAAvF,sGAAA,QAAQ,OAAA;AAAE,0GAAA,YAAY,OAAA;AAAE,mGAAA,KAAK,OAAA;AAAE,kGAAA,IAAI,OAAA;AAAE,kGAAA,IAAI,OAAA;AAAE,iGAAA,GAAG,OAAA;AAAE,yGAAA,WAAW,OAAA;AAGpE,6CAAyM;AAAhM,wGAAA,SAAS,OAAA;AAAE,+GAAA,gBAAgB,OAAA;AAAE,gHAAA,iBAAiB,OAAA;AAAE,gHAAA,iBAAiB,OAAA;AAAE,8GAAA,eAAe,OAAA;AAAE,6GAAA,cAAc,OAAA;AAAE,8GAAA,eAAe,OAAA;AAAE,gHAAA,iBAAiB,OAAA;AAAE,gHAAA,iBAAiB,OAAA;AAAE,4GAAA,aAAa,OAAA"}
+{"version":3,"file":"index.g.js","sourceRoot":"","sources":["../../src/generated/index.g.ts"],"names":[],"mappings":";AAAA,kEAAkE;;;AAElE,gDAA0K;AAAjK,sGAAA,QAAQ,OAAA;AAAE,yGAAA,WAAW,OAAA;AAAE,0GAAA,YAAY,OAAA;AAAE,uGAAA,SAAS,OAAA;AAAE,4GAAA,cAAc,OAAA;AAAE,4GAAA,cAAc,OAAA;AAAE,mGAAA,KAAK,OAAA;AAAE,kGAAA,IAAI,OAAA;AAAE,kGAAA,IAAI,OAAA;AAAE,iGAAA,GAAG,OAAA;AAAE,yGAAA,WAAW,OAAA;AAAE,8GAAA,gBAAgB,OAAA;AAI9I,6CAAyM;AAAhM,wGAAA,SAAS,OAAA;AAAE,+GAAA,gBAAgB,OAAA;AAAE,gHAAA,iBAAiB,OAAA;AAAE,gHAAA,iBAAiB,OAAA;AAAE,8GAAA,eAAe,OAAA;AAAE,6GAAA,cAAc,OAAA;AAAE,8GAAA,eAAe,OAAA;AAAE,gHAAA,iBAAiB,OAAA;AAAE,gHAAA,iBAAiB,OAAA;AAAE,4GAAA,aAAa,OAAA;AACjL,qDAAmD;AAA1C,iHAAA,cAAc,OAAA"}