中文 · DotCraft · ACP · License

Use DotCraft inside the Unity Editor.

About

dotcraft-unity is the Unity editor client for DotCraft. It connects Unity projects to DotCraft via the Agent Client Protocol (ACP) and provides an in-editor chat window.Besides DotCraft, it also supports any Agent that implements the ACP protocol, such as Claude Code, Cursor, and Codex.

• Editor native: open DotCraft from Tools → DotCraft Assistant without leaving Unity.
• Project aware: the Unity project root becomes the DotCraft workspace by default.
• ACP based: DotCraft runs as the agent process while Unity acts as the editor client.
• App Binding: expose enabled Unity tools to any bound DotCraft thread while the Unity Editor is running.
• Unity context: built-in read-only tools expose scene, selection, console, and project information.

Get Started

1. Install and configure DotCraft.

2. Open Window → Package Manager and add this Git URL:

   https://github.com/DotHarness/dotcraft-unity.git
   

   Unity resolves the official com.unity.nuget.newtonsoft-json dependency automatically.

3. Open Tools → DotCraft Assistant.

4. Click Connect, then start a conversation from the Unity Editor.

Minimum Unity version: 2022.3, recommended version: Unity 6.

Configuration

Open Edit → Project Settings → DotCraft to configure the client.

Setting	Default	Description
Agent Connection	DotCraft	DotCraft uses Hub-aware startup; Custom ACP keeps raw command/arguments for other ACP agents.
DotCraft Command	dotcraft	DotCraft executable name or full path. Used to start Hub and the ACP bridge.
DotCraft AppServer	Local via Hub	Local via Hub asks Hub for the workspace AppServer, then starts dotcraft -acp --remote ...; Remote AppServer uses a manual WebSocket URL.
Command / Arguments	dotcraft / -acp	Shown only for Custom ACP; starts the configured ACP process directly.
Workspace Path	empty	Working directory. Defaults to the Unity project root.
Environment Variables	empty	Key-value pairs passed to the DotCraft process.
Auto Reconnect	true	Reconnect after Unity Domain Reload.
Verbose Logging	false	Print DotCraft stderr to the Unity Console.
Show Thinking Content	false	Show agent reasoning text in expandable chat rows. When disabled, only lightweight thinking status is shown.
Enable Builtin Unity Tools	true	Declare the built-in read-only Unity runtime tools and enable their _unity/* handlers when using the DotCraft connection profile.
Plugin Tools	disabled	Attribute-discovered plugin runtime tools. Each tool must be enabled explicitly in Unity Tools → Plugin Tools (DotCraft only).
Enable Local Server	true	Start the localhost App Binding handoff server on port 39777 while Unity Editor is open.

For API keys, prefer environment variables in Project Settings instead of committing secrets to project files.

Built-in Tools

dotcraft-unity declares four read-only Unity runtime tools to DotCraft during ACP initialization:

Tool	Description
unity_scene_query	Query scene hierarchy with optional component details.
unity_get_selection	Read the current Unity Editor selection.
unity_get_console_logs	Retrieve recent Unity Console log entries.
unity_get_project_info	Read Unity version, project name, and package information.

These tools help DotCraft understand the current scene and project state. The model-visible tool descriptors live in this Unity client; the _unity/* ACP methods are private callbacks used to execute them. For full Unity editing automation, combine DotCraft with a dedicated Unity tool package such as SkillsForUnity or unity-mcp.

App Binding

When the DotCraft dotcraft-unity plugin is installed, DotCraft Desktop can connect to a running Unity Editor through App Binding. The Unity package listens on http://127.0.0.1:39777/dotcraft/, accepts DotCraft connect/bind handoffs, and attaches the currently enabled runtime tools to the selected DotCraft thread.

This path is independent of the ACP chat window: agents in Desktop, TUI, automations, or other AppServer clients can use the bound Unity tools as long as Unity Editor stays open. If Unity closes or scripts reload, the binding becomes offline until you bind again.

Plugin Runtime Tools

Other Unity Editor plugins can expose DotCraft-only runtime tools by marking static methods with AgentToolAttribute. New plugin tools are discovered in Edit → Project Settings → DotCraft → Unity Tools, default to disabled, and are injected only for the DotCraft connection profile.

using System.ComponentModel;
using DotCraft.Editor.Protocol;
using DotCraft.Editor.RuntimeTools;

public static class ExampleDotCraftTools
{
    [Description("Return a greeting from an example Unity plugin.")]
    [AgentTool(Namespace = "example", Name = "example_greet", Kind = AcpToolKind.Read)]
    public static object Greet([Description("Name to greet.")] string name = "Unity")
    {
        return new { message = $"Hello, {name}." };
    }
}

Method parameters are converted to a JSON Schema with Newtonsoft.Json naming rules. See Documentation~/dynamic-tools.md for the full registration contract.

Troubleshooting

Symptom	Likely Cause	Fix
Failed to start DotCraft process	dotcraft is not on PATH	Install DotCraft and add it to PATH, or set a full path in Command.
Stuck at Connecting...	DotCraft failed during startup	Enable Verbose Logging and check the Unity Console.
Disconnects after script compilation	Auto reconnect is disabled	Enable Auto Reconnect in Project Settings.
Tools are unavailable	Runtime tool descriptors were not declared or accepted	Enable Builtin Unity Tools and use a DotCraft version that supports runtime dynamic tools over ACP.

Contributing

Contributions are welcome in DotHarness/dotcraft-unity. For the agent harness itself, use DotHarness/dotcraft.

Reference

DotCraft

Agent Client Protocol

License

Apache License 2.0