Difference between revisions of "Design Document Game Boxes"

From BOARD18 Project WIKI
Jump to navigation Jump to search
(added {{Design Document Index}})
 
(43 intermediate revisions by the same user not shown)
Line 1: Line 1:
BOARD18 can be used to play any [http://en.wikipedia.org/wiki/18xx 18xx style game] for which a game box exists. A game box consists of the graphics files and control tables that describe the game board, the stock market and the various playing pieces. A game box is built using a graphics editor (such as GIMP) and a text editor. The files created with these tools can then be uploaded to the BOARD18 server. This upload should eventually be accomplished via a built-in and automatic process. '''[[Game Boxes|<span style="color: Green">A game box list can be found here.</span>]]'''
{{ReleaseNotice|2.5}}{{Design Document Index}}
{{Design Document Index}}
BOARD18 can be used to play any [http://en.wikipedia.org/wiki/18xx 18xx style game] for which a game box exists. A game box consists of the graphics files and control tables that describe the game board, the stock market and the various playing pieces. A game box is built using a graphics editor (such as GIMP) and a text editor. The files created with these tools are then packaged and uploaded to the BOARD18 server. This upload is accomplished via a built-in administrative facility.
== Graphics Files==
{{Game Box Index}}
== Graphics Standards==
=== Tile Orientation ===
 
[[File:Hexdim.png|frame]]
Historically most 18xx game boards had a hex grid orientated with the
points of the hexes facing North and South as is shown in the diagram to the right.
But a number of game boards [especially newer ones] have a hex grid orientation that is rotated 30 degrees
from this orientation. BOARD18 can handle both orientations.
 
This document will refer to map boards in the first orientation as "Point Up" or
Type P map boards. And it will refer to map boards
in the other orientation as "Flat Side Up" or Type F map boards.
 
'''[[Type_%22F%22_Board_Map_Glitch|<span style="color: Green">This note</span>]] describes a potential problem with some Type F map boards.'''
 
=== Size Standards===
=== Size Standards===


In order to coordinate the size of the various graphics files, so that things fit together, BOARD18 will use the following sizing standards. Note that some of the Control Table settings can be used to resize the uploaded graphics to meet these standards.
In order to coordinate the size of the various graphics files, so that things fit together,  
BOARD18 will use the following sizing standards. Except as stated below all graphics must
be sized to follow these standards.


==== Hex Tile Standard====
==== Hex Tile Standard====


[[File:Hexdim.png|frame]]All tiles should be sized as shown in the diagram to the right when displayed by BOARD18. If the Tile Sheet control values are correct, then this resizing should be done automatically.
All tiles should be sized as shown in the diagram above and to the right when displayed in
Type P orientation. Tiles displayed in Type F orientation will, of course,
be rotated by 30 degrees. Thus they will be 100 pix high and 116 pix wide.


==== Token Standard====
==== Token Standard====


All circular tokens should be sized to have a diameter of 30 pix. All Square tokens should be sized to have a width and height of 30 pix. Once again, resizing via the control values should be supported.
Most circular tokens should be sized to have a diameter of 30 pix. Most Square tokens should  
be sized to have a width and height of 30 pix. But some 18xx games require odd sized tokens
for special purposes. For example the destination markers in 18QQ. The game box standard has
provisions to accommodate odd sized tokens.
 
=== Graphics Files===
A BOARD18 Game Box will contain four types of graphics files.


=== Game Board===
==== Game Board Files====


The game board graphic is the background of the BOARD18 board page. As with tiles and tokens, scaling can be controlled by the Game Board control values .
[[File:GreenFragment.png|frame]]The game board graphic is the background of the BOARD18 game
board page. As with tiles and tokens all Game Board graphics must be sized correctly. That is
the hex grid must fit tiles sized to the above standard.


=== Stock Market===
==== Stock Market Files====


[[File:1826YellowFragment.png|frame]][[File:1826TokenFragment.png|frame]]The stock market graphic is the background of the BOARD18 stock market page. Scaling can be controlled by the Stock Market control values.
The stock market graphic is the background of the BOARD18 stock market page.  
All Stock Market graphics must be sized with market boxes large enough to contain tokens correctly.


=== Tiles===
==== Tile Sheets====


Hex tile graphic images are grouped onto “tile sheets” containing rows and columns of evenly spaced tiles. The illustration to the right shows a part of such a tile sheet. Each column is a different tile and each row in the column is a 60° rotation of the tile. There can be from one to six rows for each tile.
Hex tile graphic images are grouped onto “tile sheets” containing rows and columns of evenly spaced tiles. The illustration to the right shows a part of such a tile sheet. Each column is a different tile and each row in the column is a 60° rotation of the tile. There can be from one to six rows for each tile.


=== Tokens ===
==== Token Sheets ====


Token graphic images are grouped onto “token sheets” containing rows and columns of evenly spaced tokens. The illustration to the right shows a part of such a token sheet. Each sheet will contain one or two columns of circular or square tokens. Each row in the column is a different token. If there are two columns then the image in the first shows the front side of the token and the second shows the back side.
Token graphic images are grouped onto “token sheets” containing rows and columns of evenly spaced tokens. The illustration to the lower right shows such a token sheet. Each sheet will contain one or two columns of circular or square tokens. Each row in the column is a different token. If there are two columns then the image in the first shows the front side of the token and the second shows the back side.


== Control Structures==
== Control Structures==


In addition to the graphics files described in the above section, a BOARD18 game box also consists of a number of control structures. The actual game status also consists of control structures. These are formatted as two complex JSON data structures: one for the game box and one for the game session. Each of these structures is created and maintained as a single JSON file. And each is stored as a text field in the MYSQL database.
[[File:1870Tokens.png|frame]]In addition to the graphics files described in the above section, a BOARD18 game box also consists of a number of control structures. The actual game status also consists of control structures. These are formatted as two complex JSON data structures: one for the game box and one for the game session. Each of these structures is created and maintained as a single JSON file. And each is stored as a text field in the MYSQL database.
 
[[Media:1826box.json.zip|This zip file]] contains a listing of the test game box file that is being used in the development of the BOARD18 application. (It is actually a game box for 1826.) The game box file is common to all game sessions and it is never modified by BOARD18.
 
[[Media:game.json.zip|This zip file]] contains a listing of the initial game session file that is created by the the new game function of the BOARD18 application. This JSON structure will be constantly modified by BOARD18 during the course of the game.  


Do to the complexity of these structures, we will discuss them in detail in the following sub sections..
We will discuss these structures in the following sub sections. But a more detailed description of the game box structure can be found at these two pages: <br>[[Game_Box_Creation_-_Control_File_Syntax|Game Box Syntax]]
and [[Game_Box_Creation_-_Control_File_Semantics|Game Box Semantics]]


=== The JSON Box Data Structure===
=== The JSON Box Data Structure===


Th first part of the game box JSON file contains data structures that define the file itself, the game board and the stock market board. The '''bname''', '''version''' and '''author''' keys are used to identify the JSON file itself. The '''board''' and '''market '''keys head complex structures that define the game map and the stock market. They each contain fields that define the location and size of the graphic and positioning of its grid.
Th first part of the game box JSON file contains data structures that define the file itself, the game board and the stock market board. The '''bname''', '''version''' and '''author''' keys are used to identify the JSON file itself. The '''board''' and '''market '''keys head complex structures that define the game map and the stock market. They each contain fields that define the location of the graphic file and positioning of its grid.


=== The JSON Tray Data Structure===
=== The JSON Tray Data Structure===
Line 56: Line 81:
==== The Board Token Sheet Type====
==== The Board Token Sheet Type====


The sheets with a type value of '''btok''' are board token sheets. The first part of a board token sheet is the same as a tile sheet. But there is no '''tile''' key. Instead a token key defines an array of values (one for each token) that specify the the number of duplicates of that token in the game box and whether the token can be flipped. (i.e.: does it have a back side.)
The sheets with a type value of '''btok''' are board token sheets. The first part of a board token sheet is the same as a tile sheet. But there is no '''tile''' key. Instead a '''token''' key defines an array of values (one for each token) that specify the the number of duplicates of that token in the game box and whether the token can be flipped. (i.e.: does it have a back side.)


==== The Market Token Sheet Type====
==== The Market Token Sheet Type====


The sheets with a type value of '''mtok''' are market token sheets. A market token sheet is the same as a board token sheet with one exception. The token key defines an array of values (one for each token) that specify only whether the token can be flipped. There is no 'number of duplicates' field for '''mtok'''.
The sheets with a type value of '''mtok''' are market token sheets. A market token sheet is the same as a board token sheet with one exception. The '''token''' key defines an array of values (one for each token) that specify only whether the token can be flipped. There is no 'number of duplicates' field for '''mtok'''.
 
=== The JSON Game Session Data Structure===


Each game session has its own JSON data structure. The '''gname''', and '''boxID''' keys are used to identify the JSON Game Session and specify the game box that the game session uses. These are followed by four array structures.
=== The JSON Links Data Structure===


The array with the key of '''brdTls''' tracks the tiles that have been placed on the board. The array with the key of '''brdTks''' tracks the tokens that have been placed on the board. The array with the key of '''mktTks''' tracks the tokens that have been placed on the stock market. And the array with the key of '''trayCounts''' tracks the number of remaining tiles and tokens available to be played on the game board.
The data structure in the game box JSON file with the key of '''links''' defines the HTTP links associated with the game box.  
It is an array of data structures each of which describes a link to a useful file that is associated with the game box.


[[Category:Design]]
[[Category:Design]]

Latest revision as of 08:52, 21 December 2018

This page has been updated to comply with Release 2.5.x of BOARD18.
Design Document edit


BOARD18 can be used to play any 18xx style game for which a game box exists. A game box consists of the graphics files and control tables that describe the game board, the stock market and the various playing pieces. A game box is built using a graphics editor (such as GIMP) and a text editor. The files created with these tools are then packaged and uploaded to the BOARD18 server. This upload is accomplished via a built-in administrative facility.

Game Boxes edit


Graphics Standards

Tile Orientation

Hexdim.png

Historically most 18xx game boards had a hex grid orientated with the points of the hexes facing North and South as is shown in the diagram to the right. But a number of game boards [especially newer ones] have a hex grid orientation that is rotated 30 degrees from this orientation. BOARD18 can handle both orientations.

This document will refer to map boards in the first orientation as "Point Up" or Type P map boards. And it will refer to map boards in the other orientation as "Flat Side Up" or Type F map boards.

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

Size Standards

In order to coordinate the size of the various graphics files, so that things fit together, BOARD18 will use the following sizing standards. Except as stated below all graphics must be sized to follow these standards.

Hex Tile Standard

All tiles should be sized as shown in the diagram above and to the right when displayed in Type P orientation. Tiles displayed in Type F orientation will, of course, be rotated by 30 degrees. Thus they will be 100 pix high and 116 pix wide.

Token Standard

Most circular tokens should be sized to have a diameter of 30 pix. Most Square tokens should be sized to have a width and height of 30 pix. But some 18xx games require odd sized tokens for special purposes. For example the destination markers in 18QQ. The game box standard has provisions to accommodate odd sized tokens.

Graphics Files

A BOARD18 Game Box will contain four types of graphics files.

Game Board Files

GreenFragment.png

The game board graphic is the background of the BOARD18 game

board page. As with tiles and tokens all Game Board graphics must be sized correctly. That is the hex grid must fit tiles sized to the above standard.

Stock Market Files

The stock market graphic is the background of the BOARD18 stock market page. All Stock Market graphics must be sized with market boxes large enough to contain tokens correctly.

Tile Sheets

Hex tile graphic images are grouped onto “tile sheets” containing rows and columns of evenly spaced tiles. The illustration to the right shows a part of such a tile sheet. Each column is a different tile and each row in the column is a 60° rotation of the tile. There can be from one to six rows for each tile.

Token Sheets

Token graphic images are grouped onto “token sheets” containing rows and columns of evenly spaced tokens. The illustration to the lower right shows such a token sheet. Each sheet will contain one or two columns of circular or square tokens. Each row in the column is a different token. If there are two columns then the image in the first shows the front side of the token and the second shows the back side.

Control Structures

1870Tokens.png

In addition to the graphics files described in the above section, a BOARD18 game box also consists of a number of control structures. The actual game status also consists of control structures. These are formatted as two complex JSON data structures: one for the game box and one for the game session. Each of these structures is created and maintained as a single JSON file. And each is stored as a text field in the MYSQL database.

We will discuss these structures in the following sub sections. But a more detailed description of the game box structure can be found at these two pages:
Game Box Syntax and Game Box Semantics

The JSON Box Data Structure

Th first part of the game box JSON file contains data structures that define the file itself, the game board and the stock market board. The bname, version and author keys are used to identify the JSON file itself. The board and market keys head complex structures that define the game map and the stock market. They each contain fields that define the location of the graphic file and positioning of its grid.

The JSON Tray Data Structure

The data structure in the game box JSON file with the key of tray defines the tile and token sheets in the game box. It is an array of complex data structures each of which describes a tile or token sheet. There are actually three different types of sheets on a tray. The type key defines the type for each sheet in the array.

The Tile Sheet Type

The sheets with a type value of tile are tile sheets. The tName key defines the menu name for the sheet. The imgLoc key defines the location of the tile sheet image file. The next group of keys define the values that locate the actual tiles on the tile sheet image file.

Finally the tile key defines an array of values (one for each tile) that specify the the number of duplicates of that tile in the game box and the number of rotations that exist for each tile.

The Board Token Sheet Type

The sheets with a type value of btok are board token sheets. The first part of a board token sheet is the same as a tile sheet. But there is no tile key. Instead a token key defines an array of values (one for each token) that specify the the number of duplicates of that token in the game box and whether the token can be flipped. (i.e.: does it have a back side.)

The Market Token Sheet Type

The sheets with a type value of mtok are market token sheets. A market token sheet is the same as a board token sheet with one exception. The token key defines an array of values (one for each token) that specify only whether the token can be flipped. There is no 'number of duplicates' field for mtok.

The JSON Links Data Structure

The data structure in the game box JSON file with the key of links defines the HTTP links associated with the game box. It is an array of data structures each of which describes a link to a useful file that is associated with the game box.