fnf-blender-mcp 0.2.0 → 0.2.2

package/README.md

@@ -1,27 +1,29 @@
-# Higgsfield use Blender
+# Higgsfield Blender MCP
 
-The independent `fnf-blender-mcp` package in `fnf-local-pluging-bridge-mcp/blender` controls a dedicated background Blender process. No add-on, HTTP listener, WebSocket, cloud account or open Blender window is required.
+Local MCP server that controls a dedicated background Blender process. No add-on, HTTP listener, WebSocket, cloud account or open Blender window is required.
 
 ```text
 Desktop MCP client → stdio → Node MCP → process pipes → Blender --background → bpy
 ```
 
-Each MCP connection owns one process. Its scene persists between commands; it cannot access unsaved work in an already-open desktop Blender. Open saved input with `bl_open_project`, edit and render, then save a `.blend` output to inspect in the desktop UI. Disconnecting loses unsaved session changes. The After Effects package at the repository root is independent.
+Each MCP connection owns one process. Its scene persists between commands; it cannot access unsaved work in an already-open desktop Blender. Open saved input with `bl_open_project`, edit and render, then save a `.blend` output to inspect in the desktop UI. Disconnecting loses unsaved session changes.
 
-## Setup
+## Requirements
 
-Requires Node.js 24+ with npm and Blender 4.2+. Version 0.2.0 introduces the background runtime; version 0.1.0 uses the previous add-on. Verify that 0.2.0 is published before installing it; this source change alone does not publish a release.
+- Node.js 24 or later with npm.
+- Blender 4.2 or later on the same computer as the MCP client.
+
+## Installation
 
 ```sh
-npm view fnf-blender-mcp@0.2.0 version --registry=https://registry.npmjs.org/
 blenderDir="$HOME/.higgsfield/blender-mcp"
-npm install --prefix "$blenderDir" --registry=https://registry.npmjs.org/ fnf-blender-mcp@0.2.0
+npm install --prefix "$blenderDir" fnf-blender-mcp@latest
 blenderCli="$blenderDir/node_modules/fnf-blender-mcp/dist/cli.js"
 node "$blenderCli" doctor --blender "/absolute/path/to/blender"
 node "$blenderCli" config --blender "/absolute/path/to/blender" --format json
 ```
 
-Use the executable inside `Blender.app/Contents/MacOS/Blender` on macOS, or `blender.exe` on Windows. `config --format toml` prints a Codex entry. Both formats include absolute Node/server paths and `BLENDER_EXECUTABLE`; merge the entry into the intended client and refresh its connection. The helper prints configuration but does not register a server. See the [installation skill](skills/use-blender/references/installation.md) for PowerShell and migration steps.
+Use the executable inside `Blender.app/Contents/MacOS/Blender` on macOS, or `blender.exe` on Windows. `config --format toml` prints a Codex entry. Both formats include absolute Node/server paths and `BLENDER_EXECUTABLE`; merge the entry into the intended client and refresh its connection. The helper prints configuration but does not register a server. The installed package includes a `use-blender` skill with additional setup guidance.
 
 The server starts Blender on its first execution call. `doctor` checks a separate temporary background process and terminates it afterward. Verify conversation access with `bl_health` and `bl_get_scene_summary`. `BLENDER_EXECUTABLE` can be set directly; without it the runtime tries standard installation locations and PATH. No separate Python installation is needed at runtime.
 
@@ -36,33 +38,22 @@ The server starts Blender on its first execution call. `doctor` checks a separat
 | Files | `bl_save_project`, `bl_open_project` |
 | Evidence | `bl_render` |
 | Python/status | `bl_execute`, `bl_job_status` |
-| Offline guidance | `bl_get_skill` |
+| Offline guidance | `bl_list_skills`, `bl_get_skill`, `bl_get_skill_asset` |
 
 Start with `bl_get_skill(name: "blender-scene")`. Python runs sequentially on the process's main thread. Scene datablocks persist, while script-local variables do not. Assign a JSON-compatible `result` to return data. Python stdout/stderr are capped at 64 Ki characters each; JSON results are limited to 4 MiB. Native Blender diagnostics do not enter the MCP stdout protocol.
 
