@ringozz/godot 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,62 @@
+# @ringozz/godot
+
+Node-API bindings for the Godot Engine — call Godot classes, value types, and utility functions from JavaScript.
+
+This is the core runtime package. The React layer is a separate package ([`@ringozz/react-godot`](../react-godot/README.md)).
+
+## Installation
+
+```sh
+bun add @ringozz/godot
+```
+
+The package ships no engine binary itself — it auto-selects a platform addon from its optional dependencies on install: `@ringozz/godot-macos-arm64`, `@ringozz/godot-windows-x86_64`, or `@ringozz/godot-web-wasm32` (the WASM build is installed everywhere and used on web). No `project.godot` is required — the engine boots from engine defaults with `res://` = your working directory.
+
+## Usage
+
+The engine is already running when you import — `getGodot()` returns the instance synchronously. Pump frames with `runGodot()`:
+
+```ts
+import { runGodot } from '@ringozz/godot';
+import { Engine } from '@ringozz/godot/Engine';
+import { SceneTree } from '@ringozz/godot/SceneTree';
+
+const tree = Engine.getMainLoop() as SceneTree;
+const root = tree.root;
+
+const label = new Label();
+label.text = 'hello from godot-node';
+root.addChild(label);
+
+const done = runGodot(); // pumps frames until aborted
+```
+
+### What's exported where
+
+| Specifier | Contents |
+|---|---|
+| `@ringozz/godot` | Value types (`Vector3`, `Color`, …), global enums, heap types, utility functions, global constants, `runGodot()`, RAF polyfills |
+| `@ringozz/godot/ClassName` | Classes, one per module — e.g. `@ringozz/godot/Label`, `@ringozz/godot/Node` |
+| `@ringozz/godot/runtime` | Low-level dispatch: `_C`, `_S`, `_get`, `_set`, `_R`, `_G`, `_P`, `getGodot`, `GodotVar` |
+| `@ringozz/godot/debug` | `initDebug()`, `dumpStr`, `dumpTreeStr`, `statsStr`, `gc` |
+
+Class-scoped enums use bare names (import `ProcessMode` from `@ringozz/godot/Node`, not `NodeProcessMode`).
+
+### Debugging
+
+```ts
+import { initDebug } from '@ringozz/godot/debug';
+initDebug();
+// singletons + helpers now on globalThis.$: $.Engine, $.dumpTreeStr(root), $.statsStr(), $.gc()
+```
+
+`initDebug` also registers an `uncaughtException` handler that keeps the process alive, and adds `getBoundingClientRect()` to `CanvasItem`/`Node3D`.
+
+## Notes
+
+- **Memory**: non-RefCounted objects (`Node`, `Node2D`, `Node3D`, …) must call `free()` explicitly. RefCounted objects are managed by Godot's ref counting; calling `free()` clears the JS wrapper (decrements the ref).
+- **Class-registration tree-shaking**: `ClassDB.instantiate('X')` requires the JS class to be value-imported (`import { Label } from '@ringozz/godot/Label'`). If a class is only type-used (e.g. `as Label` casts), bundlers may drop its registration side effect, and wrappers fall back to an ancestor class. Render through JSX is unaffected. Workaround: keep a value reference (`void Label;`).
+
+## Development
+
+`gen/` is generated (and gitignored) by `dev/codegen.ts` from `godot --dump-extension-api-with-docs`. Regenerate + typecheck with `bun run prebuild`. Build the native addon with `bun run build`. See [`AGENTS.md`](../../AGENTS.md) for the full workflow.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/godot",
   "author": "Vladimir Davidovich",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Node-API bindings for Godot Engine — call Godot classes from JavaScript",
   "type": "module",
   "main": "./src/index.ts",
@@ -14,7 +14,8 @@
   },
   "files": [
     "src/",
-    "gen/"
+    "gen/",
+    "*.md"
   ],
   "godot": {
     "version_major": 4,