Old API Functions libtcodpy

This is all the functions included since the start of the Python port. This collection is often called libtcodpy, the name of the original Python port. These functions are reproduced by python-tcod in their entirely.

Use from tcod import libtcodpy to access this module.

A large majority of these functions are deprecated and will be removed in the future. In general this entire section should be avoided whenever possible. See Getting Started for how to make a new python-tcod project with its modern API.

bsp

libtcodpy.bsp_new_with_size(x: int, y: int, w: int, h: int) → BSP

Create a new BSP instance with the given rectangle.

Parameters:

• x (int) – Rectangle left coordinate.

• y (int) – Rectangle top coordinate.

• w (int) – Rectangle width.

• h (int) – Rectangle height.

Returns:

A new BSP instance.

Return type:

BSP

Deprecated since version 2.0: Call the BSP class instead.

libtcodpy.bsp_split_once(node: BSP, horizontal: bool, position: int) → None

Deprecated function.

Deprecated since version 2.0: Use BSP.split_once instead.

libtcodpy.bsp_split_recursive(node: BSP, randomizer: Random | None, nb: int, minHSize: int, minVSize: int, maxHRatio: float, maxVRatio: float) → None

Deprecated function.

Deprecated since version 2.0: Use BSP.split_recursive instead.

libtcodpy.bsp_resize(node: BSP, x: int, y: int, w: int, h: int) → None

Deprecated function.

Deprecated since version 2.0: Assign directly to BSP attributes instead.

libtcodpy.bsp_left(node: BSP) → BSP | None

Deprecated function.

Deprecated since version 2.0: Use BSP.children instead.

libtcodpy.bsp_right(node: BSP) → BSP | None

Deprecated function.

Deprecated since version 2.0: Use BSP.children instead.

libtcodpy.bsp_father(node: BSP) → BSP | None

Deprecated function.

Deprecated since version 2.0: Use BSP.parent instead.

libtcodpy.bsp_is_leaf(node: BSP) → bool

Deprecated function.

Deprecated since version 2.0: Use BSP.children instead.

libtcodpy.bsp_contains(node: BSP, cx: int, cy: int) → bool

Deprecated function.

Deprecated since version 2.0: Use BSP.contains instead.

libtcodpy.bsp_find_node(node: BSP, cx: int, cy: int) → BSP | None

Deprecated function.

Deprecated since version 2.0: Use BSP.find_node instead.

libtcodpy.bsp_traverse_pre_order(node: BSP, callback: Callable[[BSP, Any], None], userData: Any = 0) → None

Traverse this nodes hierarchy with a callback.

Deprecated since version 2.0: Use BSP.pre_order instead.

libtcodpy.bsp_traverse_in_order(node: BSP, callback: Callable[[BSP, Any], None], userData: Any = 0) → None

Traverse this nodes hierarchy with a callback.

Deprecated since version 2.0: Use BSP.in_order instead.

libtcodpy.bsp_traverse_post_order(node: BSP, callback: Callable[[BSP, Any], None], userData: Any = 0) → None

Traverse this nodes hierarchy with a callback.

Deprecated since version 2.0: Use BSP.post_order instead.

libtcodpy.bsp_traverse_level_order(node: BSP, callback: Callable[[BSP, Any], None], userData: Any = 0) → None

Traverse this nodes hierarchy with a callback.

Deprecated since version 2.0: Use BSP.level_order instead.

libtcodpy.bsp_traverse_inverted_level_order(node: BSP, callback: Callable[[BSP, Any], None], userData: Any = 0) → None

Traverse this nodes hierarchy with a callback.

Deprecated since version 2.0: Use BSP.inverted_level_order instead.

libtcodpy.bsp_remove_sons(node: BSP) → None

Delete all children of a given node. Not recommended.

Note

This function will add unnecessary complexity to your code. Don’t use it.

Deprecated since version 2.0: BSP deletion is automatic.

libtcodpy.bsp_delete(node: BSP) → None

Exists for backward compatibility. Does nothing.

BSP’s created by this library are automatically garbage collected once there are no references to the tree. This function exists for backwards compatibility.

Deprecated since version 2.0: BSP deletion is automatic.

color

class libtcodpy.Color(r: int = 0, g: int = 0, b: int = 0)

Old-style libtcodpy color class.

Parameters:

• r (int) – Red value, from 0 to 255.

• g (int) – Green value, from 0 to 255.

• b (int) – Blue value, from 0 to 255.

property r: int

Red value, always normalized to 0-255.

Deprecated since version 9.2: Color attributes will not be mutable in the future.

Type:

int

property g: int

Green value, always normalized to 0-255.

Deprecated since version 9.2: Color attributes will not be mutable in the future.

Type:

int

property b: int

Blue value, always normalized to 0-255.

Deprecated since version 9.2: Color attributes will not be mutable in the future.

Type:

int

__getitem__(index: Any) → Any

Return a color channel.

Deprecated since version 9.2: Accessing colors via a letter index is deprecated.

__eq__(other: object) → bool

Compare equality between colors.

Also compares with standard sequences such as 3-item tuples or lists.

__add__(other: object) → Color

Add two colors together.

Deprecated since version 9.2: Use NumPy instead for color math operations.

__sub__(other: object) → Color

Subtract one color from another.

Deprecated since version 9.2: Use NumPy instead for color math operations.

__mul__(other: object) → Color

Multiply with a scaler or another color.

Deprecated since version 9.2: Use NumPy instead for color math operations.

__repr__() → str

Return a printable representation of the current color.

libtcodpy.color_lerp(c1: tuple[int, int, int], c2: tuple[int, int, int], a: float) → Color

Return the linear interpolation between two colors.

a is the interpolation value, with 0 returning c1, 1 returning c2, and 0.5 returning a color halfway between both.

Parameters:

• c1 (Union[Tuple[int, int, int], Sequence[int]]) – The first color. At a=0.

• c2 (Union[Tuple[int, int, int], Sequence[int]]) – The second color. At a=1.

• a (float) – The interpolation value,

Returns:

The interpolated Color.

Return type:

Color

libtcodpy.color_set_hsv(c: Color, h: float, s: float, v: float) → None

Set a color using: hue, saturation, and value parameters.

Does not return a new Color. c is modified in-place.

Parameters:

• c (Union[Color, List[Any]]) – A Color instance, or a list of any kind.

• h (float) – Hue, from 0 to 360.

• s (float) – Saturation, from 0 to 1.

• v (float) – Value, from 0 to 1.

libtcodpy.color_get_hsv(c: tuple[int, int, int]) → tuple[float, float, float]

Return the (hue, saturation, value) of a color.

Parameters:

c (Union[Tuple[int, int, int], Sequence[int]]) – An (r, g, b) sequence or Color instance.

Returns:

A tuple with (hue, saturation, value) values, from 0 to 1.

Return type:

Tuple[float, float, float]

libtcodpy.color_scale_HSV(c: Color, scoef: float, vcoef: float) → None

Scale a color’s saturation and value.

Does not return a new Color. c is modified in-place.

Parameters:

• c (Union[Color, List[int]]) – A Color instance, or an [r, g, b] list.

• scoef (float) – Saturation multiplier, from 0 to 1. Use 1 to keep current saturation.

• vcoef (float) – Value multiplier, from 0 to 1. Use 1 to keep current value.

libtcodpy.color_gen_map(colors: Iterable[tuple[int, int, int]], indexes: Iterable[int]) → list[Color]

Return a smoothly defined scale of colors.

If indexes is [0, 3, 9] for example, the first color from colors will be returned at 0, the 2nd will be at 3, and the 3rd will be at 9. All in-betweens will be filled with a gradient.

Parameters:

• colors (Iterable[Union[Tuple[int, int, int], Sequence[int]]]) – Array of colors to be sampled.

• indexes (Iterable[int]) – A list of indexes.

Returns:

A list of Color instances.

Return type:

List[Color]

Example

>>> tcod.color_gen_map([(0, 0, 0), (255, 128, 0)], [0, 5])
[Color(0, 0, 0), Color(51, 25, 0), Color(102, 51, 0), Color(153, 76, 0), Color(204, 102, 0), Color(255, 128, 0)]

color controls

Libtcod color control constants. These can be inserted into Python strings with the %c format specifier as shown below.

libtcodpy.COLCTRL_1

These can be configured with libtcodpy.console_set_color_control. However, it is recommended to use libtcodpy.COLCTRL_FORE_RGB and libtcodpy.COLCTRL_BACK_RGB instead.

libtcodpy.COLCTRL_2

libtcodpy.COLCTRL_3

libtcodpy.COLCTRL_4

libtcodpy.COLCTRL_5

libtcodpy.COLCTRL_STOP

When this control character is inserted into a string the foreground and background colors will be reset for the remaining characters of the string.

>>> import tcod
>>> reset_color = f"{libtcodpy.COLCTRL_STOP:c}"

libtcodpy.COLCTRL_FORE_RGB

Sets the foreground color to the next 3 Unicode characters for the remaining characters.

>>> fg = (255, 255, 255)
>>> change_fg = f"{libtcodpy.COLCTRL_FORE_RGB:c}{fg[0]:c}{fg[1]:c}{fg[2]:c}"
>>> string = f"Old color {change_fg}new color{libtcodpy.COLCTRL_STOP:c} old color."

libtcodpy.COLCTRL_BACK_RGB

Sets the background color to the next 3 Unicode characters for the remaining characters.

>>> from typing import Tuple
>>> def change_colors(fg: Tuple[int, int, int], bg: Tuple[int, int, int]) -> str:
...     """Return the control codes to change the foreground and background colors."""
...     return "%c%c%c%c%c%c%c%c" % (libtcodpy.COLCTRL_FORE_RGB, *fg, libtcodpy.COLCTRL_BACK_RGB, *bg)
>>> string = f"Old {change_colors(fg=(255, 255, 255), bg=(0, 0, 255))}new"

