# 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](http://www.cs.cmu.edu/~baraff/sigcourse/notesd1.pdf) 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.