System

Handshake, liveness, recovery and the emergency stop. Everything here exists so that either side can be restarted mid-session without restarting the other.

Messages

/sys/hello/sys/ready/sys/ping/sys/pong/sys/sync/sys/panic/sys/assets

/sys/hello

engine → sc event since 0.1.0

The engine announces itself and asks SuperCollider to identify.

s engineName

s protocolVersion

ss

engineName s string: Free-form build identifier, e.g. "wall-game 2026.3.1-dev".
protocolVersion s string: The protocol semver the engine was built against, e.g. "0.2.0". Compared against SuperCollider's; a mismatch is logged loudly on both sides.

Acknowledged by /sys/ready.

packet /sys/hello wall-game 2026.3.1-dev 0.2.0

SuperCollider NetAddr("127.0.0.1", 57120).sendMsg('/sys/hello', "wall-game 2026.3.1-dev", "0.2.0");

engine (C#) osc.Send(Osc.SysHello, "wall-game 2026.3.1-dev", "0.2.0");

Safe to send repeatedly. The engine should send it every few seconds until a /sys/ready arrives, so that starting the two programs in either order converges on the same state.

/sys/ready

sc → engine event since 0.1.0

SuperCollider is booted, SynthDefs are loaded, and it can accept a mode.

s protocolVersion

s scVersion

ss

protocolVersion s string: The protocol semver SuperCollider was generated against.
scVersion s string: SuperCollider's own version string, for the log.

packet /sys/ready 0.2.0 3.13.0

SuperCollider ~osc[\sysReady].value("0.2.0", "3.13.0");

engine (C#) // handler for Osc.SysReady

Sent in reply to /sys/hello, and unprompted once on boot in case the engine was already running and has stopped saying hello.

/sys/ping

engine → sc event since 0.1.0

Liveness probe.

i seq

i

seq i int32: Sequence number, echoed back in /sys/pong. Wraps at 2^31.

Acknowledged by /sys/pong.

packet /sys/ping 481

SuperCollider NetAddr("127.0.0.1", 57120).sendMsg('/sys/ping', 481);

engine (C#) osc.Send(Osc.SysPing, 481);

Once a second is plenty. Two missed pongs means SuperCollider is gone or wedged — surface that in the engine's operator UI rather than failing silently.

/sys/pong

sc → engine event since 0.1.0

Liveness reply, carrying SuperCollider's current load.

i seq

f cpu

if

seq i int32: The seq from the /sys/ping being answered.
cpu f float32 0.0 – 1.0normalized: scsynth's average CPU load, 1.0 meaning the audio thread is at its limit. Above ~0.8 expect dropouts.

packet /sys/pong 481 0.34

SuperCollider ~osc[\sysPong].value(481, 0.34);

engine (C#) // handler for Osc.SysPong

/sys/sync

sc → engine event since 0.1.0

SuperCollider asks the engine to re-send all current state.

/sys/sync takes no arguments.

packet /sys/sync

SuperCollider ~osc[\sysSync].value();

engine (C#) // handler for Osc.SysSync

Sent by SuperCollider after a restart. The engine responds by re-sending every message marked `rate: state` — wall config, asset root, mix levels, loaded samples, the current mode and its parameters — which is exactly what makes a SuperCollider restart recoverable without restarting the game.

This is the reason `rate: state` exists as a category. If you add a message that carries state and forget to mark it `state`, it will be the one thing that is wrong after every restart.

The engine may also push that same set unprompted at any time; no separate message is needed for it.

/sys/panic

engine → sc event since 0.1.0

Kill all sound immediately. No fade, no release.

/sys/panic takes no arguments.

packet /sys/panic

SuperCollider NetAddr("127.0.0.1", 57120).sendMsg('/sys/panic');

engine (C#) osc.Send(Osc.SysPanic);

Frees every running node on the server and unloads the current mode. After a panic the engine must /mode/load again from scratch. Wire this to a physical button during installation — you will want it.

/sys/assets

engine → sc state since 0.2.0

Where the sample files live.

s root

s

root s string: Absolute path to the asset directory, as SuperCollider will see it. Every path in /sample/load is relative to this. A trailing slash is optional.

packet /sys/assets /Users/wall/ClimbingWall/assets

SuperCollider NetAddr("127.0.0.1", 57120).sendMsg('/sys/assets', "/Users/wall/ClimbingWall/assets");

engine (C#) osc.Send(Osc.SysAssets, "/Users/wall/ClimbingWall/assets");

Both programs must be able to read this directory — the same machine, or a shared mount. Uploaded recordings from the teacher app land here; the engine is responsible for putting them there before asking SuperCollider to load them.