Intro to piecepackr’s API

piecepackr is an R package to easily make piecepack graphics. It can be used to make piecepack game diagrams and animations as well as Print & Play layouts so you can make your own piecepack.

The core function is grid.piece() which can be used to draw any piecepack component:

grid.piece("tile_face", s=1:4, r=1:4, x=inch(seq(1, 7, by=2)))
tile faces

tile faces

grid.piece("coin_face", r=1:4, x=inch(seq(0.5, 3.5)))
coin faces

coin faces

grid.piece("pawn_face", s=3)
clubs pawn (face)

clubs pawn (face)

grid.piece("die_face", s=2, r=1)
null of spades die (face)

null of spades die (face)

piecepackr features an advanced configuration system that allows users to customize the appearance of the piecepack being used in their graphics. By default it uses an accessible french-suited configuration that should work out of the box on several OSes without the user needing to mess around with their system fonts but user’s can customize their piecepack’s appearance via use of a configuration list:

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)
grid.piece("tile_face", s=1:4, r=1:4, x=inch(seq(1, 7, by=2)), cfg=cfg)
tile faces

tile faces

grid.piece("coin_face", r=1:4, x=inch(seq(0.5, 3.5)), cfg=cfg)
coin faces

coin faces

grid.piece("pawn_face", s=3, cfg=cfg)
crowns pawn (face)

crowns pawn (face)

grid.piece("die_face", s=2, r=1, cfg=cfg)
null of moons die (face)

null of moons die (face)

The preview_layout grob allows one to see a preview of a given configuration list:

grid.piece("preview_layout", cfg=cfg)
'preview_layout' allows one to see a preview of a configuration

preview_layout’ allows one to see a preview of a configuration

Once you have a configuration you like one can use save_print_and_play to make a Print & Play pdf of your piecepack and save_piece_images to make individual images of every piecepack component (in case you would prefer to make your own layout or rule diagram in software like Inkscape):

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

If you will be drawing a bunch of piecepack graphics you may want to use the pp_cfg function which will add a “component opt” cache to your configuration (will make grid.piece work faster):

cfg <- pp_cfg(cfg)

If you are comfortable manipulating R data frames pmap_piece is a wrapper around grid.piece that can digest data frame input:

df <- tibble::tribble(~piece_side, ~suit, ~x, ~y,
                      "tile_back", NA, 2, 2,
                      "coin_back", 1, 2, 2,
                      "coin_back", 2, 1, 2,
                      "coin_back", 1, 3, 1,
                      "coin_back", 2, 1, 3,
                      "coin_back", 1, 1, 1,
                      "coin_back", 2, 3, 3,
                      "coin_back", 1, 2, 1)
df$angle <- ifelse(df$suit == 2, 180, 0)
pmap_piece(df, cfg=cfg, default.units="inches")
Tic-tac-toe example

Tic-tac-toe example

More documentation about piecepackr’s API can be found in the package’s man pages.


There are no comments yet.

Add a Comment

You can use Markdown or restructuredText to format your comment.