Implemented game API

Arkline currently exposes a JSON command protocol, not a REST gameplay API. The authoritative schema is `crates/arkline-protocol/src/lib.rs` . PROTOCOL_VERSION is currently 1 ; the dated application build version is separate. New fields often have Serde defaults for old saves, but clients must still negotiate the protocol version and tolerate unavailable optional state. This is a preview contract, not a stable third-party SDK guarantee.

Endpoints and framing

GET /health returns 200 when a successful simulation tick is less than three seconds old, otherwise 503. It does not establish gameplay, backup or account health. Use GET, not HEAD. The public proxy can present rejected upgrades as an edge error rather than preserving the origin's status.

WebSocket is request/response, not a push subscription. Poll snapshot for current state. Keep request/response ordering; there are no request IDs or durable idempotency receipts. Browser Origin must match the configured exact allowlist; native clients may omit Origin. An Origin is not an identity. No tokens belong in URLs. See public limits and transport lifecycle for the complete admission, size, timeout and rate policy.

Establishing a pilot session

These examples use an invented name and placeholder credential. On a new test world, creating a pilot changes durable state and issues starter resources; use a read-only snapshot when no creation is intended.

{"command":"snapshot"}
{"command":"connect","protocol_version":1,"pilot":"ExamplePilot","resume_token":null}

Save the returned resume_token securely, scoped to this server/world. For an existing pilot:

{"command":"connect","protocol_version":1,"pilot":"ExamplePilot","resume_token":"REPLACE_WITH_SAVED_CREDENTIAL"}

A pilot name is public, not proof of ownership. Existing names require their credential. New names are subject to server validation and registration limits. The server persists a token hash; public snapshots and ledger exports contain no resume tokens. Current game credentials are independent of website sign-in. There is no account recovery API or shared OAuth login yet.

A response contains ok and message , and may contain snapshot , assets , resume_token , or ledger . Absent optional keys can be omitted entirely. Error messages are human-readable, not stable machine error codes.

{"ok":false,"message":"Human-readable rejection reason"}

Read-only snapshot and bounded export_ledger do not require login. Mutating commands require a bound pilot session. Presence is reference-counted across simultaneous authenticated transports. Closing one connection does not necessarily make a pilot offline. Last-disconnect safety neutralizes transient controls; persisted ships and resources remain.

**Unknown outcome:** a timeout after sending a command does not prove failure. Reconnect, inspect current state and reconcile the action. Never automatically replay trades, transfers, job changes or other mutations. A lost first registration response can leave the newly created pilot's credential unavailable.

Commands and fields

Each row lists the command discriminator and its additional JSON fields. Numeric IDs are server-assigned unsigned integers. Distances/positions are meters, time fields are server milliseconds, and angles are radians. Do not derive world positions from rendered pixels or send client-computed awards.

Legacy mine and mine_asteroid quantity requests are rejected: clients cannot choose mining yield. Legacy singleton launch_drone , recall_drone , drone_hold , drone_navigate remain compatibility operations; new fleet clients should use explicit IDs. select_ship boards an owned hull; it is not unrestricted remote hull spawning.

Nested JSON types and examples

NavigationTarget uses kind : station , belt , pilot with pilot , asteroid with id , or gate with id . NavigationMode uses mode : stop , manual , approach with target , orbit with target and radius , keep_range with target and distance , or fly_to with position . Direct manual controls use pilot_input ; the server may reject modes inappropriate for a particular request.

{"command":"navigate","mode":{"mode":"approach","target":{"kind":"asteroid","id":1}}}
{"command":"navigate","mode":{"mode":"orbit","target":{"kind":"pilot","pilot":"ExamplePilot"},"radius":1000.0}}
{"command":"pilot_input","translation":[1.0,0.0,0.0],"rotation":[0.0,0.0,0.0]}
{"command":"warp","destination":"belt"}
{"command":"warp","destination":{"gate":{"id":1}}}
{"command":"lock_asteroid","id":1}
{"command":"start_mining","module_id":0,"target_id":1}
{"command":"start_resource_job","target_units":4000,"pilot":null}
{"command":"remote_control","pilot":"WorkerExample","request":{"command":"navigate","mode":{"mode":"stop"}}}

Destination deliberately has a different representation: "station" , "belt" , or {"gate":{"id":N}} . Ship classes are pioneer , prospector , borealis , stratum , monolith , hauler , vanguard ; drone classes are recon , mining , attack ; prop kinds are crate , pylon , platform . Read current target IDs from snapshots instead of assuming sample ID 1 exists or is reachable.

Snapshot, private assets and ledger

Snapshot contains server_time_ms , pilots , online_pilots , asteroids , orders , belt_ore , stored_ore , ledger_sequence , ledger_hash , remote_controls , fleet_links , resource_jobs , surface_props , and traffic . It is a world view, not proof every listed ship is connected or visible in the local system. Filter by system_id for local rendering.

PilotView contains public name, credits, active cargo ore , hull class, system/location, optional flight/power/surface/station avatar, mining modules, drone fleet and pending/completed lock lists. Old singleton lock/drone fields mirror compatibility state. FlightState uses f64 position, velocity, heading, actual acceleration, quaternion [x,y,z,w] , angular velocity, navigation mode, update timestamp and optional durable warp trajectory. Body axes are +X forward, +Y up, +Z right. Shared trajectory helpers exist so clients can present continuous travel without inventing server positions.

assets contains authenticated inactive hulls and their cargo/power, personal storage by system, membership-visible corporation storage, and invitations. Active hull cargo remains PilotView.ore . Remote control does not impersonate the worker's account or grant this asset view.

ledger is LedgerExport { protocol_version, entries, snapshot } . Each entry contains sequence, ruleset version, timestamp, previous hash, economic event and hash. Hash encoding is the ordered tuple implemented by LedgerEntry::calculate_hash , not arbitrary JSON object text. Events cover creation, extraction, escrow/trades, cargo swaps, storage and corporations. Use arkline-verifier rather than assuming a matching final balance validates history. An unsigned hash chain plus a locally pinned checkpoint cannot establish the honesty of the first history or physical mining truth.

Publishing and extending the contract

This reference and the Rust protocol describe the current game API. The planned my.arkline.network account and developer portal is intended for registration, sign-in, account management and API access, not gameplay. It is not available yet; developer API keys, shared website/game OAuth login and account recovery are not implemented. Use the pilot credential flow documented above for current integrations. Follow the official Wiki for supported integration and compatibility guidance.