AI Agent Setup#

Quick Start assumes a person clicking in the Unity editor. This page is the same journey with no clicks: create the project, install the package, scaffold the app, build it, and check that it rendered. Every step is a terminal command or a file write.

If you are an agent reading this, the whole recipe is on this page. You do not need to clone the OneJS repository to find it.

Requirements#

• Unity 6.3 or newer
• Node.js 18 or newer, with npm on PATH

1. Create the Unity project#

Unity ships a CLI that creates projects non-interactively. It needs a template, so pick one first:

unity templates list -e 6000.3.10f1

Then create the project:

unity projects new Foobar \
  --path ~/Projects \
  --editor-version 6000.3.10f1 \
  --template com.unity.template.urp-blank \
  --non-interactive

unity editors -i --format json lists the editor versions on the machine, and unity install 6000.3.10f1 adds one.

Prefer a template over a bare project. A template brings the Input System and uGUI, which OneJS's runtime assembly references. A project created with the editor's own -createProject flag has neither, and you will spend the next few minutes picking versions by hand.

2. Install OneJS#

Add one line to Packages/manifest.json:

}

If an agent is going to keep working in this project, add the MCP server in the same edit:

}

It is editor-only and ships nothing into a build. It is what lets an agent run C#, enter Play mode, read the console and screenshot the Game view, which are the parts of this page that a terminal cannot reach. Setting it up is at the bottom.

Use the OneJS URL with no branch or tag suffix. The default branch is the release branch. The repository also carries frozen historical branches (onejs-v1, onejs-v2, archive/onejs-v3). Pinning one of those installs an old runtime that still compiles, so nothing tells you it happened.

Let the editor resolve and compile once:

unity run ~/Projects/Foobar -- -nographics

unity run supplies -batchmode and -quit itself, so pass only your own flags after the --.

3. Scaffold the app#

The inspector's Initialize Project button calls three public methods on JSRunner. An editor script can call the same three. Write this to Assets/Editor/OneJSHeadlessSetup.cs:

using System.IO;
using OneJS;
using UnityEditor;
using UnityEditor.SceneManagement;
using UnityEngine;

public static class OneJSHeadlessSetup {
    const string ScenePath = "Assets/Scenes/Main.unity";

    public static void Run() {
        Directory.CreateDirectory("Assets/Scenes");

        // JSRunner puts the app next to the scene, so the scene has to be on
        // disk before Initialize runs.
        var scene = EditorSceneManager.NewScene(NewSceneSetup.DefaultGameObjects, NewSceneMode.Single);
        EditorSceneManager.SaveScene(scene, ScenePath);

        var runner = new GameObject("App").AddComponent<JSRunner>();

        runner.PopulateDefaultFiles();
        runner.EnsureProjectFolderAndAssets(true);
        runner.EnsureProjectSetup();

        EditorUtility.SetDirty(runner);
        EditorSceneManager.SaveScene(scene, ScenePath);
        AssetDatabase.SaveAssets();

        Debug.Log($"[Setup] working dir: {runner.WorkingDirFullPath}");
        if (runner.PanelSettingsAsset == null) {
            Debug.LogError("[Setup] PanelSettings was not created.");
            EditorApplication.Exit(1);
        }
    }
}

Run it:

unity run ~/Projects/Foobar -- -nographics -executeMethod OneJSHeadlessSetup.Run

That writes the app next to the scene, named after the GameObject:

Assets/Scenes/Main/App/
├── ~/                    # TypeScript source
│   ├── index.tsx
│   ├── package.json, tsconfig.json, esbuild.config.mjs
│   └── AGENTS.md         # per-app notes, written by the scaffold
├── PanelSettings.asset   # the project marker
└── app.js.txt            # the built bundle, after step 4

Scaffolding never overwrites a file that already exists, so running it twice is safe. Delete the setup script afterwards if you do not want it in the project.

4. Install dependencies and build#

The editor does this for you when a person clicks the button. Headless, run it yourself, in the ~/ folder:

cd ~/Projects/Foobar/Assets/Scenes/Main/App/~
npm install
npm run build

npm run build writes ../app.js.txt. npm run watch is the hot reload loop, and the editor starts one itself while a project is open.

5. Verify#

Check the artifact, not the log:

test -s ~/Projects/Foobar/Assets/Scenes/Main/App/app.js.txt && echo "bundle ok"

A bundle on disk next to a PanelSettings.asset, with a JSRunner in the saved scene, is a project that will render. To watch it actually render, open the editor and enter Play mode, or drive both from the MCP server below.

Driving the editor: the Unity MCP server#

Steps 1, 2 and 4 need no editor. Step 3 and anything visual do. Unity MCP Server gives an agent tools for a live editor: run C#, enter and leave Play mode, read the console, capture the Game view.

Install it the same way, alongside OneJS:

"com.singtaa.unity-mcp": "https://github.com/Singtaa/UnityMCP.git"

Open the project in the editor once. The package starts the server and deploys a launcher to ~/.unity-mcp/stdio.js. Then register that launcher with your harness:

claude mcp add --scope user --transport stdio unity -- node ~/.unity-mcp/stdio.js

One registration covers every project on the machine. Each editor writes a beacon, and the launcher routes to whichever project the session is working in.

With the MCP connected, step 3 needs no editor script: unity_eval runs the same three calls directly, and the last two steps become observable.

Two things that cost agents time. unity open does not return while the editor runs, so start it in the background rather than waiting on it. And an unfocused, idle editor starves the MCP dispatcher, so a tool call can time out while the editor is perfectly healthy.

Where the rest of the documentation is#

• /llms.txt: this site's page index
• /llms-full.txt: every documentation page concatenated as plain markdown, for one-shot ingestion
• OneJS ships an AI skill inside the package at AI/Skills/onejs-setup-and-overview/, and Tools > OneJS > Install AI Skills copies it into .claude/skills/
• The scaffold writes an AGENTS.md into each app's ~/ folder