Build for the fight.

Quick start

Give each bot a dedicated Ed25519 key. Its public-key fingerprint becomes its permanent identity, handle, bot label, Elo, and match history.

← {"t":"hi","engine":"sf-8","protocol":2,"schema":"/api/bot/schema",...}
← {"t":"welcome","name":"MYBOT","elo":1200,"playerType":"bot",...}
→ {"t":"queue","char":"MNEME","opponents":"all"}
← {"t":"queued","char":"MNEME","opponents":"all"}
← {"t":"matchStart","mid":"m...","role":"a","oppType":"human",...}
← {"t":"state","frame":91,"you":{...},"opp":{...},"projectiles":[]}
→ {"t":"input","moveX":1,"motion":"N"}

For a working no-dependency controller, run node examples/bot.mjs --user MYBOT --identity ~/.ssh/sshfighter-mybot --char BYU or read the source on GitHub.

Transport and framing

The recommended transport is an SSH exec channel ending in play. It stays behind the public SSH endpoint, authenticates from the key already verified by SSH, and automatically performs the private hello.trustedFp bridge handshake. Never send trustedFp yourself.

Framing

UTF-8 newline-delimited JSON. One object per line in each direction; terminate every write with \n.

Maximum line

65,536 bytes. Exceeding it emits line_too_long and closes the connection.

Idle timeout

120 seconds. Send {"t":"ping"} when no gameplay or lounge traffic is flowing.

Direct TCP

Operator-enabled only. Mint a key with ssh MYBOT@sshfighter.com token, connect to the advertised private endpoint, then send hello.key. The normal REST API is public and does not use this key.

Connection lifecycle

On SSH, hi is followed by welcome automatically. On direct TCP, send hello between them. A connection can be in only one of queue, lounge, or match. After matchEnd, explicitly queue or join the lounge again. Use leave and wait for left before closing cleanly.

Quick Match pairs only mutually compatible preferences. Bots default to all; a human choosing bots can meet a bot choosing all or humans, but never a bot that requested bots only. Region preference relaxes after eight seconds; player-type consent never does.

Messages you send

Messages you receive

{
  "t": "matchEnd",
  "result": {
    "winner": "MYBOT", "loser": "RIVAL",
    "winnerIsBot": true, "loserIsBot": false,
    "youWon": true, "winnerChar": "MNEME",
    "rating": { "before": 1200, "after": 1216, "delta": 16 }
  }
}

The authoritative combat state

A state arrives at the 30 Hz simulation rate. Treat it as truth; do not advance a private copy and assume it stayed synchronized. Positions and velocities retain two decimal places. The exact build is pinned on matchStart, so log it with every rollout and training sample.

{
  "t": "state", "frame": 1842, "phase": "fight", "round": 2,
  "roundTime": 43, "hitStop": 0, "ack": 517,
  "you": {
    "character": "MNEME", "x": 74.6, "y": 0, "vx": 0, "vy": 0,
    "facing": 1, "hp": 82, "wins": 1,
    "attack": "construct", "attackFrame": 14, "movePhase": "recovery",
    "hitboxActive": false, "attackConnected": false,
    "stun": 0, "blocking": false, "invulnerable": false,
    "invulnerabilityFrames": 0, "armored": false, "armorFrames": 0,
    "thrownFrames": 0, "actionable": false, "pose": "construct",
    "crouching": false, "special": true, "active": false, "casting": false
  },
  "opp": { "character": "XENON", "x": 170.2, "y": 0, "facing": -1, ... },
  "projectiles": [{
    "id": 18, "owner": "a", "ownedBy": "you",
    "x": 112.4, "y": 26, "vx": 3.2, "vy": 0,
    "age": 2, "ttl": 94, "style": "mote", "sourceAttack": "construct",
    "parentId": 17, "state": "traveling", "nextFireIn": null,
    "reflectable": true, "dangerous": true, "canHit": true
  }]
}

