Game Manual¶

Introduction¶

ColonyOps is a competitive strategy game in which multiple factions (called colonies) vie for dominance by extracting valuable resources from unexplored planets. The game operates on two interconnected layers:

Tactical Layer: Each colony deploys an extraction squad onto a planet's surface. Squad members explore the terrain, gather resources, fight hostile organisms (and rival squads), and return their haul to orbit. A single planetary mission plays out in discrete turns until its end conditions are met.
Strategic Layer: Between missions, each colony manages its growth (balancing population, economy, and military) and invests in research that unlocks new capabilities for future missions. Resources gathered during missions sustain this growth.

The overarching goal is to grow your colony as large and powerful as possible over a series of missions, outpacing all rivals in one or more of the three pillars: population, economy, or military might.

Players do not control their colony manually. Instead, they provide a remote HTTP service that implements the decision logic: the game backend calls this service during missions (to request actions for squad members) and between missions (to fetch strategic preferences). Building a smart, autonomous decision-making service is the core challenge of the game.

General Gameplay Aspects¶

Resources¶

Three raw resource types are extracted during planetary missions and added to the colony's persistent resource pool:

Resource	Extracted From	Strategic Role
Water	Bodies of water, ice deposits	Sustains population (upkeep cost)
Metal	Ore veins, mineral deposits	Drives economic growth (upkeep cost)
Alien Artifact	Abandoned alien relics	Fuels military advancement (upkeep cost)

Resources gathered during a mission only count if they are deposited at the landing craft, at a resource drop-off point, or airlifted into orbit before the mission ends. Resources still carried in a squad member's crate at the end of a mission are lost.

Missions (Tactical Layer)¶

Mission Objective¶

Each mission drops your colony's squad onto a newly generated planet. The primary objective is to extract as many resources as possible and secure them by delivering them to one of the following collection points:

The Landing Craft: deployed at the squad's initial spawn location.
A Resource Drop-Off Point: an additional collection point that can be called in from orbit (requires the appropriate tech unlock).
Airlift: an orbital call-in that instantly transfers a squad member's crate contents to the colony's resource pool without physically returning to a collection point.

Only resources that have been deposited or airlifted are retained at the end of the mission and contribute to the colony's strategic resource pool.

The Planet¶

A planet is modeled as a 2D raster grid of dimensions width × height. Each cell (tile) on the grid is identified by an (x, y) coordinate.

Movement and distance use Chebyshev distance (also known as chessboard distance). This means a unit can move to any of the 8 surrounding tiles (horizontally, vertically, or diagonally) in a single step, and all count as distance 1.

Wrap-around (toroidal topology): The planet wraps around on both axes. Moving past the right edge places you on the left edge (and vice versa); the same applies to the top and bottom. Distance calculations also account for wrap-around, always using the shortest path.

Biome types: Each planet has a randomly assigned biome that flavours the environment: ICE, DESERT, VOLCANIC, or GRASSLAND.

Initial generation: When a planet is created, resource deposits and hostile organisms are scattered randomly across the grid according to configurable probabilities. At most one entity occupies a tile at generation time; tiles with a hostile organism do not also receive a resource deposit.

Entities¶

The following entity types can exist on the planet during a mission:

Squad Member¶

A member of a colony's extraction team. Each squad member has:

Health Points (HP): when reduced to 0, the member is killed.
Armour Rating: reduces incoming damage by a percentage.
Weapon Slot: holds a single weapon (see Gear).
Consumable Slot: holds a single active consumable (see Gear).
Resource Crate: a container with a limited capacity for carrying extracted resources.

Squad members are the only entities directly controlled by the player's logic.

Resource Deposit¶

A location containing extractable resources of a specific type (Water, Metal, or Alien Artifact). Deposits have a finite quantity; once exhausted, they are removed from the map.

Deposits come in two variants:

Normal deposits: present from the start of the mission, scattered across the map during planet generation.
Large deposits: discovered during the mission via the orbital scan mechanic (see Resource Scans & Large Deposits). These contain significantly more resources.

