piecepackr: Board Game Graphics

piecepackr is an R package designed to make configurable board game graphics. It can be used with R's grid graphics system to make board game diagrams, board game animations, and custom Print & Play layouts. By default it is configured to make piecepack game diagrams, animations, and "Print & Play" layouts but can be configured to make graphics for other board game systems as well.

API Intro

grid.piece is the core function that is used used to draw board game components (by default piecepack game components):

library("piecepackr")
g.p <- function(...) { grid.piece(..., default.units="in") }
g.p("tile_back", x=0.5+c(3,1,3,1), y=0.5+c(3,3,1,1))
g.p("tile_back", x=0.5+3, y=0.5+1)
g.p("tile_back", x=0.5+3, y=0.5+1)
g.p("die_face", suit=3, rank=5, x=1, y=1)
g.p("pawn_face", x=1, y=4, angle=90)
g.p("coin_back", x=3, y=4, angle=180)
g.p("coin_back", suit=4, x=3, y=4, angle=180)
g.p("coin_back", suit=2, x=3, y=1, angle=90)
Piecepack diagram with default configuration
Piecepack diagram with default configuration

One can use lists to configure the appearance of the game components drawn by grid.piece:

dark_colorscheme <- list(suit_color="darkred,black,darkgreen,darkblue,black",
                     invert_colors.suited=TRUE, border_color="black", border_lex=2)
piecepack_suits <- list(suit_text="\U0001f31e,\U0001f31c,\U0001f451,\u269c,\uaa5c", # 🌞,🌜,πŸ‘‘,⚜,꩜
                    suit_fontfamily="Noto Emoji,Noto Sans Symbols2,Noto Emoji,Noto Sans Symbols,Noto Sans Cham",
                    suit_cex="0.6,0.7,0.75,0.9,0.9")
traditional_ranks <- list(use_suit_as_ace=TRUE, rank_text=",a,2,3,4,5")
cfg <- c(piecepack_suits, dark_colorscheme, traditional_ranks)
g.p <- function(...) { grid.piece(..., default.units="in", cfg=pp_cfg(cfg)) }
g.p("tile_back", x=0.5+c(3,1,3,1), y=0.5+c(3,3,1,1))
g.p("tile_back", x=0.5+3, y=0.5+1)
g.p("tile_back", x=0.5+3, y=0.5+1)
g.p("die_face", suit=3, rank=5, x=1, y=1)
g.p("pawn_face", x=1, y=4, angle=90)
g.p("coin_back", x=3, y=4, angle=180)
g.p("coin_back", suit=4, x=3, y=4, angle=180)
g.p("coin_back", suit=2, x=3, y=1, angle=90)
Piecepack diagram with custom configuration
Piecepack diagram with custom configuration

grid.piece even has some support for drawing components with an oblique projection:

cfg3d <- list(width.pawn=0.75, height.pawn=0.75, depth.pawn=1, 
                   dm_text.pawn="", shape.pawn="convex6", invert_colors.pawn=TRUE,
                   edge_color.coin="tan", edge_color.tile="tan")
cfg <- pp_cfg(c(cfg, cfg3d))
g.p <- function(...) { 
    grid.piece(..., op_scale=0.5, op_angle=45, cfg=cfg, default.units="in") 
}
g.p("tile_back", x=0.5+c(3,1,3,1), y=0.5+c(3,3,1,1))
g.p("tile_back", x=0.5+3, y=0.5+1, z=1/4+1/8)
g.p("tile_back", x=0.5+3, y=0.5+1, z=2/4+1/8)
g.p("die_face", suit=3, rank=5, x=1, y=1, z=1/4+1/4)
g.p("pawn_face", x=1, y=4, z=1/4+1/2, angle=90)
g.p("coin_back", x=3, y=4, z=1/4+1/16, angle=180)
g.p("coin_back", suit=4, x=3, y=4, z=1/4+1/8+1/16, angle=180)
g.p("coin_back", suit=2, x=3, y=1, z=3/4+1/8, angle=90)
Piecepack diagram in an oblique projection
Piecepack diagram in an oblique projection

save_print_and_play makes a "Print & Play" pdf of a configured piecepack, save_piece_images makes individual images of each piecepack component:

save_print_and_play(cfg, "my_piecepack.pdf", size="letter")
save_piece_images(cfg)

If you are comfortable using R data frames there is also pmap_piece which is wrapper for grid.piece that processes data frame input:

library("tibble")
df_tiles <- tibble(piece_side="tile_back", x=0.5+c(3,1,3,1), y=0.5+c(3,3,1,1))
df_coins <- tibble(piece_side="coin_back", x=rep(4:1, 4), y=rep(4:1, each=4),
                       suit=1:16%%2+rep(c(1,3), each=8),
                       angle=rep(c(180,0), each=8), z=1/4+1/16)
df <- dplyr::bind_rows(df_tiles, df_coins)
pmap_piece(df, cfg=cfg, op_scale=0.5, default.units="in")
'pmap_piece' lets you use data frames as input
'pmap_piece' lets you use data frames as input

A slightly longer intro to piecepackr's API plus several piecepackr demos and other piecpackr docs are available at piecepackr's companion website as well as some pre-configured Print & Play PDFs. More API documentation is also available in the package's man pages.

Tak Example

Although the game of Tak can be played with a piecepack stackpack here we'll show an example of configuring piecepackr to draw more traditional Tak game pieces.

Since one often plays Tak on differently sized boards one common Tak board design is to have boards made with colored cells arranged in rings from the center plus extra symbols in rings placed at the points so it is easy to see smaller sub-boards. To start we'll write a function to draw the Tak board.

library("grid")
library("piecepackr")
grobTakBoard <- function(...) {
    g <- "darkgreen"
    w <- "grey"
    fill <- c(rep(g, 5),
              rep(c(g, rep(w, 3), g),3),
              rep(g, 5))
    inner <- rectGrob(x = rep(1:5, 5), y = rep(5:1, each=5),
                 width=1, height=1, default.units="in", 
                 gp=gpar(col="gold", fill=fill, lwd=3))
    outer <- rectGrob(gp=gpar(col="black", fill="grey", gp=gpar(lex=2)))
    circles <- circleGrob(x=0.5+rep(1:4, 4), y=0.5+rep(4:1, each=4), r=0.1, 
                         gp=gpar(col=NA, fill="gold"), default.units="in")
    rects <- rectGrob(x=0.5+c(0:5, rep(c(0,5), 4), 0:5), 
                      y=0.5+c(rep(5,6), rep(c(4:1), each=2), rep(0, 6)),
                      width=0.2, height=0.2,
                      gp=gpar(col=NA, fill="orange"), default.units="in")
    grobTree(outer, inner, circles, rects)
}

Then we'll configure a Tak set and write some helper functions to draw Tak pieces with it.

cfg <- pp_cfg(list(suit_text=",,,", suit_color="white,tan4,", invert_colors=TRUE,
            ps_text="", dm_text="",
            width.tile=6, height.tile=6, depth.tile=1/4,
            grob_fn.tile=grobTakBoard,
            width.coin=0.6, height.coin=0.6, depth.coin=1/4, shape.coin="rect",
            width.saucer=0.6, height.saucer=1/4, depth.saucer=0.6, 
            shape.saucer="rect", mat_width.saucer=0,
            width.pawn=0.5, height.pawn=0.5, depth.pawn=0.8, shape.pawn="circle",
            edge_color="white,tan4", border_lex=2,
            edge_color.tile="tan", border_color.tile="black"))
g.p <- function(...) { 
    grid.piece(..., op_scale=0.7, op_angle=45, cfg=cfg, default.units="in")
}
draw_tak_board <- function(x, y) { 
    g.p("tile_back", x=x+0.5, y=y+0.5) 
}
draw_flat_stone <- function(x, y, suit=1) { 
    z <- 1/4*seq(along=suit)+1/8
    g.p("coin_back", x=x+0.5, y=y+0.5, z=z, suit=suit)
}
draw_standing_stone <- function(x, y, suit=1, n_beneath=0, angle=0) {
    z <- (n_beneath+1)*1/4+0.3
    g.p("saucer_face", x=x+0.5, y=y+0.5, z=z, suit=suit, angle=angle)
}
draw_capstone <- function(x, y, suit=1, n_beneath=0) {
    z <- (n_beneath+1)*1/4+0.4
    g.p("pawn_back", x=x+0.5, y=y+0.5, z=z, suit=suit)
}

Then we'll draw an example Tak game diagram:

pushViewport(viewport(width=inch(6), height=inch(6)))
draw_tak_board(3, 3)
draw_flat_stone(1, 1, 1)
draw_flat_stone(1, 2, 2)
draw_flat_stone(2, 4, 1)
draw_capstone(2, 4, 2, n_beneath=1)
draw_flat_stone(2, 5, 2)
draw_flat_stone(3, 4, 1:2)
draw_flat_stone(3, 3, c(2,1,1,2))
draw_flat_stone(3, 2, 1:2)
draw_flat_stone(3, 1, 2)
draw_standing_stone(4, 2, 2, angle=90)
draw_flat_stone(5, 2, 1)
draw_capstone(5, 3, 1)
popViewport()
Tak game diagram
Tak game diagram

