Font Loading Functions tcod.tileset

Tileset and font related functions.

If you want to load a tileset from a common tileset image then you only need tcod.tileset.load_tilesheet.

Tilesets can be loaded as a whole from tile-sheets or True-Type fonts, or they can be put together from multiple tile images by loading them separately using Tileset.__setitem__.

A major restriction with libtcod is that all tiles must be the same size and tiles can’t overlap when rendered. For sprite-based rendering it can be useful to use an alternative library for graphics rendering while continuing to use python-tcod’s pathfinding and field-of-view algorithms.

class tcod.tileset.Tileset(tile_width: int, tile_height: int)

A collection of graphical tiles.

Changed in version 20.1: Is now a collections.abc.MutableMapping type.

__add__(other: Iterable[tuple[int, ArrayLike | NDArray[np.uint8]]] | Mapping[int, ArrayLike | NDArray[np.uint8]], /) → Self

Combine tiles with this tileset, prefers replacing tiles.

Added in version 20.1.

__contains__(codepoint: object, /) → bool

Test if a tileset has a codepoint with n in tileset.

__copy__() → Self

Return a clone of this tileset.

This is not an exact copy. remap will not work on the clone.

Added in version 20.1.

__delitem__(codepoint: int, /) → None

Unmap a codepoint from this tileset.

Tilesets are optimized for set-and-forget, deleting a tile may not free up memory.

Added in version 20.1.

__getitem__(codepoint: int, /) → NDArray[np.uint8]

Return the RGBA tile data for the given codepoint.

The tile will have a shape of (height, width, rgba) and a dtype of uint8. Note that most grey-scale tilesets will only use the alpha channel with a solid white color channel.

Added in version 20.1.

__iadd__(other: Iterable[tuple[int, ArrayLike | NDArray[np.uint8]]] | Mapping[int, ArrayLike | NDArray[np.uint8]], /) → Self

Add tiles to this tileset inplace, prefers replacing tiles.

Added in version 20.1.

__ior__(other: Iterable[tuple[int, ArrayLike | NDArray[np.uint8]]] | Mapping[int, ArrayLike | NDArray[np.uint8]], /) → Self

Add tiles to this tileset inplace, keeps existing tiles instead of replacing them.

Added in version 20.1.

__iter__() → Iterator[int]

Iterate over the assigned codepoints of this tileset.

Added in version 20.1.

__len__() → int

Return the total count of codepoints assigned in this tileset.

Added in version 20.1.

__or__(other: Iterable[tuple[int, ArrayLike | NDArray[np.uint8]]] | Mapping[int, ArrayLike | NDArray[np.uint8]], /) → Self

Combine tiles with this tileset, prefers keeping existing tiles instead of replacing them.

Added in version 20.1.

__setitem__(codepoint: int, tile: ArrayLike | NDArray[np.uint8], /) → None

Upload a tile into this array.

Parameters:

• codepoint (int) – The Unicode codepoint you are assigning to. If the tile is a sprite rather than a common glyph then consider assigning it to a Private Use Area.

• tile (Union[ArrayLike, NDArray[np.uint8]]) – The pixels to use for this tile in row-major order and must be in the same shape as tile_shape. tile can be an RGBA array with the shape of (height, width, rgba), or a grey-scale array with the shape (height, width). The tile array will be converted to a dtype of np.uint8.

An RGB array as an input is too ambiguous and an alpha channel must be added, for example if an image has a key color than the key color pixels must have their alpha channel set to zero.

This data may be immediately sent to VRAM, which can be a slow operation.

Example:

# Examples use imageio for image loading, see https://imageio.readthedocs.io
tileset: tcod.tileset.Tileset  # This example assumes you are modifying an existing tileset.

# Normal usage when a tile already has its own alpha channel.
# The loaded tile must be the correct shape for the tileset you assign it to.
# The tile is assigned to a private use area and will not conflict with any exiting codepoint.
tileset[0x100000] = imageio.imread("rgba_tile.png")

