Minigame Scripting

Introduction

Game sessions are bound to a game board (action location) and identified by a unique name. The name of the game board is defined in the action_locations table (name field). The game itself is defined in the gameboards db table.

Gameboards Database Table

These are the fields specified by the gameboards db table:

name	numColumns	numRows	layout	pieces	numPlayers	gameboardOptions	gameRules	endgames
game's name (must be unique)	number of board's columns	number of board's rows	layout of the row/columns in a string format	type of pieces in a string format (allowed pieces: 1234567890ABCDE)	number of players, 2 default, 1 for single player games	game options (default: White,Checked) White/Black (colors the board white or black), Plain (makes it one color), Checked (checkerboard)	specify the game rules in XML format	specify the end-game rules (winning conditions) in XML format

Example Database Entry:

 'Tic Tac Toe', 3, 3, '000000000', '12', 2, 'White,Plain', "<GameRules>...</GameRules>", " <MGEndGame>...</MGEndGame>"

Action Locations Entry

The response string specifies the name to the record in gameboards and an optional prepared layout is expected to have the following format:

* <Examine>
*  <GameBoard Name='gameboard name' [Layout='board layout'] [Session='personal'|'public'] [EndGame='yes'|'no'] />
*  <Description>Description as seen by players</Description>
* </Examine>

An action location example:

 <Examine>
  <GameBoard Name='Weather game' EndGame='Yes' Script='rain' Layout="10000000A" Session="personal"/>
  <Description>Magic puzzle that makes it rain.</Description>
 </Examine>

 <Examine>
   <GameBoard Name='Tic Tac Toe' EndGame='Yes' Script='minigame_win' />
   <Description>Tic Tac Toe Board Game with $$$ prizes $$$.</Description>
 </Examine>

The Layout attribute defines the layout of the game board and optionally also preset game pieces on it. Optional - to override the default.

The Session attribute allows a game to be personal (restricted to one-player games) whereby only the player sees the game, no other players or watchers. One such minigame at one action_location can spawn a session per player who plays their own private game. Set to public is for the traditional board game, and is the default if this option is omitted.

The EndGame attribute specifies whether this game session is to adhere to the end game rules, it's Optional and Default is No.

The Script option allows name a Progression Event script to run when the gameboard meets the end game rules. The following variables are defined by the code:

• Winner
• Loser
• Target
• Actor

In the future we will add more attributes like for game options and name of a plugin or script for managed games.

Every session can have 0, 1, 2 or more players attached to it. The first player gets white game pieces and the second player black game pieces. All other players can just watch the game.

Game Rules

PlayerTurns can be:

• Ordered (order of players' moves enforced),
• StrictOrdered (as Ordered, and all players must be present),
• Relaxed (default - free for all).

MoveType can be:

• MoveOnly (player can only move existing pieces),
• PlaceOnly (player can only place new pieces on the board; cant move others),
• PlaceOrMovePiece (default - either move existing or place new pieces).

MoveablePieces can be:

• Own (player can only move their own pieces),
• Any (default - player can move any piece in play).

MoveTo can be:

• Vacancy (player can move pieces to vacant squares only),
• Anywhere (default - can move to any square, vacant or occupied).

MoveDistance can be: an integer number, it's optional and enforce the maximum distance a piece can be moved, default is any distance.

MoveDirection can be:

• Vertical
• Horizontal
• Cross
• Diagonal

it's optional and enforce the direction a piece can be moved, default is any direction. Combined with MoveDistance a rule can be defined to enforce distance and direction of a movable piece.

Example:

 <GameRules>
   <Rules PlayerTurns="StrictOrdered" MoveType="MoveOnly" MoveablePieces="Own" MoveTo="Vacancy" />
 </GameRules>

Another example:

 <GameRules>
  <Rules MoveType="PlaceOnly" MoveTo="Anywhere" MoveDistance="2" MoveDirection="Cross" />
 </GameRules>

End Game Rules

Decipher the end game rules in XML format

<MGEndGame>
 <EndGame Coords="relative"/"absolute" [SourceTile="T"] [Winner="T"]>
  <Coord Col="?" Row="?" Tile="T" [Piece="?"]/>
 </EndGame>
</MGEndGame>

Param	Value	Optional	Description
Coords	relative or absolute	no	tells the server if the coordinates of a tile in the game board are absolute or not
SourceTile	Tile Types	yes	(optional)
Winner	Tile Types	yes	winner is white or black player
Col	integer	no	column number
Row	integer	no	row number
Tile	Tile Types	no	the type of tile
Piece	[1,..., 9, A, ..., E]	yes	if the Tile Types is "S" you can choose which piece must be in the Coords position

Example:

 <MGEndGame>
 <EndGame Coords="absolute">
   <Coord Col="0" Row="0" Tile="A" />
   <Coord Col="1" Row="0" Tile="A" />
   <Coord Col="2" Row="0" Tile="A" />
   <Coord Col="0" Row="1" Tile="A" />
   <Coord Col="0" Row="2" Tile="A" />
 </EndGame>
 <EndGame Coords="absolute">
   ...
 </EndGame>
 </MGEndGame>

Example 2:

 <MGEndGame>
 <EndGame Coords="relative" SourceTile="A">
   <Coord Col="1" Row="0" Tile="F" />
   <Coord Col="2" Row="0" Tile="F" />
 </EndGame>
 <EndGame Coords="relative" SourceTile="A">
   <Coord Col="0" Row="1" Tile="F" />
   <Coord Col="0" Row="2" Tile="F" />
 </EndGame>
 <EndGame Coords="relative" SourceTile="A">
   <Coord Col="1" Row="1" Tile="F" />
   <Coord Col="2" Row="2" Tile="F" />
 </EndGame>
 <EndGame Coords="relative" SourceTile="A">
   <Coord Col="-1" Row="1" Tile="F" />
   <Coord Col="-2" Row="2" Tile="F" />
 </EndGame>
 </MGEndGame>

Tile Types

The following types of tiles can be specified in the end game rules:

Name	Description
A	tile has any played piece on
W	tile has white piece
B	tile has black piece
E	empty tile (no tile)
F	tile has piece as per first tile in pattern
S	specific tile: allows to specify the exact piece in the rule, the allowed pieces are defined in Gameboards Database Table