{"id":20550287,"url":"https://github.com/dnmfarrell/settlers-game-notation","last_synced_at":"2025-04-14T11:16:38.905Z","repository":{"id":149704044,"uuid":"44567549","full_name":"dnmfarrell/Settlers-Game-Notation","owner":"dnmfarrell","description":"Game notation for Settlers, JSON","archived":false,"fork":false,"pushed_at":"2016-11-07T15:04:04.000Z","size":498,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-14T11:16:33.200Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dnmfarrell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-19T22:21:58.000Z","updated_at":"2024-01-15T22:47:39.000Z","dependencies_parsed_at":"2024-03-08T12:15:28.113Z","dependency_job_id":null,"html_url":"https://github.com/dnmfarrell/Settlers-Game-Notation","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnmfarrell%2FSettlers-Game-Notation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnmfarrell%2FSettlers-Game-Notation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnmfarrell%2FSettlers-Game-Notation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnmfarrell%2FSettlers-Game-Notation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dnmfarrell","download_url":"https://codeload.github.com/dnmfarrell/Settlers-Game-Notation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248868767,"owners_count":21174758,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T02:24:16.426Z","updated_at":"2025-04-14T11:16:38.890Z","avatar_url":"https://github.com/dnmfarrell.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Settlers Game Notation\n\nThis document defines a notation for the game island colonization game Settlers, called \"Settlers Game Notation\" (SGN). SGN is represented as JSON and is designed to capture \"what happened\" for a game of Settlers. However, just like with Chess notation, many actions can be implied without being logged. For instance it is not necessary to record an \"end turn\" action, as the next player rolling the dice implies that the prior player's turn is finished. This philosophy helps to keep the notation clean, lean and simple.\n\n## Goal\n\nAs far as this author is aware, there is no formal, public and free notation for Settlers. This document aims to establish a common language for recording games of Settlers that can be used to implement Settlers software components like games, clients, servers and AI.\n\n## Status\n\nVersion 1.0 is a complete notation and considered mature enough to be used for implementations. This README is subject to change for errors and typos.\n\n## JSON Schema\n\nThe file [message.json](schema/v1.0/message.json) is a complete JSON schema for an SGN message.\n\n## Example\n\nA complete example game log of v1.0 SGN is included in this repo, [game.log](test-corpus/game.log). This includes over 10 rounds of play, using every example message from this schema.\n\n## Tests\n\nThe [t](t) directory has test scripts in Perl and JavaScript. [messages.json](test-corpus/messages.json) contains example valid and invalid messages used for testing. The Perl tests can be run from the root project directory with `prove`, which require [JSON::Validator](https://metacpan.org/pod/JSON::Validator) and [JSON::XS](https://metacpan.org/pod/JSON::XS):\n\n    $ prove -l\n    prove -l\n    t/messages.t .. ok\n    All tests successful.\n    Files=1, Tests=25,  0 wallclock secs ( 0.02 usr  0.01 sys +  0.19 cusr  0.02 csys =  0.24 CPU)\n    Result: PASS\n\nIf you prefer node.js, you can run the JavaScript tests, which requires [ajv](https://github.com/epoberezkin/ajv):\n\n    $ t/messages.js\n    ok 1 - load schema\n    ok 2 - Build City\n    ...\n    ok 25 - Map Definition: missing harbors\n    1..25\n\n## Definition\n\nA valid SGN document a string of newline-separated JSON messages. The idea is to capture the entirety of a game of Settlers from setup to end. The order of messages is always sequential: an SGN document could describe just the game setup for example. But it couldn't describe the deployment phase unless the setup phase is also defined earlier in the same document.\n\n## Messages\n\nEvery action in a game of Settlers is described in a message format. A message is a JSON array with the following members:\n\n    Index  Value\n    -------------------------------------------------------------------\n    0      The number of the player making the action (\"1\" - \"6\")\n    1      The two letter action code (see Actions below)\n    2      The value associated with the action code (see Events below)\n\n## Hexes\n\nAll hexes (tiles) are numbered, including sea tiles, using the axial (trapezoidal) coordinate system:\n\n               0,-3  1,-3  2,-3   3,-3\n           -1,-2  0,-2  1,-2   2,-2   3,-2\n       -2,-1  -1,-1  0,-1   1,-1   2,-1   3,-1\n    -3,0   -2,0   -1,0    0,0    1,0    2,0    3,0\n       -3,1   -2,1   -1,1   0,1    1,1    2,1\n          -3,2   -2,2   -1,2  0,2    1,2\n             -3,3   -2,3   -1,3  0,3\n\nThis is the same map with the sea tiles represented by tildes (incorrect notation but easier to interpret visually):\n\n             ~~~~  ~~~~  ~~~~   ~~~~\n          ~~~~ 0,-2   1,-2   2,-2  ~~~~\n       ~~~~  -1,-1  0,-1  1,-1  2,-1  ~~~~\n    ~~~~  -2,0   -1,0   0,0   1,0   2,0  ~~~~\n       ~~~~  -2,1   -1,1   0,1   1,1  ~~~~\n          ~~~~  -2,2   -1,2   0,2  ~~~~\n             ~~~~   ~~~~   ~~~~  ~~~~\n\nHex notation is used to define the layout of the board tiles, and other game objects like the location of the robber.\n\n## Tile Codes\n\nA tile can be any one of the `tCode` values below:\n\n    tCode Type\n    --------------\n    H     Hills\n    D     Desert\n    M     Mountains\n    S     Sea\n    F     Fields\n    FO    Forest\n    P     Pastures\n\n## Resource Number\n\nA tile can have one resource number on it (the `rNumber`), valid numbers are between 2-6 and 8-12. There is also a limit on the frequency of resource numbers. These are all the available resource numbers for a basic game:\n\n    2,3,3,4,4,5,5,6,6,8,8,9,9,10,10,11,11,12\n\n## Tile Notation\n\nA tile is defined by its hex coordinates, type code and resource number. This is a central desert tile:\n\n    {\n      tile: [0,0],\n      tCode: \"D\",\n      \"rNumber\": null\n    }\n\n## Intersections\n\nIntersections represent a point between 3 hex locations in a clockwise order. Intersections are represented as an array of 3 hex locations. E.g. the six intersections of the center hex:\n\n                   [[0,-1],[0,0],[-1,0]]\n                           /   \\\n    [[0,-1],[0,0],[-1,0]] /     \\  [[1,-1],[1,0],[0,0]]\n                         |  0,0  |\n                         |       |\n    [[0,0],[-1,1],[-1,0]] \\     /  [[1,0],[0,1],[0,0]]\n                           \\   /\n                   [[0,1],[-1,1],[0,0]]\n\n\nIntersections are used to define the location of settlements and cities.\n\n## Paths\n\nPaths are lines between contiguous intersections and are represented as an array of intersections. Each path must have at least two intersections:\n\n    [ [[0,0],[-1,1],[-1,0]], [[0,1],[-1,1],[0,0]] ]\n\nPaths are used to define where harbors and roads are placed.\n\n## Harbors\n\nHarbors are placed on paths adjacent to sea tiles. There are 6 harbor codes (`hCode`):\n\n    hCode  Type\n    --------------------\n    HR     Generic Harbor\n    HRB    Brick Harbor\n    HRG    Grain Harbor\n    HRL    Lumber Harbor\n    HRO    Ore Harbor\n    HRW    Wool Harbor\n\nTypical maps will have 4 generic harbors and 1 of every other kind.\n\n## Defining the map\n\nEvery tile is listed with its coordinates, type code and resource number. `null` represents no resource number. Harbors are declared at path locations with the harbor type code. A starter map layout:\n\n    {\n      \"tiles\": [\n        {\"tile\":[0,-3],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[1,-3],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[2,-3],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[3,-3],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[3,-2],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[3,-1],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[3,0],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[2,1],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[1,2],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[0,3],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[-1,3],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[-2,3],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[-3,3],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[-3,2],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[-3,1],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[-3,0],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[-2,-1],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[-1,-2],\"tCode\":\"S\",\"rNumber\":null},\n        {\"tile\":[1,-2],\"tCode\":\"P\",\"rNumber\":12},\n        {\"tile\":[2,-2],\"tCode\":\"F\",\"rNumber\":9},\n        {\"tile\":[2,-1],\"tCode\":\"P\",\"rNumber\":10},\n        {\"tile\":[2,0],\"tCode\":\"F\",\"rNumber\":8},\n        {\"tile\":[1,1],\"tCode\":\"M\",\"rNumber\":3},\n        {\"tile\":[0,2],\"tCode\":\"FO\",\"rNumber\":6},\n        {\"tile\":[-1,2],\"tCode\":\"F\",\"rNumber\":2},\n        {\"tile\":[-2,2],\"tCode\":\"M\",\"rNumber\":5},\n        {\"tile\":[-2,1],\"tCode\":\"H\",\"rNumber\":8},\n        {\"tile\":[-2,0],\"tCode\":\"D\",\"rNumber\":null},\n        {\"tile\":[-1,-1],\"tCode\":\"H\",\"rNumber\":4},\n        {\"tile\":[0,-1],\"tCode\":\"M\",\"rNumber\":6},\n        {\"tile\":[1,-1],\"tCode\":\"H\",\"rNumber\":5},\n        {\"tile\":[1,0],\"tCode\":\"FO\",\"rNumber\":4},\n        {\"tile\":[0,1],\"tCode\":\"P\",\"rNumber\":9},\n        {\"tile\":[-1,1],\"tCode\":\"P\",\"rNumber\":10},\n        {\"tile\":[-1,0],\"tCode\":\"FO\",\"rNumber\":3},\n        {\"tile\":[0,0],\"tCode\":\"F\",\"rNumber\":11}\n      ],\n      \"harbors\": [\n        {\"path\":[[[0,-3],[0,-2],[-1,-2]],  [[1,-3],[0,-2],[0,-3]]],   \"hCode\": \"HR\"},\n        {\"path\":[[[2,-3],[1,-2],[1,-3]],   [[2,-3],[2,-2],[1,-2]]],   \"hCode\": \"HRW\"},\n        {\"path\":[[[3,-2],[2,-1],[2,-2]],   [[3,-2],[3,-1],[2,-1]]],   \"hCode\": \"HR\"},\n        {\"path\":[[[3,-1],[3,0],[2,0]],     [[3,0],[2,1],[2,0]]],      \"hCode\": \"HR\"},\n        {\"path\":[[[2,1],[1,2],[1,1]],      [[1,1],[1,2],[0,2]]],      \"hCode\": \"HRB\"},\n        {\"path\":[[[0,2],[-1,3],[-1,2]],    [[-1,2],[-1,3],[-2,3]]],   \"hCode\": \"HRL\"},\n        {\"path\":[[[-2,2],[-2,3],[-3,3]],   [[-2,2],[-3,3],[-3,2]]],   \"hCode\": \"HR\"},\n        {\"path\":[[[-2,1],[-3,2],[-3,1]],   [[-2,0],[-2,1],[-3,1]]],   \"hCode\": \"HRG\"},\n        {\"path\":[[[-1,-1],[-2,0],[-2,-1]], [[-1,-2],[-1,-1],[-2,-1]]],\"hCode\": \"HRO\"}\n      ]\n    }\n\n## Resources\n\nThere are 5 types of resources, defined by their `rCode`:\n\n    rCode  Type\n    ------------\n    B      Brick\n    G      Grain\n    L      Lumber\n    O      Ore\n    W      Wool\n\n## Resources notation\n\nResources notation records which resources and in what quantity are being traded by players with the bank or with each other.\n\nIt uses the resource code (`rCode`) as the key and the value as the quantity. Both quantities gained and lost are listed. So a trade between player 1 and player 2 for 2 lumber for a wool looks like:\n\n    [\n      {\"player\":\"1\", resources:{\"L\":-2,\"W\": 1},\n      {\"player\":\"2\", resources:{\"L\": 2,\"W\":-1}\n    ]\n\nThe implication of this notation is that all resources must balance. For trades with the bank, `B` represents the bank. Here is a bank trade by player 2, losing 4 grain to get a brick:\n\n    [\n      {\"player\":\"2\", resources:{\"G\":-4,\"B\": 1},\n      {\"player\":\"B\", resources:{\"G\": 4,\"B\":-1}\n    ]\n\n## Assets\n\nPlayers may accumulate these throughout the game. There are four normal and two special types:\n\n    Name              How to get it\n    ---------------------------------------------------\n    Development card  Build development card action (BD)\n    Settlement        Build settlement action (BS)\n    City              Build city action (BC)\n    Road              Build road action (BR)\n    Largest army      Largest Army - gained by playing at least 3 knight cards, and more than any other player\n    Longest road      Longest Road - gained by building at least 5 connected roads, and more than any other player\n\nThere are 5 types of development cards:\n\n    cCode  Name\n    --------------------\n    KN     Knight\n    MO     Monopoly\n    RB     Road building\n    VP     Victory Point\n    YP     Year of plenty\n\n## Actions\n\nActions are taken by players. Every message in SGN is an action, consisting of an action code and a JSON object or array:\n\n    aCode Name                    Value\n    --------------------------------------------------------------------------------------\n    BC    Build City              {\"player\":\"#\",\"intersection\":\u003cintersection coordinates\u003e}\n    BD    Build Development card  {\"player\":\"#\",cCode\": \"KN|MO|RB|VP|YP\"}\n    BR    Build Road              {\"player\":\"#\",path\":\u003cpath coordinates\u003e}\n    BS    Build Settlement        {\"player\":\"#\",intersection\":\u003cintersection coordinates\u003e}\n    DM    Define Map              {\"tiles\":[...], \"harbors\":[...]}\n    MR    Move Robber             {\"tile\": \u003ctile coordinates\u003e}\n    PD    Play Development card   {\"cCode\": \"KN|MO|RB|VP|YP\", \"rCodes\":[]}\n    RD    Roll Dice               {\"result\":#}\n    ST    Steal                   [\u003cresource notation\u003e]\n    TR    Trade                   [\u003cresource notation\u003e]\n\nPlay Development card has an optional value: `rCodes`. This is required when playing Year of Plenty or Monopoly development cards and is an array containing the resources codes for the event. Monopoly can only ever be declared on one resource. Here is an example of playing Monopoly for Ore:\n\n    [\"2\",\"PD\",{\"cCode\":\"MO\",\"rCodes\":[\"O\"]}]\n\nThe player using Year of Plenty can declare up to two different resources, e.g. Grain and Brick:\n\n    [\"2\",\"PD\",{\"cCode\":\"YP\",\"rCodes\":[\"G\",\"B\"]}]\n\nOther development cards do not require the `rCodes` property.\n\n## Trading\n\nTrading is a big part of Settlers. Players may trade with each other or with the Bank.\n\nBank trades are described using the trade action. For example, here's a trade between the Bank (\"B\") and player 2:\n\n    [\n      \"2\",\n      \"TR\",\n      [\n        {\"player\":\"2\",\"resources\":{\"B\":1,\"O\":-4}},\n        {\"player\":\"B\",\"resources\":{\"B\":-1,\"O\":4}}\n      ]\n    ]\n\nHere is an example trade between player 1 and player 2:\n\n    [\n      \"2\",\n      \"TR\",\n      [\n        {\"player\":\"1\",\"resources\":{\"B\":-1,\"O\":-1,\"L\":1}},\n        {\"player\":\"2\",\"resources\":{\"O\":1,\"B\":1,\"L\":-1}}\n      ]\n    ]\n\n## Players\n\nPlayers are just string identifiers that refer to a player of the game or the banker. Player \"1\" is always the player that goes first, up until player \"6\" (the maximum number of players).\n\nOne player name is special and reserved: `B` refers to the banker.\n\n## See Also\n\n* [Pioneers](http://pio.sourceforge.net/) an open source implementation of the island colonization game.\n\n* [JSettlers](http://nand.net/jsettlers/) another open source, Java based version\n\n* [Catan](http://playcatan.com) the official website for Settlers of Catan.\n\n## Notation Version\n\n1.0\n\n## Notation Change History\n\n## 1.0 2016-11-06\n\nThe object schema has been changed to array. This is easier to read and avoids key sorting issues with dynamic languages. Compare these v0.4 messages:\n\n    {\"value\":{\"tile\":[\"-2\",\"0\"]},\"player\":\"1\",\"aCode\":\"MR\"}\n    {\"aCode\":\"BS\",\"player\":\"1\",\"value\":{\"intersection\":[[\"0\",\"-2\"],[\"-1\",\"-1\"],[\"-1\",\"-2\"]]}}\n    {\"value\":{\"path\":[[[\"0\",\"-2\"],[\"-1\",\"-1\"],[\"-1\",\"-2\"]],[[\"0\",\"-2\"],[\"0\",\"-1\"],[\"-1\",\"-1\"]]]},\"aCode\":\"BR\",\"player\":\"1\"}\n    {\"player\":\"2\",\"aCode\":\"BS\",\"value\":{\"intersection\":[[\"0\",\"2\"],[\"-1\",\"3\"],[\"-1\",\"2\"]]}}\n\nWith the same messages in v1.0 SGN:\n\n    [\"1\",\"MR\",{\"tile\":[\"-2\",\"0\"]}]\n    [\"1\",\"BS\",{\"intersection\":[[\"0\",\"-2\"],[\"-1\",\"-1\"],[\"-1\",\"-2\"]]}]\n    [\"1\",\"BR\",{\"path\":[[[\"0\",\"-2\"],[\"-1\",\"-1\"],[\"-1\",\"-2\"]],[[\"0\",\"-2\"],[\"0\",\"-1\"],[\"-1\",\"-1\"]]]}]\n    [\"2\",\"BS\",{\"intersection\":[[\"0\",\"2\"],[\"-1\",\"3\"],[\"-1\",\"2\"]]}]\n\n## 0.4 2016-10-26\n\nThe schema has been tested and the version bumped to 0.4, to match `schema/` directory structure. A complete example game log in 0.4 SGN is also provided. This version is ready to be used.\n\n### 0.04 2016-10-06\n\nEvents are now called Actions. The idea is to strip out anything that can be inferred and only record what is left. Server type attributes like \"UUID\" are not required.\n\n### 0.03 2015-12-24\n\nMessages can include a batch value. Added the trade decline event. Changed the definition of tiles and harbors to be objects rather than arrays. Resource notation is now an array of objects that include a player property. Removed `player` from every event value, except for Player Add (it was redundant). Types of things are identified by new names: `tCodes` for tile codes, `hCodes` for harbor codes and `cCodes` for development card codes. Added new `VI` event type. Defined SGN schemas for log and messages.\n\n### 0.02 2015-11-25\n\nPorts are declared on paths instead of tiles. SGN messages have event code, value, sender and UUID attributes.\n\n### 0.01 2015-11-20\n\nInitial release\n\n## Author\n\nDavid Farrell, \u0026copy; 2016\n\n## License\n\nFreeBSD, see LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnmfarrell%2Fsettlers-game-notation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdnmfarrell%2Fsettlers-game-notation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnmfarrell%2Fsettlers-game-notation/lists"}