# Load a greyscale tile.
tileset[0x100001] = imageio.imread("greyscale_tile.png", mode="L")
# If you are stuck with an RGB array then you can use the red channel as the input: `rgb[:, :, 0]`

# Loads an RGB sprite without a background.
tileset[0x100002] = imageio.imread("rgb_no_background.png", mode="RGBA")
# If you're stuck with an RGB array then you can pad the channel axis with an alpha of 255:
#   rgba = np.pad(rgb, pad_width=((0, 0), (0, 0), (0, 1)), constant_values=255)

# Loads an RGB sprite with a key color background.
KEY_COLOR = np.asarray((255, 0, 255), dtype=np.uint8)
sprite_rgb = imageio.imread("rgb_tile.png")
# Compare the RGB colors to KEY_COLOR, compress full matches to a 2D mask.
sprite_mask = (sprite_rgb != KEY_COLOR).all(axis=2)
# Generate the alpha array, with 255 as the foreground and 0 as the background.
sprite_alpha = sprite_mask.astype(np.uint8) * 255
# Combine the RGB and alpha arrays into an RGBA array.
sprite_rgba = np.append(sprite_rgb, sprite_alpha, axis=2)
tileset[0x100003] = sprite_rgba

Added in version 20.1.

get_tile(codepoint: int) → NDArray[np.uint8]

Return a copy of a tile for the given codepoint.

If the tile does not exist then a blank zero array will be returned.

The tile will have a shape of (height, width, rgba) and a dtype of uint8. Note that most grey-scale tiles will only use the alpha channel and will usually have a solid white color channel.

remap(codepoint: int, x: int, y: int = 0) → None

Reassign a codepoint to a character in this tileset.

codepoint is the Unicode codepoint to assign.

x and y is the position of the tilesheet to assign to codepoint. This is the tile position itself, not the pixel position of the tile. Large values of x will wrap to the next row, so using x by itself is equivalent to Tile Index in the Character Table Reference.

This is typically used on tilesets loaded with load_tilesheet. Other methods of Tileset creation will not have reliable tile indexes.

Added in version 11.12.

render(console: tcod.console.Console) → NDArray[np.uint8]

Render an RGBA array, using console with this tileset.

console is the Console object to render, this can not be the root console.

The output array will be a np.uint8 array with the shape of: (con_height * tile_height, con_width * tile_width, 4).

Added in version 11.9.

set_tile(codepoint: int, tile: ArrayLike | NDArray[np.uint8]) → None

Upload a tile into this array.

Deprecated since version 20.1: Was replaced with Tileset.__setitem__. Use tileset[codepoint] = tile syntax instead of this method.

property tile_height: int

Height of the tile in pixels.

property tile_shape: tuple[int, int]

Shape (height, width) of the tile in pixels.

property tile_width: int

Width of the tile in pixels.

tcod.tileset.get_default() → Tileset

Return a reference to the default Tileset.

Added in version 11.10.

Deprecated since version 11.13: The default tileset is deprecated. With contexts this is no longer needed.

tcod.tileset.load_bdf(path: str | PathLike[str]) → Tileset

Return a new Tileset from a .bdf file.

For the best results the font should be monospace, cell-based, and single-width. As an example, a good set of fonts would be the Unicode fonts and tools for X11 package.

Pass the returned Tileset to tcod.tileset.set_default and it will take effect when libtcodpy.console_init_root is called.

Added in version 11.10.

tcod.tileset.load_tilesheet(path: str | PathLike[str], columns: int, rows: int, charmap: Iterable[int] | None) → Tileset

Return a new Tileset from a simple tilesheet image.

path is the file path to a PNG file with the tileset.

columns and rows is the shape of the tileset. Tiles are assumed to take up the entire space of the image.

