Communication protocol - non-player-games/SimpleCity GitHub Wiki

State data format:

{
    zoneGrid: number[][],
    money: number,
    peopleLocation: number[][],
    time: dateTime,
    RCINeed: number[3]
}

--- communication protocol

request

UUID methodName parameters...

response

request-UUID methodName data

--- MethodName

getZoneGrid: number[][],
getMoney: number,
getPeopleLocation: number[][],
getTime: number,
getRCINeed: number[3]

startGame
quitGame

setZoneGrid x y type

-- from systems to client
simulationTick state

--- ZoneGrid

enum ZoneType {
    NONE,
    RESIDENTIAL,
    COMMERCIAL,
    INDUSTRIAL
}

request example

-- 12:01
UUID-1 getGridData

-- 12:01
UUID-2 getMoney

response

-- 12:02
UUID-2 getMoney
{JSON data} of money

-- 12:03
UUID-1 getGridData
{JSON data} of grid

General

The general form of input the simulation system receives is

uuid methodName args

To be more precise, valid commands must match the regex:

^([0-9a-f-]{36})\s+([a-zA-Z]+)(\s+(.+))?$

The uuid is to assist the client in knowing what output corresponds to what input. Basically, if a command returns output, then whatever the uuid passed in with the input command will be the uuid of the output command.

Methods

We will show the various methods for interacting with the simulation system. As a convention, we will show input from the client as [IN] uuid methodName. The first part in brackets is not actually sent by the client. Rather, it is how we differentiate for the reader input from output. Also, uuid should be replaced with an actual uuid. For example, starting a game would be shown as:

[IN] uuid startGame

And an example of the client's actual input would be: 79da77d7-ab4b-47aa-97c3-966838279305 startGame

Start Game

[IN]  uuid startGame
[OUT] uuid  OK starting game

Quit Game

[IN]  uuid quitGame
[OUT] uuid OK quitting game

Get Game Time

[IN]  uuid getTime
[OUT] uuid 4

Get Money

[IN]  uuid getMoney
[OUT] uuid 100

Get Zone Grid

[IN]  uuid getZoneGrid
[OUT] uuid {"zones":[0,0,0,0],"size":{"x":2,"y":2}}

Get People Location

[IN]  uuid getPeopleLocation
[OUT] uuid {"zones":[0,0,0,0],"size":{"x":2,"y":2}}

Get RCI Need

[IN]  uuid getRCINeed
[OUT] uuid {"residential":0,"commercial":0,"industrial":0}

Get Zone Grid

[IN] uuid setZoneGrid x y zone

x, y, and z are unsigned integers. The x and y arguments correspond to a grid x and y location. Zone is the numeric representation of the Zone enum.

Quit Game

[IN]  uuid quitGame          
[OUT] uuid OK quitting game

Error

[IN]  uuid some badly formed input
[OUT] uuid ERR error message

Shutdown

[IN]  uuid shutdown
[OUT] uuid OK shutting down simulation systems process