godot-kit 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish to npm
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci --ignore-scripts
+
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,134 @@
+# godot-kit
+
+Agentic Godot 4.x development boilerplate. Single command setup, REPL/CLI debugging, gdtoolkit integration, DAP support, scene inspector, profiler, and live log streaming.
+
+## Quick Start
+
+```bash
+# Create a new Godot project
+npx godot-kit my-game
+
+# Install gdtoolkit
+godot-dev setup
+
+# Launch Godot with remote debugger
+godot-dev launch --godot /path/to/godot4
+
+# Connect interactive REPL
+godot-dev repl
+```
+
+## What it creates
+
+```
+my-game/
+├── project.godot           # Godot 4.x project config
+├── scenes/main.tscn        # Main scene
+├── scripts/main.gd         # Main script
+├── addons/repl_bridge/     # REPL autoload (GDScript)
+│   ├── repl_bridge.gd      # Debug bridge with eval, scene dump, logs
+│   └── plugin.cfg
+├── .gdlintrc               # gdtoolkit lint config
+├── .gdformatrc             # gdtoolkit format config
+├── .vscode/
+│   ├── launch.json         # DAP debug config
+│   ├── settings.json       # Godot LSP settings
+│   └── extensions.json     # Recommends Godot Tools
+├── Makefile                # Task shortcuts
+└── README.md
+```
+
+## CLI Commands
+
+```bash
+godot-dev repl              # Interactive debugger REPL
+godot-dev inspect           # Dump scene tree (one-shot)
+godot-dev logs              # Stream Godot output logs
+godot-dev lint [files]      # Run gdlint
+godot-dev format [files]    # Run gdformat
+godot-dev launch [scene]    # Launch Godot with debugger
+godot-dev setup             # Install gdtoolkit
+```
+
+## REPL Commands
+
+| Command | Description |
+|---------|-------------|
+| `tree` | Dump scene tree |
+| `inspect <id>` | Inspect object properties |
+| `stack` | Show call stack |
+| `vars <frame>` | Show variables at stack frame |
+| `c` / `continue` | Continue execution |
+| `n` / `next` | Step over |
+| `s` / `step` | Step into |
+| `b` / `break` | Pause execution |
+| `bp <file> <line>` | Set/clear breakpoint |
+| `quit` | Exit |
+
+## Debug Architecture
+
+```
+Godot 4 Game
+  └─ --remote-debug tcp://127.0.0.1:6007
+       └─ Binary Variant Protocol (TCP)
+            └─ godot-dev repl / inspect / logs
+                 └─ lib/debugger-client.js
+                      └─ lib/protocol.js (encode/decode Godot variants)
+```
+
+### Protocol Details
+
+Godot 4.x remote debugger uses a binary TCP protocol:
+- Each packet: `uint32_LE(payload_size) + uint32_LE(param_count) + [variants...]`
+- First variant is always the command string
+- Remaining variants are parameters
+- Types: NIL, BOOL, INT (32/64), FLOAT (32/64), STRING, VECTOR2/3/4, COLOR, ARRAY, DICTIONARY, OBJECT, etc.
+
+### Ports
+
+| Service | Port | Protocol |
+|---------|------|----------|
+| Remote Debugger (game) | 6007 | Binary TCP |
+| Language Server (LSP) | 6005 | JSON-RPC TCP |
+| Debug Adapter (DAP) | 6006 | DAP over TCP |
+
+## gdtoolkit
+
+```bash
+# Install (requires Python 3.7+)
+pip install "gdtoolkit==4.*"
+
+# Or via pipx
+pipx install "gdtoolkit==4.*"
+```
+
+Provides `gdlint` and `gdformat` for GDScript linting and formatting.
+
+## VSCode Integration
+
+1. Install [Godot Tools](https://marketplace.visualstudio.com/items?itemName=geequlim.godot-tools)
+2. Set Godot 4 executable path in VSCode settings
+3. Press `F5` to launch with DAP debugger
+
+## Programmatic API
+
+```js
+const { GodotDebuggerClient } = require('godot-kit');
+
+const client = new GodotDebuggerClient('127.0.0.1', 6007);
+await client.connect();
+
+client.on('break', (params) => console.log('Paused at', params));
+client.on('output', (params) => console.log('[godot]', params));
+
+client.requestSceneTree();
+client.on('message', (msg) => {
+  if (msg.command === 'scene:scene_tree_parse_end') {
+    // msg.params contains scene tree data
+  }
+});
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+'use strict';
+
+const { Command } = require('commander');
+const { GodotDebuggerClient } = require('../lib/debugger-client');
+const { parseSceneNode, formatSceneTree } = require('../lib/scene-tree');
+const { startRepl } = require('../lib/repl-commands');
+const { execSync, spawn } = require('child_process');
+
+const program = new Command();
+program.name('godot-dev').description('Agentic Godot 4.x CLI - REPL, debugger, inspector, profiler').version('1.0.0');
+
+function makeClient(opts) {
+  return new GodotDebuggerClient(opts.host || '127.0.0.1', parseInt(opts.port || '6007'));
+}
+
+async function connectOrDie(client) {
+  try {
+    await client.connect();
+    console.log(`Connected to Godot debugger at ${client.host}:${client.port}`);
+  } catch (e) {
+    console.error(`Cannot connect to Godot at ${client.host}:${client.port}`);
+    console.error('Launch Godot with: --remote-debug tcp://127.0.0.1:6007');
+    console.error('Or run: godot-dev launch');
+    process.exit(1);
+  }
+}
+
+program.command('repl').description('Interactive REPL connected to running Godot debugger')
+  .option('-h, --host <host>', 'Godot host', '127.0.0.1')
+  .option('-p, --port <port>', 'Debugger port', '6007')
+  .action(async (opts) => {
+    const client = makeClient(opts);
+    await connectOrDie(client);
+    startRepl(client);
+  });
+
+program.command('inspect').description('Dump scene tree from running Godot game (one-shot)')
+  .option('-h, --host <host>', 'Godot host', '127.0.0.1')
+  .option('-p, --port <port>', 'Debugger port', '6007')
+  .action(async (opts) => {
+    const client = makeClient(opts);
+    await connectOrDie(client);
+    client.requestSceneTree();
+    let done = false;
+    client.on('message', (msg) => {
+      if (String(msg.command) === 'scene:scene_tree_parse_end' && !done) {
+        done = true;
+        try { formatSceneTree(parseSceneNode(msg.params)).forEach(l => console.log(l)); }
+        catch (e) { console.log(JSON.stringify(msg.params, null, 2)); }
+        client.disconnect(); process.exit(0);
+      }
+    });
+    setTimeout(() => { if (!done) { console.error('Timeout: no scene tree received.'); client.disconnect(); process.exit(1); } }, 5000);
+  });
+
+program.command('logs').description('Stream Godot output logs')
+  .option('-h, --host <host>', 'Godot host', '127.0.0.1')
+  .option('-p, --port <port>', 'Debugger port', '6007')
+  .action(async (opts) => {
+    const client = makeClient(opts);
+    await connectOrDie(client);
+    console.log('Streaming Godot logs (Ctrl+C to stop)...');
+    client.on('output', (p) => { for (const s of p) { if (typeof s === 'string') process.stdout.write(s + '\n'); } });
+    client.on('godot_error', (p) => process.stderr.write('[ERROR] ' + p.join(' ') + '\n'));
+    client.on('profile_frame', (p) => console.log('[PROFILE]', JSON.stringify(p)));
+    client.on('disconnected', () => { console.log('Godot disconnected.'); process.exit(0); });
+    process.on('SIGINT', () => { client.disconnect(); process.exit(0); });
+  });
+
+program.command('lint [files...]').description('Lint GDScript files using gdtoolkit')
+  .action((files) => {
+    const targets = files.length ? files : ['.'];
+    try {
+      const r = execSync(['gdlint', ...targets].join(' '), { stdio: 'pipe', encoding: 'utf8' });
+      if (r) console.log(r);
+      console.log('\x1b[32mLint passed.\x1b[0m');
+    } catch (e) {
+      if (e.stdout) process.stdout.write(e.stdout);
+      if (e.stderr) process.stderr.write(e.stderr);
+      process.exit(e.status || 1);
+    }
+  });
+
+program.command('format [files...]').description('Format GDScript files using gdtoolkit')
+  .option('--check', 'Check only, do not write')
+  .action((files, opts) => {
+    const targets = files.length ? files : ['.'];
+    const args = ['gdformat', ...(opts.check ? ['--check'] : []), ...targets];
+    try {
+      const r = execSync(args.join(' '), { stdio: 'pipe', encoding: 'utf8' });
+      if (r) console.log(r);
+      console.log('\x1b[32mFormat complete.\x1b[0m');
+    } catch (e) {
+      if (e.stdout) process.stdout.write(e.stdout);
+      if (e.stderr) process.stderr.write(e.stderr);
+      process.exit(e.status || 1);
+    }
+  });
+
+program.command('launch [scene]').description('Launch Godot with remote debugger enabled')
+  .option('--godot <path>', 'Path to Godot executable', 'godot')
+  .option('--project <path>', 'Godot project path', '.')
+  .option('-p, --port <port>', 'Debugger port', '6007')
+  .option('--profiling', 'Enable profiling')
+  .option('--debug-collisions', 'Show collision shapes')
+  .option('--debug-navigation', 'Show navigation')
+  .action((scene, opts) => {
+    const args = ['--path', opts.project, '--remote-debug', `tcp://127.0.0.1:${opts.port}`, '--verbose'];
+    if (opts.profiling) args.push('--profiling');
+    if (opts.debugCollisions) args.push('--debug-collisions');
+    if (opts.debugNavigation) args.push('--debug-navigation');
+    if (scene) args.push(scene);
+    console.log(`Launching: ${opts.godot} ${args.join(' ')}`);
+    const proc = spawn(opts.godot, args, { stdio: 'inherit' });
+    proc.on('exit', (code) => process.exit(code || 0));
+  });
+
+program.command('setup').description('Install gdtoolkit for GDScript linting/formatting')
+  .action(() => {
+    console.log('Installing gdtoolkit for Godot 4.x...');
+    const cmds = ['pip install --upgrade "gdtoolkit==4.*"', 'pip3 install --upgrade "gdtoolkit==4.*"'];
+    for (const cmd of cmds) {
+      try { execSync(cmd, { stdio: 'inherit' }); console.log('\x1b[32mgdtoolkit installed.\x1b[0m'); return; }
+      catch (e) { continue; }
+    }
+    console.error('Failed. Install Python and pip first.'); process.exit(1);
+  });
+
+program.parse(process.argv);