charmap is a sequence of codepoints to map the tilesheet to in row-major order. This is a list or generator of codepoints which map the tiles like this: charmap[tile_index] = codepoint. For common tilesets charmap should be tcod.tileset.CHARMAP_CP437. Generators will be sliced so itertools.count can be used which will give all tiles the same codepoint as their index, but this will not map tiles onto proper Unicode. If None is used then no tiles will be mapped, you will need to use Tileset.remap to assign codepoints to this Tileset.

Image alpha and key colors are handled automatically. For example any tileset from the Dwarf Fortress tileset repository will load correctly with the following example:

Example:

from pathlib import Path

import tcod.tileset

THIS_DIR = Path(__file__, "..")  # Directory of this script file
FONT = THIS_DIR / "assets/tileset.png"  # Replace with any tileset from the DF tileset repository

# Will raise FileNotFoundError if the font is missing!
tileset = tcod.tileset.load_tilesheet(FONT, 16, 16, tcod.tileset.CHARMAP_CP437)

The tileset return value is usually passed to the tileset parameter of tcod.context.new.

Added in version 11.12.

tcod.tileset.load_truetype_font(path: str | PathLike[str], tile_width: int, tile_height: int) → Tileset

Return a new Tileset from a .ttf or .otf file.

Same as set_truetype_font, but returns a Tileset instead. You can send this Tileset to set_default.

This function is provisional. The API may change.

tcod.tileset.procedural_block_elements(*, tileset: Tileset) → Tileset

tcod.tileset.procedural_block_elements(*, shape: tuple[int, int]) → Tileset

Generate and return a Tileset with procedurally generated block elements.

Parameters:

• tileset – A Tileset with tiles of any shape. The codepoints of this tileset will be overwritten. This parameter is deprecated and only shape should be used.

• shape – The (height, width) tile size to generate.

This will overwrite all of the codepoints listed here except for the shade glyphs.

This function is useful for other functions such as Console.draw_semigraphics which use more types of block elements than are found in Code Page 437.

Added in version 13.1.

Changed in version 20.1: Added shape parameter, now returns a Tileset. tileset parameter is deprecated.

Example:

 >>> import tcod.tileset
 >>> tileset = tcod.tileset.Tileset(8, 8)
 >>> tileset += tcod.tileset.procedural_block_elements(shape=tileset.tile_shape)
 >>> tileset.get_tile(0x259E)[:, :, 3]  # "▞" Quadrant upper right and lower left.
 array([[  0,   0,   0,   0, 255, 255, 255, 255],
        [  0,   0,   0,   0, 255, 255, 255, 255],
        [  0,   0,   0,   0, 255, 255, 255, 255],
        [  0,   0,   0,   0, 255, 255, 255, 255],
        [255, 255, 255, 255,   0,   0,   0,   0],
        [255, 255, 255, 255,   0,   0,   0,   0],
        [255, 255, 255, 255,   0,   0,   0,   0],
        [255, 255, 255, 255,   0,   0,   0,   0]], dtype=uint8)
 >>> tileset.get_tile(0x2581)[:, :, 3]  # "▁" Lower one eighth block.
 array([[  0,   0,   0,   0,   0,   0,   0,   0],
        [  0,   0,   0,   0,   0,   0,   0,   0],
        [  0,   0,   0,   0,   0,   0,   0,   0],
        [  0,   0,   0,   0,   0,   0,   0,   0],
        [  0,   0,   0,   0,   0,   0,   0,   0],
        [  0,   0,   0,   0,   0,   0,   0,   0],
        [  0,   0,   0,   0,   0,   0,   0,   0],
        [255, 255, 255, 255, 255, 255, 255, 255]], dtype=uint8)
>>> tileset.get_tile(0x258D)[:, :, 3]  # "▍" Left three eighths block.
array([[255, 255, 255,   0,   0,   0,   0,   0],
       [255, 255, 255,   0,   0,   0,   0,   0],
       [255, 255, 255,   0,   0,   0,   0,   0],
       [255, 255, 255,   0,   0,   0,   0,   0],
       [255, 255, 255,   0,   0,   0,   0,   0],
       [255, 255, 255,   0,   0,   0,   0,   0],
       [255, 255, 255,   0,   0,   0,   0,   0],
       [255, 255, 255,   0,   0,   0,   0,   0]], dtype=uint8)