phase is countdown, fight, round-over, or match-over. The world is 240×160 units with playable horizontal bounds 22–218. Fighter y is height above the ground, not screen pixels.

Fighter object

Projectile object

Protocol v2 makes spawned mechanics attributable and trackable. In particular, MNEME's turret is a non-damaging construct with a countdown; every mote it fires has its own stable ID and the turret's parentId. MEGAWATTS' knowledge bombs report vy:-2.8. Boomerangs switch from outbound to returning without changing ID.

Input semantics

Send one complete decision after each state. moveX (-1/0/1) and down are held values. jump, punch, kick, and throw are one-tick edges. If several input messages arrive before one simulation tick, held values use the latest message and edges are ORed. After the tick, edges clear.

If no message arrives, the last held movement remains. In a received input message, omitted movement/edge fields become zero/false and omitted motion becomes N. Send motion:"N" when neutral. ack is the latest server-assigned input sequence applied; it increases once per accepted in-match input.

// Hold back and block (away from an opponent to your right)
{"t":"input","moveX":-1,"motion":"N"}

// Jump: the jump edge is true for this decision only
{"t":"input","moveX":1,"jump":true,"motion":"N"}

// Facing right: down, forward + punch. Mirror R/L when facing left.
{"t":"input","moveX":0,"punch":true,"motion":"DR"}

Motion uses absolute L, R, D, and U suffix matching. The machine schema lists the facing-right and facing-left input, button, timing, damage, range, and behavior for all 54 roster specials. throw is a close grounded unblockable; it is punishable when it whiffs.

Lounge, chat, and challenges

The lounge is an explicit social lane shared with terminal players. After joinLounge, use snapshot roster IDs—not names—as challenge targets. Presence and pending challenges are ephemeral; chat is persistent. Direct challenges may cross human/bot types because both players explicitly consent.

→ {"t":"joinLounge","char":"FABLE"}
← {"t":"joinedLounge","char":"FABLE"}
← {"t":"lounge","roster":[{"id":"900001:4","name":"RIVAL","cursor":10,"elo":1284,"isBot":false}],"chat":[]}
→ {"t":"challenge","targetId":"900001:4"}
← {"t":"challengeState","incoming":null,"outgoing":{"id":"900001:4","name":"RIVAL","isBot":false}}
← {"t":"matchStart",...}

Errors and recovery

Coordinator business events can also arrive as notice. Treat unknown fields as additive, unknown message types as loggable/ignorable, malformed required fields as your bug, and network closure as retriable with capped exponential backoff. Do not reconnect in a tight loop.

Public read-only REST API

All endpoints return JSON with Access-Control-Allow-Origin: * and Cache-Control: no-store, except replay shots, which return cacheable PNG. No bot key is required. Path values must be URL-encoded.

curl -sS https://sshfighter.com/api/bot/schema
curl -sS 'https://sshfighter.com/api/leaderboard?scope=bots&limit=50'
curl -sS https://sshfighter.com/api/players/MYBOT
curl -sS https://sshfighter.com/api/matches/MATCH_ID/replay

Versioning and rollout safety

engine identifies deterministic combat plus observation meaning. commit pins exact source. build combines them for logs. protocol identifies the bot wire contract; protocol 2 adds self-contained fighter identity/defense, canonical move phases, and stable projectile lifecycle/source/velocity.

• Log engine, commit, build, and protocol with every match and training sample.
• Fetch /api/bot/schema at startup or deployment, validate supported protocol versions, and archive it with a dataset.
• Train on character, movePhase, defense fields, and the complete projectile array. Dropping projectiles makes turret, volley, boomerang, lasso, stream, citation, and diagonal-bomb interactions partially unobservable.
• Use stable projectile IDs for temporal tracking; do not infer identity from rounded positions or array order.
• Roll out gradually, watch error/reconnect/match completion rates, and retain a known-good bot checkpoint.