console

libtcodpy.console_set_custom_font(fontFile: str | PathLike[str], flags: int = 1, nb_char_horiz: int = 0, nb_char_vertic: int = 0) → None

Load the custom font file at fontFile.

Call this before function before calling libtcodpy.console_init_root.

Flags can be a mix of the following:

• libtcodpy.FONT_LAYOUT_ASCII_INCOL: Decode tileset raw in column-major order.

• libtcodpy.FONT_LAYOUT_ASCII_INROW: Decode tileset raw in row-major order.

• libtcodpy.FONT_TYPE_GREYSCALE: Force tileset to be read as greyscale.

• libtcodpy.FONT_TYPE_GRAYSCALE

• libtcodpy.FONT_LAYOUT_TCOD: Unique layout used by libtcod.

• libtcodpy.FONT_LAYOUT_CP437: Decode a row-major Code Page 437 tileset into Unicode.

nb_char_horiz and nb_char_vertic are the columns and rows of the font file respectfully.

Deprecated since version 11.13: Load fonts using tcod.tileset.load_tilesheet instead. See Getting Started for more info.

Changed in version 16.0: Added PathLike support. fontFile no longer takes bytes.

libtcodpy.console_init_root(w: int, h: int, title: str | None = None, fullscreen: bool = False, renderer: int | None = None, order: Literal['C', 'F'] = 'C', vsync: bool | None = None) → Console

Set up the primary display and return the root console.

w and h are the columns and rows of the new window (in tiles.)

title is an optional string to display on the windows title bar.

fullscreen determines if the window will start in fullscreen. Fullscreen mode is unreliable unless the renderer is set to tcod.RENDERER_SDL2 or tcod.RENDERER_OPENGL2.

renderer is the rendering back-end that libtcod will use. If you don’t know which to pick, then use tcod.RENDERER_SDL2. Options are:

• tcod.RENDERER_SDL: Forces the SDL2 renderer into software mode.

• tcod.RENDERER_OPENGL: An OpenGL 1 implementation.

• tcod.RENDERER_GLSL: A deprecated SDL2/OpenGL2 renderer.

• tcod.RENDERER_SDL2: The recommended SDL2 renderer. Rendering is decided by SDL2 and can be changed by using an SDL2 hint.

• tcod.RENDERER_OPENGL2: An SDL2/OPENGL2 renderer. Usually faster than regular SDL2. Requires OpenGL 2.0 Core.

order will affect how the array attributes of the returned root console are indexed. order=’C’ is the default, but order=’F’ is recommended.

If vsync is True then the frame-rate will be synchronized to the monitors vertical refresh rate. This prevents screen tearing and avoids wasting computing power on overdraw. If vsync is False then the frame-rate will be uncapped. The default is False but will change to True in the future. This option only works with the SDL2 or OPENGL2 renderers, any other renderer will always have vsync disabled.

The returned object is the root console. You don’t need to use this object but you should at least close it when you’re done with the libtcod window. You can do this by calling Console.close or by using this function in a context, like in the following example:

with libtcodpy.console_init_root(80, 50, vsync=True) as root_console:
    ...  # Put your game loop here.
...  # Window closes at the end of the above block.

Changed in version 4.3: Added order parameter. title parameter is now optional.

Changed in version 8.0: The default renderer is now automatic instead of always being RENDERER_SDL.

Changed in version 10.1: Added the vsync parameter.

Deprecated since version 11.13: Use tcod.context for window management. See Getting Started for more info.

libtcodpy.console_flush(console: Console | None = None, *, keep_aspect: bool = False, integer_scaling: bool = False, snap_to_integer: bool | None = None, clear_color: tuple[int, int, int] | tuple[int, int, int, int] = (0, 0, 0), align: tuple[float, float] = (0.5, 0.5)) → None

Update the display to represent the root consoles current state.

console is the console you want to present. If not given the root console will be used.

If keep_aspect is True then the console aspect will be preserved with a letterbox. Otherwise the console will be stretched to fill the screen.

If integer_scaling is True then the console will be scaled in integer increments. This will have no effect if the console must be shrunk. You can use tcod.console.recommended_size to create a console which will fit the window without needing to be scaled.

clear_color is an RGB or RGBA tuple used to clear the screen before the console is presented, this will normally affect the border/letterbox color.

align determines where the console will be placed when letter-boxing exists. Values of 0 will put the console at the upper-left corner. Values of 0.5 will center the console.

snap_to_integer is deprecated and setting it will have no effect. It will be removed in a later version.

Changed in version 11.8: The parameters console, keep_aspect, integer_scaling, snap_to_integer, clear_color, and align were added.

Changed in version 11.11: clear_color can now be an RGB tuple.

See also

libtcodpy.console_init_root tcod.console.recommended_size

Deprecated since version 11.13: This function is not supported by contexts.

libtcodpy.console_blit(src: Console, x: int, y: int, w: int, h: int, dst: Console, xdst: int, ydst: int, ffade: float = 1.0, bfade: float = 1.0) → None

Blit the console src from x,y,w,h to console dst at xdst,ydst.

Deprecated since version 8.5: Call the Console.blit method instead.

libtcodpy.console_check_for_keypress(flags: int = 2) → Key

Return a recently pressed key.

Deprecated since version 9.3: Use the tcod.event.get function to check for events.

Example:

for event in tcod.event.get():
    if isinstance(event, tcod.event.KeyDown):
        ...

libtcodpy.console_clear(con: Console) → None

Reset a console to its default colors and the space character.

Parameters:

con (Console) – Any Console instance.

See also

console_set_default_background console_set_default_foreground

Deprecated since version 8.5: Call the Console.clear method instead.

libtcodpy.console_credits() → None

libtcodpy.console_credits_render(x: int, y: int, alpha: bool) → bool

libtcodpy.console_credits_reset() → None

libtcodpy.console_delete(con: Console) → None

Closes the window if con is the root console.

libtcod objects are automatically garbage collected once they go out of scope.

This function exists for backwards compatibility.

Deprecated since version 9.3: This function is not needed for normal tcod.console.Console’s. The root console should be used in a with statement instead to ensure that it closes.

libtcodpy.console_fill_background(con: Console, r: Sequence[int], g: Sequence[int], b: Sequence[int]) → None

Fill the background of a console with r,g,b.

Parameters:

• con (Console) – Any Console instance.

• r (Sequence[int]) – An array of integers with a length of width*height.

• g (Sequence[int]) – An array of integers with a length of width*height.

• b (Sequence[int]) – An array of integers with a length of width*height.

Deprecated since version 8.4: You should assign to tcod.console.Console.bg instead.

libtcodpy.console_fill_char(con: Console, arr: Sequence[int]) → None

Fill the character tiles of a console with an array.

arr is an array of integers with a length of the consoles width and height.

Deprecated since version 8.4: You should assign to tcod.console.Console.ch instead.

libtcodpy.console_fill_foreground(con: Console, r: Sequence[int], g: Sequence[int], b: Sequence[int]) → None

Fill the foreground of a console with r,g,b.

Parameters:

• con (Console) – Any Console instance.

• r (Sequence[int]) – An array of integers with a length of width*height.

• g (Sequence[int]) – An array of integers with a length of width*height.

• b (Sequence[int]) – An array of integers with a length of width*height.

Deprecated since version 8.4: You should assign to tcod.console.Console.fg instead.

libtcodpy.console_from_file(filename: str | PathLike[str]) → Console

Return a new console object from a filename.

The file format is automatically determined. This can load REXPaint .xp, ASCII Paint .apf, or Non-delimited ASCII .asc files.

Parameters:

filename (Text) – The path to the file, as a string.

Returns: A new :any`Console` instance.

Deprecated since version 12.7: Use libtcodpy.console_load_xp to load REXPaint consoles.

Other formats are not actively supported.

Changed in version 16.0: Added PathLike support.

libtcodpy.console_from_xp(filename: str | PathLike[str]) → Console

Return a single console from a REXPaint .xp file.

Changed in version 16.0: Added PathLike support.

libtcodpy.console_get_alignment(con: Console) → int

Return this consoles current alignment mode.

Parameters:

con (Console) – Any Console instance.

Deprecated since version 8.5: Check Console.default_alignment instead.

libtcodpy.console_get_background_flag(con: Console) → int

Return this consoles current blend mode.

Parameters:

con (Console) – Any Console instance.

Deprecated since version 8.5: Check Console.default_bg_blend instead.

libtcodpy.console_get_char(con: Console, x: int, y: int) → int

Return the character at the x,y of this console.

Deprecated since version 8.4: Array access performs significantly faster than using this function. See Console.ch.

libtcodpy.console_get_char_background(con: Console, x: int, y: int) → Color

Return the background color at the x,y of this console.

Deprecated since version 8.4: Array access performs significantly faster than using this function. See Console.bg.

libtcodpy.console_get_char_foreground(con: Console, x: int, y: int) → Color

Return the foreground color at the x,y of this console.

Deprecated since version 8.4: Array access performs significantly faster than using this function. See Console.fg.

libtcodpy.console_get_default_background(con: Console) → Color

Return this consoles default background color.

Deprecated since version 8.5: Use Console.default_bg instead.

libtcodpy.console_get_default_foreground(con: Console) → Color

Return this consoles default foreground color.

Deprecated since version 8.5: Use Console.default_fg instead.

libtcodpy.console_get_fade() → int

Deprecated function.

Deprecated since version 11.13: This function is not supported by contexts.

libtcodpy.console_get_fading_color() → Color

Deprecated function.

Deprecated since version 11.13: This function is not supported by contexts.

libtcodpy.console_get_height(con: Console) → int

Return the height of a console.

Parameters:

con (Console) – Any Console instance.

Returns:

The height of a Console.

Return type:

int

Deprecated since version 2.0: Use Console.height instead.

libtcodpy.console_get_height_rect(con: Console, x: int, y: int, w: int, h: int, fmt: str) → int