package/bin/create.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const getTemplates = require('../lib/templates');
+
+const targetDir = process.argv[2] ? path.resolve(process.argv[2]) : (process.env.INIT_CWD || process.cwd());
+const projectName = path.basename(targetDir);
+
+console.log(`\n  godot-kit - Agentic Godot 4.x Boilerplate\n`);
+console.log(`  Project: ${projectName}`);
+console.log(`  Target:  ${targetDir}\n`);
+
+fs.mkdirSync(targetDir, { recursive: true });
+
+const templates = getTemplates(projectName);
+for (const [relPath, content] of Object.entries(templates)) {
+  const full = path.join(targetDir, relPath);
+  fs.mkdirSync(path.dirname(full), { recursive: true });
+  fs.writeFileSync(full, content, 'utf8');
+  console.log(`  + ${relPath}`);
+}
+
+const readme = `# ${projectName}
+
+Scaffolded by [godot-kit](https://github.com/AnEntrypoint/godot-kit).
+
+## Setup
+\`\`\`bash
+npm install -g godot-kit
+godot-dev setup
+\`\`\`
+
+## Commands
+\`\`\`bash
+godot-dev launch --godot /path/to/godot4  # Launch with debugger
+godot-dev repl                            # Interactive REPL
+godot-dev inspect                         # Dump scene tree
+godot-dev logs                            # Stream logs
+godot-dev lint                            # GDScript lint
+godot-dev format                          # GDScript format
+\`\`\`
+
+## REPL Commands
+\`continue|c\`, \`next|n\`, \`step|s\`, \`break|b\`, \`stack\`, \`vars <frame>\`, \`tree\`, \`inspect <id>\`, \`bp <file> <line>\`
+
+## Debug Ports
+| Service | Port |
+|---------|------|
+| Remote Debugger | 6007 |
+| LSP | 6005 |
+| DAP | 6006 |
+`;
+
+fs.writeFileSync(path.join(targetDir, 'README.md'), readme, 'utf8');
+console.log(`  + README.md`);
+
+console.log(`
+  Done! Next steps:
+
+  1. Open project in Godot 4.x editor
+  2. Install gdtoolkit:     godot-dev setup
+  3. Launch with debugger:  godot-dev launch --godot /path/to/godot4
+  4. Connect REPL:          godot-dev repl
+  5. Inspect scene tree:    godot-dev inspect
+
+  VSCode: Install "Godot Tools" extension, use F5 to debug.
+  Docs:   https://github.com/AnEntrypoint/godot-kit
+`);