Turret¶

A stationary defensive structure deployed by a colony (via an orbital call-in). Turrets have health points and automatically attack the closest enemy entity within their range each turn, targeting any entity not belonging to the owning colony (rival squad members, rival turrets, rival drop-off points). Turrets are destroyed when their HP reaches 0.

A colony has a maximum number of concurrent turrets it may have active on the map (determined by tech research).

Hostile Organism¶

An alien creature native to the planet. Hostile organisms are stationary, have health points, and automatically attack the closest squad member or turret within their range each turn, regardless of which colony owns them. They are not affiliated with any colony. Hostile organisms vary in strength: some are weak scouts, others are heavily armoured predators.

Landing Craft¶

The initial drop-off point for the colony's squad. It marks the location where squad members can deposit resources. When a squad is respawned after a wipeout, a new landing craft is placed at the new spawn location.

Resource Drop-Off Point¶

An additional resource deposit location that can be called in from orbit. It has health points and can be destroyed by enemies. Squad members can deposit resources here just as they would at the landing craft, saving a potentially long trip back to the original spawn point.

NPC Behaviour¶

Turrets and Hostile Organisms act autonomously at the start of each turn, before player actions are resolved. Each NPC selects the closest valid target within its attack range (using Chebyshev distance with wrap-around) and fires at it. If multiple targets share the same distance, the selection is deterministic but unspecified.

Turrets target any living entity not belonging to the turret's owning colony.
Hostile Organisms target any squad member or turret, regardless of colony affiliation.

Actions¶

Each turn, the game engine asks the player logic to provide an Action for every living squad member. The following actions are available:

Action	Description
NoAction	Do nothing this turn.
MoveAction	Move to a target location within movement range. Under normal circumstances, a squad member can move 1 tile per turn (Chebyshev). With an active Jetpack consumable, the movement range increases.
ExtractResourceAction	Extract resources from the deposit at the squad member's current tile. Extracted resources are placed in the member's crate (limited by crate capacity).
DropOffResourceAction	Deposit all resources from the crate at the current location. The member must be standing on the landing craft or a resource drop-off point.
CallInFromOrbitAction	Call in orbital support (see below).
AttackAction	Attack a target entity within weapon range. Requires the squad member to have a weapon with remaining uses.
LootAction	Loot a defeated (dead) entity at the same location: pick up their weapon and/or resources.

Orbital Call-In Commands¶

Orbital call-ins are powerful abilities unlocked via the military and economic tech trees. Each call-in has a cooldown: after use, it cannot be used again until the cooldown timer expires. The following commands are available:

Command	Description
`DEPLOY_REINFORCEMENT`	Drop a new squad member at the caller's location (must not exceed squad cap).
`PERFORM_ION_STRIKE`	Perform an orbital strike at the caller's location, damaging all non-allied entities in the blast area.
`AIRLIFT_RESOURCES`	Instantly transfer the caller's crate contents to the colony's extracted resource total; no need to physically return to a drop-off point.
`DEPLOY_JETPACK`	Grant the calling squad member a Jetpack consumable.
`DEPLOY_MAGMA_BORE`	Grant the calling squad member a Magma Bore consumable.
`DEPLOY_MEDIC_KIT`	Grant the calling squad member a Medic Kit consumable.
`DEPLOY_AMMO_PACK`	Grant the calling squad member an Ammo Pack consumable (requires an equipped weapon).
`DEPLOY_TURRET`	Deploy a defensive turret at the caller's location (must not exceed turret cap).
`DEPLOY_RESOURCE_DROP_OFF`	Deploy a resource drop-off point at the caller's location.

Action Priority¶

When multiple actions are submitted in the same turn, they are resolved in a fixed priority order to avoid conflicts:

Attack: resolved first so targets cannot escape.
Loot: loot defeated entities before they despawn.
Extract: gather resources from deposits.
Drop-Off: transfer crate contents to a collection point.
Call-In: orbital call-ins (reinforcements, consumables, strikes, etc.).
Move: movement is executed last.