Return the height of this text once word-wrapped into this rectangle.

Returns:

The number of lines of text once word-wrapped.

Return type:

int

Deprecated since version 8.5: Use Console.get_height_rect instead.

libtcodpy.console_get_width(con: Console) → int

Return the width of a console.

Parameters:

con (Console) – Any Console instance.

Returns:

The width of a Console.

Return type:

int

Deprecated since version 2.0: Use Console.width instead.

libtcodpy.console_hline(con: Console, x: int, y: int, l: int, flag: int = 13) → None

Draw a horizontal line on the console.

This always uses the character 196, the horizontal line character.

Deprecated since version 8.5: Use Console.hline instead.

libtcodpy.console_is_fullscreen() → bool

Returns True if the display is fullscreen.

Returns:

True if the display is fullscreen, otherwise False.

Return type:

bool

Deprecated since version 11.13: This function is not supported by contexts.

libtcodpy.console_is_key_pressed(key: int) → bool

Return True if a key is held.

Deprecated since version 12.7: Use tcod.event.get_keyboard_state to check if a key is held.

libtcodpy.console_is_window_closed() → bool

Returns True if the window has received and exit event.

Deprecated since version 9.3: Use the tcod.event module to check for “QUIT” type events.

libtcodpy.console_load_apf(con: Console, filename: str | PathLike[str]) → bool

Update a console from an ASCII Paint .apf file.

Deprecated since version 12.7: This format is no longer supported.

Changed in version 16.0: Added PathLike support.

libtcodpy.console_load_asc(con: Console, filename: str | PathLike[str]) → bool

Update a console from a non-delimited ASCII .asc file.

Deprecated since version 12.7: This format is no longer supported.

Changed in version 16.0: Added PathLike support.

libtcodpy.console_load_xp(con: Console, filename: str | PathLike[str]) → bool

Update a console from a REXPaint .xp file.

Deprecated since version 11.18: Functions modifying console objects in-place are deprecated. Use libtcodpy.console_from_xp to load a Console from a file.

Changed in version 16.0: Added PathLike support.

libtcodpy.console_list_load_xp(filename: str | PathLike[str]) → list[Console] | None

Return a list of consoles from a REXPaint .xp file.

Changed in version 16.0: Added PathLike support.

libtcodpy.console_list_save_xp(console_list: Sequence[Console], filename: str | PathLike[str], compress_level: int = 9) → bool

Save a list of consoles to a REXPaint .xp file.

Changed in version 16.0: Added PathLike support.

libtcodpy.console_map_ascii_code_to_font(asciiCode: int, fontCharX: int, fontCharY: int) → None

Set a character code to new coordinates on the tile-set.

asciiCode should be any Unicode codepoint.

Parameters:

• asciiCode (int) – The character code to change.

• fontCharX (int) – The X tile coordinate on the loaded tileset. 0 is the leftmost tile.

• fontCharY (int) – The Y tile coordinate on the loaded tileset. 0 is the topmost tile.

Deprecated since version 11.13: Setup fonts using the tcod.tileset module. Tileset.remap replaces this function.

libtcodpy.console_map_ascii_codes_to_font(firstAsciiCode: int, nbCodes: int, fontCharX: int, fontCharY: int) → None

Remap a contiguous set of codes to a contiguous set of tiles.

Both the tile-set and character codes must be contiguous to use this function. If this is not the case you may want to use console_map_ascii_code_to_font.

Parameters:

• firstAsciiCode (int) – The starting character code.

• nbCodes (int) – The length of the contiguous set.

• fontCharX (int) – The starting X tile coordinate on the loaded tileset. 0 is the leftmost tile.

• fontCharY (int) – The starting Y tile coordinate on the loaded tileset. 0 is the topmost tile.

Deprecated since version 11.13: Setup fonts using the tcod.tileset module. Tileset.remap replaces this function.

libtcodpy.console_map_string_to_font(s: str, fontCharX: int, fontCharY: int) → None

Remap a string of codes to a contiguous set of tiles.

Parameters:

• s (AnyStr) – A string of character codes to map to new values. Any null character ‘x00’ will prematurely end the printed text.

• fontCharX (int) – The starting X tile coordinate on the loaded tileset. 0 is the leftmost tile.

• fontCharY (int) – The starting Y tile coordinate on the loaded tileset. 0 is the topmost tile.

Deprecated since version 11.13: Setup fonts using the tcod.tileset module. Tileset.remap replaces this function.

libtcodpy.console_new(w: int, h: int) → Console

Return an offscreen console of size: w,h.

Deprecated since version 8.5: Create new consoles using tcod.console.Console instead of this function.

libtcodpy.console_print(con: Console, x: int, y: int, fmt: str) → None

Print a color formatted string on a console.

Parameters:

• con (Console) – Any Console instance.

• x (int) – Character x position from the left.

• y (int) – Character y position from the top.

• fmt (AnyStr) – A unicode or bytes string optionally using color codes.

Deprecated since version 8.5: Use Console.print_ instead.

libtcodpy.console_print_ex(con: Console, x: int, y: int, flag: int, alignment: int, fmt: str) → None

Print a string on a console using a blend mode and alignment mode.

Parameters:

• con (Console) – Any Console instance.

• x (int) – Character x position from the left.

• y (int) – Character y position from the top.

• flag – Blending mode to use.

• alignment – The libtcod alignment constant.

• fmt – A unicode or bytes string, optionally using color codes.

Deprecated since version 8.5: Use Console.print_ instead.

libtcodpy.console_print_frame(con: Console, x: int, y: int, w: int, h: int, clear: bool = True, flag: int = 13, fmt: str = '') → None

Draw a framed rectangle with optional text.

This uses the default background color and blend mode to fill the rectangle and the default foreground to draw the outline.

fmt will be printed on the inside of the rectangle, word-wrapped. If fmt is empty then no title will be drawn.

Changed in version 8.2: Now supports Unicode strings.

Deprecated since version 8.5: Use Console.print_frame instead.

libtcodpy.console_print_rect(con: Console, x: int, y: int, w: int, h: int, fmt: str) → int

Print a string constrained to a rectangle.

If h > 0 and the bottom of the rectangle is reached, the string is truncated. If h = 0, the string is only truncated if it reaches the bottom of the console.

Returns:

The number of lines of text once word-wrapped.

Return type:

int

Deprecated since version 8.5: Use Console.print_rect instead.

libtcodpy.console_print_rect_ex(con: Console, x: int, y: int, w: int, h: int, flag: int, alignment: int, fmt: str) → int

Print a string constrained to a rectangle with blend and alignment.

Returns:

The number of lines of text once word-wrapped.

Return type:

int

Deprecated since version 8.5: Use Console.print_rect instead.

libtcodpy.console_put_char(con: Console, x: int, y: int, c: int | str, flag: int = 13) → None

Draw the character c at x,y using the default colors and a blend mode.

Parameters:

• con (Console) – Any Console instance.

• x (int) – Character x position from the left.

• y (int) – Character y position from the top.

• c (Union[int, AnyStr]) – Character to draw, can be an integer or string.

• flag (int) – Blending mode to use, defaults to BKGND_DEFAULT.

libtcodpy.console_put_char_ex(con: Console, x: int, y: int, c: int | str, fore: tuple[int, int, int], back: tuple[int, int, int]) → None

Draw the character c at x,y using the colors fore and back.

Parameters:

• con (Console) – Any Console instance.

• x (int) – Character x position from the left.

• y (int) – Character y position from the top.

• c (Union[int, AnyStr]) – Character to draw, can be an integer or string.

• fore (Union[Tuple[int, int, int], Sequence[int]]) – An (r, g, b) sequence or Color instance.

• back (Union[Tuple[int, int, int], Sequence[int]]) – An (r, g, b) sequence or Color instance.

libtcodpy.console_rect(con: Console, x: int, y: int, w: int, h: int, clr: bool, flag: int = 13) → None

Draw a the background color on a rect optionally clearing the text.

If clr is True the affected tiles are changed to space character.

Deprecated since version 8.5: Use Console.rect instead.

libtcodpy.console_save_apf(con: Console, filename: str | PathLike[str]) → bool

Save a console to an ASCII Paint .apf file.

Deprecated since version 12.7: This format is no longer supported.

Changed in version 16.0: Added PathLike support.

libtcodpy.console_save_asc(con: Console, filename: str | PathLike[str]) → bool

Save a console to a non-delimited ASCII .asc file.

Deprecated since version 12.7: This format is no longer supported.

Changed in version 16.0: Added PathLike support.

libtcodpy.console_save_xp(con: Console, filename: str | PathLike[str], compress_level: int = 9) → bool

Save a console to a REXPaint .xp file.

Changed in version 16.0: Added PathLike support.

libtcodpy.console_set_alignment(con: Console, alignment: int) → None

Change this consoles current alignment mode.

• tcod.LEFT

• tcod.CENTER

• tcod.RIGHT

Parameters:

• con (Console) – Any Console instance.

• alignment (int) – The libtcod alignment constant.

Deprecated since version 8.5: Set Console.default_alignment instead.

libtcodpy.console_set_background_flag(con: Console, flag: int) → None

Change the default blend mode for this console.

Parameters:

• con (Console) – Any Console instance.

• flag (int) – Blend mode to use by default.

Deprecated since version 8.5: Set Console.default_bg_blend instead.

libtcodpy.console_set_char(con: Console, x: int, y: int, c: int | str) → None

Change the character at x,y to c, keeping the current colors.

Parameters:

• con (Console) – Any Console instance.

• x (int) – Character x position from the left.

• y (int) – Character y position from the top.

• c (Union[int, AnyStr]) – Character to draw, can be an integer or string.

Deprecated since version 8.4: Array access performs significantly faster than using this function. See Console.ch.

