The Players module is a table with one row per seat. Without it, a custom map's seats are inferred: seat 0 is human, everything else is a computer opponent, everyone is on their own team, and each seat's race is guessed by counting the race prefixes of the entities you placed. That inference is why a map with more goblin critters than dwarf buildings on a seat could hand that seat the wrong faction.
A roster replaces every part of that guess.
The seat table
| Column | What it sets |
|---|---|
| Controller | User, computer, neutral, hostile, creep, or none |
| Race | The seat's faction, explicitly |
| Team | Seats sharing a team number are allied |
| Colour | The seat's player colour |
| Resources | Absolute starting gold, lumber, stone and oil |
| Workers | How many starting workers, independent of the town hall |
| Tech | Upgrade or building ids the seat starts with already researched or unlocked |
| AI | Difficulty, personality, first attack tick, passive |
Controller is the interesting one. User is a human slot. Computer is an AI opponent. Neutral is a seat that owns things but takes no actions, which is how you place a village that neither side starts at war with. Hostile is neutral-but-at-war-with-everyone. Creep is the neutral camp owner. None is a seat that exists in the roster but is not filled, which is how you write a map that supports up to eight players but plays fine with three.
The roster is a pure function of the map bytes. No randomness enters it, which is what makes every client in a lockstep match resolve the same seats from the same file.
Teams
Team numbers are the whole model. Two seats with the same team number are allied for vision, for damage and for victory. Alliances can then be changed at runtime by a trigger, which is how a free-for-all that becomes 2v2 halfway through works.
Map rules
Alongside the seat table sits a small set of rules that apply to the whole map:
- Heroes. Whether the same hero may be taken twice by one player, or twice across the whole match, and an optional fixed per-player hero cap that replaces the normal town-hall tier cap.
- Standard victory. On by default. Off means the engine never decides who won, and the map's triggers do it.
- Minimum and maximum players. What the lobby will let people set up.
- No starting units. Explicit control over whether seats get an automatic town hall and workers.
- Fog. Normal fog of war, a map that starts fully explored (units outside vision stay hidden), or no fog.
Making a one-player map work
A single-seat map is legal, and there are exactly two things to get right.
Declare a roster of one seat. Without one, the seat count is floored at two, and a one-spawn map boots with a phantom AI sitting at seat 1 with no base.
Turn standard victory off. This is the one that catches everyone. The win check ends the match as soon as one player is left alive, and on a one-seat map that is true on tick 1. The map declares victory before the player has done anything. The validator refuses to publish a one-seat map with standard victory still on, and that rule exists because the failure is instant, total and completely unexplained if you have not seen it before.
With both set, the map boots with one human seat and ends when a trigger says
it ends. Tower Defense and survival maps are the same shape:
standardVictory: false, an integer counter for lives, and a trigger that
declares defeat when it reaches zero.
AI settings
The AI block per seat is deliberately small.
Difficulty flows through to the existing AI difficulty setting. Personality is normally drawn at random per match; forcing it makes an opponent play predictably, which is what a scripted scenario wants. The random draw comes from the match's seeded generator, so a forced seat still makes that draw and then discards it. Every later random number in the match is the same as it would have been without the override.
First attack tick and passive control when, and whether, it attacks at all. Both hold back attack waves and harassment raids. A passive seat still builds, trains and defends its base, and it still contests neutral objectives such as a monument or relics. All three settings apply to the built-in AI. A seat whose difficulty is LLM ignores them.
The built-in AI settings control the standard opponent. For authored behaviour, turn built-in AI off and use triggers or sandboxed scripts to spawn units and issue orders. This supports scripted encounters and custom decision logic through the public API; it does not replace native AI systems. See Build a custom game.
Spawn points and cameras
A seat's spawn point is its town hall position and, by default, its camera start. Giving a seat an explicit camera position separates the two, so the match can open looking at a lane, a hero or a landmark rather than at a building.
Next: Triggers.