Getting started

Algohol is a deterministic arena game for people who like building systems. You do not control a character directly. You build the decision-maker: code that reads an observation, chooses what to do, and sends an action back to the arena.

At the start, your unit is a blank slate. It has no built-in memory, no navigation ability, and no objective sense of the whole world. It only receives the subjective line-of-sight observation the arena gives it. Your algorithm is what makes that unit move, look, survive, compete, and pursue the current objective. It becomes as capable as the system you build around it.

The challenge is partly technical and partly strategic. You are not only writing code that works; you are designing behavior under uncertainty. A good algorithm has to decide what to notice, what to ignore, when to spend resources, when to retreat, and how to turn limited information into useful action. In team scenarios, that becomes a coordination problem too: units can take roles, share signals, cover each other, specialize, or follow a shared plan. Algohol is a place to experiment with control systems, tactics, and cooperation, then watch those ideas survive contact with the arena.

Your first challenge

Your first challenge is getting into the game. Algohol expects some technical skill and curiosity: you need to create an account, register your first algorithm, assign it to an arena you control, and connect your algorithm client before you worry about public competition.

The goal is to make the basic player setup work once:

Create an Algohol account
Register an algorithm in the portal
Create or select your private arena
Assign the algorithm to that arena in the portal or viewer
Read its first observations
Submit valid actions
Review what happened after the run

When this challenge is complete, you have a working player in an arena you can use for experiments. From there, Algohol becomes an iteration game: study what your algorithm saw, compare that with what it did, and improve the black box between observation and action.

Your unit has no map of the arena. It perceives only what is inside its own field of view, and terrain accumulates in the observation as the unit explores. Building that map is what finding objectives, resources and opponents depends on.

Before entering open public arenas, spend a good amount of time fine-tuning your algorithms, or they will get smoked. Your private arena is your playground. Invite friends to play with you, run experiments, and find weak spots together.

What you need

An Algohol account — create one at algohol.net
A registered algorithm with a device token, created in the portal after signing in
A private arena for early testing, with your algorithm assigned to its roster
Code that can make HTTP requests, open a WebSocket, and process JSON
Player Lab to inspect and test the player connection while developing

The loop

Authenticate using your device token to get a session bearer token and your gaii
Pick an arena where your algorithm is assigned. You can assign it from the portal or viewer roster controls; the auth response also lists the arena ids where it is already assigned.
Open your private observation stream — a WebSocket at /api/arenas/:arenaId/players/:gaii/ws
On each observation message, read the game state and decide on an action
POST the action to the arena
Repeat until the match ends

Your algorithm runs on your own machine or wherever you choose to host it. The arena does not run your code; it only receives your actions and sends back the information your unit is allowed to observe.

Prompt an agent to build your first algorithm

If you use a coding agent, you can give it a starter prompt that asks it to read the Algohol docs and create the first minimal algorithm client for you. Review the prompt before copying it, then paste it into your agent.

Starter prompt

You are helping me create my first Algohol algorithm.

Your task is to read the Algohol documentation and build a minimal working algorithm client for me.

Start by reading:
- https://docs.algohol.net/llms.txt (index of all docs pages)
- https://docs.algohol.net/doc/howtoplay-getting-started.md
- https://docs.algohol.net/doc/howtoplay-connecting.md
- https://docs.algohol.net/doc/api-authentication.md
- https://docs.algohol.net/doc/api-endpoints.md
- https://docs.algohol.net/doc/api-observation.md
- https://docs.algohol.net/doc/api-actions.md
- https://docs.algohol.net/doc/scifi-observation.md
- https://docs.algohol.net/doc/scifi-actions.md

These are raw markdown; fetch them directly rather than through a tool that summarizes HTML, so literal JSON examples are not lost.

Do not invent API endpoints, request formats, authentication rules, observation fields, or action schemas.

Where the docs and the live arena disagree, the live arena wins. Treat these as authoritative at runtime: observation.arena.allowedActions for what you may send, frame.arenaBaseline for unit parameters and arena geometry, and the 400 response body (which names the offending field and links the relevant doc page) when a request is rejected. Log the first frame and the first action response verbatim rather than assuming a shape. If something is still unclear after that, ask me before continuing.

Goal:
Create a first playable algorithm that can connect to Algohol, receive observations, decide valid actions, submit them, and keep running.

Assume the algorithm should start in a private arena I control. The algorithm must be assigned to that arena first, usually in the Algohol portal or viewer. Do not build portal assignment automation unless the documentation explicitly describes it. Confirm with me only that the algorithm is already assigned to a private arena (yes/no) — do not ask me for the arena id itself yet. Then resolve the arena id yourself: authenticate with the device token, check the `arenas` array in the response, and call the player-frame endpoint for each candidate id — a `200` confirms it is playable. Only ask me for the arena id directly as a last resort, if `arenas` is empty or none of its entries return `200`.

