Configuration lists


piecepackr allows one to alter the appearance of one’s board game pieces through the use of configuration lists. Here is an example:

dark_colorscheme <- list(suit_color="darkred,black,darkgreen,darkblue,black",
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",
traditional_ranks <- list(use_suit_as_ace=TRUE, rank_text=",a,2,3,4,5")
cfg <- c(piecepack_suits, dark_colorscheme, traditional_ranks)
gp_text <- gpar(fontsize=25, fontface="bold")
grid.text("grid.piece('preview_layout')", x=0.25, y=0.90, gp=gp_text)
pushViewport(viewport(x=0.25, y=0.43, width=inch(6)))
grid.text("grid.piece('preview_layout', cfg=cfg)", x=0.75, y=0.90, gp=gp_text)
pushViewport(viewport(x=0.75, y=0.43, width=inch(6)))
grid.piece("preview_layout", cfg=cfg)
Configuration list example

Configuration list example

There are lot more examples of customizing piecepack piece appearances with configuration lists in the Print & Play demos.

Although one can further customize the appearance of one’s board game pieces through the use of custom grob functions the default piecepackr grob function uses the configuration list to determine a board game component’s shape, “primary” symbol,”directional mark” symbol, and gridlines (if any). This program uses the abstraction that every board game component has a “component_side” name (like belt_face), a suit, a rank, a primary symbol, a directional mark symbol, and embellishments like border lines, grid lines, and padding. On top of the normal “suited” piecepack suits this program also recognizes an extra “unsuit” suit which is used to configure “neutral” components like tile backs and coin faces. Although the primary and directional mark symbols can be configured directly (i.e. tile_face.ps_fontsize) they are often configured indirectly by specifying various “suit” and “rank” symbol configurations (i.e. rank_cex).

Configurations are often allowed to be comma-separated to be able to specify different values for different suits or ranks e.g. background_color=white or background_color=pink,grey,grey,pink,white (note how the last [5th] element specifies that the “unsuit” background color should be “white”).

Configuration cascading

The configurations in this program “cascade” (sort of like in “Cascading Style Sheets”). A style configuration has the following format:


The configuration “cascade” priorities are as follows:

  1. Direct styles have priority over indirect styles e.g. dm_text has priority over suit_text.tile_face for which symbol is used in the corner of the tile face and in turn suit_fontfamily has priority over fontfamily for which fonts are used on the coin back. This is because indirect styles are only used to a generate reasonable default if a direct style cannot be found.
  2. Then if there is a tie .component_side has priority over .component which has priority over no component specification e.g. dm_text.saucer_back has priority over dm_text.saucer which has priority over just dm_text.
  3. Then if there is still a tie .r# has priority over no rank specification e.g. invert_colors.r1 has priority over invert_colors.
  4. Then if there is still a tie .s# has priority over .suited / .unsuited which has priority over no suit specification e.g. invert_colors.s2 has priority over invert_colors.suited has priority over just invert_colors.

Table of configuration list styles

Configuration list styles
name description indirect setters comma-separated
ps_text “primary symbol” text suit_text, rank_text, use_suit_as_ace  
ps_fontface fontface of “primary symbol” symbol suit_fontface, rank_fontface, fontface, use_suit_as_ace  
ps_fontfamily font of “primary symbol” symbol suit_fontfamily, rank_fontfamily, fontfamily, use_suit_as_ace  
ps_fontsize fontsize of “primary symbol” symbol    
ps_cex Multiplier to apply to the “primary symbol” fontsize (cumulative with cex) suit_cex, rank_cex, use_suit_as_ace  
ps_t Angle (in degrees) of polar coordinates of “primary symbol” (from center)   suit
ps_r Radius from center (relative units) of polar coordinates of “primary symbol”   suit
ps_color Color of “primary symbol” suit_color, background_color, invert_colors  
dm_text “directional mark” text suit_text suit
dm_fontface font of “directional mark” suit_fontface, fontface suit
dm_fontfamily font of “directional mark” suit_fontfamily, fontfamily suit
dm_fontsize fontsize of “directional mark”    
dm_cex Multiplier to apply to the “directional mark” fontsize (cumulative with cex) suit_cex suit
dm_t Angle (in degrees) of polar coordinates of “directional mark” symbol (from center)   suit
dm_r Radius from center (relative units) of polar coordinates of “directional mark”   suit
dm_color Color of “directional mark” symbol suit_color, background_color, invert_colors suit
shape Shape of component: either rect, circle, halma, kite, pyramid, concave# or convex# where # is the number of outside polygon vertices    
shape_t If shape is concave# or convex# then angle of first vertex (in degrees) of the polygon    
shape_r If shape is concave# then how far from the center are the inner vertices (from 0 to 0.5)    
background_color Background color of the component suit_color, invert_colors suit
invert_colors Should we switch the background color with the suit color?    
border_color Color of the border of the component   suit
border_lex Multiplier to apply to the default border line width    
gridline_color Color of the gridlines suit_color, background_color, invert_colors suit
gridline_lex Multiplier to apply to the default grid line width    
edge_color Which color to use for the edge of the piece when drawn with an oblique projection. suit_color, background_color suit
annotation_color What color to suggest for annotating graphics    
mat_color Color of the “matting” suit_color, background_color, invert_colors suit
mat_width Width of the “matting” (from 0.0 to 1.0)   padding
suit_text Suit symbols to use as “primary” symbol or “directional mark”   suit
suit_fontface Font(s) of the suit symbols fontface suit
suit_fontfamily Font(s) of the suit symbols fontfamily suit
suit_cex Multiplier to apply to the suit symbols fontsize   suit
suit_color Suit colors   suit
rank_text Rank symbols to use as “primary” symbol suit_text, use_suit_as_ace rank
rank_fontface Font(s) of the rank symbols suit_fontface, use_suit_as_ace, fontface rank
rank_fontfamily Font(s) of the rank symbols suit_fontfamily, use_suit_as_ace, fontfamily rank
rank_cex Multiplier to apply to the rank symbols fontsize suit_cex, use_suit_as_ace rank
use_suit_as_ace Boolean for whether the suit symbol should be used for the ‘ace’ rank    
cex Multiplier to apply to all the fontsizes    
fontfamily Default font ‘family’    
fontface Default font ‘face’    
n_ranks Number of ranks rank_text  
n_suits Number of suits suit_text  
coin_arrangement Number of degrees the direction of the bottom of the coin differs from top of coin    
die_arrangement Arrangement of dice (for use in 3D projections and paper Print & Play arrangements). Either "counter_up", "counter_down", "opposites_sum_to_5", or (a comma-separated string of) the integers 1, 2, 3, 4, 5, and 6 (in any order) with each integer optionally followed by ^ (default), <, v, or >.    
width Width of component in inches    
height Height of component in inches width  
depth Depth of the component in inches width  
grob_fn Which grob function to use to make a 2D grob of the game piece.    
grob_with_bleed_fn Which function to use to make a grob of the game piece with a “bleed”. Introduced in v1.10.    
op_grob_fn Which function to use to make a 3D grob of the game piece when the piece is drawn with an oblique projection. Introduced in v1.3.    
obj_fn Which function to use to save Wavefront OBJ file of the game piece (which is used by default piece() and piece3d() functions). Introduced in v1.4.    
rayrender_fn Which function to use to create game pieces for use with rayrender graphic system (via piece() function). Introduced in v1.4.    
rayvertex_fn Which function to use to create game pieces for use with rayvertex graphic system (via piece_mesh() function). Introduced in v1.9.    
rgl_fn Which function to use to draw game pieces in rgl graphic system (via piece3d() function). Introduced in v1.4.    
title Title of the piecepack    
description Description of the piecepack    
credit Additional credits    
copyright Additional copyrights    
spdx_id [SPDX Identifier]( for the graphical design license. Introduced in v1.10.    
lacks_rank Which “piece_side“‘s should we assume don’t vary by rank. Introduced in v1.7.    
lacks_suit Which “piece_side“‘s should we assume don’t vary by suit. Introduced in v1.7.    
shadow_fn Which function to use to make a grob of the edges of the game piece when the piece is drawn with a 3D oblique projection. Deprecated in v1.3 (use op_grob_fn instead). Removed in v1.10.    

Configuration List R6 Object

If you will be drawing lots of piecepack images you should use the pp_cfg function to create a configuration list R6 object. It (on-the-fly) builds a cache so it really speeds up future component drawing.

cfg <- pp_cfg(cfg)

Storing/sharing configuration lists

One can export configuration lists using R’s RData binary format and the save command and re-load them back in with the load command. Simple configuration lists can alternatively be stored in plaintext using formats like JSON (i.e. via the jsonlite package).

save(cfg, file="my_cfg.RData")

This website offers for download demo_cfgs.RData which contains every Print & Play demos configuration list.

cfgs <- new.env()
load("demo_cfgs.RData", envir=cfgs)
##  [1] "default1_cutlines"   "chess2_borders"      "dual4_cutlines"
##  [4] "zodiac_cn1_borders"  "dingbats1_borders"   "zodiac_cn2_cutlines"
##  [7] "chess2_cutlines"     "dingbats2_cutlines"  "chess5_bleed"
## [10] "orthodox2_bleed"     "dual2_bleed"         "dingbats2_borders"
## [13] "dual6_cutlines"      "chess4_cutlines"     "orthodox2_borders"
## [16] "orthodox1_cutlines"  "default1_borders"    "dual1_cutlines"
## [19] "orthodox3_cutlines"  "dual5_bleed"         "dingbats1_bleed"
## [22] "chess1_bleed"        "default1_bleed"      "zodiac_cn2_bleed"
## [25] "rainbow1_bleed"      "chess1_cutlines"     "orthodox3_borders"
## [28] "dingbats1_cutlines"  "dual3_cutlines"      "rainbow1_cutlines"
## [31] "dual3_bleed"         "reversi1_bleed"      "chess4_bleed"
## [34] "chess5_cutlines"     "chess3_borders"      "chess4_borders"
## [37] "chess1_borders"      "dual5_cutlines"      "zodiac_cn2_borders"
## [40] "reversi1_cutlines"   "zodiac_cn1_cutlines" "dingbats2_bleed"
## [43] "dual6_bleed"         "chess2_bleed"        "dual1_bleed"
## [46] "orthodox1_bleed"     "orthodox3_bleed"     "zodiac_cn1_bleed"
## [49] "chess5_borders"      "chess3_cutlines"     "dual2_cutlines"
## [52] "orthodox2_cutlines"  "orthodox1_borders"   "rainbow2_cutlines"
## [55] "reversi1_borders"    "dual4_bleed"         "chess3_bleed"
## [58] "rainbow2_bleed"
## $background_color : grey70
## $copyright : © 2019 Trevor L Davis.  Some Rights Reserved.
## $credit : ● This piecepack uses characters from the font Quivira. Public Domain.,
## $description :
## $fontfamily : Quivira
## $invert_colors.suited : TRUE
## $lacks_rank : tile_back,coin_back,card_back,pawn_face,pawn_back,belt_face,saucer_face,saucer_back,suitdie_face
## $lacks_suit : tile_back,saucer_back,coin_face,card_back
## $n_ranks : 6
## $n_suits : 4
## $rank_text : ,a,2,3,4,5
## $spdx_id : CC-BY-SA-4.0
## $suit_color : black,black,black,black,grey40
## $suit_text : ,,,,
## $title : Swiss-suited (Black)
## $use_suit_as_ace : TRUE
grid.piece("preview_layout", cfg=cfgs$dual5_cutlines)
Preview of 'dual5_cutlines' configuration from 'demo_cfgs.RData'

Preview of ‘dual5_cutlines’ configuration from ‘demo_cfgs.RData’

pushViewport(viewport(width=inch(6), height=inch(4)))
grid.piece("tile_face", rank=1:6,
           cfg=paste0("dual", 1:6, "_cutlines"), envir=cfgs,
           x=inch(rep(c(1,3,5), 2)), y=inch(rep(c(1,3), each=3)))
Can use multiple configurations stored in an environment at the same time

Can use multiple configurations stored in an environment at the same time


There are no comments yet.

Add a Comment

You can use Markdown or restructuredText to format your comment.