plateformer-evolve/AI_TCP_API.md

AI TCP API

The AI handler listens on 127.0.0.1:8765 by default. Set AI_HOST, AI_PORT, or AI_MAX_WORKERS to change the server configuration. Messages are UTF-8 JSON objects separated by newlines. The connection stays open for multiple requests.

Ping

Request: {"type":"ping"}

Response: {"ok":true,"type":"pong"}

Start a simulation

The server chooses the map. For the first training simulation it selects the map closest to difficulty 0. After a simulation finishes, the server computes each model's score from coins, progress toward the finish, and whether it won. The best score becomes the next training difficulty. Validation requests ignore the training score and randomly select a map with difficulty at least 70, or any map when no such map exists.

The score is from 0 to 100:

40 * coin_progress + 40 * distance_progress + 20 * won

where coin_progress is collected coins divided by the map's total coins, distance_progress is progress from the spawn point to the finish, and won is 1 when the finish was reached and 0 when the model stopped elsewhere, including on spikes.

Send one model entry per model. The model entries contain only an ID; moves are requested separately on every turn.

{"type":"simulate","validation":false,"models":[{"id":"model-a"},{"id":"model-b"}]}

Every model gets a separate Game instance and can run in parallel. Valid requests. Valid moves are left_down, left, left_up, up, right_up, right, and right_down. Send null for a model when it has no more moves; that model is stopped for the current generation.

The response identifies the selected map and returns the initial state:

{
  "ok":true,
  "type":"move_request",
  "map":{"name":"default","difficulty":30.0,"layout":[["stone", "stone"]]},
  "results":{"model-a":{"won":false,"coins":0,"moves":0,"position":[1,4],"finished":false},"model-b":{"won":false,"coins":0,"moves":0,"position":[1,4],"finished":false}}
}

Advance one turn

The client must send exactly one move for every model on each turn. The server advances all model simulations in parallel and replies before the client must predict the next moves.

{"type":"step","moves":{"model-a":"right","model-b":null}}

The response is move_request with the selected map and updated per-model states, asking the client for the next move of every model. When every model has finished, the response type becomes simulation_result and includes the best model's server-computed score, which is used to choose the next training map.

The result score is 1000 for a win, plus 10 per coin, minus the number of moves. Malformed requests receive {"ok":false,"error":"..."}.