Strategy for the first version:
- The objective is to explore the arena — cover new ground, not to survive by standing still.
- Aiming costs no energy. Moving has a small per-tick cost (agentStats.motorEnergyCost, nonzero by default), and scanning costs much more on top of that; a default arena has no passive energy regeneration. Prefer walking and sweeping the view over scanning.
- The arena is enclosed by a solid wall and the unit cannot walk off the edge. Do not write edge-avoidance or boundary-margin logic.
- Do handle real hazards: gap tiles, platform edges, and tiles where blocksMovement is true.
- Build a map from visibleTiles as the unit explores, and remember where recovery zones are so it can recharge.
- Verify the direction convention with a single test move before trusting any spatial logic.

Requirements:
- Prefer a small, readable implementation over cleverness.
- Use the simplest language/runtime suitable for the documented API.
- Put configuration such as the device token, base URL, and (only if the automatic resolution above failed) the arena id in environment variables. Read the gaii, displayName, and arena assignment from the authentication response rather than configuring them by hand. The base URL defaults to https://arena.algohol.net in code; only ask me about it if I mention a non-production environment.
- Add clear startup instructions.
- Log connection status, observations received, actions submitted, rejected actions, the outcomes reported in observation.actionResults and observation.events, and errors. Sample or log-on-change anything that repeats every frame.
- Handle reconnects, token expiry, and generation or sessionId changes.
- Start against a private arena I control, not a public arena.
- If the arena is already `finished` when you start, do not wait for it to auto-reset — automatic reset is a per-arena setting that defaults off. Report the phase to me and ask me to reset the arena from the portal or viewer instead of polling and hoping.

Before writing code:
1. Summarize what the docs say the client must do.
2. List the credentials and configuration values you cannot resolve yourself — normally just the device token, plus the arena id only if the automatic resolution above fails.
3. Confirm that the algorithm is assigned to the target private arena, or ask me to assign it in the portal or viewer.
4. Ask me for all missing values together, in one batch, not across separate turns.

Then create the project files and explain how I run the algorithm.

Arenas

An arena is a live match instance. Each arena has:

ruleset — the environment family (determines physics, terrain, and action vocabulary)
mode — the objective: last-man-standing, navigation, king-of-the-hill, etc.
joinPolicy — open (join freely), lobby (wait for host), or closed
phase — waiting, live, or finished

GET https://arena.algohol.net/api/arenas is public and requires no authentication. It returns arena metadata: allowed actions with their parameter schemas, unit parameters, world profile, and live mode state.

For the first run, use a private arena and assign your algorithm to it from the portal or viewer roster controls. Assignment places the algorithm on the arena roster; your algorithm client still needs to authenticate, open its observation stream, and submit actions. API-based joining is possible after assignment, but the normal first path is: create/register in the portal, assign in the portal or viewer, then run your client against that assigned arena.

The observation

Every player-frame message on your observation WebSocket carries an observation — a JSON object describing what your unit currently sees. It includes:

arena — the actions the engine accepts right now, mode parameters, and the zones your unit can see
self — your unit's current state: position, orientation, and its ruleset resources
visiblePlayers and other visible entity fields — entities your unit perceives; which entity types appear depends on the ruleset

Session constants that do not change tick to tick — arena size, boundary, unit parameters — arrive separately in arenaBaseline, and only when they change.

You only receive information your unit can observe. Walls, terrain, and your unit's field of view limit what appears in the observation. See the ruleset-specific observation reference for the full field list.

The action

After reading an observation, POST a command. The action schema depends on the ruleset; the full list of accepted action types is in observation.arena.allowedActions.

The engine resolves at 20 Hz. Only the last submitted command between ticks is executed. See Action envelope for the request body, and the ruleset action reference for what you can put in it.

What happens when you win or lose

When a match ends, the arena enters the finished phase. A match report is published with outcome, participants, and statistics.

Automatic reset is a per-arena setting (autoReset), off by default. Unless it was explicitly enabled, a finished arena stays in the finished phase — observation is null and no new session begins — until someone resets it manually from the portal or viewer. Do not assume a finished private arena will start a new session on its own; check state.phase and prompt for a manual reset, or check the arena's autoReset setting, rather than waiting.

Next missions

After the first working loop, improve your algorithm one mission at a time. Good next steps are:

Map the arena — accumulate the terrain and zones you observe rather than reacting only to the current frame
Route around obstacles instead of moving on a straight bearing
Use Player Lab to inspect the connection and observation flow while developing
Add ruleset-specific behavior from the SciFi action and observation references
Record observations and actions so you can debug why the algorithm failed
Compare two algorithm versions in the same private arena conditions
Enter a public, ranked, blind, or sealed format once the private arena behavior is stable