package/lib/debugger-client.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const net = require('net');
+const { EventEmitter } = require('events');
+const { buildPacket, parsePacket, splitPackets } = require('./protocol');
+
+class GodotDebuggerClient extends EventEmitter {
+  constructor(host = '127.0.0.1', port = 6007) {
+    super();
+    this.host = host;
+    this.port = port;
+    this.socket = null;
+    this.buffer = Buffer.alloc(0);
+    this.connected = false;
+  }
+
+  connect() {
+    return new Promise((resolve, reject) => {
+      this.socket = new net.Socket();
+      this.socket.connect(this.port, this.host, () => {
+        this.connected = true;
+        this.emit('connected');
+        resolve();
+      });
+      this.socket.on('data', (chunk) => {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        this._processBuffer();
+      });
+      this.socket.on('close', () => {
+        this.connected = false;
+        this.emit('disconnected');
+      });
+      this.socket.on('error', (err) => {
+        this.connected = false;
+        if (!this.connected) reject(err);
+        else this.emit('error', err);
+      });
+    });
+  }
+
+  _processBuffer() {
+    const packets = splitPackets(this.buffer);
+    let consumed = 0;
+    for (const pkt of packets) {
+      const msg = parsePacket(pkt);
+      if (msg) {
+        this.emit('message', msg);
+        this._handleMessage(msg);
+        consumed += pkt.length;
+      }
+    }
+    if (consumed > 0) this.buffer = this.buffer.subarray(consumed);
+  }
+
+  _handleMessage(msg) {
+    const cmd = String(msg.command);
+    if (cmd === 'debug_enter') this.emit('break', msg.params);
+    else if (cmd === 'debug_exit') this.emit('continue', msg.params);
+    else if (cmd === 'stack_dump') this.emit('stack_dump', msg.params);
+    else if (cmd === 'stack_frame_vars') this.emit('stack_frame_vars', msg.params);
+    else if (cmd === 'scene:scene_tree_parse_begin') this.emit('scene_tree_begin', msg.params);
+    else if (cmd === 'scene:scene_tree_parse_end') this.emit('scene_tree_end', msg.params);
+    else if (cmd === 'scene:inspect_object') this.emit('inspect_object', msg.params);
+    else if (cmd === 'output') this.emit('output', msg.params);
+    else if (cmd === 'performance:profile_frame') this.emit('profile_frame', msg.params);
+    else if (cmd === 'error') this.emit('godot_error', msg.params);
+    else this.emit('unknown', msg);
+  }
+
+  send(cmd, params = []) {
+    if (!this.connected || !this.socket) return false;
+    const buf = buildPacket(cmd, params);
+    this.socket.write(buf);
+    return true;
+  }
+
+  requestSceneTree() { return this.send('scene:request_scene_tree'); }
+  requestInspectObject(objectId) { return this.send('scene:inspect_object', [BigInt(objectId)]); }
+  requestStackDump() { return this.send('get_stack_dump'); }
+  requestStackFrameVars(frameId) { return this.send('get_stack_frame_vars', [frameId]); }
+  sendBreak() { return this.send('break'); }
+  sendContinue() { return this.send('continue'); }
+  sendNext() { return this.send('next'); }
+  sendStep() { return this.send('step'); }
+
+  setBreakpoint(filePath, line, enabled = true) {
+    return this.send('breakpoint', [filePath, line, enabled]);
+  }
+
+  disconnect() {
+    if (this.socket) { this.socket.destroy(); this.socket = null; }
+    this.connected = false;
+  }
+}
+
+module.exports = { GodotDebuggerClient };