libtcodpy.console_set_char_background(con: Console, x: int, y: int, col: tuple[int, int, int], flag: int = 1) → None

Change the background color of x,y to col using a blend mode.

Parameters:

• con (Console) – Any Console instance.

• x (int) – Character x position from the left.

• y (int) – Character y position from the top.

• col (Union[Tuple[int, int, int], Sequence[int]]) – An (r, g, b) sequence or Color instance.

• flag (int) – Blending mode to use, defaults to BKGND_SET.

libtcodpy.console_set_char_foreground(con: Console, x: int, y: int, col: tuple[int, int, int]) → None

Change the foreground color of x,y to col.

Parameters:

• con (Console) – Any Console instance.

• x (int) – Character x position from the left.

• y (int) – Character y position from the top.

• col (Union[Tuple[int, int, int], Sequence[int]]) – An (r, g, b) sequence or Color instance.

Deprecated since version 8.4: Array access performs significantly faster than using this function. See Console.fg.

libtcodpy.console_set_color_control(con: int, fore: tuple[int, int, int], back: tuple[int, int, int]) → None

Configure color controls.

Parameters:

• con (int) – Color control constant to modify.

• fore (Union[Tuple[int, int, int], Sequence[int]]) – An (r, g, b) sequence or Color instance.

• back (Union[Tuple[int, int, int], Sequence[int]]) – An (r, g, b) sequence or Color instance.

libtcodpy.console_set_default_background(con: Console, col: tuple[int, int, int]) → None

Change the default background color for a console.

Parameters:

• con (Console) – Any Console instance.

• col (Union[Tuple[int, int, int], Sequence[int]]) – An (r, g, b) sequence or Color instance.

Deprecated since version 8.5: Use Console.default_bg instead.

libtcodpy.console_set_default_foreground(con: Console, col: tuple[int, int, int]) → None

Change the default foreground color for a console.

Parameters:

• con (Console) – Any Console instance.

• col (Union[Tuple[int, int, int], Sequence[int]]) – An (r, g, b) sequence or Color instance.

Deprecated since version 8.5: Use Console.default_fg instead.

libtcodpy.console_set_fade(fade: int, fadingColor: tuple[int, int, int]) → None

Deprecated function.

Deprecated since version 11.13: This function is not supported by contexts.

libtcodpy.console_set_fullscreen(fullscreen: bool) → None

Change the display to be fullscreen or windowed.

Parameters:

fullscreen (bool) – Use True to change to fullscreen. Use False to change to windowed.

Deprecated since version 11.13: This function is not supported by contexts.

libtcodpy.console_set_key_color(con: Console, col: tuple[int, int, int]) → None

Set a consoles blit transparent color.

Deprecated since version 8.5: Pass the key color to tcod.console.Console.blit instead of calling this function.

libtcodpy.console_set_window_title(title: str) → None

Change the current title bar string.

Parameters:

title (AnyStr) – A string to change the title bar to.

Deprecated since version 11.13: This function is not supported by contexts.

libtcodpy.console_vline(con: Console, x: int, y: int, l: int, flag: int = 13) → None

Draw a vertical line on the console.

This always uses the character 179, the vertical line character.

Deprecated since version 8.5: Use Console.vline instead.

libtcodpy.console_wait_for_keypress(flush: bool) → Key

Block until the user presses a key, then returns a new Key.

Parameters:

flush – If True then the event queue is cleared before waiting for the next event.

Returns:

A new Key instance.

Return type:

Key

Deprecated since version 9.3: Use the tcod.event.wait function to wait for events.

Example:

for event in tcod.event.wait():
    if isinstance(event, tcod.event.KeyDown):
        ...

Event

class libtcodpy.Key

Key Event instance.

vk

TCOD_keycode_t key code

Type:

int

c

character if vk == TCODK_CHAR else 0

Type:

int

text

text[TCOD_KEY_TEXT_SIZE]; text if vk == TCODK_TEXT else text[0] == ‘0’

Type:

Text

pressed

does this correspond to a key press or key release event?

Type:

bool

lalt

True when left alt is held.

Type:

bool

lctrl

True when left control is held.

Type:

bool

lmeta

True when left meta key is held.

Type:

bool

ralt

True when right alt is held.

Type:

bool

rctrl

True when right control is held.

Type:

bool

rmeta

True when right meta key is held.

Type:

bool

shift

True when any shift is held.

Type:

bool

Deprecated since version 9.3: Use events from the tcod.event module instead.

__repr__() → str

Return a representation of this Key object.

class libtcodpy.Mouse

Mouse event instance.

x

Absolute mouse position at pixel x.

Type:

int

y

Type:

int

dx

Movement since last update in pixels.

Type:

int

dy

Type:

int

cx

Cell coordinates in the root console.

Type:

int

cy

Type:

int

dcx

Movement since last update in console cells.

Type:

int

dcy

Type:

int

lbutton

Left button status.

Type:

bool

rbutton

Right button status.

Type:

bool

mbutton

Middle button status.

Type:

bool

lbutton_pressed

Left button pressed event.

Type:

bool

rbutton_pressed

Right button pressed event.

Type:

bool

mbutton_pressed

Middle button pressed event.

Type:

bool

wheel_up

Wheel up event.

Type:

bool

wheel_down

Wheel down event.

Type:

bool

Deprecated since version 9.3: Use events from the tcod.event module instead.

__repr__() → str

Return a representation of this Mouse object.

Event Types

libtcodpy.EVENT_NONE

libtcodpy.EVENT_KEY_PRESS

libtcodpy.EVENT_KEY_RELEASE

libtcodpy.EVENT_KEY

Same as libtcodpy.EVENT_KEY_PRESS | libtcodpy.EVENT_KEY_RELEASE

libtcodpy.EVENT_MOUSE_MOVE

libtcodpy.EVENT_MOUSE_PRESS

libtcodpy.EVENT_MOUSE_RELEASE

libtcodpy.EVENT_MOUSE

Same as libtcodpy.EVENT_MOUSE_MOVE | libtcodpy.EVENT_MOUSE_PRESS | libtcodpy.EVENT_MOUSE_RELEASE

libtcodpy.EVENT_FINGER_MOVE

libtcodpy.EVENT_FINGER_PRESS

libtcodpy.EVENT_FINGER_RELEASE

libtcodpy.EVENT_FINGER

Same as libtcodpy.EVENT_FINGER_MOVE | libtcodpy.EVENT_FINGER_PRESS | libtcodpy.EVENT_FINGER_RELEASE

libtcodpy.EVENT_ANY

Same as libtcodpy.EVENT_KEY | libtcodpy.EVENT_MOUSE | libtcodpy.EVENT_FINGER

sys

libtcodpy.sys_set_fps(fps: int) → None

Set the maximum frame rate.

You can disable the frame limit again by setting fps to 0.

Parameters:

fps (int) – A frame rate limit (i.e. 60)

Deprecated since version 11.13: This function is not supported by contexts.

libtcodpy.sys_get_fps() → int

Return the current frames per second.

This the actual frame rate, not the frame limit set by libtcodpy.sys_set_fps.

This number is updated every second.

Returns:

The currently measured frame rate.

Return type:

int

Deprecated since version 11.13: This function is not supported by contexts.

libtcodpy.sys_get_last_frame_length() → float

Return the delta time of the last rendered frame in seconds.

Returns:

The delta time of the last rendered frame.

Return type:

float

Deprecated since version 11.13: This function is not supported by contexts.

libtcodpy.sys_sleep_milli(val: int) → None

Sleep for ‘val’ milliseconds.

Parameters:

val (int) – Time to sleep for in milliseconds.

Deprecated since version 2.0: Use time.sleep instead.

libtcodpy.sys_elapsed_milli() → int

Get number of milliseconds since the start of the program.

Returns:

Time since the program has started in milliseconds.

Return type:

int

Deprecated since version 2.0: Use Python’s time module instead.

libtcodpy.sys_elapsed_seconds() → float

Get number of seconds since the start of the program.

Returns:

Time since the program has started in seconds.

Return type:

float

Deprecated since version 2.0: Use Python’s time module instead.

libtcodpy.sys_set_renderer(renderer: int) → None

Change the current rendering mode to renderer.

Deprecated since version 11.13: This function is not supported by contexts.

libtcodpy.sys_get_renderer() → int

Return the current rendering mode.

Deprecated since version 11.13: This function is not supported by contexts. Check Context.renderer_type instead.

libtcodpy.sys_save_screenshot(name: str | PathLike[str] | None = None) → None

Save a screenshot to a file.

By default this will automatically save screenshots in the working directory.

The automatic names are formatted as screenshotNNN.png. For example: screenshot000.png, screenshot001.png, etc. Whichever is available first.

Parameters:

name – File path to save screenshot.

Deprecated since version 11.13: This function is not supported by contexts. Use Context.save_screenshot instead.

Changed in version 16.0: Added PathLike support.

libtcodpy.sys_force_fullscreen_resolution(width: int, height: int) → None

Force a specific resolution in fullscreen.

Will use the smallest available resolution so that:

• resolution width >= width and resolution width >= root console width * font char width

• resolution height >= height and resolution height >= root console height * font char height

Parameters:

• width (int) – The desired resolution width.

• height (int) – The desired resolution height.

Deprecated since version 11.13: This function is not supported by contexts.

libtcodpy.sys_get_current_resolution() → tuple[int, int]

Return a monitors pixel resolution as (width, height).

Deprecated since version 11.13: This function is deprecated, which monitor is detected is ambiguous.

libtcodpy.sys_get_char_size() → tuple[int, int]

Return the current fonts character size as (width, height).

Returns:

The current font glyph size in (width, height)

Return type:

Tuple[int,int]

Deprecated since version 11.13: This function is not supported by contexts.

libtcodpy.sys_update_char(asciiCode: int, fontx: int, fonty: int, img: Image, x: int, y: int) → None

Dynamically update the current font with img.

