Addressing

Address segments are categories. Arguments are instances.

This is the rule that matters most, so it comes first.

/wall/hold/touch   i f f   holdId velocity timestamp     ✓
/wall/hold/12/touch    f f   velocity timestamp          ✗

The first form needs one OSCdef. It handles every hold on any size of wall, it logs in one place, and changing how a touch is handled is a single edit. A bigger wall requires no code change at all.

The second form needs wildcard pattern matching in the responder, or 120 separate responders. Logging means matching on a pattern. The hold number arrives as a string fragment of an address, so it has to be parsed back into an integer, and every consumer has to agree on how. It is more fragile in every direction, and it buys nothing.

Use address segments for things that have genuinely different shapes — /wall/hold/touch and /wall/hold/release carry different arguments and mean different things. Use arguments for things that differ only by which instance they refer to.

Naming

• Lowercase segments, a–z and digits. No spaces, no punctuation beyond /.
• Hierarchical, general to specific: /wall/hold/touch, not /touch/hold/wall.
• The first segment is the group, and it is meaningful: sys, wall, audio, mode. A message’s group decides which file it lives in and which colour it gets on this site — the validator fails the build if an address and its file disagree.
• No OSC pattern-matching characters in a published address: no *, ?, [], {}. They are legal OSC, and they will silently match things you did not intend.
• Argument names are lowerCamelCase. They become variable names in the generated SuperCollider and engine code, so they have to be identifiers.

Mode addresses

Anything a specific mode owns lives under /mode/<modeId>/:

/mode/chase/hit
/mode/synth/notes
/mode/arcade/objective/progress

Anything that applies to every mode lives under /mode/ directly, and is part of the shared lifecycle:

/mode/load  /mode/start  /mode/stop  /mode/param

Adding a mode therefore adds no lifecycle plumbing on either side. The SuperCollider dispatcher already knows how to load, start, stop and tweak it.

Addresses are permanent

Once an address has been published in a tagged version, it is never repurposed and never given different arguments. If it was wrong, it gets deprecated:

- address: /mode/synth/note
  deprecated: true
  deprecatedSince: "0.4.0"
  replacedBy: /mode/synth/notes

It stays in the schema. This site renders it with a deprecation banner, and the generated SuperCollider keeps a no-op responder on it so that an engine build from three weeks ago cannot crash the sound system in front of an audience.

Removing it entirely is a major version bump, and worth doing only when you know nothing is still sending it.