tcod.tileset.set_default(tileset: Tileset) → None

Set the default tileset.

The display will use this new tileset immediately.

Added in version 11.10.

Deprecated since version 11.13: The default tileset is deprecated. With contexts this is no longer needed.

tcod.tileset.set_truetype_font(path: str | PathLike[str], tile_width: int, tile_height: int) → None

Set the default tileset from a .ttf or .otf file.

path is the file path for the font file.

tile_width and tile_height are the desired size of the tiles in the new tileset. The font will be scaled to fit the given tile_height and tile_width.

This function must be called before libtcodpy.console_init_root. Once the root console is setup you may call this function again to change the font. The tileset can be changed but the window will not be resized automatically.

Added in version 9.2.

Deprecated since version 11.13: This function does not support contexts. Use load_truetype_font instead.

tcod.tileset.CHARMAP_CP437 = [0, 9786, 9787, 9829, 9830, 9827, 9824, 8226, 9688, 9675, 9689, 9794, 9792, 9834, 9835, 9788, 9658, 9668, 8597, 8252, 182, 167, 9644, 8616, 8593, 8595, 8594, 8592, 8735, 8596, 9650, 9660, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 8962, 199, 252, 233, 226, 228, 224, 229, 231, 234, 235, 232, 239, 238, 236, 196, 197, 201, 230, 198, 244, 246, 242, 251, 249, 255, 214, 220, 162, 163, 165, 8359, 402, 225, 237, 243, 250, 241, 209, 170, 186, 191, 8976, 172, 189, 188, 161, 171, 187, 9617, 9618, 9619, 9474, 9508, 9569, 9570, 9558, 9557, 9571, 9553, 9559, 9565, 9564, 9563, 9488, 9492, 9524, 9516, 9500, 9472, 9532, 9566, 9567, 9562, 9556, 9577, 9574, 9568, 9552, 9580, 9575, 9576, 9572, 9573, 9561, 9560, 9554, 9555, 9579, 9578, 9496, 9484, 9608, 9604, 9612, 9616, 9600, 945, 223, 915, 960, 931, 963, 181, 964, 934, 920, 937, 948, 8734, 966, 949, 8745, 8801, 177, 8805, 8804, 8992, 8993, 247, 8776, 176, 8729, 183, 8730, 8319, 178, 9632, 160]

A code page 437 character mapping.

See Code Page 437 for more info and a table of glyphs.

Added in version 11.12.

Changed in version 14.0: Character at index 0x7F was changed from value 0x7F to the HOUSE ⌂ glyph 0x2302.

tcod.tileset.CHARMAP_TCOD = [32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 91, 92, 93, 94, 95, 96, 123, 124, 125, 126, 9617, 9618, 9619, 9474, 9472, 9532, 9508, 9524, 9500, 9516, 9492, 9484, 9488, 9496, 9624, 9629, 9600, 9622, 9626, 9616, 9623, 8593, 8595, 8592, 8594, 9650, 9660, 9668, 9658, 8597, 8596, 9744, 9745, 9675, 9673, 9553, 9552, 9580, 9571, 9577, 9568, 9574, 9562, 9556, 9559, 9565, 0, 0, 0, 0, 0, 0, 0, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 0, 0, 0, 0, 0, 0, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 0, 0, 0, 0, 0, 0]

The layout used by older libtcod fonts, in Unicode.

This layout is non-standard, and it’s not recommend to make a font for it, but you might need it to load an existing font made for libtcod.

This character map is in Unicode, so old code using the non-Unicode tcod.CHAR_* constants will need to be updated.

See Deprecated TCOD Layout for a table of glyphs used in this character map.

Added in version 11.12.