Opening in Unity

Add a cart to a Unity project

The download button on a cart. Needs a Unity project (6.3 or newer) with OneJS installed from the Package Manager: https://github.com/Singtaa/OneJS.git

At the project's root, where Assets and ProjectSettings are:

npx ojplay add @<handle>/<name>

That is the line under the download button. It puts the cart in its own folder at the project's root, beside Assets, installs it, and puts a runner for it in a scene: your first build scene, or a new Assets/Scenes/Main.unity. Open that scene and press Play. OneJS builds the cart when the project opens, and again each time you save.

With the project open in Unity, it leaves your scenes alone and says which prefab to drag in.

Your own cart Lands as a git clone, or a submodule in a project that is a git repository. Edit, save, git push: the site builds it
Somebody else's Lands as the build they published. To change it, fork it on the site and add yours
A piece of an app you have Run the line in that app's ~ folder instead. oj.json lists the cart, and import { Bolt } from "@<handle>/<name>" works; its art ships with your build

Your cart file does not change.

What it writes

<Name>/ The cart, beside Assets. What ojplay init adds there (package.json, tsconfig.json, types) is kept out of git, so git status shows only your cart
Assets/<Name>/<Name>.prefab A JSRunner that runs the cart, linked by the name in its oj.json: the thing placed in the scene
Assets/<Name>/PanelSettings.asset The runner's panel settings
Assets/Scenes/Main.unity Only when the build list has no scene, and then added to it

Unity writes nothing inside the cart. It builds the cart into Library/, and a player build ships the cart's files under StreamingAssets.

By hand, the same thing: git clone https://play.onejs.com/@<handle>/<name>.git at the project's root (or git submodule add in a project that is a git repository), then add a JSRunner, pick the cart from the Cart dropdown in its inspector, and press Set Up. Running a Root Cart on onejs.com has the rest.

Carts in Assets/<Name>/~

A OneJS older than 3.9.9 cannot run a cart from the project's root, so there ojplay add puts it in Assets/<Name>/~, inside a OneJS app with OneJS's own build files around it. It keeps working there.

On OneJS 3.9.11 or newer, that app's runner offers Move to Project Root in its inspector. It moves the cart to <Name>/ beside Assets (with git mv when git tracks it), links the runner to the cart by name, deletes the app's built bundle, and takes out the files OneJS's setup put in the cart. A file somebody changed is left, and listed in the Console. The PanelSettings and the prefab stay. A runner in a scene that is not open still points at the app: pick the cart in its Cart field.

Input

input needs the Input System package, with Active Input Handling set to Input System or Both. New Unity 6 projects have it. Without it: one warning, and input stays idle.

Positions from Input System actions are in screen space. input.mouse and input.touches are converted for you.

What changes

In Unity
assetUrl The cart's own folder, or StreamingAssets in a build
mount() Starts its own runtime
A .sl shader Becomes a real shader, compiled by Unity
The control theme Comes with you
show() Logs a line when its value changes, at most once a second, and draws nothing

What you gain: your own C#, all of Unity, scenes, 3D, every build target, no sandbox.

From your own machine

Every cart is a git repository, and the editor is one client of it. A new cart can start on your machine instead of the site: ojplay new "<name>" writes the starter into a new repository with no account, and its first ojplay push makes the cart on the site, public, logging you in first if you are not. A name you already use is refused at that push, and nothing is made; rename it in oj.json, commit and push again.

A cart already on the site clones with its address plus .git, with no login. Pushing to your own needs npx ojplay login once per machine.

git clone https://play.onejs.com/@<handle>/<name>.git
cd <name>
ojplay init             # package.json, tsconfig.json and types, all gitignored
npm install
ojplay run              # the cart in the site's real container, in a local Chrome
git push origin main  # builds on the site, and becomes what everyone plays

A push to main builds the commit on the site and, if it builds, makes it what everyone plays. The result comes back on the remote: lines, with the file, line and column of any compile error. The push lands either way, so the last commit that built keeps running until the next one that does.

ojplay is a command you install once, npm install -g ojplay (or prefix each command with npx, which needs no install). It wraps the rest: new, add, build, typecheck, run, test, status, push and runtime, and ojplay help describes each one. Inside a cart that has its own ojplay in node_modules, it runs that one. An AI agent handed a cart should start at agents.md, which the first lines of a new cart's index.tsx point at.

A cart's own Node programs (a server, a tool that makes its files) go in server/ or tools/: ojplay init's tsconfig.json leaves those two folders out, since Node's globals are not a cart's, and each keeps a tsconfig of its own.

The editor keeps your typing as a draft only you see, and its Push commits on top of whatever main holds by then, so a git push in between is kept: Push lists what came in, and asks which version to keep of any file both changed. Git refuses a push that is not a fast forward, so whoever is second finds out rather than winning. The site does accept a force push, and it replaces what was pushed from the editor, so pull instead.