Bukkit

Overview

Piece styles control how the chess pieces on a board are drawn; their shape and the materials used to draw them.

There are two types of piece style: block and entity. Block styles use blocks to construct the chess pieces on the board, while entity styles use the Citizens plugin to create NPC entities for the chess pieces.

Piece styles are stored as files in plugins/ChessCraft/piece_styles/ under your Bukkit folder. There is one file per set style; it is a YAML file and must have a .yml extension. There is also a custom/ folder under this folder, where you should save any custom piece style files you might create.

See Stock Styles for a list of stock board and piece styles that are shipped with the plugin.

Block chess piece styles use the same material specification syntax as boards do (see Material specifications in Board Styles).

If you want to create your own block style or modify an existing block style, the easiest option is to use the Piece Designer (new in v1.0.0). Entity styles are simpler to define and can be created by editing a YAML file directly; see Entity Styles below for more information.

Block Styles

Here is the default piece style, standard.yml:

# Name for this set - should match the filename
name: Standard

# List of materials used in the set
# Can be specified as plain integer (e.g. '0' - air), material name (e.g. iron_block)
#  or material plus data (e.g. 35:0, wool:white)
# If you use plain integers, they must be quoted, or the set will not load!
# If you use material names, they must match the org.bukkit.Material definitions exactly
#  - see http://jd.bukkit.org/apidocs/org/bukkit/Material.html
materials:
  black:
    O: air
    X: gold_block
  white:
    O: air
    X: iron_block

# Piece definitions
# This is a list of list of strings such that:
# - definition[0] is the lowest layer on the Y-axis
# - definition[0][0] is the northmost row on the lowest layer
# - each string runs from west to east and consists of materials defined above
#
pieces:
  P: [ [ OXO, XXX, OXO ], [ OXO, XXX, OXO ], [ OOO, OXO, OOO ] ]
  N: [ [ XXX, XXX, XXX ], [ OXO, XXX, OXO ], [ OOO, OXO, OOO ], [ OXO, OXO, OOO ], [ OOO, OXO, OOO ] ]
  B: [ [ XXX, XXX, XXX ], [ OXO, XXX, OXO ], [ OOO, OXO, OOO ], [ OXO, XXX, OXO ], [ OOO, OXO, OOO ] ]
  R: [ [ XXX, XXX, XXX ], [ XXX, XXX, XXX ], [ OXO, XXX, OXO ], [ XXX, XXX, XXX ], [ XOX, OOO, XOX ] ]
  Q: [ [ XXX, XXX, XXX ], [ OXO, XXX, OXO ], [ OXO, XXX, OXO ], [ OOO, OXO, OOO ], [ OXO, XXX, OXO ], [ OOO, OXO, OOO ] ]
  K: [ [ XXX, XXX, XXX ], [ OXO, XXX, OXO ], [ OXO, XXX, OXO ], [ OXO, XXX, OXO ], [ XXX, XXX, XXX ], [ XOX, OOO, XOX ] ]

The sections are as follows:

• A name section. The name should match the filename.
• An optional comment section. This is just some free-form text (may include newlines) with any notes regarding the style, e.g. author credits.
• A materials section. This defines the materials used for the white and black pieces, mapping a material specification to a character.
• A pieces section. This defines the actual piece shapes and is described in more detail below. There is one entry for each chess piece: P (pawn), N (knight), B (bishop), R (rook), Q (queen) and K (king). All of these must be present.

Piece Shape Definition

Look at the simplest definition from the list above (the pawn):

P: [ [ OXO, XXX, OXO ], [ OXO, XXX, OXO ], [ OOO, OXO, OOO ] ]
#    -----layer 1-----  -----layer 2-----  -----layer 3-----

This is a list of list of strings.

The outer elements define each layer of the piece on the Y axis, moving upwards from the bottom layer. So in the above example:

• There are 3 outer elements, so the piece will be 3 blocks tall.
• The first outer element is [ OXO, XXX, OXO ]. This is the bottom layer of the pawn, and itself contains 3 elements.
• These 3 elements represent a row of 3 blocks each: the first element OXO is the northmost row, the second XXX is the row to the south of that, and the third element OXO is the southmost (but see the Notes below for discussion on what "north" means here)
• Each of these rows is a string of 3 characters, which have been defined in the materials section. These define blocks, moving west to east. So OXO is air, then a gold or iron block depending on whether the piece is white or black, then air again.

In this way, a 3-dimensional piece can be built up. In this case the piece is 3x3x3. All the pieces in this set have a base size of 3x3, but their heights vary - e.g. the rook, knight & bishop are 5 layers tall and the king and queen are 6 layers tall.

Notes

• "North" might be more accurately defined as "the direction the white pieces face" - your knight definition should always have the knight facing north. If a board is created with a different orientation (e.g. white facing west), the chess pieces will be automatically drawn facing the right way.
• To use a set style with a board style, the tallest piece in the set must be no taller than the board's height attribute, and the widest piece must be no wider than the board's square_size attribute.

Entity Styles

Here is an example entity style ("entity.yml"):

# ChessCraft entity piece style definition file
# See http://dev.bukkit.org/server-mods/chesscraft/pages/piece-styles
# 
# 'name' is the name for this set, and should match the filename
# 
# 'comment' is a freeform comment about the set (can be multi-line)
# 
# 'pieces.<colour>.<X>' defines the NPC used for a chess piece," +
#  where <colour> is one of black, white and <X> is one of P,R,N,B,Q,K
#
#  The piece definition is a compound structure with a mandatory "entity"
#  field, which must be a Bukkit EntityType for a living entity - see
#  http://jd.bukkit.org/dev/apidocs/org/bukkit/entity/EntityType.html
#
#  Other fields are optional and modify the appearance of the piece.
#  Different entities understand different fields - see
#  http://dev.bukkit.org/server-mods/chesscraft/pages/piece-styles for
#  full information.
name: entity
comment: Entity chess set
type: entity

pieces:
  white:
    P: { entity: sheep, baby: true }
    R: { entity: wolf, tame: true, color: blue }
    N: { entity: horse, variant: horse, color: white, style: none }
    B: { entity: villager, profession: librarian }
    Q: { entity: mushroom_cow }
    K: { entity: iron_golem }
  black:
    P: { entity: magma_cube, size: 2 }
    R: { entity: pig_zombie, held: gold_sword }
    N: { entity: horse, variant: undead_horse }
    B: { entity: skeleton, variant: wither, held: stone_sword, helmet: leather_helmet }
    Q: { entity: witch, held: stick }
    K: { entity: blaze }

The sections are as follows:

• A name section. The name should match the filename.
• An optional comment section. This is just some free-form text (may include newlines) with any notes regarding the style, e.g. author credits.
• A type section, which must be entity.
• A pieces section, with white and black subsections. Each of those sections has exactly six entries: P, R, N, B, Q, K, for each type of piece on the board.

Each piece definition has a mandatory entity field, which represents the entity type. Any living entity type from http://jd.bukkit.org/dev/apidocs/org/bukkit/entity/EntityType.html may be used here (case insensitive).

Depending on the entity type, further fields may be used to customise the appearance of the entity. Here are the accepted fields:

All values are case-insensitive.

In addition:

• any tameable animal (horse, wolf, ocelot) accepts the tame boolean field, false by default
• any ageable animal (a creature which has a baby version) accepts the baby boolean field, false by default
• all entities accept the held, boots, legs, chest & helmet fields to set entity equipment (but not all actually display equipment)

Use a Bukkit material name from http://jd.bukkit.org/rb/apidocs/org/bukkit/Material.html for entity equipment. Note that only some entities actually display held or worn equipment (e.g. there's no point putting a helmet on a blaze...).

Required and Recommended Plugins

If you're using entity sets, you must install the Citizens plugin. Ensure that the version you install matches the current CraftBukkit version. You may need to check http://ci.citizensnpcs.co/ for development builds.

It is strongly recommended to install the ProtocolLib plugin too. Without this, every entity on the board will make its usual noises, leading to a deafening din. With ProtocolLib installed, ChessCraft will silence all mob sounds where the mob is on a chess board, preserving player sanity.