package/lib/index.js

@@ -0,0 +1,7 @@
+'use strict';
+
+const { GodotDebuggerClient } = require('./debugger-client');
+const { parseSceneNode, formatSceneTree } = require('./scene-tree');
+const { buildPacket, parsePacket, splitPackets } = require('./protocol');
+
+module.exports = { GodotDebuggerClient, parseSceneNode, formatSceneTree, buildPacket, parsePacket, splitPackets };

package/lib/protocol.js

@@ -0,0 +1,184 @@
+'use strict';
+
+const TYPES = {
+  NIL: 0, BOOL: 1, INT: 2, FLOAT: 3, STRING: 4,
+  VECTOR2: 5, VECTOR2I: 6, RECT2: 7, RECT2I: 8,
+  VECTOR3: 9, VECTOR3I: 10, TRANSFORM2D: 11,
+  VECTOR4: 12, VECTOR4I: 13, PLANE: 14,
+  QUATERNION: 15, AABB: 16, BASIS: 17,
+  TRANSFORM3D: 18, PROJECTION: 19,
+  COLOR: 20, STRING_NAME: 21, NODE_PATH: 22,
+  RID: 23, OBJECT: 24, CALLABLE: 25, SIGNAL: 26,
+  DICTIONARY: 27, ARRAY: 28,
+  PACKED_BYTE_ARRAY: 29, PACKED_INT32_ARRAY: 30,
+  PACKED_INT64_ARRAY: 31, PACKED_FLOAT32_ARRAY: 32,
+  PACKED_FLOAT64_ARRAY: 33, PACKED_STRING_ARRAY: 34,
+  PACKED_VECTOR2_ARRAY: 35, PACKED_VECTOR3_ARRAY: 36,
+  PACKED_COLOR_ARRAY: 37, PACKED_VECTOR4_ARRAY: 38,
+};
+
+const ENCODE_FLAG_64 = 1 << 16;
+
+function encodeString(s) {
+  const strBuf = Buffer.from(s, 'utf8');
+  const pad = (4 - (strBuf.length % 4)) % 4;
+  const b = Buffer.alloc(4 + strBuf.length + pad);
+  b.writeUInt32LE(strBuf.length, 0);
+  strBuf.copy(b, 4);
+  return b;
+}
+
+function encodeVariant(value) {
+  if (value === null || value === undefined) {
+    return Buffer.from([0, 0, 0, 0]);
+  }
+  if (typeof value === 'boolean') {
+    const b = Buffer.alloc(8);
+    b.writeUInt32LE(TYPES.BOOL, 0);
+    b.writeUInt32LE(value ? 1 : 0, 4);
+    return b;
+  }
+  if (typeof value === 'bigint') {
+    const b = Buffer.alloc(12);
+    b.writeUInt32LE(TYPES.INT | ENCODE_FLAG_64, 0);
+    b.writeBigInt64LE(value, 4);
+    return b;
+  }
+  if (typeof value === 'number') {
+    if (Number.isInteger(value)) {
+      const b = Buffer.alloc(8);
+      b.writeUInt32LE(TYPES.INT, 0);
+      b.writeInt32LE(value, 4);
+      return b;
+    }
+    const b = Buffer.alloc(8);
+    b.writeUInt32LE(TYPES.FLOAT, 0);
+    b.writeFloatLE(value, 4);
+    return b;
+  }
+  if (typeof value === 'string') {
+    const sb = encodeString(value);
+    const b = Buffer.alloc(4 + sb.length);
+    b.writeUInt32LE(TYPES.STRING, 0);
+    sb.copy(b, 4);
+    return b;
+  }
+  if (Array.isArray(value)) {
+    const parts = value.map(encodeVariant);
+    const dataLen = 4 + parts.reduce((a, p) => a + p.length, 0);
+    const b = Buffer.alloc(4 + dataLen);
+    b.writeUInt32LE(TYPES.ARRAY, 0);
+    b.writeUInt32LE(value.length, 4);
+    let off = 8;
+    for (const p of parts) { p.copy(b, off); off += p.length; }
+    return b;
+  }
+  return Buffer.from([0, 0, 0, 0]);
+}
+
+function buildPacket(cmd, params = []) {
+  const cmdVar = encodeVariant(cmd);
+  const paramVars = params.map(encodeVariant);
+  const payloadSize = 4 + cmdVar.length + paramVars.reduce((a, p) => a + p.length, 0);
+  const buf = Buffer.alloc(4 + payloadSize);
+  buf.writeUInt32LE(payloadSize, 0);
+  buf.writeUInt32LE(1 + params.length, 4);
+  cmdVar.copy(buf, 8);
+  let off = 8 + cmdVar.length;
+  for (const p of paramVars) { p.copy(buf, off); off += p.length; }
+  return buf;
+}
+
+function decodeString(buf, offset) {
+  const len = buf.readUInt32LE(offset);
+  const str = buf.toString('utf8', offset + 4, offset + 4 + len);
+  const pad = (4 - (len % 4)) % 4;
+  return { value: str, size: 4 + len + pad };
+}
+
+function decodeVariant(buf, offset) {
+  if (offset + 4 > buf.length) return { value: null, size: 4 };
+  const typeRaw = buf.readUInt32LE(offset);
+  const type = typeRaw & 0xff;
+  const flag64 = !!(typeRaw & ENCODE_FLAG_64);
+  offset += 4;
+
+  switch (type) {
+    case TYPES.NIL: return { value: null, size: 4 };
+    case TYPES.BOOL: return { value: buf.readUInt32LE(offset) !== 0, size: 8 };
+    case TYPES.INT:
+      if (flag64) return { value: buf.readBigInt64LE(offset), size: 12 };
+      return { value: buf.readInt32LE(offset), size: 8 };
+    case TYPES.FLOAT:
+      if (flag64) return { value: buf.readDoubleLe ? buf.readDoubleLe(offset) : buf.readDoubleLE(offset), size: 12 };
+      return { value: buf.readFloatLE(offset), size: 8 };
+    case TYPES.STRING:
+    case TYPES.STRING_NAME: {
+      const r = decodeString(buf, offset);
+      return { value: r.value, size: 4 + r.size };
+    }
+    case TYPES.NODE_PATH: {
+      const r = decodeString(buf, offset);
+      return { value: r.value, size: 4 + r.size };
+    }
+    case TYPES.VECTOR2: return { value: { x: buf.readFloatLE(offset), y: buf.readFloatLE(offset+4) }, size: 4+8 };
+    case TYPES.VECTOR3: return { value: { x: buf.readFloatLE(offset), y: buf.readFloatLE(offset+4), z: buf.readFloatLE(offset+8) }, size: 4+12 };
+    case TYPES.COLOR: return { value: { r: buf.readFloatLE(offset), g: buf.readFloatLE(offset+4), b: buf.readFloatLE(offset+8), a: buf.readFloatLE(offset+12) }, size: 4+16 };
+    case TYPES.OBJECT:
+      if (typeRaw & ENCODE_FLAG_64) return { value: { objectId: buf.readBigUInt64LE(offset) }, size: 4+8 };
+      return { value: { objectId: buf.readUInt32LE(offset) }, size: 4+4 };
+    case TYPES.ARRAY: {
+      const count = buf.readUInt32LE(offset);
+      let off = offset + 4;
+      const items = [];
+      for (let i = 0; i < count; i++) {
+        const r = decodeVariant(buf, off);
+        items.push(r.value);
+        off += r.size;
+      }
+      return { value: items, size: 4 + (off - offset - 4) };
+    }
+    case TYPES.DICTIONARY: {
+      const count = buf.readUInt32LE(offset) & 0x7fffffff;
+      let off = offset + 4;
+      const dict = {};
+      for (let i = 0; i < count; i++) {
+        const kr = decodeVariant(buf, off); off += kr.size;
+        const vr = decodeVariant(buf, off); off += vr.size;
+        dict[String(kr.value)] = vr.value;
+      }
+      return { value: dict, size: 4 + (off - offset - 4) };
+    }
+    default: return { value: `<type:${type}>`, size: 4 };
+  }
+}
+
+function parsePacket(buf) {
+  if (buf.length < 8) return null;
+  const payloadSize = buf.readUInt32LE(0);
+  if (buf.length < 4 + payloadSize) return null;
+  const paramCount = buf.readUInt32LE(4);
+  const params = [];
+  let off = 8;
+  for (let i = 0; i < paramCount; i++) {
+    const r = decodeVariant(buf, off);
+    params.push(r.value);
+    off += r.size;
+  }
+  return { command: params[0], params: params.slice(1), totalSize: 4 + payloadSize };
+}
+
+function splitPackets(buf) {
+  const packets = [];
+  let off = 0;
+  while (off + 4 <= buf.length) {
+    const payloadSize = buf.readUInt32LE(off);
+    const total = 4 + payloadSize;
+    if (off + total > buf.length) break;
+    packets.push(buf.subarray(off, off + total));
+    off += total;
+  }
+  return packets;
+}
+
+module.exports = { buildPacket, parsePacket, splitPackets, TYPES };

