OneJS AGENTS.md

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, .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.

Alternative: skip the button and just enter Play mode. On first play, JSRunnerAutoWatch auto-creates and assigns PanelSettings, scaffolds missing files, runs npm install + npm run build in the background, and starts the watcher. The first run takes a moment while packages install.