Game Box Creation - Control File Semantics

From BOARD18 Project WIKI
Revision as of 13:36, 21 May 2020 by Rich (talk | contribs) (→‎Orientation Value: added note)
Jump to navigation Jump to search
Game Box Creation edit

You may also want to look at the design document for more information about game boxes.

Before starting work on the JSON file, you should create the image files for your game box.

Text Values

The start of the JSON file contains a number of text values. There are also some text values at the start of some top level objects in the file. These values are discussed here.

Box Descriptor Values

The start of the JSON file contains three values that together should uniquely identify this game box.

  1. "bname": the name of the game. EG: "1870" or "1826".
  2. "version": I use my initials combined with a sequential number. EG: "REP01"
  3. "author": your name. EG: "Rich Price"

Image Location Value

Each image has an "imgLoc" value that specifies the relative location of the image file. For the provided directory structure this will always have this form "images/nnnn/file.png" where nnnn is the game name and file.png is the name of the image file.

Orientation Value

The hex grid on the map board will either be in "Point Up" orientation or in "Flat Side Up" orientation.
Map boards that are in "Point Up" orientation will be referred to as Type P map boards.
Map boards that are in "Flat Side Up" orientation will be referred to as Type F map boards.
The "orientation" value in the "board" object will be set to either "P" or "F" to indicate the orientation of the map board's hex grid.
For backward compatibility a missing "orientation" value will default to "P".

This note describes a potential problem with some Type F map boards.

Tray Values

Each tray object has two text values.

  1. "type": the tray type will be one of three values : "tile" for a tile tray, "btok" for a game board token tray or "mtok" for a stock market token tray. The format of each of these three tray types is different from the other two.
  2. "tName": the name of the tray which will appear in the tray menu. EG: "Yellow Tiles".

Measured Numeric Values

You will have to determine a number of measurements for each image file. These will make up most of the numeric values in the JSON file. These two sub-sections discuss this process for each image file type.

Game Board Image File

  • Measure the distance in pixels from the left edge of the image to the start of the first [left most] hex on the map. This is the "xStart" value.
  • Measure the distance in pixels from start of the left most hex on the map to the start of the second left most hex on the map. These two hexes will not be on the same row on a "Point Up" orientation map. On a properly scaled image file this will always be 50 pixels for "Point Up" orientation and 87 pixels for "Flat Side Up" orientation. This is the "xStep" value.
  • Measure the distance in pixels from the top edge of the image to the start of the first [top most] hex on the map. This is the "yStart" value.
  • Measure the distance in pixels from start of the top most hex on the map to the start of the second top most hex on the map. These two hexes will not be in the same column on a "Flat Side Up" orientation map. On a properly scaled image file this will always be 87 pixels for "Point Up" orientation and 50 pixels for "Flat Side Up" orientation. This is the "yStep" value.
  • This note describes a potential problem with some Type F map boards.

Stock Market Image File

  • Measure the distance in pixels from the left edge of the image to the start of the first [left most] price box in the market. This is the "xStart" value.
  • Measure the distance in pixels from start of the left most price box in the market to the start of the second left most price box in the market. This is the "xStep" value.
  • Measure the distance in pixels from the top edge of the image to the start of the first [top most] price box in the market. This is the "yStart" value.
  • Measure the distance in pixels from start of the top most price box in the market to the start of the second top most price box in the market. This is the "yStep" value.

Tile and Token Sheet Image Files

If you created your sheets using the fixed size Python scripts described here, then you can use the standard values shown below for these image files. If not, then you should use this procedure to develop these values.

  • Measure the distance in pixels from the left edge of the image to the start of the first [left most] tile or token on the sheet. This is the "xStart" value.
  • Measure the width in pixels of a tile or token on the sheet. On a properly scaled image file this will always be 100 pixels. This is the "xSize" value.
  • Measure the distance in pixels from start of the left most tile or token on the sheet to the start of the second left most tile or token on the sheet.
    On a single column token sheet this value is not used and could be zero. This is the "xStep" value.
  • Measure the distance in pixels from the top edge of the image to the start of the first [top most] tile or token on the map. This is the "yStart" value.
  • Measure the hight in pixels of a tile or token on the sheet. On a properly scaled image file this will always be 116 pixels. This is the "ySize" value.
  • Measure the distance in pixels from start of the top most tile or token on the map to the start of the second top most tile or token on the map. This is the "yStep" value.

If a tile sheet has been generated by the BD18-new-tile-P-sheet.py and BD18-add-tile-P-to-sheet.py scripts within GIMP then these values will be:

    "xStart":20, 
    "xSize":100, 
    "xStep":120, 
    "yStart":20, 
    "ySize":116, 
    "yStep":130,  

If a tile sheet has been generated by the BD18-new-tile-F-sheet.py and BD18-add-tile-F-to-sheet.py scripts within GIMP then these values will be:

    "xStart":20, 
    "xSize":116, 
    "xStep":130, 
    "yStart":20, 
    "ySize":100, 
    "yStep":120, 

If a token sheet has been generated by the BD18-new-token-sheet.py and BD18-add-token-to-sheet.py scripts within GIMP then these values will be:

    "xStart":10, 
    "xSize":30, 
    "xStep":40, 
    "yStart":10, 
    "ySize":30, 
    "yStep":40, 

Other Tray Objects

Each of the three tray objects contains a different tile or token object. These objects are arrays that contain one object per tile or token on the sheet.
These array element objects contain simple objects and are defined here.

Array Element Objects in "tile" Trays

  • "dups": the number of available tiles of this type. The Blackwater Station Tile Manifests have these counts.
    Versions 2.4.1 and higher will allow an umlimited number of tiles of this type if the "dups"field contains 0 (zero).
  • "rots": the number of rotation images for this tile. Just count the tile images in the column.

Array Element Objects in "btok" Trays

  • "dups": the number of available tokens of this type.
    Versions 2.4.1 and higher will allow an umlimited number of tokens of this type if the "dups"field contains 0 (zero).
  • "flip": true if this is a 2 sided token.

Array Element Objects in "mtok" Trays

  • "flip": true if this is a 2 sided token.

Link Objects

Each object pair in the "link" array contains a link to a web page and that link's name.
These array element objects each contain two simple objects that are defined here.

  • "link_name": Name that will appear in the useful links menu item.
  • "link_url": URL for this link in the useful links menu item.

The BOARD18 project maintains a public folder on Google Drive that contains rules and related files for 18XX games.
This folder is at drive.google.com/drive/folders/0B-wwptMMyHTAZHpJODJ4OGc5SVk.
If you wish to add a file to this folder then Email the file to rich at board18.org.