Game Update Messages

Updates for the players are encoded as any number of messages concatenated together. Each message is a variable-length byte sequence.

Each message is at least one byte long. The type of the message is determined by magic bits in that first byte (similar to opcodes in CPU instruction set encodings). The first byte may also have bit-fields embedding data into it, for some message types.

Opcode Summary

Quick table summarizing the opcodes of all the message types. A few are left unused, reserved for future use.

The patterns must be checked in the correct order, so that more specific bit sequences are matched first.

Messages Documentation

Here is the complete list of game update messages and their encodings:

Player Update

Something notable happened with a specific player.

Assembly:

PLAYER plid status ...

PLAYER plid/sub status ...

Encoding:

The next byte:

PlayerId is the gameplay plid (view) that is affected.

PlayerSubId is the individual user/client, in game modes where multiple people can control a single in-game plid.

For messages that apply to all PlayerSubIds of a given PlayerId, the PlayerSubId field must be all-ones.

The next byte specifies the message kind (what happened):

Then follows the data payload for the given message kind.

Tremor

Some explosion occurred at an unknown location. Client should shake the screen lightly.

Assembly:

SHAKE

Encoding:

Smoke Start

A tile was smoked.

Assembly:

SMOKE y,x

Encoding:

Followed by the coordinate of the tile.

Smoke End

A tile is no longer smoked.

Assembly:

UNSMOKE y,x

Encoding:

Followed by the coordinate of the tile.

Debug

Special message reserved for use during development.

Assembly:

DEBUG i y,x

Encoding:

Followed by:

• u8 magic value
• Tile coordinate

Flag State

Report the presence or absence of a flag on a given tile.

Assembly:

FLAG p y,x

(p == plid, 0 == no flag)

Encoding:

Followed by:

Reserved bits must be zero.

p is the PlayerId that placed the flag. Zero means no flag.

Followed by the coordinate of the tile.

Construction Update

Update on the progress of a pending structure.

Assembly:

BUILD y,x current rate

Followed by the coordinates of the tile.

Followed by u16 indicating current accumulated units.

Followed by u16 indicating rate of construction.

Digits (+ Implied Capture)

The specified tiles are owned by the player and display the given Minesweeper digit.

Can be used to capture tiles, if the tile is not owned by the player.

Can be used to update digits on owned tiles, when they change.

Assembly:

DIGITS d/y,x ...
DIGITS d*/y,x ...

Compact (single) Encoding:

Followed by the coordinate of the tile.

Multi-tile Encoding:

Followed by the coordinates of the tiles.

Followed by the digit for each tile, two digits packed into one byte:

(this encoding allows them to be easily read when inspecting a hex dump)

For an odd number of tiles, the final digit is ignored (should be encoded as zero).

Structure Gone

The structure on the given tile is removed.

Used when a built structure is destroyed or bulldozed. Used when a pending (unbuilt) structure is canceled.

Assembly:

NOSTRUCT y,x

Encoding:

Followed by the tile coordinates.

Structure HP

The HP of a structure changed.

Assembly:

STRUCTHP y,x hp

Encoding:

HP must be > 0.

Followed by the tile coordinates.

Explosions

Explosions have occurred.

If the client should know what item was destroyed, send a "Reveal Item" first.

Assembly:

EXPLODE y,x ...

Encoding:

Followed by the coordinates of the tiles.

Construction Queued

A new structure is pending construction.

Assembly:

BUILDNEW y,x {road|bridge|wall|tower}

Encoding:

The Structure Kind is:

• 0000: Road
• 0001: Bridge
• 0010: Wall
• 0011: Tower
• other values reserved

Must not be 1111.

Followed by tile coordinate.

Followed by u16 indicating total points required to complete construction.

Reveal Structure

There is a structure on the specified tile.

Used both when revealing foreign structures and also when own structures finish construction.

Assembly:

STRUCT y,x {road|bridge|wall|tower}

Encoding:

The Structure Kind is:

• 0000: Road
• 0001: Bridge
• 0010: Wall
• 0011: Tower
• other values reserved

Must not be 1111.

Followed by tile coordinate.

City MoneyInfo

Reports how much money a city has.

Assembly:

CITMONEY i money

CITINCOME i money income

Followed by:

• u8: City ID
• u32: current money
• [u16: current income rate]

The top bit (bit 31) of money indicates whether the income is reported too. The income field is only present if this bit is 1.

The remaining 31 bits are used for the money value.

City Transaction

Reports that a city has gained or spent a given sum of money.

Assembly:

CITTRANS i spent

Followed by:

• u8: City ID
• i16: the amount of money

City ResInfo

Update on the resources of a city.

Assembly:

CITRES i res

Followed by:

• u8: City ID
• u16: the amount of resources

City TradeInfo

Update on the export/import policy of a city.

Assembly:

CITTRADE export import

Followed by:

• u8: City ID
• u8: Export rate
• u8: Import rate

Tile Kind Update

Changes the base tile type.

Assembly:

TILE y,x {water|regular|fertile|destroyed|foundation|mountain|forest}

Encoding:

The Tile Kind is:

• 0000: Water
• 0001: (reserved)
• 0010: Mountain
• 0011: Forest
• 0100: Destroyed Land
• 0101: Foundation
• 0110: Regular Land
• 0111: Fertile Land
• ... : (reserved)

Followed by tile coordinate.

Reveal Item

There is an item on the specified tile.

Used both when revealing foreign items and also when acking own deployed items.

Assembly:

ITEM y,x {none|decoy|mine|trap}

Encoding:

The Item Kind is:

• 0000: None
• 0001: Decoy
• 0010: Mine
• 0011: Trap
• ... : (reserved)

Followed by tile coordinate.

Ownership Update

Multiple tiles are now known to be owned by the specified player id.

Assembly:

OWNER p y,x ...

Encoding:

The PlayerId must not be zero.

Followed by the coordinates of the tiles.

If any of the tiles are of a clustered tile kind (mountain, forest), it is assumed that the ownership update applies to the entire cluster. There is no need to list every tile coordinate of the cluster.