@tmhs/godot-correctness-mcp 0.1.0

package/dist/symbols/schema.js

@@ -0,0 +1,109 @@
+import { z } from "zod";
+/**
+ * Schema for the compact Godot symbol database produced by
+ * scripts/generate-symbol-db.ts from `godot --dump-extension-api`. Only the
+ * fields needed for API lookup and cross-version diffing are kept; hashes,
+ * memory offsets, class sizes, and native structures are stripped.
+ *
+ * Bump SCHEMA_VERSION when the shape changes so stale artifacts fail validation.
+ */
+export const SCHEMA_VERSION = 1;
+const argSchema = z.object({
+    name: z.string(),
+    type: z.string(),
+    /** Default value as Godot renders it, e.g. "false", "0", "Vector2(0, 0)". */
+    default: z.string().optional(),
+});
+const methodSchema = z.object({
+    name: z.string(),
+    /** Return type name, or null for void. */
+    ret: z.string().nullable(),
+    args: z.array(argSchema),
+    isConst: z.boolean().optional(),
+    isStatic: z.boolean().optional(),
+    isVirtual: z.boolean().optional(),
+    isVararg: z.boolean().optional(),
+});
+const propertySchema = z.object({
+    name: z.string(),
+    type: z.string(),
+    getter: z.string().optional(),
+    setter: z.string().optional(),
+});
+const signalSchema = z.object({
+    name: z.string(),
+    args: z.array(argSchema),
+});
+const enumSchema = z.object({
+    name: z.string(),
+    isBitfield: z.boolean().optional(),
+    values: z.array(z.object({ name: z.string(), value: z.number() })),
+});
+const classConstantSchema = z.object({ name: z.string(), value: z.number() });
+const classSchema = z.object({
+    inherits: z.string().nullable(),
+    apiType: z.string(),
+    isRefcounted: z.boolean().optional(),
+    isInstantiable: z.boolean().optional(),
+    methods: z.array(methodSchema),
+    properties: z.array(propertySchema),
+    signals: z.array(signalSchema),
+    enums: z.array(enumSchema),
+    constants: z.array(classConstantSchema),
+});
+const builtinOperatorSchema = z.object({
+    name: z.string(),
+    right: z.string().nullable(),
+    ret: z.string(),
+});
+const builtinConstantSchema = z.object({
+    name: z.string(),
+    type: z.string(),
+    value: z.string(),
+});
+const builtinClassSchema = z.object({
+    members: z.array(z.object({ name: z.string(), type: z.string() })),
+    constants: z.array(builtinConstantSchema),
+    enums: z.array(enumSchema),
+    operators: z.array(builtinOperatorSchema),
+    methods: z.array(methodSchema),
+    isKeyed: z.boolean().optional(),
+});
+const utilityFunctionSchema = z.object({
+    name: z.string(),
+    ret: z.string().nullable(),
+    category: z.string(),
+    args: z.array(argSchema),
+    isVararg: z.boolean().optional(),
+});
+const metaSchema = z.object({
+    /** Full patch version, e.g. "4.4.1". */
+    godotVersion: z.string(),
+    /** Minor-line label used to name the artifact, e.g. "4.4". */
+    versionLabel: z.string(),
+    /** Godot's own version string, e.g. "4.4.1.stable.official". */
+    versionFull: z.string(),
+    /** Release tag the binary came from, e.g. "4.4.1-stable". */
+    releaseTag: z.string().nullable(),
+    /** Downloaded archive filename, if the binary was fetched. */
+    archiveName: z.string().nullable(),
+    /** SHA-256 of the downloaded archive, if fetched. */
+    archiveSha256: z.string().nullable(),
+    /** Provenance of the binary, e.g. "godotengine/godot-builds" or "local". */
+    source: z.string(),
+    schemaVersion: z.literal(SCHEMA_VERSION),
+    generatedAt: z.string(),
+});
+export const symbolDbSchema = z.object({
+    meta: metaSchema,
+    classes: z.record(z.string(), classSchema),
+    builtinClasses: z.record(z.string(), builtinClassSchema),
+    utilityFunctions: z.array(utilityFunctionSchema),
+    globalEnums: z.array(enumSchema),
+    singletons: z.array(z.object({ name: z.string(), type: z.string() })),
+});
+/** Parse and validate an already-decompressed DB object. Throws on mismatch. */
+export function parseSymbolDb(data) {
+    return symbolDbSchema.parse(data);
+}
+//# sourceMappingURL=schema.js.map

