Contributing

Contributing

The repository layout, how to build and run the app from source on macOS and Windows, the checks to run and the repo rules.

Bug reports, fixes and features are welcome. For anything bigger than a fix, open an issue first so you can agree on the approach before you write the code. The full guide is CONTRIBUTING.md.

License of contributions

Satura Space is licensed under Apache-2.0. By opening a pull request you agree that your contribution is licensed under the same terms (inbound = outbound, as section 5 of the license says). There's no CLA and no sign-off line to add.

Layout

PathWhat
apps/orchestratorThe desktop app (Electron, React). Launches, streams and drives Unity editors.
packages/saturaspace-engineUnity package the app injects into each project: the stream server, the editor bridge, C# hot reload.
packages/saturaspace-sdkUnity package for game code: SaturaHandle, SaturaLog, staging prefabs.
packages/mcpPython MCP server. Agents use its one tool, satura_exec, to drive Unity and the app.
packages/companion-appSatura Remote, the phone companion: the relay and the phone web app it serves.
tools/Build helpers for the vendored engine libraries.

Build and run from source

You need:

  • macOS on Apple Silicon, or Windows 10/11 x64
  • Unity 6 (6000.0 or newer) and Unity Hub, signed in
  • Node 24 and pnpm 10 (corepack [email protected] works without a global install)
  • Python 3.12 or newer for the MCP server
  • On macOS, the Xcode Command Line Tools; on Windows, Visual Studio with the C++ toolset. The install rebuilds node-pty for Electron and builds the app's shared-surface addon.

Windows: native helpers first

On Windows, build the two native helpers once before installing, from a PowerShell prompt at the repo root:

apps/orchestrator/resources/winhook/build-win.ps1
packages/saturaspace-engine/.native/sharedsurface/build-win.ps1

macOS uses the committed winhook.dylib and SaturaSharedSurface.bundle. If you change their sources, rebuild them with the build.sh next to each.

Install and run

On both platforms:

cd apps/orchestrator
corepack [email protected] install
corepack [email protected] dev

A plain pnpm must be 10.x in apps/orchestrator too.

The MCP server's Python environment

The dev app runs the MCP server from source, so set up its Python environment once: run packages/mcp/run.sh on macOS, or on Windows run python -m venv .venv and pip install -r requirements.txt in packages/mcp.

Packaging and signing are in apps/orchestrator/PACKAGING.md. Local packs build unsigned, and contributors don't need any signing setup.

A test project and a dev instance

Check changes on a dev instance, a second copy of the dev app with its own settings, ports and Unity project, and drive it with app handles instead of clicking around.

For the test project, make a copy of any Unity 6 project that uses the Input System (Active Input Handling set to Input System Package, not Both), or create an empty one from Unity Hub. Point SATURA_TEST_PROJECT at it; handles that write files only run on that project. Then:

cd apps/orchestrator
export SATURA_TEST_PROJECT=~/projects/my-test-project
corepack [email protected] dev:instance alt
node scripts/satura.mjs --instance alt handle unity.ready

Call unity.ready first and read value and logs after every call. If a handle you need is missing, add one in src/main/handles or src/renderer/src/handles. Handles inside a game are in the engine's handles guide.

Checks

There are no automated test suites. A change is checked on a dev instance through handles. Pull requests run CI: the app's typecheck, a byte-compile of the MCP server and a syntax check of the relay. Run them locally first:

cd apps/orchestrator
corepack [email protected] typecheck
node scripts/engine-check.mjs --project "$SATURA_TEST_PROJECT"
cd packages/mcp
python -m compileall -q server.py unity_mcp
cd packages/companion-app/relay
for f in src/*.mjs scripts/*.mjs; do node --check "$f"; done

engine-check.mjs compiles the engine and SDK C# against a project that has imported the engine once. Building the phone app the relay serves is in packages/companion-app/README.md.

Repo rules

  • No code comments, in any language. Put the reasoning in the pull request or the commit message.
  • No formatter. The source isn't prettier-formatted; match the style around your change.
  • Commits are one short type(scope): summary line with no body, like fix(engine): bind the stream input socket to loopback. One feature is one to three commits.
  • Prove it with handles and logs. Show that a change works with handle output or log lines from a dev instance; keep screenshots for visual changes. Don't add test files or test frameworks.
  • The editor runs the engine and MCP it launched with. After changing packages/saturaspace-engine or packages/mcp, restart the dev app and reopen the project.
  • Leave versions alone. The app, the engine and the SDK share one version, bumped together when a release is cut.