Gameboard

[DRAFT]

The GameBoard library

A reusable and configurable system for game-like challenges.

[TODO]

• Board quick setup
• Creating and placing a gamepiece
• Pathfinding
• Styling concepts
• Custom board setup

GameBoard quick setup

Here's an example to quickly get up and running:

from gameboard import GameBoard
from gameboard_helpers import CommonSetups, Style

tiles = {
  'grass': {'color': 'green', 'line_color': 'darkgreen'},
  'mud': {'color': 'brown','line_color': 'darkgrey'}
}

class Challenge:
  fn __init__(self, context):
    ...
    board = GameBoard()
    CommonSetups.square(board)
    Style.topdown(board, context.canvas, tiles)
    board.fill(10, 10, {'tile_id'='grass'})
    board.add_cell(2, 3, {'tile_id'='mud'})
    fit_board_into(board, 5, 5, 10, 10)

The CommonSetups class configures the board to use a square tiled grid with four directions. The Styles class then configures how the board is displayed: the look of the tiles and how they are laid out. [TODO] add link to documentation for CommonSetups and Styles.

You can fit the board into view with the function fit_board_into(board, x, y, w, h), provided in the gameboard_helpers module.

The GameBoard library

GameBoard

A GameBoard can be used to represent a playfield with evenly spaced cells (like square or hexagonal). Using the two matrices base and projection you're able to configure a multitude of orthographic styles. The property neighbor_deltas gives a list of how cells are connected and is mainly used for pathfinding.

Cells

A location on the board is called a cell, consisting of a coordinate and some properties associated with it like a tile_id. You may add cells in any configuration, so non-square and irregular boards are allowed. Use add_cell(x, y, cell_data) to add cells. cell_data is a dictionary that is required to contain a tile_id entry. The tile ID is used to construct the visuals for the cell, explained in the Visuals section.

The method fill(width, height, cell_data, x=0, y=0) fills a square area; useful for quickly creating a square gameboard or rooms within one.

Visuals

The GameBoard constructs the tile visuals when adding a cell using the tile_factory function. The Style class assigns this for you, but if the prebuild styles doesn't cover your needs you may wish to make your own tile_factory function and assign it to the GameBoard.

tile_factory should simply take a tile_id as an argument and return a new GraphicalObject that is the visual representation of this tile. You'll likely need access to the canvas and other information about the board when creating a tile; To achieve this you may either wrap the configuration of the tile_factory in a closure or create a callable class using a __call__(self, tile_id) method.

# The outer closure takes the additional parameters and returns the actual tile_factory function that has access to the closures arguments.
def configure_tile_factory(canvas):
  def tile_factory(tile_id):
    color = "#40FF40" if tile_id == "grass" else "#505050"
    return canvas.new_circle(1.0, color)
  return tile_factory

class Challenge:
  def __init__(self, context):
    board = GameBoard()
    board.tile_factory = configure_tile_factory(context.canvas)

The returned GraphicalObject will be managed by the GameBoard and placed automatically.

Helper tile_factory functions

The gameboard_helper contains a set of predefined tile_factory functions, used by the Style class but available on their own if needed.

configure_square_tile_factory creates square tiles that can be used with any projection, like topdown, isometric or any other orthographic layout. The graphics are simple flat polygons, useful for quick prototyping or pretty as they are. The configuration requires a dictionary of tile properties, e.g.: {'grass': {'color': '#00FF00', 'line_color': '#005000'}, where the key is the tile_id.

configure_hex_tile_factory works like the square counterpart, except with hexagonal tiles.

GamePiece

The GamePiece class should be used for anything that can be placed on the GameBoard.

from gameboard import GameBoard, GamePiece

class Challenge:
  def __init__(self, context):
    board = GameBoard()
    gfx = context.canvas.new_circle(1.0, '#FF00FF')
    actor = GamePiece(gfx)
    board.place_game_piece(actor, 1, 1)

You can use it as-is for many cases or create your own derived class for more flexibility.

Pathfinding

The library comes with some general pathfinding tools that are easily configured with functions in the gameboard_helper module. The Pathfinding class, located in the gameboard module lets you construct a graph and traverse it with an implementation of the AStar algorithm. It's a very generalized implementation, though nodes are denoted with integer coordinates (x,y).

Quick setup

from gameboard import GameBoard
from gameboard_helpers import generate_board_pathfinding

class Challenge:
  def __init__(self, context):
    board = GameBoard()
    ...
    pathfinding = generate_board_pathfinding(board)

GamePiece pathfinding

You may pass the resulting pathfinding instance to one or more GamePieces. Doing this enables the step_towards method that makes it very simple to traverse the board.

from gameboard import GameBoard, GamePiece
from gameboard_helpers import generate_board_pathfinding

class Challenge:
  def __init__(self, context):
    board = GameBoard()
    ...
    pathfinding = generate_board_pathfinding(board)
    self.piece = GamePiece(gfx, pathfinding)
    board.place_game_piece(self.piece, 0, 0)

  def step(self):
    self.piece.step_towards(4, 5)

Each time step_towards is called the game piece is moved one step towards the target by referencing the pathfinding graph provided to the game piece's constructor. The method returns true if a step was taken, false otherwise. You may have to refer to the game piece's coordinate to see if it arrived at the goal or if it was unable to move.

get_possible_moves returns a list of coordinates a game piece may move to, based on the pathfinding graph.

Helper for generation

The generate_board_pathfinding will likely cover most uses. By default it takes the neighbor_delta from the board itself to generate connections between cells. If movement differs between characters you may provide a move set as the second argument. The generator will consider walls as blocking if using a WalledGameBoard and setting the third argument wall_check to true (default).

It will also consider node weights if added to a cell, resulting in paths avoiding higher weight tiles without blocking them completely.

board.add_cell(x, y, {'tile_id':'grass', 'weight': 2.0})

[TODO] Explain collision groups.

Building a graph

In case the provided generate_board_pathfinding isn't sufficient you may construct your own Pathfinding graph. The Pathfinding class provides methods for adding nodes and connecting them. It's not coupled with the gameboard in anyway and keeps track of its own graph of nodes. [TODO] Explain the dynamic check function.