package/dist/symbols/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/symbols/schema.ts"],"names":[],"mappings":"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"}

package/dist/tools/api.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** Register the API symbol lookup / summary / diff tools. */
+export declare function registerApiTools(server: McpServer): void;

package/dist/tools/api.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { availableVersions, loadSymbolDb } from "../symbols/db.js";
+import { classSummary, diffClass, diffSymbol, lookupSymbol, } from "../symbols/lookup.js";
+const VERSION = z.enum(["4.4", "4.5"]);
+const KIND = z.enum([
+    "class",
+    "method",
+    "property",
+    "signal",
+    "enum",
+    "constant",
+    "builtin_class",
+    "builtin_method",
+    "utility_function",
+    "singleton",
+    "global_enum",
+]);
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function fail(message) {
+    return { content: [{ type: "text", text: JSON.stringify({ error: message }, null, 2) }] };
+}
+/** Register the API symbol lookup / summary / diff tools. */
+export function registerApiTools(server) {
+    server.tool("api_symbol_lookup", "Look up a Godot API symbol (class, method, property, or signal) by name across " +
+        "the pinned Godot versions. Supports 'Owner.member' queries. Returns full " +
+        "signature data, or closest-match suggestions on a miss.", {
+        symbol: z.string().describe("Symbol name, e.g. 'Node', 'move_and_slide', or 'Node.get_child_count'"),
+        version: VERSION.optional().describe("Limit to one version; omit to search all available versions"),
+        kind: KIND.optional().describe("Restrict results to one symbol kind"),
+    }, async (args) => {
+        const { symbol, version, kind } = args;
+        const versions = version ? [version] : availableVersions();
+        if (versions.length === 0)
+            return fail("No symbol databases are available.");
+        try {
+            const byVersion = Object.fromEntries(versions.map((v) => [v, lookupSymbol(loadSymbolDb(v), symbol, kind ? { kind } : {})]));
+            return ok({ symbol, versions, results: byVersion });
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : String(err));
+        }
+    });
+    server.tool("api_class_summary", "Full member listing for one Godot class in one version: inheritance chain, " +
+        "methods, properties, signals, enums, and constants.", {
+        class: z.string().describe("Class name, e.g. 'CharacterBody2D'"),
+        version: VERSION.describe("Which Godot version to summarize"),
+    }, async (args) => {
+        const { class: className, version } = args;
+        try {
+            const db = loadSymbolDb(version);
+            const summary = classSummary(db, className);
+            if (!summary) {
+                const suggestions = lookupSymbol(db, className, { kind: "class" }).suggestions ?? [];
+                return fail(`Class '${className}' not found in Godot ${version}.` +
+                    (suggestions.length ? ` Did you mean: ${suggestions.map((s) => s.name).join(", ")}?` : ""));
+            }
+            return ok({ version, ...summary });
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : String(err));
+        }
+    });
+    server.tool("api_diff", "Diff a Godot class or symbol between two versions (default 4.4 -> 4.5): what " +
+        "was added, removed, or had its signature changed, with old and new signatures " +
+        "side by side.", {
+        symbol: z.string().describe("Class name (e.g. 'TileMap') or symbol (e.g. 'move_and_slide')"),
+        from: VERSION.optional().describe("Base version (default 4.4)"),
+        to: VERSION.optional().describe("Target version (default 4.5)"),
+    }, async (args) => {
+        const { symbol, from = "4.4", to = "4.5" } = args;
+        if (from === to)
+            return fail("'from' and 'to' must be different versions.");
+        try {
+            const fromDb = loadSymbolDb(from);
+            const toDb = loadSymbolDb(to);
+            // A dotted query is always a member; otherwise try a class diff first.
+            if (!symbol.includes(".")) {
+                const cd = diffClass(fromDb, toDb, symbol);
+                if (cd.presence.inFrom || cd.presence.inTo)
+                    return ok({ type: "class", diff: cd });
+            }
+            return ok({ type: "symbol", diff: diffSymbol(fromDb, toDb, symbol) });
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : String(err));
+        }
+    });
+}
+//# sourceMappingURL=api.js.map

package/dist/tools/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/tools/api.ts"],"names":[],"mappings":"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"}

package/dist/tools/lint.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** Register the GDScript lint tools (lint_file, lint_project). */
+export declare function registerLintTools(server: McpServer): void;

