OneJS: Instructions file for Codex

OneJS v3: Agent Guide

Before adding anything that crosses between C# and JavaScript, read DESIGN.md. It states what belongs on each side, the four rules a wrapper has to satisfy, and why an interpreter on native makes it a portability question rather than a performance one.

Condensed facts for AI agents working with OneJS. Full documentation: https://onejs.com/docs

OneJS runs React 19 + TypeScript UIs inside Unity. TSX compiles with esbuild into a single bundle that the JSRunner component executes through QuickJS (or the browser's own JS engine on WebGL), rendering through UI Toolkit. No webview, no DOM.

Requirements

• Unity 6000.3+ (Unity 6.3)
• Node.js 18+ on the dev machine

Install

Package Manager: + > Add package from git URL:

https://github.com/Singtaa/OneJS.git

Or clone into Assets: git clone https://github.com/Singtaa/OneJS.git. Package id: com.singtaa.onejs. No other Unity packages or scoped registries required.

Project setup

1. Add the JSRunner component to a GameObject in a saved scene.
2. Click Initialize Project in its inspector. This creates, next to the scene:

{SceneDir}/{SceneName}/{GameObjectName}/
├── ~/                      # TS/TSX source (the ~ suffix keeps Unity from importing it)
│   ├── index.tsx           # entry point
│   ├── package.json, tsconfig.json, esbuild.config.mjs
│   └── styles/main.uss, types/global.d.ts, AGENTS.md, CLAUDE.md, .gitignore
├── PanelSettings.asset     # project marker: the one mandatory JSRunner field
├── UIDocument.uxml
├── app.js.txt              # built bundle (esbuild writes ../app.js.txt)
└── app.js.map.txt

then runs npm install and npm run build automatically.

Key model:

• Panel Settings is the project marker. The folder containing the assigned PanelSettings asset defines the project; the bundle is always loaded from {that folder}/app.js.txt. A folder is considered valid when it contains ~/ or app.js.txt.
• Or a root cart. A runner with Cart set runs a play.onejs.com cart from a folder at the project root (<root>/*/oj.json), linked by its oj.json name; its PanelSettings is then only panel settings, its editor bundle is Library/OneJS/Carts/{folder}/app.js.txt, and Unity writes nothing inside the cart. See the setup skill's root cart workflow.
• Do not add a UIDocument. JSRunner adds and wires one at runtime (and an EventSystem if missing). On Unity 6.5+, do not substitute the new PanelRenderer either: it never attaches a panel outside Play mode, so edit-mode preview would render nothing.
• Edit-mode preview: JSRunner renders the UI in the Game view without Play mode whenever Panel Settings is valid and app.js.txt exists, ticking at 30 Hz. The Scene view's OneJS overlay decides which previews tick: in the default Auto mode only the selected runner (with nothing selected, the one nearest the Scene view camera), so an unselected runner's timers freeze while its hot reload keeps working. Play Mode is never gated: every runner ticks every frame, as in a player build.
• Scaffolding never overwrites existing files, and writes each default file once: ~/.onejs/scaffold records what the app was given, so a deleted file stays deleted until Restore in the Build tab brings it back.
• ~/.onejs/ holds small per-app OneJS state the project commits, never caches or machine-local files.