Installation

To install the development version of piecepackr use the following commands in R:

install.packages("remotes")
remotes::install_github("trevorld/piecepackr")

The default piecepackr configuration should work out on the box on most modern OSes including Windows without the user needing to mess with their system fonts. However if you wish to use advanced piecepackr configurations you'll need to install additional Unicode fonts and Windows users are highly recommended to use and install piecepackr on "Ubuntu on Bash on Windows" if planning on using Unicode symbols from multiple fonts. The following bash commands will give you a good selection of fonts (Noto, Quivira, and Dejavu) on Ubuntu:

sudo apt install fonts-dejavu fonts-noto 
fonts_dir=${XDG_DATA_HOME:="$HOME/.local/share"}/fonts
curl -O http://www.quivira-font.com/files/Quivira.otf
mv Quivira.otf $fonts_dir/
curl -O https://noto-website-2.storage.googleapis.com/pkgs/NotoEmoji-unhinted.zip
unzip NotoEmoji-unhinted.zip NotoEmoji-Regular.ttf
mv NotoEmoji-Regular.ttf $fonts_dir/
rm NotoEmoji-unhinted.zip

Note piecpackr works best if the version of R installed was compiled with support for Cairo and fortunately this is typically the case. One can confirm if this is true via R's capabilities function:

> capabilities("cairo")
cairo
 TRUE

Also although most users won't need them piecpackr contains utility functions that depend on the system dependencies ghostscript and poppler-utils:

  1. save_print_and_play will embed additional metadata into the pdf if ghostscript is available.
  2. get_embedded_font (a debugging helper function) needs pdffonts (usually found in poppler-utils)

You can install these utilities on Ubuntu with

sudo apt install ghostscript poppler-utils

Frequently Asked Questions

What is the package licence?

This software package is released under a Creative Commons Attribution-ShareAlike 4.0 International license (CC BY-SA 4.0). This license is compatible with version 3 of the GNU Public License (GPL-3).

How should I Print & Play my piecepack?

The Print-and-Play pdf's produced by the save_print_and_play function can be configured in two different ways:

single-sided

Print single-sided on label paper, cut out the labels, and apply to components (in the material of your choice) or print single-sided on paper(board), apply adhesive to the back, fold over in half "hot-dog-style", and cut out the components. One will need to to some additional folding and application of adhesive/tape in order to construct the dice, pawns, and pyramids. One can build more dice/pawns/pawn belts if you cut them out before folding the paper(board) in half but if you don't do so you should still have all the "standard" piecepack components.

double-sided

Print double-sided on paper(board) and cut out the components. One will need to do some additional folding and application of adhesive/tape in order to construct the dice, pawns, and pyramids.

The Piecepack Wiki has a page on making piecepacks. The BoardGameGeek Print-and-Play Wiki also has lots of good info like how to quickly make coins uisng an arch punch.

Warning: Generally it is advisable to uncheck 'fit to size' when printing PDF files otherwise your components maybe re-sized by the printer.

What are the dimensions of the components?

Although one can use the API to make layouts with components of different sizes the default print-and-play pdf's draw components of the following size which (except for the pawns and non-standard "pawn belts") matches the traditional Mesomorph piecepack dimensions if one uses the default component shapes and sizes:

Components are drawn into rectangular drawing spaces (which are always squares except for pawn components). The program allows one to customize piecepack component shapes. If a components shape is rect it will fill up the entire rectangular drawing space, if it is a circle then the rectangular drawing space will be circumscribed around the circle. If a components shape is a convex# or concave# where # is the number of exterior vertices then the rectangular drawing space will be circumscribed around a circle that will be circumscribed around that convex/concave polygon. The rectangular drawing space also is circumscribed around the special halma, kite, and pyramid shapes.

Warning: Generally it is advisable to uncheck 'fit to size' when printing PDF files otherwise your components maybe re-sized by the printer.

What are the possible color options?

You can specify colors either by RGB hex color codes or R color strings. "transparent" is a color option which does what you'd expect it to (if used for something other than the background color will render the element effectively invisible). Warning: you shouldn't mix "transparent" backgrounds with the invert_colors options.