package/dist/tools/lint.js

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { loadConfig } from "../lint/config.js";
+import { lintSource } from "../lint/engine.js";
+import { lintProject } from "../lint/project.js";
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function fail(message) {
+    return { content: [{ type: "text", text: JSON.stringify({ error: message }, null, 2) }] };
+}
+/** Register the GDScript lint tools (lint_file, lint_project). */
+export function registerLintTools(server) {
+    server.tool("lint_file", "Lint a single GDScript (.gd) file against the default ruleset. Provide either " +
+        "inline source or a path on disk. Config is loaded from the file's directory " +
+        "if a godot-correctness.config.json is present. Returns a findings array.", {
+        path: z.string().describe("Path to the .gd file (used for the reported location and config lookup)"),
+        source: z.string().optional().describe("Inline GDScript source; if omitted, the file at 'path' is read"),
+    }, async (args) => {
+        const { path, source } = args;
+        try {
+            const code = source ?? readFileSync(path, "utf-8");
+            const config = loadConfig(dirname(path));
+            const findings = await lintSource(path, code, config);
+            return ok({ file: path, findings, count: findings.length });
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : String(err));
+        }
+    });
+    server.tool("lint_project", "Lint every GDScript file under a project root, honoring include/exclude globs " +
+        "from godot-correctness.config.json. Returns aggregated findings and severity counts.", {
+        path: z.string().describe("Path to the Godot project root"),
+    }, async (args) => {
+        const { path } = args;
+        try {
+            return ok(await lintProject(path));
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : String(err));
+        }
+    });
+}
+//# sourceMappingURL=lint.js.map

package/dist/tools/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../../src/tools/lint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAIjD,SAAS,EAAE,CAAC,IAAa;IACvB,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC9E,CAAC;AAED,SAAS,IAAI,CAAC,OAAe;IAC3B,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC5F,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,iBAAiB,CAAC,MAAiB;IACjD,MAAM,CAAC,IAAI,CACT,WAAW,EACX,gFAAgF;QAC9E,8EAA8E;QAC9E,0EAA0E,EAC5E;QACE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yEAAyE,CAAC;QACpG,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gEAAgE,CAAC;KACzG,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAyC,CAAC;QACnE,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YACnD,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YACzC,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YACtD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAChE,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,cAAc,EACd,gFAAgF;QAC9E,sFAAsF,EACxF;QACE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;KAC5D,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,MAAM,EAAE,IAAI,EAAE,GAAG,IAAwB,CAAC;QAC1C,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAChE,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/scenes.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** Register the scene / resource / registry static-analysis tools. */
+export declare function registerSceneTools(server: McpServer): void;

package/dist/tools/scenes.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { projectReport } from "../scenes/report.js";
+import { validateProjectConfig, validateRegistries, validateScenes, } from "../scenes/validate.js";
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function fail(message) {
+    return { content: [{ type: "text", text: JSON.stringify({ error: message }, null, 2) }] };
+}
+function guard(fn) {
+    try {
+        return ok(fn());
+    }
+    catch (err) {
+        return fail(err instanceof Error ? err.message : String(err));
+    }
+}
+/** Register the scene / resource / registry static-analysis tools. */
+export function registerSceneTools(server) {
+    server.tool("validate_scenes", "Validate every .tscn under a project root: ext_resource paths resolve, " +
+        "ExtResource references are declared, and there are no duplicate resource ids.", { path: z.string().describe("Path to the Godot project root") }, async (args) => guard(() => {
+        const findings = validateScenes(args.path);
+        return { findings, count: findings.length };
+    }));
+    server.tool("validate_project_config", "Validate project.godot: the main scene exists, autoload paths exist, and " +
+        "input actions are well-formed.", { path: z.string().describe("Path to the Godot project root") }, async (args) => guard(() => {
+        const findings = validateProjectConfig(args.path);
+        return { findings, count: findings.length };
+    }));
+    server.tool("validate_registries", "Deep-validate data-driven .tres registries in the configured registryDirs: " +
+        "each parses, its script resolves (recording class_name), and every " +
+        "resource-path property points at an existing file (the dangling-path check).", { path: z.string().describe("Path to the Godot project root") }, async (args) => guard(() => validateRegistries(args.path)));
+    server.tool("project_report", "Aggregate all static checks (scenes, project config, registries, and " +
+        "GDScript lint) into one report with severity counts.", { path: z.string().describe("Path to the Godot project root") }, async (args) => {
+        try {
+            return ok(await projectReport(args.path));
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : String(err));
+        }
+    });
+}
+//# sourceMappingURL=scenes.js.map

