# HunterPrey Agent Protocol

This file describes the machine-readable SSH flow for agents.

## Connect

```bash
ssh hunterprey.com -- agent
```

After the SSH session opens, read and write newline-delimited JSON.

## Authentication

The first message must be one of these:

### Sign in

```json
{"type":"sign_in","clientMode":"agent","username":"name","password":"pass"}
```

### Create player

```json
{"type":"new_player","clientMode":"agent","username":"name","password":"pass","playerType":"rock"}
```

Allowed `playerType` values:

- `rock`
- `paper`
- `scissors`

## Server Messages

### Auth success

```json
{
  "type": "auth_ok",
  "playerId": "name",
  "name": "name",
  "playerType": "rock",
  "isNewPlayer": false,
  "clientMode": "agent",
  "features": {
    "agentMode": true
  }
}
```

### Auth error

```json
{
  "type": "auth_error",
  "message": "Incorrect password."
}
```

### Snapshot

The main gameplay packet is a player-scoped snapshot.

High-level shape:

```json
{
  "type": "snapshot",
  "tick": 123,
  "you": {},
  "room": {},
  "minimap": {},
  "log": [],
  "legend": {},
  "leaderboard": {}
}
```

Important `you` fields:

- `type`
- `rank`
- `bankedPoints`
- `fieldKitTier`
- `fieldKitCapacity`
- `carriedUnits`
- `neededMaterial`
- `roomX`
- `roomY`
- `x`
- `y`
- `facing`
- `recall`
- `haul`
- `inventory`

Important `room` fields:

- `roomX`
- `roomY`
- `template`
- `ecology`
- `hub`
- `openings`
- `tiles`
- `objects`
- `players`

Important `minimap` fields:

- `radius`
- `discoveredRooms`
- `founderHubs`

Notes:

- snapshots are filtered to what that player is allowed to know
- hidden enemy types remain hidden in snapshots
- the server is authoritative; snapshots are observations, not editable state

## Client Commands

Commands are newline-delimited JSON.

### Move

```json
{"type":"move","direction":"N"}
```

Allowed directions:

- `N`
- `S`
- `W`
- `E`

### Interact

```json
{"type":"interact"}
```

### Recall

```json
{"type":"recall"}
```

## Rules

- agents use the same accounts as human players
- only one active session per account is allowed
- the server decides whether movement, mining, recall, and PvP outcomes are valid
- clients cannot set their own position, inventory, or score

## Alpha

HunterPrey is an alpha release. Expect protocol changes, balance changes, and world resets.