package/lib/repl-commands.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const readline = require('readline');
+const { parseSceneNode, formatSceneTree } = require('./scene-tree');
+
+function startRepl(client) {
+  client.on('output', (params) => {
+    for (const p of params) {
+      if (typeof p === 'string') process.stdout.write('\x1b[90m[godot] ' + p + '\x1b[0m\n');
+    }
+  });
+  client.on('break', (params) => {
+    console.log(`\x1b[33m[BREAK] ${params[1] || '?'}:${params[2] || 0}\x1b[0m`);
+    console.log('Commands: continue|c, next|n, step|s, stack, vars <frame>, tree, inspect <id>, bp <file> <line>');
+  });
+  client.on('stack_dump', (params) => {
+    console.log('\x1b[36m--- Stack Dump ---\x1b[0m');
+    for (let i = 0; i < params.length; i += 3) {
+      console.log(`  Frame ${i / 3}: ${params[i + 1]}:${params[i + 2]} in ${params[i]}`);
+    }
+  });
+  client.on('godot_error', (params) => {
+    console.error('\x1b[31m[ERROR]', params.join(' '), '\x1b[0m');
+  });
+  client.on('disconnected', () => { console.log('\x1b[31mGodot disconnected.\x1b[0m'); process.exit(0); });
+  client.on('message', (msg) => handleMessage(msg, client));
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: '\x1b[32mgodot> \x1b[0m' });
+  rl.prompt();
+  rl.on('line', (line) => { dispatch(line.trim(), client, rl); rl.prompt(); });
+  rl.on('close', () => { client.disconnect(); process.exit(0); });
+}
+
+function handleMessage(msg, client) {
+  const cmd = String(msg.command);
+  if (cmd === 'scene:scene_tree_parse_end') {
+    try {
+      formatSceneTree(parseSceneNode(msg.params)).forEach(l => console.log(l));
+    } catch (e) {
+      console.log('[scene]', JSON.stringify(msg.params, null, 2));
+    }
+  }
+  if (cmd === 'scene:inspect_object') {
+    console.log('\x1b[36m--- Object Properties ---\x1b[0m');
+    const props = msg.params[2];
+    if (Array.isArray(props)) {
+      for (let i = 0; i < props.length; i += 5) {
+        console.log(`  ${props[i]}: ${JSON.stringify(props[i + 4])}`);
+      }
+    }
+  }
+  if (cmd === 'stack_frame_vars') {
+    const count = msg.params[0];
+    console.log('\x1b[36m--- Variables ---\x1b[0m');
+    for (let i = 0; i < count; i++) {
+      console.log(`  ${msg.params[1 + i * 3]} = ${JSON.stringify(msg.params[1 + i * 3 + 2])}`);
+    }
+  }
+}
+
+function dispatch(line, client, rl) {
+  const parts = line.split(/\s+/);
+  const cmd = parts[0];
+  if (!cmd) return;
+  const MAP = {
+    quit: () => { client.disconnect(); process.exit(0); },
+    exit: () => { client.disconnect(); process.exit(0); },
+    c: () => client.sendContinue(),
+    continue: () => client.sendContinue(),
+    n: () => client.sendNext(),
+    next: () => client.sendNext(),
+    s: () => client.sendStep(),
+    step: () => client.sendStep(),
+    b: () => client.sendBreak(),
+    break: () => client.sendBreak(),
+    stack: () => client.requestStackDump(),
+    vars: () => client.requestStackFrameVars(parseInt(parts[1] || '0')),
+    tree: () => client.requestSceneTree(),
+    inspect: () => client.requestInspectObject(parts[1] || '0'),
+    bp: () => client.setBreakpoint(parts[1], parseInt(parts[2]), parts[3] !== 'false'),
+  };
+  if (MAP[cmd]) MAP[cmd]();
+  else console.log('Unknown: continue|c, next|n, step|s, break|b, stack, vars, tree, inspect, bp');
+}
+
+module.exports = { startRepl };