I have some images I want to use as suit/rank/directional mark symbols, how can I use them with this program?

There are a couple of approaches one can take:

  1. Take them and put them into a font. FontForge is a popular open-source program suitable for this task. fontcustom is a popular command-line wrapper around FontForge. You may need to convert your images from one format to another format first. To guarantee dispatch by fontconfig you might want to put the symbols in a part of the "Private Use Area" of Unicode not used by any other fonts on your system. If you do that you won't need to specify your font otherwise you'll need to configure the suit_symbols_font, rank_symbols_font, and/or dm_font options.
  2. Write a custom grob function to insert the desired symbols using functions like grid's rasterGrob or grImport2's pictureGrob.

Why does the package sometimes use a different font then the one I instructed it to use for a particular symbol?

The program uses Cairo which uses fontconfig to select fonts. fontconfig picks what it thinks is the 'best' font and sometimes it annoyingly decides that the font to use for a particular symbol is not the one you asked it to use. (although sometimes the symbol it chooses instead still looks nice in which case maybe you shouldn't sweat it). It is hard but not impossible to configure which fonts are dispatched by fontconfig. A perhaps easier way to guarantee your symbols will be dispatched would be to either make a new font and re-assign the symbols to code points in the Unicode "Private Use Area" that aren't used by any other font on your system or to simply temporarily move (or permanently delete) from your system font folders the undesired fonts that fontconfig chooses over your requested fonts:

# temporarily force fontconfig to use Noto Emoji instead of Noto Color Emoji in my piecepacks on Ubuntu 18.04
$ sudo mv /usr/share/fonts/truetype/noto/NotoColorEmoji.ttf ~/
## Make some piecepacks
$ sudo mv ~/NotoColorEmoji.ttf /usr/share/fonts/truetype/noto/

Also as a sanity check use the command-line tool fc-match to make sure you specified your font correctly in the first place (i.e. fc-match "Noto Sans" on my system returns "Noto Sans" but fc-match "Sans Noto" returns "DejaVu Sans" and not "Noto Sans" as one may have expected). To help determine which fonts are actually being embedded you can use the get_embedded_font function:

fonts <- c('Noto Sans Symbols2', 'Noto Emoji', 'sans')
chars <- c('β™₯', 'β™ ', '♣', '♦', '🌞' ,'🌜' ,'꩜')
get_embedded_font(fonts, chars)
requested_font            embedded_font char

1 Noto Sans Symbols2 NotoSansSymbols2-Regular β™₯ 2 Noto Sans Symbols2 NotoSansSymbols2-Regular β™  3 Noto Sans Symbols2 NotoSansSymbols2-Regular ♣ 4 Noto Sans Symbols2 NotoSansSymbols2-Regular ♦ 5 Noto Sans Symbols2 NotoEmoji 🌞 6 Noto Sans Symbols2 NotoEmoji 🌜 7 Noto Sans Symbols2 NotoSansCham-Regular ꩜ 8 Noto Emoji NotoEmoji β™₯ 9 Noto Emoji NotoEmoji β™  10 Noto Emoji NotoEmoji ♣ 11 Noto Emoji NotoEmoji ♦ 12 Noto Emoji NotoEmoji 🌞 13 Noto Emoji NotoEmoji 🌜 14 Noto Emoji NotoSansCham-Regular ꩜ 15 sans Arimo β™₯ 16 sans Arimo β™  17 sans Arimo ♣ 18 sans Arimo ♦ 19 sans NotoEmoji 🌞 20 sans NotoEmoji 🌜 21 sans NotoSansCham-Regular ꩜

How do I use this package in piecepack rulesets?

There are two main ways that this package could be used to help make piecepack rulesets:

  1. The save_piece_images function makes individual images of components. By default it makes them in the svg formats with rotations of 0 degrees but with configuration can also make them in the bmp, jpeg, pdf, png, ps, and tiff formats as well as 90, 180, and 270 degree rotations. These can be directly inserted into your ruleset or even used to build diagrams with the aid of a graphics editor program. An example filename is tile_face_s1_r5_t180.pdf where tile is the component, face is the side, s1 indicates it was the first suit, r5 indicates it was the 5th rank, t180 indicates it was rotated 180 degrees, and pdf indicates it is a pdf image.
  2. This R package can be directly used with the grid graphics library in R to make diagrams. The important function for diagram drawing exported by the piecepack R package is grid.piece (or alternatives like pmap_piece) which draws piecepack components to the graphics device. The ppgames R package has code for several game diagram examples. One can also use this package to make animations.