Actions whose preconditions are not met (e.g., attacking an out-of-range target, extracting from an empty deposit) are silently ignored.

Gear¶

Weapons¶

A squad member can hold one weapon at a time in their weapon slot. Weapons are characterised by:

Type: determines the weapon's behaviour profile.
Damage: the amount of HP removed from the target per hit (before armour mitigation).
Range: maximum Chebyshev distance at which the weapon can hit a target.
Uses: how many times the weapon can be fired before it is depleted.

The three weapon types are:

Weapon	Characteristics
Laser Pistol	A short-range sidearm with moderate damage and limited ammunition. Unlocked early in the military tree.
Plasma Rifle	A ranged weapon with higher damage and more ammunition than the Laser Pistol. Requires deeper military research.
Energy Sword	A melee weapon (range 0, must be on the same tile as the target) with moderate damage, but unlimited uses. Requires military research.

Weapon stats (exact damage, range, uses) are determined by the colony's tech research and are subject to balance changes.

Consumables¶

A squad member can have one active consumable at a time. Consumables are deployed via orbital call-ins and last for a limited number of turns before expiring. Only one consumable can be active at a time: deploying a new one replaces the current one.

Consumable	Effect
Jetpack	Increases the squad member's movement range for the duration, allowing rapid traversal of the map.
Magma Bore	Multiplies the amount of resources extracted per turn while active: critical for quickly mining large deposits.
Medic Kit	Heals the squad member each turn for a percentage of their max HP while active.
Ammo Pack	Fully restores the squad member's weapon uses each turn while active.

Consumable durations and exact effects are influenced by tech tree research.

Resource Scans & Large Deposits¶

Each colony's orbiting spacecraft continuously scans the planet for large resource deposits. This is modeled as a per-colony cooldown timer that ticks down each turn. When the timer reaches zero:

A large resource deposit is spawned at a random location on the map.
The colony's player logic is notified of the discovery (location and resource type).
The timer resets and begins counting down again.

Large deposits contain substantially more resources than normal deposits and represent high-value targets. However, the information may be intercepted by rival colonies (see Communications & Interception).

The total number of large deposits that can be discovered during a mission is finite: once the limit is reached, no more scans complete.

Tech research can:

Reduce the scan cooldown (finding deposits faster).
Bias the resource type of discovered deposits toward a preferred type.
Automatically deploy a turret at the deposit location upon discovery.

Communications & Interception¶

All communication between a colony's squad on the planet surface and the orbiting spacecraft is potentially vulnerable to interception by rival colonies. In gameplay terms, this means that critical intel, such as the location of a newly discovered large deposit, may be picked up by competitors, allowing them to race your squad to the site.

The interception chance is a configurable mechanic that represents how secure your colony's communications are. The military tech tree includes effects that reduce the interception chance, making it progressively harder for rivals to eavesdrop on your operational communications.

Death & Squad Wipeout¶

When a squad member's HP is reduced to 0, they are killed. The body remains on the map as a lootable corpse for a limited number of turns. During this time, any squad member (friendly or hostile) standing on the same tile can loot the corpse, picking up the fallen member's weapon and/or any resources remaining in their crate.

After the despawn timer expires (or once the corpse has been fully looted), it is removed from the map.

Full Squad Wipeout¶

If all of a colony's squad members are killed simultaneously (none remain alive), the colony suffers a wipeout. A respawn countdown begins, and once it expires:

A new squad spawns at a new random location on the map.
A new landing craft is placed at the new spawn location.
The old landing craft is removed.

The respawn time is influenced by the colony's population (higher population → shorter respawn wait).

Mission End Conditions¶

A mission ends when either of the following conditions is met:

All large deposits exhausted: Every large resource deposit that could be discovered has been found (the scan limit is reached) and all large deposits currently on the map have been fully mined.
Turn limit reached: The mission has lasted the maximum number of turns allowed.

When a mission ends:

All extracted resources (deposited or airlifted during the mission) are added to each colony's persistent resource pool.
Resources still in a squad member's crate are lost.
The strategic layer processes the results: applying growth, paying upkeep, and advancing research (see next section).

Colony Management (Strategic Layer)¶

The strategic layer operates between missions. It determines how your colony evolves over time: growing stronger (or weaker) based on the resources gathered and the choices you make.

Growth Settings & Upkeep¶

Each colony has three core stats that persist across missions:

Stat	Resource for Upkeep	Role
Population	Water	Determines squad size and respawn speed
Economy Size	Metal	Determines depth of economic tech tree research
Military Might	Alien Artifact	Determines depth of military tech tree research

Growth Levels¶

For each stat, the player sets a growth level that determines how aggressively that stat grows after each mission:

Level	Effect
`NONE`	No growth: the stat remains stable (still requires upkeep).
`SLOW`	Modest growth per mission.
`NORMAL`	Moderate growth per mission.
`MAX`	Aggressive growth per mission.

The Upkeep Cycle¶

After each mission, the following happens for each stat:

Resources from the mission are added to the colony's resource pool.
Upkeep is deducted: maintaining a larger stat costs more resources. Upkeep scales sub-linearly: larger colonies are more efficient per unit, but the absolute cost still increases.
Growth is applied: if upkeep was successfully paid, the stat grows according to the selected growth level.
Failure to pay: if the colony does not have enough resources to cover upkeep for a stat, that stat shrinks instead of growing.

The core challenge of the strategic layer is finding the right balance: growing too aggressively risks bankruptcy if missions don't yield enough resources. Growing too conservatively means falling behind rivals.

Research Trees¶

Two tech trees provide powerful bonuses that affect mission gameplay:

Economic Tech Tree¶

Focused on resource gathering, logistics, and field operations. The three main branches are:

Mining: improves extraction speed, unlocks the Magma Bore consumable, reduces scan cooldowns, and can specialise in a specific resource type (Water, Metal, or Alien Artifact mastery).
Logistics: increases crate capacity, unlocks resource drop-off points, reduces airlift cooldowns, and can provide survey/intel advantages (faster scanning, reduced interception risk).
Field Ops: unlocks the Jetpack consumable, increases vision range and movement speed, and can further specialise in mobility or forward operations (combining drop-off points with enhanced jetpack performance).

Military Tech Tree¶

Focused on combat effectiveness and orbital support. The three main branches are:

Assault: improves weapon damage and unlocks advanced weapons (Energy Sword for melee specialists, Plasma Rifle for marksmen), with associated ammo supply capabilities.
Defence: increases squad member HP and armour, unlocks the Medic Kit consumable, and improves reinforcement availability.
Tactics: focuses on orbital strike capability (Ion Strike) and turret deployment mastery, including secure communications (reduced interception chance) and automated turret deployment.

Research Depth & Targets¶

Each tree is structured as a root node with branching paths leading to leaf nodes. The player selects a research target by choosing a leaf node: this determines which branch of the tree their colony progresses along.

The depth of research (how many nodes along the chosen path are unlocked) is derived from the colony's corresponding stat:

Economic tree depth ← Economy Size
Military tree depth ← Military Might

As your stat grows, more nodes along your chosen path are unlocked, granting their effects. If you change your research target to a different leaf (branch), your depth resets to reflect the new path: effects from the old branch are lost in favour of the new one.

Strategic Impact on Missions¶

The strategic layer directly affects mission gameplay in the following ways:

Colony Stat / Research	Mission Effect
Population (higher)	Larger squad size (more members deployed). Faster respawn after wipeout.
Economy Size (higher)	Deeper economic tech → better extraction, mobility, logistics
Military Might (higher)	Deeper military tech → better weapons, defences, orbital strikes
Total Colony Score (higher)	Increased initial spawn delay: a larger colony's bureaucracy takes longer to organise a deployment. This "Bureaucratic Overhead" penalty means your squad enters the mission later than smaller, more agile colonies.