package/lib/scene-tree.js

@@ -0,0 +1,27 @@
+'use strict';
+
+function parseSceneNode(params, ofs = { offset: 0 }) {
+  const childCount = params[ofs.offset++];
+  const name = params[ofs.offset++];
+  const className = params[ofs.offset++];
+  const id = params[ofs.offset++];
+  const sceneFilePath = params[ofs.offset++];
+  const viewFlags = params[ofs.offset++];
+  const children = [];
+  for (let i = 0; i < childCount; i++) {
+    children.push(parseSceneNode(params, ofs));
+  }
+  return { name, className, id, sceneFilePath, viewFlags, children };
+}
+
+function formatSceneTree(node, indent = 0) {
+  const prefix = '  '.repeat(indent);
+  const lines = [`${prefix}[${node.className}] ${node.name} (id:${node.id})`];
+  if (node.sceneFilePath) lines[0] += ` <${node.sceneFilePath}>`;
+  for (const child of node.children) {
+    lines.push(...formatSceneTree(child, indent + 1));
+  }
+  return lines;
+}
+
+module.exports = { parseSceneNode, formatSceneTree };

package/lib/templates.js

@@ -0,0 +1,146 @@
+'use strict';
+
+module.exports = function getTemplates(projectName) {
+  return {
+    'project.godot': `; Engine configuration file.
+config_version=5
+
+[application]
+
+config/name="${projectName}"
+config/features=PackedStringArray("4.3")
+config/icon="res://icon.svg"
+run/main_scene="res://scenes/main.tscn"
+
+[autoload]
+
+ReplBridge="res://addons/repl_bridge/repl_bridge.gd"
+
+[debug]
+
+settings/stdout/print_fps=true
+settings/stdout/verbose_stdout=true
+`,
+
+    'scenes/main.tscn': `[gd_scene load_steps=2 format=3 uid="uid://main"]
+
+[ext_resource type="Script" path="res://scripts/main.gd" id="1_main"]
+
+[node name="Main" type="Node"]
+script = ExtResource("1_main")
+`,
+
+    'scripts/main.gd': `extends Node
+
+func _ready() -> void:
+\tprint("[%s] Ready" % name)
+\tReplBridge.log_info("Game started: " + name)
+
+func _process(_delta: float) -> void:
+\tpass
+`,
+
+    'addons/repl_bridge/repl_bridge.gd': `extends Node
+
+const VERSION := "1.0.0"
+var _log_buffer: Array[String] = []
+
+func _ready() -> void:
+\tprint("[ReplBridge] v", VERSION, " initialized")
+\tEngineDebugger.register_message_capture("repl", _on_repl_message)
+
+func _on_repl_message(msg: String, data: Array) -> bool:
+\tmatch msg:
+\t\t"ping":
+\t\t\tEngineDebugger.send_message("repl:pong", ["pong", Time.get_ticks_msec()])
+\t\t\treturn true
+\t\t"get_logs":
+\t\t\tEngineDebugger.send_message("repl:logs", _log_buffer.duplicate())
+\t\t\treturn true
+\t\t"get_scene":
+\t\t\tvar tree_data := _dump_scene_tree(get_tree().root, 0)
+\t\t\tEngineDebugger.send_message("repl:scene", tree_data)
+\t\t\treturn true
+\t\t"eval":
+\t\t\tvar expr := Expression.new()
+\t\t\tvar err := expr.parse(data[0] if data.size() > 0 else "")
+\t\t\tif err == OK:
+\t\t\t\tvar result = expr.execute([], self)
+\t\t\t\tEngineDebugger.send_message("repl:eval_result", [str(result)])
+\t\t\telse:
+\t\t\t\tEngineDebugger.send_message("repl:eval_error", [expr.get_error_text()])
+\t\t\treturn true
+\treturn false
+
+func log_info(msg: String) -> void:
+\t_log_buffer.append("[INFO] " + msg)
+\tif _log_buffer.size() > 1000: _log_buffer.pop_front()
+\tprint(msg)
+
+func _dump_scene_tree(node: Node, depth: int) -> Array:
+\tvar result := []
+\tresult.append({"name": node.name, "class": node.get_class(), "depth": depth})
+\tfor child in node.get_children(): result.append_array(_dump_scene_tree(child, depth + 1))
+\treturn result
+`,
+
+    'addons/repl_bridge/plugin.cfg': `[plugin]
+name="ReplBridge"
+description="Remote REPL bridge for godot-kit CLI debugging"
+author="AnEntrypoint"
+version="1.0.0"
+script="repl_bridge.gd"
+`,
+
+    '.gdlintrc': `# gdtoolkit linter config (Godot 4.x)
+max-line-length = 120
+`,
+
+    '.gdformatrc': `line_length = 120
+`,
+
+    '.vscode/settings.json': `{
+  "godot_tools.editor_path": "",
+  "godot_tools.gdscript_lsp_server_port": 6005,
+  "[gdscript]": { "editor.defaultFormatter": "geequlim.godot-tools" }
+}
+`,
+
+    '.vscode/launch.json': `{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Godot Game",
+      "type": "godot",
+      "request": "launch",
+      "project": "\${workspaceFolder}",
+      "address": "tcp://127.0.0.1",
+      "port": 6007,
+      "profiling": false
+    },
+    {
+      "name": "Attach to Godot",
+      "type": "godot",
+      "request": "attach",
+      "project": "\${workspaceFolder}",
+      "address": "tcp://127.0.0.1",
+      "port": 6007
+    }
+  ]
+}
+`,
+
+    '.vscode/extensions.json': `{ "recommendations": ["geequlim.godot-tools"] }
+`,
+
+    'icon.svg': `<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128">
+  <rect width="128" height="128" rx="16" fill="#478cbf"/>
+  <text x="64" y="80" font-size="56" text-anchor="middle" fill="white" font-family="sans-serif">G</text>
+</svg>
+`,
+
+    '.gitignore': `.godot/\n*.import\nexport_presets.cfg\n*.translation\nnode_modules/\n`,
+
+    'Makefile': `setup:\n\tgodot-dev setup\nrun:\n\tgodot-dev launch\nrepl:\n\tgodot-dev repl\ninspect:\n\tgodot-dev inspect\nlogs:\n\tgodot-dev logs\nlint:\n\tgodot-dev lint\nformat:\n\tgodot-dev format\n.PHONY: setup run repl inspect logs lint format\n`,
+  };
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "godot-kit",
+  "version": "1.0.0",
+  "description": "Agentic Godot 4.x development boilerplate - REPL/CLI debugging, gdtoolkit, DAP, scene inspector, profiler",
+  "bin": {
+    "godot-kit": "bin/create.js",
+    "godot-dev": "bin/cli.js"
+  },
+  "main": "./lib/index.js",
+  "scripts": {
+    "test": "node bin/cli.js --help"
+  },
+  "keywords": [
+    "godot",
+    "gdscript",
+    "game-dev",
+    "debugger",
+    "repl",
+    "boilerplate",
+    "gdtoolkit"
+  ],
+  "author": "AnEntrypoint",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "readline": "^1.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AnEntrypoint/godot-kit.git"
+  }
+}