package/dist/tools/scenes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenes.js","sourceRoot":"","sources":["../../src/tools/scenes.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@tmhs/godot-correctness-mcp",
+  "version": "0.1.0",
+  "description": "Offline static correctness MCP server for Godot 4.x GDScript projects",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "godot-correctness-mcp": "dist/index.js",
+    "gdcorrect": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "data",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "validate:artifacts": "tsx scripts/validate-symbol-db.ts",
+    "dev": "tsx watch src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "picomatch": "^4.0.5",
+    "web-tree-sitter": "^0.26.11",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/picomatch": "^4.0.3",
+    "tsx": "^4.19.4",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.8"
+  },
+  "author": "TMHSDigital",
+  "license": "CC-BY-NC-ND-4.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TMHSDigital/godot-correctness-mcp.git"
+  },
+  "homepage": "https://github.com/TMHSDigital/godot-correctness-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/TMHSDigital/godot-correctness-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/skills/data-driven-resources.md

@@ -0,0 +1,78 @@
+# Data-driven resources and registry loading
+
+Custom `Resource` types let you drive game content from `.tres` files instead of
+hardcoding it. Keep resources as **pure data**, load them through a validated
+**registry**, and this server's `validate_registries` tool can catch dangling
+references before they fail at runtime.
+
+## Keep Resource state data-only
+
+A data resource should hold values, not runtime/session state. Runtime state
+(current health, cooldown timers, whoever owns it) belongs on the node that uses
+the resource, not on the shared resource instance — resources are shared by
+reference, so mutating one at runtime mutates it everywhere and can leak into
+saved copies.
+
+```gdscript
+# item.gd - data only
+extends Resource
+class_name ItemData
+
+@export var id: StringName
+@export var display_name: String
+@export var icon: Texture2D
+@export var scene_path: String  # path to a .tscn to spawn; validated statically
+```
+
+```gdscript
+# WRONG: runtime state on the shared data resource
+extends Resource
+class_name ItemData
+@export var display_name: String
+var current_stack := 0  # <- mutated at runtime, shared across every holder
+```
+
+Put `current_stack` on the inventory node instead, keyed by `ItemData`.
+
+## Registry-loading pattern
+
+Load a directory of `.tres` into a typed dictionary once, keyed by a stable id.
+
+```gdscript
+# item_registry.gd (autoload)
+extends Node
+
+const ITEM_DIR := "res://resources/items"
+var _items: Dictionary[StringName, ItemData] = {}
+
+func _ready() -> void:
+	for file in DirAccess.get_files_at(ITEM_DIR):
+		if not file.ends_with(".tres"):
+			continue
+		var res := load(ITEM_DIR.path_join(file)) as ItemData
+		if res == null:
+			push_error("Not an ItemData: %s" % file)
+			continue
+		_items[res.id] = res
+
+func get_item(id: StringName) -> ItemData:
+	return _items.get(id)
+```
+
+## Validate before runtime
+
+String path properties like `scene_path` above are invisible failures: a renamed
+or deleted `.tscn` only errors when something actually loads it. Configure the
+registry directory so the static validator checks every `.tres`:
+
+```json
+// godot-correctness.config.json
+{
+  "registryDirs": ["resources/items"],
+  "pathPropertyPatterns": ["*_path", "*_scene"]
+}
+```
+
+Then `validate_registries` (or `gdcorrect validate-registries .`) confirms each
+`.tres` parses, its script resolves, and every resource-path property points at
+an existing file. See also [[signal-hygiene]] and [[typed-gdscript]].

package/skills/resource-preload.md

