Render Schema Documentation
Games on the Abstract Play service must produce representations of the play area based on this schema. The front-end renderer will then translate that into various forms. The
description fields in the schema itself are rather curt because JSON doesn’t allow niceties like multi-line strings. So this file is intended to give you complete instructions on how to build an instance of this schema.
This document describes version 1.0.0 of the schema.
The JSON file represents the game table.
At the very least, the table must contain a
board, upon which one places
The table can also have multiple
areas, which get placed vertically below the board in the order provided. These are used by specialized renderers for showing things like global stashes or previous game states.
This section walks through each of the properties of the schema and explains what they’re for and how to use them. The
definitions section is only there for convenience of notation and is not itself discussed.
This tells the renderer which engine to use. The following engines are available:
This is the renderer used by most games. It does not support stacked pieces.
This works almost identically to the
defaultengine but supports stacking multiple pieces in a single space.
This engine generates Homeworlds boards only.
Here you map references to glyphs and their options to (usually) single characters used to represent pieces in the
pieces property. For player pieces, you need to use the object schema that includes the
player property. For most other pieces, you’ll just have a string that points to the glyph you want.
Glyphs are resolved based on user settings. The renderer will look at each glyph sheet in order until it finds the first implementation of that glyph. If it fails, an error will be thrown.
If you pass an array of glyphs, they are simply layered over each other, creating a composite piece. The object form supports the following options
This marks the piece as belonging to a specific player. The fill colour will be chosen based on user settings. This is the preferred way to assign colours to pieces.
A 3- or 6-digit hex colour value. This should only be used for tweaking composite pieces. Do not use this to assign player colours, which should be determined by player settings. Use the
playerproperty for that. This setting is ignored if
playeris also defined.
This is a factor for growing or shrinking a glyph. Values <1 cause the glyph to shrink. Values >1 cause it to grow.
Applies an opacity to the entire glyph. A number between 0 and 1 where 0 is completely transparent.
A number between -360 and 360 representing the number of degrees to rotate the glyph. A negative value rotates counterclockwise.
A way of nudging a glyph off mathematical centre. Negative values nudge the piece up and to the left.
Now for the game board itself. This is rendered first, followed by the pieces. There are only two options currently.
The first is a set of preset boards, which includes the following:
A grid of squares, all of the same colour.
squaresbut alternating dark and light colours. The bottom-left cell is always dark.
Pieces are placed on the intersections of a grid of squares.
vertexbut with small nodes at the traditional points, if the board is one of the traditional sizes. Otherwise it renders exactly like
A pointy-topped hex grid where the odd-numbered rows are indented.
A pointy-topped hex grid where the even-numbered rows are indented.
A flat-topped hex grid where the odd-numbered rows are indented.
A flat-topped hex grid where the even-numbered rows are indented.
A hex-shaped board composed of hexagons.
A hex-shaped board composed of triangles.
A basic snub square grid.
The Homeworlds-specific schema is next and is adequately described there.
Now that the board has been rendered, and there are spaces for the pieces, here’s where you define where those pieces go. There are a few different ways of approaching this.
First is a simple string. Each pieces must be represented by only a single character, mapped in the
\nto separate rows (the first row is the top row). Hyphens represent a single blank space. Underscores represent an entire empty row. Commas and whitespace are forbidden.
This option is also a simple string but it uses commas to separate cells. This allows you to use multiple characters per cell. How multi-character cells are handled depends on the renderer. The default renderer just looks for a matching
legendentry. But a stacking renderer will assume each character is a piece in a stack.
You still use
\nto separate rows (the first row is the top row), and whitespace is still forbidden. Hyphens are not reserved (just don’t put anything after the comma to represent blankk spaces), but underscores still represent blank rows.
This nested-array approach is more explicit but also more verbose. Each top-level array is a row (the first row is the top row). Each row is itself an array of cells in that row (from left to right). And each cell is itself an array of pieces in that cell.
Different renderers will handle this differently. The default renderer will simply layer the glyphs on top of each other. A stacking renderer will try to stack the pieces.
Finally is the Homeworlds schema. This is also an array of arrays. Each top-level array is a system, and each of those contains an array of ships. The systems must be declared in the same order as in the
boardproperty. The renderer will deal with positioning the systems on the playing surface.
This section is unique to different renderers. The default renderer ignores it. The Homewords renderer uses it for the global stash. Each area is rendered vertically below the game board.
This is how a game tells the renderer how illustrate state changes. Most commonly it’s a simple arrow showing where a piece moved from and to. But more complex ones will be made available as needed.
This property is an array of each player in player order. The front end can use this information to render a helpful sidebar identifying pieces a player controls, running scores, etc.
The default renderer will only process
score. Any additional properties will need to be handled by a specific renderer.