Starflag Protocol

It's OSC. Messages are sent by clients to the engine. Each message is replied to over the same socket as an OSC message or bundle.

Public information

• /world

  • /world/size i
  • The response to /team/*

• /game/join sss (name, team name, password)

  • /game/welcome ii (team id, agent id) or /game/full/{team,game}

  Will be allocated an appropriate agent id and told the appropriate team id. First agent joining from a team name will be allocated an available team id.

• /team/*

  • /team/id rsi (color, name, size)
  • /team/id/base fffi (position, size)
  • The response to /team/id/flag

Protected information

Authorization is determined by originating socket, for agent percepts and actions, or by hash for /game/state.

• /team/*/flag

  • /team/id/flag/position fff (vector)

• /agent/*/*/perceive

  For each agent within range, including itself:

  • /agent/team/id/position fff (vector)
  • /agent/team/id/orientation fffffffff (3x3 row-major order rotational matrix)

  To a UI, everybody is in range, and the following information is also provided:

  • /agent/team/id/momentum fff (vector)
  • /agent/team/id/angular_momentum fff (vector)
  • /agent/team/id/thrust ffff (current thrust values: pitch, roll, yaw, main drive)

• /agent/*/*/thrust ffff (strength for each thruster: pitch, roll, yaw, main drive. Ranges from -1 to 1, except main drive which ranges from 0 to 1)

• /agent/*/*/fire

  • maybe /agent/team/id/reloading in which case no shot was fired

• /agent/*/*/magnet f [0..1]

Read this paper for descriptions of the state variables returned in response to /agent/*/*/perceive. In summary, the state variables here map to the state variables from the article as:

• position: x(t)
• orientation: R(t)
• momentum: P(t)
• angular_momentum: L(t)

For UIs

In addition to the public messages, UIs can get the entire changing game state with this message.

• /game/state s (hash)

  • The response to /agent/*/*/perceive
  • The response to /team/*/flag

  or

  • /unauthorized s "/game/state"

  The hash is a SHA1 hash of the timestamp followed by the pre-shared key. This is to allow UIs to see the entire world state while preventing agents from doing so.

Generic Messages

• /game/over is (winning team, winning team's name)

• /ack

  Always sent in reply by the engine except on error; probably accompanied by other replies.

• /error ss (error string, pattern)

• /unauthorized s (pattern)

  Sent when not authorized to access that pattern.