@@ -0,0 +1,43 @@
+# preload vs load
+
+Choose between `preload` and `load` by *when* you need the resource and whether
+the path is known at compile time.
+
+## preload: compile-time, known path
+
+`preload` resolves at parse time and bakes the dependency into the script. Use it
+for assets you always need and whose path is a constant literal.
+
+```gdscript
+const BulletScene := preload("res://actors/bullet.tscn")
+
+func fire() -> void:
+	var b := BulletScene.instantiate()
+	add_child(b)
+```
+
+Because `preload` needs a constant literal path, prefer it over `load("res://...")`
+with a hardcoded string — it fails at compile time (not runtime) if the path is
+wrong, and it does not re-hit the disk cache each call.
+
+## load: runtime, dynamic path
+
+Use `load` when the path is computed (e.g. from a data resource) or the asset is
+optional/lazy.
+
+```gdscript
+func spawn_from(item: ItemData) -> Node:
+	var scene := load(item.scene_path) as PackedScene  # path came from data
+	return scene.instantiate() if scene else null
+```
+
+Data-driven paths like `item.scene_path` are exactly what
+[[data-driven-resources]] and the `validate_registries` tool guard: a dangling
+`res://` path here is invisible until this line runs. Validate registries in CI
+so a bad path fails the build, not the player's session.
+
+## Do not preload inside hot loops
+
+`preload` is resolved once at parse time regardless of where it appears, but keep
+`load()` calls out of `_process`/`_physics_process`; cache the `PackedScene` once.
+See [[typed-gdscript]].

package/skills/signal-hygiene.md

@@ -0,0 +1,46 @@
+# Signal hygiene
+
+Godot 4 signals are first-class. Connect with the typed `Callable` API, avoid
+frame-fragile lookups, and disconnect (or use one-shot) when a connection should
+not outlive the node.
+
+## Prefer the typed connect API
+
+```gdscript
+# Godot 4: reference the signal object and pass a Callable
+button.pressed.connect(_on_button_pressed)
+
+# Avoid the stringly-typed legacy form
+button.connect("pressed", Callable(self, "_on_button_pressed"))
+```
+
+## Connect once, disconnect deliberately
+
+Connecting in `_ready()` without cleanup risks double-connections (if the node
+re-enters the tree) or dangling references (if the emitter outlives the receiver).
+
+```gdscript
+func _ready() -> void:
+	# One-shot: auto-disconnects after the first emission.
+	get_tree().create_timer(1.0).timeout.connect(_spawn, CONNECT_ONE_SHOT)
+	EventBus.player_died.connect(_on_player_died)
+
+func _exit_tree() -> void:
+	if EventBus.player_died.is_connected(_on_player_died):
+		EventBus.player_died.disconnect(_on_player_died)
+```
+
+This server's `connect-without-disconnect` lint rule flags `connect()` in
+`_ready()` when there is no matching `disconnect()` and no `CONNECT_ONE_SHOT`.
+
+## await a signal instead of polling
+
+```gdscript
+func flash() -> void:
+	modulate = Color.RED
+	await get_tree().create_timer(0.1).timeout  # await a real signal
+	modulate = Color.WHITE
+```
+
+Never `await` a plain value — `await` expects a signal or a coroutine
+(the `await-misuse` rule catches `await <literal>`). See [[typed-gdscript]].

package/skills/typed-gdscript.md

@@ -0,0 +1,47 @@
+# Typed GDScript patterns
+
+Static types make GDScript faster (typed instructions) and let tools catch
+mistakes. Prefer inference with `:=`, annotate function signatures, and cache
+node references with `@onready`.
+
+## Type every declaration
+
+```gdscript
+var speed := 300.0            # inferred float via :=
+var target: Node2D = null     # explicit type when there is no initializer
+const MAX_HP := 100           # inferred int
+
+func take_damage(amount: int) -> void:
+	_hp = maxi(_hp - amount, 0)
+```
+
+Avoid bare `var x = 3` — it is untyped. Use `:=` to infer or `: Type` to
+annotate. The `untyped-declaration` rule flags declarations with neither.
+
+## Cache node references with @onready
+
+```gdscript
+# Resolved once, after the node enters the tree.
+@onready var sprite: Sprite2D = $Sprite2D
+@onready var _agent: NavigationAgent2D = $NavigationAgent2D
+```
+
+Do not look nodes up every frame:
+
+```gdscript
+# WRONG: $ / get_node() inside _process runs every frame
+func _process(delta: float) -> void:
+	$Sprite2D.rotation += delta   # get-node-in-process
+```
+
+The `missing-onready` rule flags a class-level node-path member without
+`@onready`; `get-node-in-process` flags per-frame lookups.
+
+## Prefer $ over string paths
+
+```gdscript
+@onready var hp_bar := $UI/HPBar          # rename-safe editor reference
+# var hp_bar = get_node("UI/HPBar")       # stringly-nodepath: fragile
+```
+
+See [[signal-hygiene]] and [[data-driven-resources]].