+The npm archive contains the Blender craft modules. `bl_list_skills` lists the modules in the installed package and their references/assets; `bl_get_skill` reads an entry or reference, and `bl_get_skill_asset` returns the local path of a bundled file. The original five `bl_get_skill` names remain valid. An MCP client can read this guidance directly without installing the modules as client-side skills; client-side installation is optional for hosts that support automatic skill activation. Existing installations do not gain new modules or tools until the npm package is updated and the MCP connection refreshed. Skill guidance does not execute Blender operations or prove a live connection.
+
 Render a camera frame to PNG; files up to 4 MiB receive an inline preview. Cycles supports sample overrides. Save/render require `overwrite: true` for existing output files; opening a different project refuses unsaved changes unless explicitly discarded. Arbitrary Python is not sandboxed and can bypass these typed-tool guards. Automatic execution of Python embedded in opened `.blend` files is disabled.
 
-## Session lifecycle
+## Troubleshooting and limits
 
 A timed-out job continues and keeps its `job_id`. Query `bl_job_status` before retrying; additional execution commands are rejected while it runs. No automatic retries or rollbacks occur. Status retains at most 128 jobs within the MCP process. If Blender crashes, the session fails and is not restarted automatically: inspect output files before reconnecting to a new empty session. Closing the MCP terminates its child process, including a running job; save needed changes first.
 
-In 0.2.0, `launch`, `install-addon`, `bl_screenshot`, bridge discovery, PID selection and runtime-directory overrides are removed. Use camera renders for visual evidence. No existing desktop scenes, preferences or installed add-ons are modified during startup. Multiple MCP connections have separate background scenes.
-
-## Development and validation
-
-From the repository root:
-
-```sh
-cd blender
-npm ci
-npm test
-npm run typecheck
-npm run test:package
-BLENDER_EXECUTABLE=/absolute/path/to/blender npm run test:live
-```
-
-Offline tests exercise actual MCP and child-process pipes using a Python CLI fixture, persistent session state, isolation, timeout recovery, process death, bounded results/history, output formatting, CLI configuration and typed-script guards. They do not replace live Blender validation. `test:package` installs the archive independently and verifies 19 tools, offline guidance and the absence of add-on files. `test:live` uses real Blender for geometry, materials, keyframes, file guards and a small Cycles render in disposable files.
+Use camera renders for visual evidence. No existing desktop scenes, preferences or installed add-ons are modified during startup. Multiple MCP connections have separate background scenes.
 
 Verified on macOS arm64 with Blender 4.2.23 LTS: persistent scene, mesh/material/camera/light edits, keyframes, save/reopen guards and a Cycles PNG preview. Windows/Linux native Blender execution has not been verified locally.
 
-See [RELEASING.md](RELEASING.md) for release steps. The setup skill is mirrored in fnf-mcp-server's `/use-blender` command; keep its body and references synchronized. See [UPSTREAM.md](UPSTREAM.md) for provenance and [LICENSE](LICENSE) for the MIT license.
+The installed package includes `UPSTREAM.md` and `LICENSE` for provenance and licensing details.
+
+Background Blender does not reliably mark direct Python edits as dirty. The MCP also tracks attempted mutations, including failed commands and arbitrary `bl_execute` calls, conservatively as unsaved until `bl_save_project` or an explicitly permitted `bl_open_project` succeeds. Read tools preserve this state.

package/dist/server.js

@@ -3,7 +3,7 @@ import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import { BL_TOOLS } from "./tools.js";
 import { BlenderTransport } from "./transport.js";