All cells using this asciiCode will be updated at the next call to libtcodpy.console_flush.

Parameters:

• asciiCode (int) – Ascii code corresponding to the character to update.

• fontx (int) – Left coordinate of the character in the bitmap font (in tiles)

• fonty (int) – Top coordinate of the character in the bitmap font (in tiles)

• img (Image) – An image containing the new character bitmap.

• x (int) – Left pixel of the character in the image.

• y (int) – Top pixel of the character in the image.

Deprecated since version 11.13: This function is not supported by contexts. Use Tileset.set_tile instead to update tiles.

libtcodpy.sys_register_SDL_renderer(callback: Callable[[Any], None]) → None

Register a custom rendering function with libtcod.

Note

This callback will only be called by the SDL renderer.

The callback will receive a CData void* pointer to an SDL_Surface* struct.

The callback is called on every call to libtcodpy.console_flush.

Parameters:

callback – A function which takes a single argument.

Deprecated since version 11.13: This function is not supported by contexts.

libtcodpy.sys_check_for_event(mask: int, k: Key | None, m: Mouse | None) → int

Check for and return an event.

Parameters:

• mask (int) – Event Types to wait for.

• k (Optional[Key]) – A tcod.Key instance which might be updated with an event. Can be None.

• m (Optional[Mouse]) – A tcod.Mouse instance which might be updated with an event. Can be None.

Deprecated since version 9.3: Use the tcod.event.get function to check for events.

libtcodpy.sys_wait_for_event(mask: int, k: Key | None, m: Mouse | None, flush: bool) → int

Wait for an event then return.

If flush is True then the buffer will be cleared before waiting. Otherwise each available event will be returned in the order they’re received.

Parameters:

• mask (int) – Event Types to wait for.

• k (Optional[Key]) – A tcod.Key instance which might be updated with an event. Can be None.

• m (Optional[Mouse]) – A tcod.Mouse instance which might be updated with an event. Can be None.

• flush (bool) – Clear the event buffer before waiting.

Deprecated since version 9.3: Use the tcod.event.wait function to wait for events.

pathfinding

libtcodpy.dijkstra_compute(p: Dijkstra, ox: int, oy: int) → None

libtcodpy.dijkstra_delete(p: Dijkstra) → None

Does nothing. libtcod objects are managed by Python’s garbage collector.

This function exists for backwards compatibility with libtcodpy.

libtcodpy.dijkstra_get(p: Dijkstra, idx: int) → tuple[int, int]

libtcodpy.dijkstra_get_distance(p: Dijkstra, x: int, y: int) → int

libtcodpy.dijkstra_is_empty(p: Dijkstra) → bool

libtcodpy.dijkstra_new(m: Map, dcost: float = 1.41) → Dijkstra

libtcodpy.dijkstra_new_using_function(w: int, h: int, func: Callable[[int, int, int, int, Any], float], userData: Any = 0, dcost: float = 1.41) → Dijkstra

libtcodpy.dijkstra_path_set(p: Dijkstra, x: int, y: int) → bool

libtcodpy.dijkstra_path_walk(p: Dijkstra) → tuple[int, int] | tuple[None, None]

libtcodpy.dijkstra_reverse(p: Dijkstra) → None

libtcodpy.dijkstra_size(p: Dijkstra) → int

libtcodpy.path_compute(p: AStar, ox: int, oy: int, dx: int, dy: int) → bool

Find a path from (ox, oy) to (dx, dy). Return True if path is found.

Parameters:

• p (AStar) – An AStar instance.

• ox (int) – Starting x position.

• oy (int) – Starting y position.

• dx (int) – Destination x position.

• dy (int) – Destination y position.

Returns:

True if a valid path was found. Otherwise False.

Return type:

bool

libtcodpy.path_delete(p: AStar) → None

Does nothing. libtcod objects are managed by Python’s garbage collector.

This function exists for backwards compatibility with libtcodpy.

libtcodpy.path_get(p: AStar, idx: int) → tuple[int, int]

Get a point on a path.

Parameters:

• p (AStar) – An AStar instance.

• idx (int) – Should be in range: 0 <= inx < path_size

libtcodpy.path_get_destination(p: AStar) → tuple[int, int]

Get the current destination position.

Parameters:

p (AStar) – An AStar instance.

Returns:

An (x, y) point.

Return type:

Tuple[int, int]

libtcodpy.path_get_origin(p: AStar) → tuple[int, int]

Get the current origin position.

This point moves when path_walk returns the next x,y step.

Parameters:

p (AStar) – An AStar instance.

Returns:

An (x, y) point.

Return type:

Tuple[int, int]

libtcodpy.path_is_empty(p: AStar) → bool

Return True if a path is empty.

Parameters:

p (AStar) – An AStar instance.

Returns:

True if a path is empty. Otherwise False.

Return type:

bool

libtcodpy.path_new_using_function(w: int, h: int, func: Callable[[int, int, int, int, Any], float], userData: Any = 0, dcost: float = 1.41) → AStar

Return a new AStar using the given callable function.

Parameters:

• w (int) – Clipping width.

• h (int) – Clipping height.

• func – Callback function with the format: f(origin_x, origin_y, dest_x, dest_y, userData) -> float

• userData (Any) – An object passed to the callback.

• dcost (float) – A multiplier for the cost of diagonal movement. Can be set to 0 to disable diagonal movement.

Returns:

A new AStar instance.

Return type:

AStar

libtcodpy.path_new_using_map(m: Map, dcost: float = 1.41) → AStar

Return a new AStar using the given Map.

Parameters:

• m (Map) – A Map instance.

• dcost (float) – The path-finding cost of diagonal movement. Can be set to 0 to disable diagonal movement.

Returns:

A new AStar instance.

Return type:

AStar

libtcodpy.path_reverse(p: AStar) → None

Reverse the direction of a path.

This effectively swaps the origin and destination points.

Parameters:

p (AStar) – An AStar instance.

libtcodpy.path_size(p: AStar) → int

Return the current length of the computed path.

Parameters:

p (AStar) – An AStar instance.

Returns:

Length of the path.

Return type:

int

libtcodpy.path_walk(p: AStar, recompute: bool) → tuple[int, int] | tuple[None, None]

Return the next (x, y) point in a path, or (None, None) if it’s empty.

When recompute is True and a previously valid path reaches a point where it is now blocked, a new path will automatically be found.

Parameters:

• p (AStar) – An AStar instance.

• recompute (bool) – Recompute the path automatically.

Returns:

A single (x, y) point, or (None, None)

Return type:

Union[Tuple[int, int], Tuple[None, None]]

heightmap

libtcodpy.heightmap_add(hm: NDArray[np.float32], value: float) → None

Add value to all values on this heightmap.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• value (float) – A number to add to this heightmap.

Deprecated since version 2.0: Do hm[:] += value instead.

libtcodpy.heightmap_add_fbm(hm: NDArray[np.float32], noise: tcod.noise.Noise, mulx: float, muly: float, addx: float, addy: float, octaves: float, delta: float, scale: float) → None

Add FBM noise to the heightmap.

The noise coordinate for each map cell is ((x + addx) * mulx / width, (y + addy) * muly / height).

The value added to the heightmap is delta + noise * scale.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• noise (Noise) – A Noise instance.

• mulx (float) – Scaling of each x coordinate.

• muly (float) – Scaling of each y coordinate.

• addx (float) – Translation of each x coordinate.

• addy (float) – Translation of each y coordinate.

• octaves (float) – Number of octaves in the FBM sum.

• delta (float) – The value added to all heightmap cells.

• scale (float) – The noise value is scaled with this parameter.

Deprecated since version 8.1: An equivalent array of noise samples can be taken using a method such as Noise.sample_ogrid.

libtcodpy.heightmap_add_hill(hm: NDArray[np.float32], x: float, y: float, radius: float, height: float) → None

Add a hill (a half spheroid) at given position.

If height == radius or -radius, the hill is a half-sphere.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• x (float) – The x position at the center of the new hill.

• y (float) – The y position at the center of the new hill.

• radius (float) – The size of the new hill.

• height (float) – The height or depth of the new hill.

libtcodpy.heightmap_add_hm(hm1: NDArray[np.float32], hm2: NDArray[np.float32], hm3: NDArray[np.float32]) → None

Add two heightmaps together and stores the result in hm3.

Parameters:

• hm1 (numpy.ndarray) – The first heightmap.

• hm2 (numpy.ndarray) – The second heightmap to add to the first.

• hm3 (numpy.ndarray) – A destination heightmap to store the result.

Deprecated since version 2.0: Do hm3[:] = hm1[:] + hm2[:] instead.

libtcodpy.heightmap_add_voronoi(hm: NDArray[np.float32], nbPoints: Any, nbCoef: int, coef: Sequence[float], rnd: tcod.random.Random | None = None) → None

Add values from a Voronoi diagram to the heightmap.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• nbPoints (Any) – Number of Voronoi sites.

• nbCoef (int) – The diagram value is calculated from the nbCoef closest sites.

• coef (Sequence[float]) – The distance to each site is scaled by the corresponding coef. Closest site : coef[0], second closest site : coef[1], …

• rnd (Optional[Random]) – A Random instance, or None.

libtcodpy.heightmap_clamp(hm: NDArray[np.float32], mi: float, ma: float) → None

Clamp all values on this heightmap between mi and ma.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• mi (float) – The lower bound to clamp to.

• ma (float) – The upper bound to clamp to.

Deprecated since version 2.0: Do hm.clip(mi, ma) instead.

libtcodpy.heightmap_clear(hm: NDArray[np.float32]) → None

Add value to all values on this heightmap.

Parameters:

hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

Deprecated since version 2.0: Do hm.array[:] = 0 instead.

libtcodpy.heightmap_copy(hm1: NDArray[np.float32], hm2: NDArray[np.float32]) → None

Copy the heightmap hm1 to hm2.

Parameters:

• hm – A numpy.ndarray formatted for heightmap functions.

• hm1 (numpy.ndarray) – The source heightmap.

• hm2 (numpy.ndarray) – The destination heightmap.

Deprecated since version 2.0: Do hm2[:] = hm1[:] instead.

libtcodpy.heightmap_count_cells(hm: NDArray[np.float32], mi: float, ma: float) → int

Return the number of map cells which value is between mi and ma.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• mi (float) – The lower bound.

• ma (float) – The upper bound.

Returns:

The count of values which fall between mi and ma.

Return type:

int

Deprecated since version 8.1: Can be replaced by an equivalent NumPy function such as: numpy.count_nonzero((mi <= hm) & (hm < ma))

libtcodpy.heightmap_delete(hm: Any) → None

Does nothing. libtcod objects are managed by Python’s garbage collector.

This function exists for backwards compatibility with libtcodpy.

Deprecated since version 2.0: libtcod-cffi deletes heightmaps automatically.

libtcodpy.heightmap_dig_bezier(hm: NDArray[np.float32], px: tuple[int, int, int, int], py: tuple[int, int, int, int], startRadius: float, startDepth: float, endRadius: float, endDepth: float) → None

Carve a path along a cubic Bezier curve.

Both radius and depth can vary linearly along the path.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• px (Sequence[int]) – The 4 x coordinates of the Bezier curve.

• py (Sequence[int]) – The 4 y coordinates of the Bezier curve.

• startRadius (float) – The starting radius size.

• startDepth (float) – The starting depth.

• endRadius (float) – The ending radius size.

• endDepth (float) – The ending depth.

libtcodpy.heightmap_dig_hill(hm: NDArray[np.float32], x: float, y: float, radius: float, height: float) → None

Dig a hill in a heightmap.

This function takes the highest value (if height > 0) or the lowest (if height < 0) between the map and the hill.

It’s main goal is to carve things in maps (like rivers) by digging hills along a curve.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• x (float) – The x position at the center of the new carving.

• y (float) – The y position at the center of the new carving.

• radius (float) – The size of the carving.

• height (float) – The height or depth of the hill to dig out.

libtcodpy.heightmap_get_interpolated_value(hm: NDArray[np.float32], x: float, y: float) → float

Return the interpolated height at non integer coordinates.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• x (float) – A floating point x coordinate.

• y (float) – A floating point y coordinate.

Returns:

The value at x, y.

Return type:

float

libtcodpy.heightmap_get_minmax(hm: NDArray[np.float32]) → tuple[float, float]

Return the min and max values of this heightmap.

Parameters:

hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

Returns:

The (min, max) values.

Return type:

Tuple[float, float]

Deprecated since version 2.0: Use hm.min() or hm.max() instead.

libtcodpy.heightmap_get_normal(hm: NDArray[np.float32], x: float, y: float, waterLevel: float) → tuple[float, float, float]

Return the map normal at given coordinates.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• x (float) – The x coordinate.

• y (float) – The y coordinate.

• waterLevel (float) – The heightmap is considered flat below this value.

Returns:

An (x, y, z) vector normal.

Return type:

Tuple[float, float, float]

libtcodpy.heightmap_get_slope(hm: NDArray[np.float32], x: int, y: int) → float

Return the slope between 0 and (pi / 2) at given coordinates.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• x (int) – The x coordinate.

• y (int) – The y coordinate.

Returns:

The steepness at x, y. From 0 to (pi / 2)

Return type:

float

libtcodpy.heightmap_get_value(hm: NDArray[np.float32], x: int, y: int) → float

Return the value at x, y in a heightmap.

Deprecated since version 2.0: Access hm as a NumPy array instead.

libtcodpy.heightmap_has_land_on_border(hm: NDArray[np.float32], waterlevel: float) → bool

Returns True if the map edges are below waterlevel, otherwise False.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• waterlevel (float) – The water level to use.

Returns:

True if the map edges are below waterlevel, otherwise False.

Return type:

bool

libtcodpy.heightmap_kernel_transform(hm: NDArray[np.float32], kernelsize: int, dx: Sequence[int], dy: Sequence[int], weight: Sequence[float], minLevel: float, maxLevel: float) → None

Apply a generic transformation on the map, so that each resulting cell value is the weighted sum of several neighbor cells.

This can be used to smooth/sharpen the map.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• kernelsize (int) –

  Should be set to the length of the parameters::

  dx, dy, and weight.

• dx (Sequence[int]) – A sequence of x coordinates.

• dy (Sequence[int]) – A sequence of y coordinates.

• weight (Sequence[float]) – A sequence of kernelSize cells weight. The value of each neighbor cell is scaled by its corresponding weight

• minLevel (float) – No transformation will apply to cells below this value.

• maxLevel (float) – No transformation will apply to cells above this value.

See examples below for a simple horizontal smoothing kernel : replace value(x,y) with 0.33*value(x-1,y) + 0.33*value(x,y) + 0.33*value(x+1,y). To do this, you need a kernel of size 3 (the sum involves 3 surrounding cells). The dx,dy array will contain:

• dx=-1, dy=0 for cell (x-1, y)

• dx=1, dy=0 for cell (x+1, y)

• dx=0, dy=0 for cell (x, y)

• The weight array will contain 0.33 for each cell.

Example

>>> import numpy as np
>>> heightmap = np.zeros((3, 3), dtype=np.float32)
>>> heightmap[:,1] = 1
>>> dx = [-1, 1, 0]
>>> dy = [0, 0, 0]
>>> weight = [0.33, 0.33, 0.33]
>>> tcod.heightmap_kernel_transform(heightmap, 3, dx, dy, weight,
...                                 0.0, 1.0)

libtcodpy.heightmap_lerp_hm(hm1: NDArray[np.float32], hm2: NDArray[np.float32], hm3: NDArray[np.float32], coef: float) → None

Perform linear interpolation between two heightmaps storing the result in hm3.

This is the same as doing hm3[:] = hm1[:] + (hm2[:] - hm1[:]) * coef

Parameters:

• hm1 (numpy.ndarray) – The first heightmap.

• hm2 (numpy.ndarray) – The second heightmap to add to the first.

• hm3 (numpy.ndarray) – A destination heightmap to store the result.

• coef (float) – The linear interpolation coefficient.

libtcodpy.heightmap_multiply_hm(hm1: NDArray[np.float32], hm2: NDArray[np.float32], hm3: NDArray[np.float32]) → None

Multiplies two heightmap’s together and stores the result in hm3.

Parameters:

• hm1 (numpy.ndarray) – The first heightmap.

• hm2 (numpy.ndarray) – The second heightmap to multiply with the first.

• hm3 (numpy.ndarray) – A destination heightmap to store the result.

Deprecated since version 2.0: Do hm3[:] = hm1[:] * hm2[:] instead. Alternatively you can do HeightMap(hm1.array[:] * hm2.array[:]).

libtcodpy.heightmap_new(w: int, h: int, order: str = 'C') → NDArray[np.float32]

Return a new numpy.ndarray formatted for use with heightmap functions.

w and h are the width and height of the array.

order is given to the new NumPy array, it can be ‘C’ or ‘F’.

You can pass a NumPy array to any heightmap function as long as all the following are true:: * The array is 2 dimensional. * The array has the C_CONTIGUOUS or F_CONTIGUOUS flag. * The array’s dtype is dtype.float32.

The returned NumPy array will fit all these conditions.

Changed in version 8.1: Added the order parameter.

libtcodpy.heightmap_normalize(hm: NDArray[np.float32], mi: float = 0.0, ma: float = 1.0) → None

Normalize heightmap values between mi and ma.

Parameters:

• hm – A numpy.ndarray formatted for heightmap functions.

• mi (float) – The lowest value after normalization.

• ma (float) – The highest value after normalization.

libtcodpy.heightmap_rain_erosion(hm: NDArray[np.float32], nbDrops: int, erosionCoef: float, sedimentationCoef: float, rnd: tcod.random.Random | None = None) → None

Simulate the effect of rain drops on the terrain, resulting in erosion.

nbDrops should be at least hm.size.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• nbDrops (int) – Number of rain drops to simulate.

• erosionCoef (float) – Amount of ground eroded on the drop’s path.

• sedimentationCoef (float) – Amount of ground deposited when the drops stops to flow.

• rnd (Optional[Random]) – A tcod.Random instance, or None.

libtcodpy.heightmap_scale(hm: NDArray[np.float32], value: float) → None

Multiply all items on this heightmap by value.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• value (float) – A number to scale this heightmap by.

Deprecated since version 2.0: Do hm[:] *= value instead.

libtcodpy.heightmap_scale_fbm(hm: NDArray[np.float32], noise: tcod.noise.Noise, mulx: float, muly: float, addx: float, addy: float, octaves: float, delta: float, scale: float) → None

Multiply the heightmap values with FBM noise.

Parameters:

• hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.

• noise (Noise) – A Noise instance.

• mulx (float) – Scaling of each x coordinate.

• muly (float) – Scaling of each y coordinate.

• addx (float) – Translation of each x coordinate.

• addy (float) – Translation of each y coordinate.

• octaves (float) – Number of octaves in the FBM sum.

• delta (float) – The value added to all heightmap cells.

• scale (float) – The noise value is scaled with this parameter.

Deprecated since version 8.1: An equivalent array of noise samples can be taken using a method such as Noise.sample_ogrid.

libtcodpy.heightmap_set_value(hm: NDArray[np.float32], x: int, y: int, value: float) → None

Set the value of a point on a heightmap.

Deprecated since version 2.0: hm is a NumPy array, so values should be assigned to it directly.

image

libtcodpy.image_load(filename: str | PathLike[str]) → Image

Load an image file into an Image instance and return it.

Parameters:

filename – Path to a .bmp or .png image file.

Changed in version 16.0: Added PathLike support.

Deprecated since version 16.0: Use tcod.image.Image.from_file instead.