Player API¶

Overview¶

Players interact with the game by providing an HTTP service (at a URL known as the logicUrl) that the game backend calls at specific moments. This service must implement two sets of endpoints:

Mission API: called during active missions to control squad members and receive tactical updates.
Strategy API: called between missions to fetch the colony's growth preferences and research targets.

The game backend acts as the client; your service is the server. All communication uses JSON over HTTP.

Mission API (Tactical)¶

These endpoints are called by the game backend during an active mission:

Unknown missionId

Every endpoint below that takes a {missionId} path segment (not just PUT /missions/{missionId}) should respond with 404 Not Found when that missionId is not known to your service (e.g. after a restart wiped your in-memory state).

The backend treats a 404 from any of them as "this service has forgotten the mission" and recovers by re-sending the initial POST /missions and retrying. Returning your endpoint's normal success response for an unknown mission instead breaks that recovery.

POST /missions

Called when: A new mission starts.

Request body: Mission, containing all initial information about the mission.

Expected response: 201 Created

Use this to initialise any internal state for the mission.

PUT /missions/{missionId}

Called when: A new turn is about to begin.

Request body: Mission, containing the current state of the mission (updated turn number, current mission control state including orbital call-in cooldowns and extracted resource totals).

Expected responses:

204 No Content: acknowledged.
404 Not Found: indicates the service has forgotten about this mission (e.g., after a restart). The backend will re-send the initial POST /missions and retry.

POST /missions/{missionId}/request-action

Called when: The engine needs an action for a specific squad member this turn.

Request body: ActionRequest containing:

turnNumber: the current turn.
member: the full state of the squad member (HP, location, weapon, consumable, crate contents).
locationsInView: a list of all tiles within the squad member's vision range, including the entities present at each tile.

Expected response: 200 OK with a JSON body representing the chosen Action directly (e.g., MoveAction, AttackAction, ExtractResourceAction, etc., no wrapper object). The action must include a type discriminator field.

If the service returns an error or is unreachable, the engine defaults to NoAction.

POST /missions/{missionId}/scan-completed

Called when: The colony's orbital scan discovers a large resource deposit.

Request body: DepositFoundEvent containing:

turnNumber: when the discovery was made.
location: the (x, y) coordinates of the newly spawned large deposit.
resourceType: the type of resource in the deposit.

Expected response: 204 No Content

Use this to update your pathfinding/strategy to prioritise the new deposit.

DELETE /missions/{missionId}

Called when: The mission has ended.

Expected response: 204 No Content

Use this to clean up any state associated with the mission.

Strategy API (Strategic)¶

This endpoint is called between missions (before a new mission begins) to determine the colony's strategic preferences:

GET /strategy

Called when: The game needs the colony's desired growth configuration and chosen research path.

Expected response: 200 OK with a JSON body:

{
    "growthSettings": {
        "populationGrowth": "SLOW | NORMAL | MAX | NONE",
        "economicGrowth": "SLOW | NORMAL | MAX | NONE",
        "militaryGrowth": "SLOW | NORMAL | MAX | NONE"
    },
    "researchTargets": {
        "economicResearchTarget": "<leaf-node-id>",
        "militaryResearchTarget": "<leaf-node-id>"
    }
}

growthSettings: Each field accepts one of the four growth levels. This determines how aggressively each stat grows after the next mission (assuming upkeep can be paid).
researchTargets: Each field must contain the id of a leaf node in the respective tech tree. This determines which branch of the tree the colony progresses along. The available leaf node IDs can be discovered by inspecting the tech tree configuration.

Error Handling & Recovery¶

The game backend is resilient to temporary failures in the player service:

If the service is unreachable during a mission, squad members default to NoAction.
If the service returns 404 for a turn update or action request, the backend will attempt to re-send the mission start notification and retry.
If the strategy endpoints fail, the colony's previous settings are preserved.

It is recommended to build your service to be stateless or recoverable: it may be restarted at any time, and the backend will re-initialise it by re-sending the mission start event.