-import { getSkill, SKILL_NAMES } from "./skills.js";
+import { getSkill, getSkillAsset, listSkills } from "./skills.js";
 const packageInfo = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
 const errorResult = (error) => ({ isError: true, content: [{ type: "text", text: String(error) }] });
 export async function formatResult(job) {
@@ -32,7 +32,7 @@ export async function formatResult(job) {
 }
 export function createServer(transport = new BlenderTransport()) {
     const server = new McpServer({ name: "higgsfield-use-blender", title: "Higgsfield use Blender", version: packageInfo.version }, {
-        instructions: "Control a dedicated background Blender process; it cannot access an open desktop window. Save .blend files before disconnecting; unsaved state is lost on reconnect. Read bl_get_skill(blender-scene), then bl_health and bl_get_scene_summary before edits. Prefer typed tools; use bl_execute for other bpy operations. Commands can partially mutate before errors. On timeout, query bl_job_status; never blindly retry. Render and view results. Cloud generation is provided by a separate Higgsfield MCP, not this server.",
+        instructions: "Control a dedicated background Blender process; it cannot access an open desktop window. Save .blend files before disconnecting; unsaved state is lost on reconnect. Read bl_get_skill(blender-scene), then bl_health and bl_get_scene_summary before edits. For specialized work, call bl_list_skills, load the relevant skill with bl_get_skill and only needed references; bl_get_skill_asset locates bundled assets. Prefer typed tools; use bl_execute for other bpy operations. Commands can partially mutate before errors. On timeout, query bl_job_status; never blindly retry. Render and view results. Cloud generation is provided by a separate Higgsfield MCP, not this server.",
     });
     for (const tool of BL_TOOLS) {
         server.registerTool(tool.name, {
@@ -40,7 +40,8 @@ export function createServer(transport = new BlenderTransport()) {
             annotations: { readOnlyHint: tool.readOnly, destructiveHint: !tool.readOnly, idempotentHint: tool.readOnly, openWorldHint: tool.name === "bl_execute" },
         }, async (args) => {
             try {
-                return await formatResult(await transport.execute(tool.code(args), tool.name === "bl_render" ? 300 : 120));
+                const mutates = !tool.readOnly && !["bl_save_project", "bl_open_project"].includes(tool.name);
+                return await formatResult(await transport.execute(tool.code(args), tool.name === "bl_render" ? 300 : 120, mutates));
             }
             catch (error) {
                 return errorResult(error);
@@ -59,10 +60,43 @@ export function createServer(transport = new BlenderTransport()) {
             return errorResult(error);
         }
     });
+    server.registerTool("bl_list_skills", {
+        title: "List Blender Skills", description: "List bundled Blender skill names, descriptions, references and assets. Does not require Blender to be running.",
+        inputSchema: z.object({}).strict(),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async () => {
+        try {
+            const index = await listSkills();
+            return { content: [{ type: "text", text: JSON.stringify(index) }], structuredContent: index };
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
     server.registerTool("bl_get_skill", {
-        title: "Read Blender Skill", description: "Load offline Blender craft guidance. Start with blender-scene, then read the relevant topic. Does not require Blender to be running.",
-        inputSchema: z.object({ name: z.enum(SKILL_NAMES).default("blender-scene") }).strict(),
+        title: "Read Blender Skill", description: "Load a bundled Blender skill or one of its listed references. Start with blender-scene. Legacy topic names remain supported. Does not require Blender to be running.",
+        inputSchema: z.object({ name: z.string().default("blender-scene"), document: z.string().default("SKILL.md") }).strict(),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ name, document }) => {
+        try {
+            return { content: [{ type: "text", text: await getSkill(name, document) }] };
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("bl_get_skill_asset", {
+        title: "Locate Blender Skill Asset", description: "Return the absolute path and size of an asset bundled with a listed Blender skill. The path is local to the MCP host.",
+        inputSchema: z.object({ name: z.string(), path: z.string() }).strict(),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    }, async ({ name }) => ({ content: [{ type: "text", text: await getSkill(name) }] }));
+    }, async ({ name, path }) => {
+        try {
+            const asset = await getSkillAsset(name, path);
+            return { content: [{ type: "text", text: JSON.stringify(asset) }], structuredContent: asset };
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
     return server;
 }

package/dist/skills.d.ts

@@ -1,2 +1,15 @@
-export declare const SKILL_NAMES: readonly ["blender-scene", "modeling", "materials", "lighting-camera", "animation"];
-export declare function getSkill(name: typeof SKILL_NAMES[number]): Promise<string>;
+export declare function listSkills(): Promise<{
+    skills: {
+        name: string;
+        description: string;
+        references: string[];
+        assets: string[];
+    }[];
+}>;
+export declare function getSkill(name: string, document?: string): Promise<string>;
+export declare function getSkillAsset(name: string, path: string): Promise<{
+    name: string;
+    path: string;
+    absolute_path: string;
+    bytes: number;
+}>;

package/dist/skills.js

@@ -1,6 +1,90 @@
-import { readFile } from "node:fs/promises";
-export const SKILL_NAMES = ["blender-scene", "modeling", "materials", "lighting-camera", "animation"];
-export async function getSkill(name) {
-    const relative = name === "blender-scene" ? "SKILL.md" : `references/${name}.md`;
-    return readFile(new URL(`../skills/blender-scene/${relative}`, import.meta.url), "utf8");
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const root = fileURLToPath(new URL("../skills/", import.meta.url));
+const legacyReferences = new Set(["modeling", "materials", "lighting-camera", "animation"]);
+const skillName = /^blender-[a-z0-9-]+$/;
+const documentPath = /^references\/[a-zA-Z0-9/_-]+\.md$/;
+const assetPath = /^assets\/[a-zA-Z0-9][a-zA-Z0-9/._-]*$/;
+function validParts(path) {
+    return !path.split("/").some(part => part === "" || part === "." || part === "..");
+}
+async function bundledFile(name, path) {
+    const corpus = await realpath(root);
+    const base = await realpath(resolve(root, name));
+    const skillLocal = relative(corpus, base);
+    if (skillLocal === ".." || skillLocal.startsWith("../") || skillLocal.startsWith("..\\") || isAbsolute(skillLocal)) {
+        throw new Error("Skill path escapes the bundled corpus");
+    }
+    const file = await realpath(resolve(base, path));
+    const local = relative(base, file);
+    if (local === ".." || local.startsWith("../") || local.startsWith("..\\") || isAbsolute(local)) {
+        throw new Error("Skill path escapes the bundled corpus");
+    }
+    if (!(await stat(file)).isFile())
+        throw new Error("Skill path is not a file");
+    return file;
+}
+async function files(name, folder) {
+    try {
+        const candidates = (await readdir(resolve(root, name, folder), { recursive: true }))
+            .map(path => `${folder}/${path}`)
+            .filter(path => validParts(path) && (folder === "assets" ? assetPath.test(path) : documentPath.test(path)))
+            .sort();
+        const checked = await Promise.all(candidates.map(async (path) => {
+            if (!(await stat(resolve(root, name, path))).isFile())
+                return null;
+            await bundledFile(name, path);
+            return path;
+        }));
+        return checked.filter((path) => path !== null);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+async function requireSkill(name) {
+    if (!skillName.test(name))
+        throw new RangeError(`Unknown Blender skill '${name}'`);
+    try {
+        await bundledFile(name, "SKILL.md");
+    }
+    catch {
+        throw new RangeError(`Unknown Blender skill '${name}'. Call bl_list_skills for available names.`);
+    }
+}
+export async function listSkills() {
+    const entries = await readdir(root, { withFileTypes: true });
+    const names = entries.filter(entry => entry.isDirectory() && skillName.test(entry.name)).map(entry => entry.name).sort();
+    return { skills: await Promise.all(names.map(async (name) => {
+            const entry = await readFile(await bundledFile(name, "SKILL.md"), "utf8");
+            return {
+                name,
+                description: /^description:\s*(.+)$/m.exec(entry)?.[1] ?? "",
+                references: await files(name, "references"),
+                assets: await files(name, "assets"),
+            };
+        })) };
+}
+export async function getSkill(name, document = "SKILL.md") {
+    if (legacyReferences.has(name)) {
+        if (document !== "SKILL.md")
+            throw new RangeError("Legacy topic aliases do not have references");
+        return readFile(await bundledFile("blender-scene", `references/${name}.md`), "utf8");
+    }
+    await requireSkill(name);
+    if (document !== "SKILL.md" && (!validParts(document) || !documentPath.test(document) || !(await files(name, "references")).includes(document))) {
+        throw new RangeError(`Unknown reference '${document}' for '${name}'`);
+    }
+    return readFile(await bundledFile(name, document), "utf8");
+}
+export async function getSkillAsset(name, path) {
+    await requireSkill(name);
+    if (!validParts(path) || !assetPath.test(path) || !(await files(name, "assets")).includes(path)) {
+        throw new RangeError(`Unknown asset '${path}' for '${name}'`);
+    }
+    const absolute_path = await bundledFile(name, path);
+    return { name, path, absolute_path, bytes: (await stat(absolute_path)).size };
 }

package/dist/tools.js

@@ -189,7 +189,7 @@ result = _info`),
 ];
 BL_TOOLS.push(scriptTool("bl_health", "Inspect Blender", "Start or inspect this MCP session’s background Blender. Returns its version, PID, active file and scene; does not inspect an open desktop window.", {}, `import os
 result = {"version": bpy.app.version_string, "pid": os.getpid(), "background": bpy.app.background,
-          "file": bpy.data.filepath, "dirty": bpy.data.is_dirty, "scene": bpy.context.scene.name}`), scriptTool("bl_save_project", "Save Blender Project", "Save the current scene to an absolute .blend path. Existing files require overwrite=true.", {
+          "file": bpy.data.filepath, "dirty": _mcp_session["dirty"] or bpy.data.is_dirty, "scene": bpy.context.scene.name}`), scriptTool("bl_save_project", "Save Blender Project", "Save the current scene to an absolute .blend path. Existing files require overwrite=true.", {
     path: z.string().min(1), overwrite: z.boolean().default(false),
 }, `import os
 _path = _args["path"]
@@ -197,16 +197,20 @@ if not os.path.isabs(_path) or not _path.lower().endswith(".blend"):
     raise ValueError("Provide an absolute .blend path")
 if os.path.exists(_path) and not _args["overwrite"]:
     raise ValueError("File exists; use a new path or explicitly set overwrite=true")
-bpy.ops.wm.save_as_mainfile(filepath=_path, check_existing=False)
+if "FINISHED" not in bpy.ops.wm.save_as_mainfile(filepath=_path, check_existing=False):
+    raise RuntimeError("Project save did not finish")
+_mcp_session["dirty"] = False
 result = {"path": bpy.data.filepath, "saved": not bpy.data.is_dirty}`), scriptTool("bl_open_project", "Open Blender Project", "Replace the active project with an existing .blend file. Refuses unsaved changes unless discard_unsaved=true.", {
     path: z.string().min(1), discard_unsaved: z.boolean().default(false),
 }, `import os
 _path = _args["path"]
 if not os.path.isabs(_path) or not os.path.isfile(_path) or not _path.lower().endswith(".blend"):
     raise ValueError("Provide an existing absolute .blend path")
-if bpy.data.is_dirty and not _args["discard_unsaved"]:
+if (_mcp_session["dirty"] or bpy.data.is_dirty) and not _args["discard_unsaved"]:
     raise ValueError("The current project has unsaved changes; save first or explicitly set discard_unsaved=true")
-bpy.ops.wm.open_mainfile(filepath=_path, use_scripts=False)
+if "FINISHED" not in bpy.ops.wm.open_mainfile(filepath=_path, use_scripts=False):
+    raise RuntimeError("Project open did not finish")
+_mcp_session["dirty"] = False
 result = {"path": bpy.data.filepath, "scene": bpy.context.scene.name}`), scriptTool("bl_insert_keyframe", "Insert Object Keyframe", "Key the current location, Euler rotation or scale of a named object at a frame.", {
     name: z.string().min(1), property: z.enum(["location", "rotation_euler", "scale"]), frame: z.number().int(),
 }, `_obj = bpy.data.objects.get(_args["name"])

package/dist/transport.d.ts

@@ -25,6 +25,6 @@ export declare class BlenderTransport {
     private start;
     private launch;
     status(jobId: string): Promise<JobResult>;
-    execute(code: string, timeoutSeconds?: number): Promise<JobResult>;
+    execute(code: string, timeoutSeconds?: number, mutates?: boolean): Promise<JobResult>;
     close(): Promise<void>;
 }

package/dist/transport.js

@@ -152,7 +152,7 @@ export class BlenderTransport {
             throw new Error("Unknown job_id for this MCP session; history is limited to 128 jobs and disappears on reconnect.");
         return job;
     }
-    async execute(code, timeoutSeconds = 120) {
+    async execute(code, timeoutSeconds = 120, mutates = true) {
         if (!code || code.length > 1_000_000)
             throw new Error("Python source must contain 1–1000000 characters.");
         await this.start();
@@ -166,7 +166,7 @@ export class BlenderTransport {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => reject(new Error(`Blender is still running; job_id=${id}. Use bl_job_status on this MCP session before retrying. No automatic retry or cancellation was sent.`)), timeoutSeconds * 1000);
             this.active = { id, finish: result => { clearTimeout(timer); resolve(result); } };
-            this.child.stdin.write(JSON.stringify({ job_id: id, code }) + "\n", error => { if (error)
+            this.child.stdin.write(JSON.stringify({ job_id: id, code, mutates }) + "\n", error => { if (error)
                 this.fail(error); });
         });
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fnf-blender-mcp",
-  "version": "0.2.0",
-  "description": "Higgsfield use Blender: local stdio MCP controlling a background Blender process without add-ons.",
+  "version": "0.2.2",
+  "description": "Local MCP server for Blender with a background process and offline creative skills.",
   "type": "module",
   "license": "MIT",
   "engines": {
@@ -15,7 +15,6 @@
     "dist",
     "skills",
     "README.md",
-    "RELEASING.md",
     "UPSTREAM.md",
     "LICENSE",
     "scripts/*.py"
@@ -42,20 +41,11 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "homepage": "https://www.npmjs.com/package/fnf-blender-mcp",
   "keywords": [
     "blender",
     "mcp",
     "higgsfield",
     "3d",
     "bpy"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/higgsfield-ai/fnf-local-pluging-bridge-mcp.git",
-    "directory": "blender"
-  },
-  "bugs": {
-    "url": "https://github.com/higgsfield-ai/fnf-local-pluging-bridge-mcp/issues"
-  }
+  ]
 }

package/scripts/background_runner.py

@@ -9,6 +9,7 @@ import traceback
 PREFIX = "HF_BLENDER_JSON:"
 MAX_RESULT = 4 * 1024 * 1024
 MAX_REQUEST = 8 * 1024 * 1024
+SESSION = {"dirty": False}
 
 
 class BoundedText(io.TextIOBase):
@@ -30,10 +31,16 @@ def execute(request):
     code = request["code"]
     if not isinstance(code, str) or not 0 < len(code) <= 1_000_000:
         raise ValueError("Invalid Python source length")
+    mutates = request.get("mutates", True)
+    if not isinstance(mutates, bool):
+        raise ValueError("Invalid mutation flag")
     stdout, stderr = BoundedText(), BoundedText()
     response = {"job_id": job_id, "state": "completed"}
     try:
-        namespace = {"__name__": "__blender_mcp__"}
+        namespace = {"__name__": "__blender_mcp__", "_mcp_session": SESSION}
+        # Background RNA writes may leave bpy.data.is_dirty false, even after partial failure.
+        if mutates:
+            SESSION["dirty"] = True
         with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
             exec(compile(code, "<blender-mcp>", "exec"), namespace)
         result = namespace.get("result")

package/skills/blender-animation/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: blender-animation
+description: Dynamic-by-default motion — the motion plan, semantic rigs, deliberate interpolation, constraints and drivers, surface contact, rotational aliasing, visibility keying, dynamic defaults per subject type, and the motion audit. For motion produced by a rigid-body solver rather than keyframes, use blender-destruction.
+---
+
+# Animation
+
+Read [blender-scene](../blender-scene/SKILL.md) for the local session contract.
+Tool names below use its capability mapping when the named interface is absent;
+read only the relevant rows in [blender-volatile](../blender-volatile/SKILL.md).
+
+Motion is part of the default deliverable: unless the user explicitly asked
+for a static scene, the Scene Passport defines at least one purposeful beat.
+"Dynamic" means the viewer can watch something change and read it — not that
+everything moves at once.
+
+## Motion plan
+
+Pin down before keying anything:
+
+- fps, frame range, playback duration;
+- rest pose and beat structure: anticipation → action → settle;
+- the carrier of each beat — object, camera, light, material, or environment;
+- the loop boundary, if the motion loops;
+- constraints, parenting, and control objects involved.
+
+One clear primary action, restrained secondaries, and at least one stable
+frame suitable for inspection and thumbnails.
+
+## Build animation
+
+- Bulk transform/lens keys → `bl_keyframe_properties`; turntable, camera
+  orbit/dolly, idle → `bl_create_motion_preset`; frame inspection →
+  `bl_set_frame`.
+- Drop to `bl_execute` only for what typed tools cannot express: F-curve
+  edits, constraints, drivers, armatures, shape keys, simulations, NLA.
+- Key rigs and semantic controls, not a pile of unrelated child transforms.
+  Key only properties that need to change.
+- Choose interpolation on purpose: Bezier for organic motion, linear for
+  constant rates, constant for stepped switches.
+- Pick quaternion or Euler deliberately so rotations do not flip mid-move;
+  connector boundaries speak radians.
+- Object animation and data animation are separate sets. Lens, `clip_start`,
+  and `dof.focus_distance` keys belong to `camera.data`. Follow Path
+  `offset_factor` belongs to the constraint and is animated on its owning
+  object, through `constraints[...].offset_factor`. Retime both object and
+  data actions, filtering their correct action slots (`blender-volatile`),
+  then check each shot's transform, path, lens, and focus key ranges.
+- Simulations must be deterministic enough that the audited frames reproduce.
+
+## Constraints and drivers
+
+- **`Copy Location` on a spinning child is forbidden.** Any residual offset
+  between target and owner orbits with the spin, and the part reads as about
+  to detach. Only rotation can be compensated.
+- Copy the steering component alone, in the control object's space
+  (CUSTOM to CUSTOM, single axis, mix AFTER). Copying full world rotation
+  drags support noise into the tilt.
+- The local space of a bone-parented child is useless: its own rotation is
+  static and the motion lives in the bone. Name the control object explicitly.
+- **Rolling contact is verified arithmetically.** Rotation per frame equals
+  distance per frame divided by radius, and the residual stays sub-millimetre.
+  The driver's sign follows the direction of the part's local axis; the
+  contact point holding still is the proof.
+- Ray-based ground tracking over a faceted support mesh returns noise, not
+  travel. Disable it and solve the surface response deliberately.
+
+## Surface contact solve
+
+For anything that must stay planted on uneven ground while it moves:
+
+1. One ray per support point gives the gaps.
+2. The mean gap is the height correction.
+3. Compute the slope angle with `atan2(height_difference, support_distance)`.
+   Use the full horizontal distance between the two compared support points,
+   not the half-span. For points at `-a` and `+a`, the denominator is `2*a`.
+   Resolve the sign and roll/pitch axis in the rig's local frame and check
+   the resulting contact gaps; banked or uneven supports may need a fitted
+   support plane rather than two independent slopes.
+4. Two passes per frame for convergence.
+5. Ease in and out over roughly 20 frames with a quintic so no correction
+   pops on entry.
+
+A baked contact holds height but does not pick up lateral slope: it passes on
+straights and drifts on arcs. Level ground under a tilted body means the body
+is wrong, not the ground.
+
+## Rotational aliasing
+
+An N-fold symmetric spinner strobes when its step per frame lands near a
+multiple of its symmetry sector — the blades nearly fill the previous
+positions and the eye reads a jerk or a reversal. Hold a constant step half a
+sector away from any multiple of the sector, then re-phase after the shot so
+the rotation stays continuous.
+
+Blur decides that read more than the keys do. A shutter near 0.2 at one step
+is no smear at all; 0.75 over 12 steps is the working baseline, raised toward
+0.95 by key for the fastest passage. The viewport never renders blur — spin
+and smear are judged from a render only.
+
+## Visibility keying
+
+- Visibility switches are keyed with constant interpolation.
+- **Constraint targets hide in render only.** `hide_viewport` drops an object
+  from the depsgraph, and every constraint reading it gets a stale matrix.
+- Everything else hides in render and viewport together. A render-only hide
+  leaves the viewport lying about framing: geometry sitting millimetres in
+  front of a lens still blocks the preview.
+- Props belong to the shots that need them, not to every range sharing a
+  state.
+- `animation_data_clear()` removes visibility keys along with everything else.
+
+## Dynamic defaults
+
+When the brief names no motion:
+
+- product/prop — slow turntable or camera orbit, settling on the hero angle;
+- environment — subtle camera drift plus a restrained practical-light change;
+- character/creature — idle breathing or weight shift, only if the rig
+  supports it;
+- abstract — one focal transformation with a small secondary response.
+
+Never invent character acting, destructive simulation, or a camera that never
+stops when subtle motion already satisfies the dynamic requirement.
+
+## Motion audit
+
+Sample at minimum: first/rest frame, departure, peak of the fastest change,
+settle, final frame plus the loop seam where one exists. Inspect animated
+properties through `bl_get_object` and `bl_execute`, and view camera renders
+at selected frames using `bl_set_frame` and `bl_render`. This replaces the
+unavailable `bl_audit_motion` and `bl_render_contact_sheet` tools. At each
+sample check framing, collisions
+and intersections, visibility, constraint behavior, shading continuity, and
+motion direction. Open F-curves only when the typed audit cannot explain a
+failure — a still render proves nothing about animation.
+
+The pass fails if expected properties carry no keys, motion is imperceptible,
+objects teleport, rotations flip, the camera loses the subject, or the loop
+jumps. Fix and sample again.