libtcodpy.image_from_console(console: Console) → Image

Return an Image with a Consoles pixel data.

This effectively takes a screen-shot of the Console.

Parameters:

console (Console) – Any Console instance.

Deprecated since version 16.0: Tileset.render is a better alternative.

libtcodpy.image_blit(image: Image, console: Console, x: float, y: float, bkgnd_flag: int, scalex: float, scaley: float, angle: float) → None

libtcodpy.image_blit_2x(image: Image, console: Console, dx: int, dy: int, sx: int = 0, sy: int = 0, w: int = -1, h: int = -1) → None

libtcodpy.image_blit_rect(image: Image, console: Console, x: int, y: int, w: int, h: int, bkgnd_flag: int) → None

libtcodpy.image_clear(image: Image, col: tuple[int, int, int]) → None

libtcodpy.image_delete(image: Image) → None

Does nothing. libtcod objects are managed by Python’s garbage collector.

This function exists for backwards compatibility with libtcodpy.

libtcodpy.image_get_alpha(image: Image, x: int, y: int) → int

libtcodpy.image_get_mipmap_pixel(image: Image, x0: float, y0: float, x1: float, y1: float) → tuple[int, int, int]

libtcodpy.image_get_pixel(image: Image, x: int, y: int) → tuple[int, int, int]

libtcodpy.image_get_size(image: Image) → tuple[int, int]

libtcodpy.image_hflip(image: Image) → None

libtcodpy.image_invert(image: Image) → None

libtcodpy.image_is_pixel_transparent(image: Image, x: int, y: int) → bool

libtcodpy.image_new(width: int, height: int) → Image

libtcodpy.image_put_pixel(image: Image, x: int, y: int, col: tuple[int, int, int]) → None

libtcodpy.image_refresh_console(image: Image, console: Console) → None

Update an image made with image_from_console.

Deprecated since version 16.0: This function is unnecessary, use Tileset.render instead.

libtcodpy.image_rotate90(image: Image, num: int = 1) → None

libtcodpy.image_save(image: Image, filename: str | PathLike[str]) → None

libtcodpy.image_scale(image: Image, neww: int, newh: int) → None

libtcodpy.image_set_key_color(image: Image, col: tuple[int, int, int]) → None

libtcodpy.image_vflip(image: Image) → None

line

libtcodpy.line_init(xo: int, yo: int, xd: int, yd: int) → None

Initialize a line whose points will be returned by line_step.

This function does not return anything on its own.

Does not include the origin point.

Parameters:

• xo (int) – X starting point.

• yo (int) – Y starting point.

• xd (int) – X destination point.

• yd (int) – Y destination point.

Deprecated since version 2.0: This function was replaced by tcod.los.bresenham.

libtcodpy.line_step() → tuple[int, int] | tuple[None, None]

After calling line_init returns (x, y) points of the line.

Once all points are exhausted this function will return (None, None)

Returns:

The next (x, y) point of the line setup by line_init, or (None, None) if there are no more points.

Return type:

Union[Tuple[int, int], Tuple[None, None]]

Deprecated since version 2.0: This function was replaced by tcod.los.bresenham.

libtcodpy.line(xo: int, yo: int, xd: int, yd: int, py_callback: Callable[[int, int], bool]) → bool

Iterate over a line using a callback function.

Your callback function will take x and y parameters and return True to continue iteration or False to stop iteration and return.

This function includes both the start and end points.

Parameters:

• xo (int) – X starting point.

• yo (int) – Y starting point.

• xd (int) – X destination point.

• yd (int) – Y destination point.

• py_callback (Callable[[int, int], bool]) – A callback which takes x and y parameters and returns bool.

Returns:

False if the callback cancels the line interaction by

returning False or None, otherwise True.

Return type:

bool

Deprecated since version 2.0: This function was replaced by tcod.los.bresenham.

libtcodpy.line_iter(xo: int, yo: int, xd: int, yd: int) → Iterator[tuple[int, int]]

Returns an Iterable over a Bresenham line.

This Iterable does not include the origin point.

Parameters:

• xo (int) – X starting point.

• yo (int) – Y starting point.

• xd (int) – X destination point.

• yd (int) – Y destination point.

Returns:

An Iterable of (x,y) points.

Return type:

Iterable[Tuple[int,int]]

Deprecated since version 11.14: This function was replaced by tcod.los.bresenham.

libtcodpy.line_where(x1: int, y1: int, x2: int, y2: int, inclusive: bool = True) → tuple[NDArray[np.intc], NDArray[np.intc]]

Return a NumPy index array following a Bresenham line.

If inclusive is true then the start point is included in the result.

New in version 4.6.

Deprecated since version 11.14: This function was replaced by tcod.los.bresenham.

map

libtcodpy.map_clear(m: Map, transparent: bool = False, walkable: bool = False) → None

Change all map cells to a specific value.

Deprecated since version 4.5: Use tcod.map.Map.transparent and tcod.map.Map.walkable arrays to set these properties.

libtcodpy.map_compute_fov(m: Map, x: int, y: int, radius: int = 0, light_walls: bool = True, algo: int = 12) → None

Compute the field-of-view for a map instance.

Deprecated since version 4.5: Use tcod.map.Map.compute_fov instead.

libtcodpy.map_copy(source: Map, dest: Map) → None

Copy map data from source to dest.

Deprecated since version 4.5: Use Python’s copy module, or see tcod.map.Map and assign between array attributes manually.

libtcodpy.map_delete(m: Map) → None

Does nothing. libtcod objects are managed by Python’s garbage collector.

This function exists for backwards compatibility with libtcodpy.

libtcodpy.map_get_height(map: Map) → int

Return the height of a map.

Deprecated since version 4.5: Check the tcod.map.Map.height attribute instead.

libtcodpy.map_get_width(map: Map) → int

Return the width of a map.

Deprecated since version 4.5: Check the tcod.map.Map.width attribute instead.

libtcodpy.map_is_in_fov(m: Map, x: int, y: int) → bool

Return True if the cell at x,y is lit by the last field-of-view algorithm.

Note

This function is slow.

Deprecated since version 4.5: Use tcod.map.Map.fov to check this property.

libtcodpy.map_is_transparent(m: Map, x: int, y: int) → bool

Return True is a map cell is transparent.

Note

This function is slow.

Deprecated since version 4.5: Use tcod.map.Map.transparent to check this property.

libtcodpy.map_is_walkable(m: Map, x: int, y: int) → bool

Return True is a map cell is walkable.

Note

This function is slow.

Deprecated since version 4.5: Use tcod.map.Map.walkable to check this property.

libtcodpy.map_new(w: int, h: int) → Map

Return a tcod.map.Map with a width and height.

Deprecated since version 4.5: Use the tcod.map module for working with field-of-view, or tcod.path for working with path-finding.

libtcodpy.map_set_properties(m: Map, x: int, y: int, isTrans: bool, isWalk: bool) → None

Set the properties of a single cell.

Note

This function is slow.

Deprecated since version 4.5: Use tcod.map.Map.transparent and tcod.map.Map.walkable arrays to set these properties.

mouse

libtcodpy.mouse_get_status() → Mouse

libtcodpy.mouse_is_cursor_visible() → bool

Return True if the mouse cursor is visible.

Deprecated since version 16.0: Use tcod.sdl.mouse.show instead.

libtcodpy.mouse_move(x: int, y: int) → None

libtcodpy.mouse_show_cursor(visible: bool) → None

Change the visibility of the mouse cursor.

Deprecated since version 16.0: Use tcod.sdl.mouse.show instead.

namegen

libtcodpy.namegen_destroy() → None

libtcodpy.namegen_generate(name: str) → str

libtcodpy.namegen_generate_custom(name: str, rule: str) → str

libtcodpy.namegen_get_sets() → list[str]

libtcodpy.namegen_parse(filename: str | PathLike[str], random: Random | None = None) → None

noise

libtcodpy.noise_delete(n: Noise) → None

Does nothing. libtcod objects are managed by Python’s garbage collector.

This function exists for backwards compatibility with libtcodpy.

libtcodpy.noise_get(n: Noise, f: Sequence[float], typ: int = 0) → float

Return the noise value sampled from the f coordinate.

f should be a tuple or list with a length matching the dimensions attribute of Noise. If f is shorter than dimensions the missing coordinates will be filled with zeros.

Parameters:

• n (Noise) – A Noise instance.

• f (Sequence[float]) – The point to sample the noise from.

• typ (int) – The noise algorithm to use.

Returns:

The sampled noise value.

Return type:

float

libtcodpy.noise_get_fbm(n: Noise, f: Sequence[float], oc: float, typ: int = 0) → float

Return the fractal Brownian motion sampled from the f coordinate.

Parameters:

• n (Noise) – A Noise instance.

• f (Sequence[float]) – The point to sample the noise from.

• typ (int) – The noise algorithm to use.

• oc (float) – The level of level. Should be more than 1.

Returns:

The sampled noise value.

Return type:

float

libtcodpy.noise_get_turbulence(n: Noise, f: Sequence[float], oc: float, typ: int = 0) → float

Return the turbulence noise sampled from the f coordinate.

Parameters:

• n (Noise) – A Noise instance.

• f (Sequence[float]) – The point to sample the noise from.

• typ (int) – The noise algorithm to use.

• oc (float) – The level of level. Should be more than 1.

Returns:

The sampled noise value.

Return type:

float

libtcodpy.noise_new(dim: int, h: float = 0.5, l: float = 2.0, random: Random | None = None) → Noise

Return a new Noise instance.

Parameters:

• dim (int) – Number of dimensions. From 1 to 4.

• h (float) – The hurst exponent. Should be in the 0.0-1.0 range.

• l (float) – The noise lacunarity.

• random (Optional[Random]) – A Random instance, or None.

Returns:

The new Noise instance.

Return type:

Noise

