╔══ SPACE EMPIRES IV ══╗ (0.11.1) [ RULES ]
[ < BACK TO RULES ]

The AI orders processor

Space Empires can write a turn's orders for you. An empire's orders are ordinary text either way — the AI produces the same order tokens a player would type, and they are parsed, validated, and executed by exactly the same code. Nothing the AI produces bypasses a rule, and nothing it is shown breaches another player's secrecy.

This document describes when the AI is asked, what it is told, and what it is allowed to see.

When the AI is asked

There are three ways orders can come from the AI.

You ask for them. The order entry screen has a button that fills the box with a generated set of orders. They are a draft: they appear in the textarea as editable text, and nothing is submitted until you press submit. You may edit them freely, or clear them and write your own. This is available on every turn of every game.

The admin asks for them on an empire's behalf. The per-game admin screen can generate orders for any empire in the game. As above, they are a draft.

Turn processing fills in silence — but only in the opening turns. When a turn is processed, any empire that has submitted no orders at all has a set generated and submitted for it automatically. This happens on turns 1, 2 and 3 only.

From turn 4 onward an empire that submits nothing plays the turn with no orders — its fleets hold position, and it builds nothing. Two reasons:

  • Each silent empire costs one call to an external service, made one after another, so a game where several empires go quiet spends most of its processing time waiting on the network, and gets slower the more empires it has.
  • Submitting nothing on turn 2 usually means a player is still finding their feet. Submitting nothing on turn 12 more likely means they have chosen to sit still, and a machine playing on their behalf is not what they wanted.

If you want AI orders after turn 3, ask for them yourself — the button is always there.

What the AI is shown

The AI is given the same view of the universe that the player's own report shows, built by the same visibility rules that decide what goes in that report. It is told:

  • Your worlds — connections, industry, raw materials stored and produced, population, and how many ships each can build this turn.
  • Your fleets — ships, cargo, strategy, and where each one is.
  • Enemy fleets you can see, named by your aliases for them, never by their real ids.
  • Enemy worlds you can see.
  • Which worlds adjacent to yours you have not yet explored.

It is not shown any part of the map you have not reached, any fleet you cannot see, or anything belonging to another player that your own report would not contain. An empire playing by AI has no informational advantage over one playing by hand, and no player learns anything about another by using it.

What the AI is told the rules are

The AI is given a condensed statement of the rules as its system prompt, kept in web/src/lib/server/ai/space-empires-rules.md. That file is a summary written for a machine, not a second source of truth: where it and this repository's rules.md disagree, rules.md is correct and the summary is a bug.

The engine is the final authority regardless. Orders the AI produces are parsed and validated identically to typed ones, so an illegal order is refused with the same message a player would get, and appears in the same "ORDERS NOT PROCESSED" section of the report.

Failure

Order generation calls an external service and can fail — a missing API key, a network error, a rate limit, or a reply that does not parse.

When it fails during automatic turn processing, the empire simply plays that turn with no orders. A failing AI never blocks or delays a turn for everybody else.

When it fails while you asked for it yourself, the order entry screen reports the error and leaves your text untouched.

Limits

Player-initiated generation is rate limited to 5 requests per user per hour. The limit exists because each request costs a call to a paid external service. Admin-initiated and automatic generation are not rate limited.

Configuration

Generation requires an API key in the environment; without one, every request fails in the manner described above, and the game is fully playable by hand.

Variable Meaning
DEEPSEEK_API_KEY Required. Generation fails without it.
DEEPSEEK_API_MODEL Optional. Defaults to a current DeepSeek model.

Orders that were generated automatically are recorded as such in the database, so a turn's history distinguishes them from orders a player wrote.