libtcodpy.noise_set_type(n: Noise, typ: int) → None

Set a Noise objects default noise algorithm.

Parameters:

• n – Noise object.

• typ (int) – Any NOISE_* constant.

parser

libtcodpy.parser_delete(parser: Any) → None

Does nothing. libtcod objects are managed by Python’s garbage collector.

This function exists for backwards compatibility with libtcodpy.

libtcodpy.parser_get_bool_property(parser: Any, name: str) → bool

libtcodpy.parser_get_char_property(parser: Any, name: str) → str

libtcodpy.parser_get_color_property(parser: Any, name: str) → Color

libtcodpy.parser_get_dice_property(parser: Any, name: str) → Dice

libtcodpy.parser_get_float_property(parser: Any, name: str) → float

libtcodpy.parser_get_int_property(parser: Any, name: str) → int

libtcodpy.parser_get_list_property(parser: Any, name: str, type: Any) → Any

libtcodpy.parser_get_string_property(parser: Any, name: str) → str

libtcodpy.parser_new() → Any

libtcodpy.parser_new_struct(parser: Any, name: str) → Any

libtcodpy.parser_run(parser: Any, filename: str | PathLike[str], listener: Any = None) → None

random

libtcodpy.random_delete(rnd: Random) → None

Does nothing. libtcod objects are managed by Python’s garbage collector.

This function exists for backwards compatibility with libtcodpy.

libtcodpy.random_get_double(rnd: Random | None, mi: float, ma: float) → float

Return a random float in the range: mi <= n <= ma.

Deprecated since version 2.0: Use random_get_float instead. Both functions return a double precision float.

libtcodpy.random_get_double_mean(rnd: Random | None, mi: float, ma: float, mean: float) → float

Return a random weighted float in the range: mi <= n <= ma.

Deprecated since version 2.0: Use random_get_float_mean instead. Both functions return a double precision float.

libtcodpy.random_get_float(rnd: Random | None, mi: float, ma: float) → float

Return a random float in the range: mi <= n <= ma.

The result is affected by calls to random_set_distribution.

Parameters:

• rnd (Optional[Random]) – A Random instance, or None to use the default.

• mi (float) – The lower bound of the random range, inclusive.

• ma (float) – The upper bound of the random range, inclusive.

Returns:

A random double precision float

in the range mi <= n <= ma.

Return type:

float

libtcodpy.random_get_float_mean(rnd: Random | None, mi: float, ma: float, mean: float) → float

Return a random weighted float in the range: mi <= n <= ma.

The result is affected by calls to random_set_distribution.

Parameters:

• rnd (Optional[Random]) – A Random instance, or None to use the default.

• mi (float) – The lower bound of the random range, inclusive.

• ma (float) – The upper bound of the random range, inclusive.

• mean (float) – The mean return value.

Returns:

A random weighted double precision float

in the range mi <= n <= ma.

Return type:

float

libtcodpy.random_get_instance() → Random

Return the default Random instance.

Returns:

A Random instance using the default random number generator.

Return type:

Random

libtcodpy.random_get_int(rnd: Random | None, mi: int, ma: int) → int

Return a random integer in the range: mi <= n <= ma.

The result is affected by calls to random_set_distribution.

Parameters:

• rnd (Optional[Random]) – A Random instance, or None to use the default.

• mi (int) – The lower bound of the random range, inclusive.

• ma (int) – The upper bound of the random range, inclusive.

Returns:

A random integer in the range mi <= n <= ma.

Return type:

int

libtcodpy.random_get_int_mean(rnd: Random | None, mi: int, ma: int, mean: int) → int

Return a random weighted integer in the range: mi <= n <= ma.

The result is affected by calls to random_set_distribution.

Parameters:

• rnd (Optional[Random]) – A Random instance, or None to use the default.

• mi (int) – The lower bound of the random range, inclusive.

• ma (int) – The upper bound of the random range, inclusive.

• mean (int) – The mean return value.

Returns:

A random weighted integer in the range mi <= n <= ma.

Return type:

int

libtcodpy.random_new(algo: int = 1) → Random

Return a new Random instance. Using algo.

Parameters:

algo (int) – The random number algorithm to use.

Returns:

A new Random instance using the given algorithm.

Return type:

Random

libtcodpy.random_new_from_seed(seed: Hashable, algo: int = 1) → Random

Return a new Random instance. Using the given seed and algo.

Parameters:

• seed (Hashable) – The RNG seed. Should be a 32-bit integer, but any hashable object is accepted.

• algo (int) – The random number algorithm to use.

Returns:

A new Random instance using the given algorithm.

Return type:

Random

libtcodpy.random_restore(rnd: Random | None, backup: Random) → None

Restore a random number generator from a backed up copy.

Parameters:

• rnd (Optional[Random]) – A Random instance, or None to use the default.

• backup (Random) – The Random instance which was used as a backup.

Deprecated since version 8.4: You can use the standard library copy and pickle modules to save a random state.

libtcodpy.random_save(rnd: Random | None) → Random

Return a copy of a random number generator.

Deprecated since version 8.4: You can use the standard library copy and pickle modules to save a random state.

libtcodpy.random_set_distribution(rnd: Random | None, dist: int) → None

Change the distribution mode of a random number generator.

Parameters:

• rnd (Optional[Random]) – A Random instance, or None to use the default.

• dist (int) – The distribution mode to use. Should be DISTRIBUTION_*.

struct

libtcodpy.struct_add_flag(struct: Any, name: str) → None

libtcodpy.struct_add_list_property(struct: Any, name: str, typ: int, mandatory: bool) → None

libtcodpy.struct_add_property(struct: Any, name: str, typ: int, mandatory: bool) → None

libtcodpy.struct_add_structure(struct: Any, sub_struct: Any) → None

libtcodpy.struct_add_value_list(struct: Any, name: str, value_list: Iterable[str], mandatory: bool) → None

libtcodpy.struct_get_name(struct: Any) → str

libtcodpy.struct_get_type(struct: Any, name: str) → int

libtcodpy.struct_is_mandatory(struct: Any, name: str) → bool

other

class libtcodpy.ConsoleBuffer(width: int, height: int, back_r: int = 0, back_g: int = 0, back_b: int = 0, fore_r: int = 0, fore_g: int = 0, fore_b: int = 0, char: str = ' ')

Simple console that allows direct (fast) access to cells. Simplifies use of the “fill” functions.

Deprecated since version 6.0: Console array attributes perform better than this class.

Parameters:

• width (int) – Width of the new ConsoleBuffer.

• height (int) – Height of the new ConsoleBuffer.

• back_r (int) – Red background color, from 0 to 255.

• back_g (int) – Green background color, from 0 to 255.

• back_b (int) – Blue background color, from 0 to 255.

• fore_r (int) – Red foreground color, from 0 to 255.

• fore_g (int) – Green foreground color, from 0 to 255.

• fore_b (int) – Blue foreground color, from 0 to 255.

• char (AnyStr) – A single character str or bytes object.

blit(dest: Console, fill_fore: bool = True, fill_back: bool = True) → None

Use libtcod’s “fill” functions to write the buffer to a console.

Parameters:

• dest (Console) – Console object to modify.

• fill_fore (bool) – If True, fill the foreground color and characters.

• fill_back (bool) – If True, fill the background color.

clear(back_r: int = 0, back_g: int = 0, back_b: int = 0, fore_r: int = 0, fore_g: int = 0, fore_b: int = 0, char: str = ' ') → None

Clear the console.

Values to fill it with are optional, defaults to black with no characters.

Parameters:

• back_r (int) – Red background color, from 0 to 255.

• back_g (int) – Green background color, from 0 to 255.

• back_b (int) – Blue background color, from 0 to 255.

• fore_r (int) – Red foreground color, from 0 to 255.

• fore_g (int) – Green foreground color, from 0 to 255.

• fore_b (int) – Blue foreground color, from 0 to 255.

• char (AnyStr) – A single character str or bytes object.

copy() → ConsoleBuffer

Return a copy of this ConsoleBuffer.

Returns:

A new ConsoleBuffer copy.

Return type:

ConsoleBuffer

set(x: int, y: int, back_r: int, back_g: int, back_b: int, fore_r: int, fore_g: int, fore_b: int, char: str) → None

Set the background color, foreground color and character of one cell.

Parameters:

• x (int) – X position to change.

• y (int) – Y position to change.

• back_r (int) – Red background color, from 0 to 255.

• back_g (int) – Green background color, from 0 to 255.

• back_b (int) – Blue background color, from 0 to 255.

• fore_r (int) – Red foreground color, from 0 to 255.

• fore_g (int) – Green foreground color, from 0 to 255.

• fore_b (int) – Blue foreground color, from 0 to 255.

• char (AnyStr) – A single character str or bytes object.

set_back(x: int, y: int, r: int, g: int, b: int) → None

Set the background color of one cell.

Parameters:

• x (int) – X position to change.

• y (int) – Y position to change.

• r (int) – Red background color, from 0 to 255.

• g (int) – Green background color, from 0 to 255.

• b (int) – Blue background color, from 0 to 255.

set_fore(x: int, y: int, r: int, g: int, b: int, char: str) → None

Set the character and foreground color of one cell.

Parameters:

• x (int) – X position to change.

• y (int) – Y position to change.

• r (int) – Red foreground color, from 0 to 255.

• g (int) – Green foreground color, from 0 to 255.

• b (int) – Blue foreground color, from 0 to 255.

• char (AnyStr) – A single character str or bytes object.

class libtcodpy.Dice(nb_dices=0, nb_faces=0, multiplier=0, addsub=0)

A libtcod dice object.

Parameters:

• nb_dices (int) – Number of dice.

• nb_faces (int) – Number of sides on a die.

• multiplier (float) – Multiplier.

• addsub (float) – Addition.

Deprecated since version 2.0: You should make your own dice functions instead of using this class which is tied to a CData object.