libtcodpy

bsp

tcod.bsp_new_with_size(x, y, w, h)[source]

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.

tcod.bsp_split_once(node, horizontal, position)[source]

Deprecated since version 2.0: Use BSP.split_once instead.

tcod.bsp_split_recursive(node, randomizer, nb, minHSize, minVSize, maxHRatio, maxVRatio)[source]

Deprecated since version 2.0: Use BSP.split_recursive instead.

tcod.bsp_resize(node, x, y, w, h)[source]

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

tcod.bsp_left(node)[source]

Deprecated since version 2.0: Use BSP.children instead.

tcod.bsp_right(node)[source]

Deprecated since version 2.0: Use BSP.children instead.

tcod.bsp_father(node)[source]

Deprecated since version 2.0: Use BSP.parent instead.

tcod.bsp_is_leaf(node)[source]

Deprecated since version 2.0: Use BSP.children instead.

tcod.bsp_contains(node, cx, cy)[source]

Deprecated since version 2.0: Use BSP.contains instead.

tcod.bsp_find_node(node, cx, cy)[source]

Deprecated since version 2.0: Use BSP.find_node instead.

tcod.bsp_traverse_pre_order(node, callback, userData=0)[source]

Traverse this nodes hierarchy with a callback.

Deprecated since version 2.0: Use BSP.walk instead.

tcod.bsp_traverse_in_order(node, callback, userData=0)[source]

Traverse this nodes hierarchy with a callback.

Deprecated since version 2.0: Use BSP.walk instead.

tcod.bsp_traverse_post_order(node, callback, userData=0)[source]

Traverse this nodes hierarchy with a callback.

Deprecated since version 2.0: Use BSP.walk instead.

tcod.bsp_traverse_level_order(node, callback, userData=0)[source]

Traverse this nodes hierarchy with a callback.

Deprecated since version 2.0: Use BSP.walk instead.

tcod.bsp_traverse_inverted_level_order(node, callback, userData=0)[source]

Traverse this nodes hierarchy with a callback.

Deprecated since version 2.0: Use BSP.walk instead.

tcod.bsp_remove_sons(node)[source]

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.

tcod.bsp_delete(node)[source]

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 tcod.Color(r=0, g=0, b=0)[source]
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.
r

int – Red value, always normalised to 0-255.

g

int – Green value, always normalised to 0-255.

b

int – Blue value, always normalised to 0-255.

__eq__(other)[source]

Compare equality between colors.

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

__add__(other)[source]

Add two colors together.

__sub__(other)[source]

Subtract one color from another.

__mul__(other)[source]

Multiply with a scaler or another color.

__repr__()[source]

Return a printable representation of the current color.

tcod.color_lerp(c1, c2, a)[source]

Return the linear interpolation between two colors.

a is the interpolation value, with 0 returing c1, 1 returning c2, and 0.5 returing 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

tcod.color_set_hsv(c, h, s, v)[source]

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

Does not return a new Color. c is modified inplace.

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.
tcod.color_get_hsv(c)[source]

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]
tcod.color_scale_HSV(c, scoef, vcoef)[source]

Scale a color’s saturation and value.

Does not return a new Color. c is modified inplace.

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.
tcod.color_gen_map(colors, indexes)[source]

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)]

console

tcod.console_set_custom_font(fontFile, flags=1, nb_char_horiz=0, nb_char_vertic=0)[source]

Load a custom font file.

Call this before function before calling tcod.console_init_root.

Flags can be a mix of the following:

  • tcod.FONT_LAYOUT_ASCII_INCOL
  • tcod.FONT_LAYOUT_ASCII_INROW
  • tcod.FONT_TYPE_GREYSCALE
  • tcod.FONT_TYPE_GRAYSCALE
  • tcod.FONT_LAYOUT_TCOD
Parameters:
  • fontFile (AnyStr) – Path to a font file.
  • flags (int) –
  • nb_char_horiz (int) –
  • nb_char_vertic (int) –
tcod.console_init_root(w, h, title, fullscreen=False, renderer=0)[source]

Set up the primary display and return the root console.

Parameters:
  • w (int) – Width in character tiles for the root console.
  • h (int) – Height in character tiles for the root console.
  • title (AnyStr) – This string will be displayed on the created windows title bar.
  • renderer – Rendering mode for libtcod to use.
Returns:

Returns a special Console instance representing the root console.

Return type:

Console

tcod.console_flush()[source]

Update the display to represent the root consoles current state.

tcod.console_blit(src, x, y, w, h, dst, xdst, ydst, ffade=1.0, bfade=1.0)[source]

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

tcod.console_check_for_keypress(flags=2)[source]
tcod.console_clear(con)[source]

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

Parameters:con (Console) – Any Console instance.
tcod.console_credits()[source]
tcod.console_credits_render(x, y, alpha)[source]
tcod.console_credits_reset()[source]
tcod.console_delete(con)[source]
tcod.console_fill_background(con, r, g, b)[source]

Fill the backgound 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.
tcod.console_fill_char(con, arr)[source]

Fill the character tiles of a console with an array.

Parameters:
  • con (Console) – Any Console instance.
  • arr (Sequence[int]) – An array of integers with a length of width*height.
tcod.console_fill_foreground(con, r, g, b)[source]

Fill the foregound 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.
tcod.console_from_file(filename)[source]

Return a new console object from a filename.

The file format is automactially 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.

tcod.console_from_xp(filename)[source]

Return a single console from a REXPaint .xp file.

tcod.console_get_alignment(con)[source]

Return this consoles current alignment mode.

Parameters:con (Console) – Any Console instance.
tcod.console_get_background_flag(con)[source]

Return this consoles current blend mode.

Parameters:con (Console) – Any Console instance.
tcod.console_get_char(con, x, y)[source]

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

tcod.console_get_char_background(con, x, y)[source]

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

tcod.console_get_char_foreground(con, x, y)[source]

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

tcod.console_get_default_background(con)[source]

Return this consoles default background color.

tcod.console_get_default_foreground(con)[source]

Return this consoles default foreground color.

tcod.console_get_fade()[source]
tcod.console_get_fading_color()[source]
tcod.console_get_height(con)[source]

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.get_hright instead.

tcod.console_get_height_rect(con, x, y, w, h, fmt)[source]

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
tcod.console_get_width(con)[source]

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.get_width instead.

tcod.console_hline(con, x, y, l, flag=13)[source]

Draw a horizontal line on the console.

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

tcod.console_is_fullscreen()[source]

Returns True if the display is fullscreen.

Returns:True if the display is fullscreen, otherwise False.
Return type:bool
tcod.console_is_key_pressed(key)[source]
tcod.console_is_window_closed()[source]

Returns True if the window has received and exit event.

tcod.console_load_apf(con, filename)[source]

Update a console from an ASCII Paint .apf file.

tcod.console_load_asc(con, filename)[source]

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

tcod.console_load_xp(con, filename)[source]

Update a console from a REXPaint .xp file.

tcod.console_list_load_xp(filename)[source]

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

tcod.console_list_save_xp(console_list, filename, compress_level=9)[source]

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

tcod.console_map_ascii_code_to_font(asciiCode, fontCharX, fontCharY)[source]

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

asciiCode must be within the bounds created during the initialization of the loaded tile-set. For example, you can’t use 255 here unless you have a 256 tile tile-set loaded. This applies to all functions in this group.

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.
tcod.console_map_ascii_codes_to_font(firstAsciiCode, nbCodes, fontCharX, fontCharY)[source]

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.
tcod.console_map_string_to_font(s, fontCharX, fontCharY)[source]

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

Parameters:
  • s (AnyStr) – A string of character codes to map to new values. The null character ‘’ will prematurely end this function.
  • 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.
tcod.console_new(w, h)[source]

Return an offscreen console of size: w,h.

tcod.console_print(con, x, y, fmt)[source]

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 optionaly using color codes.
tcod.console_print_ex(con, x, y, flag, alignment, fmt)[source]

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.
tcod.console_print_frame(con, x, y, w, h, clear=True, flag=13, fmt='')[source]

Draw a framed rectangle with optinal 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.

tcod.console_print_rect(con, x, y, w, h, fmt)[source]

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
tcod.console_print_rect_ex(con, x, y, w, h, flag, alignment, fmt)[source]

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

Returns:The number of lines of text once word-wrapped.
Return type:int
tcod.console_put_char(con, x, y, c, flag=13)[source]

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.
tcod.console_put_char_ex(con, x, y, c, fore, back)[source]

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.
tcod.console_rect(con, x, y, w, h, clr, flag=13)[source]

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

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

tcod.console_save_apf(con, filename)[source]

Save a console to an ASCII Paint .apf file.

tcod.console_save_asc(con, filename)[source]

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

tcod.console_save_xp(con, filename, compress_level=9)[source]

Save a console to a REXPaint .xp file.

tcod.console_set_alignment(con, alignment)[source]

Change this consoles current alignment mode.

  • tcod.LEFT
  • tcod.CENTER
  • tcod.RIGHT
Parameters:
  • con (Console) – Any Console instance.
  • alignment (int) –
tcod.console_set_background_flag(con, flag)[source]

Change the default blend mode for this console.

Parameters:
  • con (Console) – Any Console instance.
  • flag (int) – Blend mode to use by default.
tcod.console_set_char(con, x, y, c)[source]

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.
tcod.console_set_char_background(con, x, y, col, flag=1)[source]

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.
tcod.console_set_char_foreground(con, x, y, col)[source]

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.
tcod.console_set_color_control(con, fore, back)[source]

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.
tcod.console_set_default_background(con, col)[source]

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.
tcod.console_set_default_foreground(con, col)[source]

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.
tcod.console_set_fade(fade, fadingColor)[source]
tcod.console_set_fullscreen(fullscreen)[source]

Change the display to be fullscreen or windowed.

Parameters:fullscreen (bool) – Use True to change to fullscreen. Use False to change to windowed.
tcod.console_set_key_color(con, col)[source]

Set a consoles blit transparent color.

tcod.console_set_window_title(title)[source]

Change the current title bar string.

Parameters:title (AnyStr) – A string to change the title bar to.
tcod.console_vline(con, x, y, l, flag=13)[source]

Draw a vertical line on the console.

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

tcod.console_wait_for_keypress(flush)[source]

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

Parameters:bool (flush) – If True then the event queue is cleared before waiting for the next event.
Returns:A new Key instance.
Return type:Key

Event

class tcod.Key[source]

Key Event instance

vk

int – TCOD_keycode_t key code

c

int – character if vk == TCODK_CHAR else 0

text

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

pressed

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

lalt

bool – True when left alt is held.

lctrl

bool – True when left control is held.

lmeta

bool – True when left meta key is held.

ralt

bool – True when right alt is held.

rctrl

bool – True when right control is held.

rmeta

bool – True when right meta key is held.

shift

bool – True when any shift is held.

__repr__()[source]

Return a representation of this Key object.

class tcod.Mouse[source]

Mouse event instance

x

int – Absolute mouse position at pixel x.

y

int

dx

int – Movement since last update in pixels.

dy

int

cx

int – Cell coordinates in the root console.

cy

int

dcx

int – Movement since last update in console cells.

dcy

int

lbutton

bool – Left button status.

rbutton

bool – Right button status.

mbutton

bool – Middle button status.

lbutton_pressed

bool – Left button pressed event.

rbutton_pressed

bool – Right button pressed event.

mbutton_pressed

bool – Middle button pressed event.

wheel_up

bool – Wheel up event.

wheel_down

bool – Wheel down event.

__repr__()[source]

Return a representation of this Mouse object.

Event Types

tcod.EVENT_NONE
tcod.EVENT_KEY_PRESS
tcod.EVENT_KEY_RELEASE
tcod.EVENT_KEY

Same as tcod.EVENT_KEY_PRESS | tcod.EVENT_KEY_RELEASE

tcod.EVENT_MOUSE_MOVE
tcod.EVENT_MOUSE_PRESS
tcod.EVENT_MOUSE_RELEASE
tcod.EVENT_MOUSE

Same as tcod.EVENT_MOUSE_MOVE | tcod.EVENT_MOUSE_PRESS | tcod.EVENT_MOUSE_RELEASE

tcod.EVENT_FINGER_MOVE
tcod.EVENT_FINGER_PRESS
tcod.EVENT_FINGER_RELEASE
tcod.EVENT_FINGER

Same as tcod.EVENT_FINGER_MOVE | tcod.EVENT_FINGER_PRESS | tcod.EVENT_FINGER_RELEASE

tcod.EVENT_ANY

Same as tcod.EVENT_KEY | tcod.EVENT_MOUSE | tcod.EVENT_FINGER

sys

tcod.sys_set_fps(fps)[source]

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)
tcod.sys_get_fps()[source]

Return the current frames per second.

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

This number is updated every second.

Returns:The currently measured frame rate.
Return type:int
tcod.sys_get_last_frame_length()[source]

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

Returns:The delta time of the last rendered frame.
Return type:float
tcod.sys_sleep_milli(val)[source]

Sleep for ‘val’ milliseconds.

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

Deprecated since version 2.0: Use time.sleep instead.

tcod.sys_elapsed_milli()[source]

Get number of milliseconds since the start of the program.

Returns:Time since the progeam has started in milliseconds.
Return type:int

Deprecated since version 2.0: Use time.clock instead.

tcod.sys_elapsed_seconds()[source]

Get number of seconds since the start of the program.

Returns:Time since the progeam has started in seconds.
Return type:float

Deprecated since version 2.0: Use time.clock instead.

tcod.sys_set_renderer(renderer)[source]

Change the current rendering mode to renderer.

Deprecated since version 2.0: RENDERER_GLSL and RENDERER_OPENGL are not currently available.

tcod.sys_get_renderer()[source]

Return the current rendering mode.

tcod.sys_save_screenshot(name=None)[source]

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:Optional[AnyStr] (file) – File path to save screenshot.
tcod.sys_force_fullscreen_resolution(width, height)[source]

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.
tcod.sys_get_current_resolution()[source]

Return the current resolution as (width, height)

Returns:The current resolution.
Return type:Tuple[int,int]
tcod.sys_get_char_size()[source]

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

Returns:The current font glyph size in (width, height)
Return type:Tuple[int,int]
tcod.sys_update_char(asciiCode, fontx, fonty, img, x, y)[source]

Dynamically update the current frot with img.

All cells using this asciiCode will be updated at the next call to tcod.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.
tcod.sys_register_SDL_renderer(callback)[source]

Register a custom randering function with libtcod.

Note

This callback will only be called by the SDL renderer.

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

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

Parameters:Callable[[CData], None] (callback) – A function which takes a single argument.
tcod.sys_check_for_event(mask, k, m)[source]

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.
tcod.sys_wait_for_event(mask, k, m, flush)[source]

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 recieved.

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.

pathfinding

tcod.dijkstra_compute(p, ox, oy)[source]
tcod.dijkstra_delete(p)[source]
tcod.dijkstra_get(p, idx)[source]
tcod.dijkstra_get_distance(p, x, y)[source]
tcod.dijkstra_is_empty(p)[source]
tcod.dijkstra_new(m, dcost=1.41)[source]
tcod.dijkstra_new_using_function(w, h, func, userData=0, dcost=1.41)[source]
tcod.dijkstra_path_set(p, x, y)[source]
tcod.dijkstra_path_walk(p)[source]
tcod.dijkstra_reverse(p)[source]
tcod.dijkstra_size(p)[source]
tcod.path_compute(p, ox, oy, dx, dy)[source]

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

tcod.path_delete(p)[source]

Does nothing.

tcod.path_get(p, idx)[source]

Get a point on a path.

Parameters:
  • p (AStar) – An AStar instance.
  • idx (int) – Should be in range: 0 <= inx < path_size
tcod.path_get_destination(p)[source]

Get the current destination position.

Parameters:p (AStar) – An AStar instance.
Returns:An (x, y) point.
Return type:Tuple[int, int]
tcod.path_get_origin(p)[source]

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]
tcod.path_is_empty(p)[source]

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
tcod.path_new_using_function(w, h, func, userData=0, dcost=1.41)[source]

Return a new AStar using the given callable function.

Parameters:
  • w (int) – Clipping width.
  • h (int) – Clipping height.
  • func (Callable[[int, int, int, int, Any], float]) –
  • userData (Any) –
  • 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

tcod.path_new_using_map(m, dcost=1.41)[source]

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

tcod.path_reverse(p)[source]

Reverse the direction of a path.

This effectively swaps the origin and destination points.

Parameters:p (AStar) – An AStar instance.
tcod.path_size(p)[source]

Return the current length of the computed path.

Parameters:p (AStar) – An AStar instance.
Returns:Length of the path.
Return type:int
tcod.path_walk(p, recompute)[source]

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

tcod.heightmap_add(hm, value)[source]

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.

tcod.heightmap_add_fbm(hm, noise, mulx, muly, addx, addy, octaves, delta, scale)[source]

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.
tcod.heightmap_add_hill(hm, x, y, radius, height)[source]

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.
tcod.heightmap_add_hm(hm1, hm2, hm3)[source]

Add two heightmaps together and stores the result in hm3.

Parameters:

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

tcod.heightmap_add_voronoi(hm, nbPoints, nbCoef, coef, rnd=None)[source]

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.
tcod.heightmap_clamp(hm, mi, ma)[source]

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.

tcod.heightmap_clear(hm)[source]

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.

tcod.heightmap_copy(hm1, hm2)[source]

Copy the heightmap hm1 to hm2.

Parameters:

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

tcod.heightmap_count_cells(hm, mi, ma)[source]

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

tcod.heightmap_delete(hm)[source]

Does nothing.

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

tcod.heightmap_dig_bezier(hm, px, py, startRadius, startDepth, endRadius, endDepth)[source]

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.
tcod.heightmap_dig_hill(hm, x, y, radius, height)[source]

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.
tcod.heightmap_get_interpolated_value(hm, x, y)[source]

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

tcod.heightmap_get_minmax(hm)[source]

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: Do hm.min() or hm.max() instead.

tcod.heightmap_get_normal(hm, x, y, waterLevel)[source]

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]

tcod.heightmap_get_slope(hm, x, y)[source]

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

tcod.heightmap_get_value(hm, x, y)[source]

Return the value at x, y in a heightmap.

Parameters:
  • hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.
  • x (int) – The x position to pick.
  • y (int) – The y position to pick.
Returns:

The value at x, y.

Return type:

float

Deprecated since version 2.0: Do value = hm[y, x] instead.

tcod.heightmap_has_land_on_border(hm, waterlevel)[source]

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

tcod.heightmap_kernel_transform(hm, kernelsize, dx, dy, weight, minLevel, maxLevel)[source]

Apply a generic transformation on the map, so that each resulting cell value is the weighted sum of several neighbour 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 coorinates.
  • dy (Sequence[int]) – A sequence of y coorinates.
  • weight (Sequence[float]) – A sequence of kernelSize cells weight. The value of each neighbour 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)
tcod.heightmap_lerp_hm(hm1, hm2, hm3, coef)[source]

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.
tcod.heightmap_multiply_hm(hm1, hm2, hm3)[source]

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

Parameters:

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

tcod.heightmap_new(w, h)[source]

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

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

Parameters:
  • w (int) – The width of the new HeightMap.
  • h (int) – The height of the new HeightMap.
Returns:

A C-contiguous mapping of float32 values.

Return type:

numpy.ndarray

tcod.heightmap_normalize(hm, mi=0.0, ma=1.0)[source]

Normalize heightmap values between mi and ma.

Parameters:
  • mi (float) – The lowest value after normalization.
  • ma (float) – The highest value after normalization.
tcod.heightmap_rain_erosion(hm, nbDrops, erosionCoef, sedimentationCoef, rnd=None)[source]

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.
tcod.heightmap_scale(hm, value)[source]

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.

tcod.heightmap_scale_fbm(hm, noise, mulx, muly, addx, addy, octaves, delta, scale)[source]

Multiply the heighmap 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.
tcod.heightmap_set_value(hm, x, y, value)[source]

Set the value of a point on a heightmap.

Parameters:
  • hm (numpy.ndarray) – A numpy.ndarray formatted for heightmap functions.
  • x (int) – The x position to change.
  • y (int) – The y position to change.
  • value (float) – The value to set.

Deprecated since version 2.0: Do hm[y, x] = value instead.

image

tcod.image_load(filename)[source]

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

Parameters:filename (AnyStr) – Path to a .bmp or .png image file.
tcod.image_from_console(console)[source]

Return an Image with a Consoles pixel data.

This effectively takes a screen-shot of the Console.

Parameters:console (Console) – Any Console instance.
tcod.image_blit(image, console, x, y, bkgnd_flag, scalex, scaley, angle)[source]
tcod.image_blit_2x(image, console, dx, dy, sx=0, sy=0, w=-1, h=-1)[source]
tcod.image_blit_rect(image, console, x, y, w, h, bkgnd_flag)[source]
tcod.image_clear(image, col)[source]
tcod.image_delete(image)[source]
tcod.image_get_alpha(image, x, y)[source]
tcod.image_get_mipmap_pixel(image, x0, y0, x1, y1)[source]
tcod.image_get_pixel(image, x, y)[source]
tcod.image_get_size(image)[source]
tcod.image_hflip(image)[source]
tcod.image_invert(image)[source]
tcod.image_is_pixel_transparent(image, x, y)[source]
tcod.image_new(width, height)[source]
tcod.image_put_pixel(image, x, y, col)[source]
tcod.image_refresh_console(image, console)[source]
tcod.image_rotate90(image, num=1)[source]
tcod.image_save(image, filename)[source]
tcod.image_scale(image, neww, newh)[source]
tcod.image_set_key_color(image, col)[source]
tcod.image_vflip(image)[source]

line

tcod.line_init(xo, yo, xd, yd)[source]

Initilize 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: Use line_iter instead.

tcod.line_step()[source]

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: Use line_iter instead.

tcod.line(xo, yo, xd, yd, py_callback)[source]

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 interation by

returning False or None, otherwise True.

Return type:

bool

Deprecated since version 2.0: Use line_iter instead.

tcod.line_iter(xo, yo, xd, yd)[source]

returns an iterator

This iterator 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 iterator of (x,y) points.

Return type:

Iterator[Tuple[int,int]]

map

tcod.map_clear(m, walkable=False, transparent=False)[source]
tcod.map_compute_fov(m, x, y, radius=0, light_walls=True, algo=12)[source]
tcod.map_copy(source, dest)[source]
tcod.map_delete(m)[source]
tcod.map_get_height(map)[source]
tcod.map_get_width(map)[source]
tcod.map_is_in_fov(m, x, y)[source]
tcod.map_is_transparent(m, x, y)[source]
tcod.map_is_walkable(m, x, y)[source]
tcod.map_new(w, h)[source]
tcod.map_set_properties(m, x, y, isTrans, isWalk)[source]

mouse

tcod.mouse_get_status()[source]
tcod.mouse_is_cursor_visible()[source]
tcod.mouse_move(x, y)[source]
tcod.mouse_show_cursor(visible)[source]

namegen

tcod.namegen_destroy()[source]
tcod.namegen_generate(name)[source]
tcod.namegen_generate_custom(name, rule)[source]
tcod.namegen_get_sets()[source]
tcod.namegen_parse(filename, random=None)[source]

noise

tcod.noise_delete(n)[source]

Does nothing.

tcod.noise_get(n, f, typ=0)[source]

Return the noise value sampled from the f coordinate.

f should be a tuple or list with a length matching Noise.dimensions. If f is shoerter than Noise.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

tcod.noise_get_fbm(n, f, oc, typ=0)[source]

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.
  • octaves (float) – The level of level. Should be more than 1.
Returns:

The sampled noise value.

Return type:

float

tcod.noise_get_turbulence(n, f, oc, typ=0)[source]

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.
  • octaves (float) – The level of level. Should be more than 1.
Returns:

The sampled noise value.

Return type:

float

tcod.noise_new(dim, h=0.5, l=2.0, random=None)[source]

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

tcod.noise_set_type(n, typ)[source]

Set a Noise objects default noise algorithm.

Parameters:typ (int) – Any NOISE_* constant.

parser

tcod.parser_delete(parser)[source]
tcod.parser_get_bool_property(parser, name)[source]
tcod.parser_get_char_property(parser, name)[source]
tcod.parser_get_color_property(parser, name)[source]
tcod.parser_get_dice_property(parser, name)[source]
tcod.parser_get_float_property(parser, name)[source]
tcod.parser_get_int_property(parser, name)[source]
tcod.parser_get_list_property(parser, name, type)[source]
tcod.parser_get_string_property(parser, name)[source]
tcod.parser_new()[source]
tcod.parser_new_struct(parser, name)[source]
tcod.parser_run(parser, filename, listener=None)[source]

random

tcod.random_delete(rnd)[source]

Does nothing.

tcod.random_get_double(rnd, mi, ma)[source]

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

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

tcod.random_get_double_mean(rnd, mi, ma, mean)[source]

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

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

tcod.random_get_float(rnd, mi, ma)[source]

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

The result is affacted by calls to random_set_distribution.

Parameters:
  • rnd (Optional[Random]) – A Random instance, or None to use the default.
  • low (float) – The lower bound of the random range, inclusive.
  • high (float) – The upper bound of the random range, inclusive.
Returns:

A random double precision float

in the range mi <= n <= ma.

Return type:

float

tcod.random_get_float_mean(rnd, mi, ma, mean)[source]

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

The result is affacted by calls to random_set_distribution.

Parameters:
  • rnd (Optional[Random]) – A Random instance, or None to use the default.
  • low (float) – The lower bound of the random range, inclusive.
  • high (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

tcod.random_get_instance()[source]

Return the default Random instance.

Returns:A Random instance using the default random number generator.
Return type:Random
tcod.random_get_int(rnd, mi, ma)[source]

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

The result is affacted by calls to random_set_distribution.

Parameters:
  • rnd (Optional[Random]) – A Random instance, or None to use the default.
  • low (int) – The lower bound of the random range, inclusive.
  • high (int) – The upper bound of the random range, inclusive.
Returns:

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

Return type:

int

tcod.random_get_int_mean(rnd, mi, ma, mean)[source]

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

The result is affacted by calls to random_set_distribution.

Parameters:
  • rnd (Optional[Random]) – A Random instance, or None to use the default.
  • low (int) – The lower bound of the random range, inclusive.
  • high (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

tcod.random_new(algo=1)[source]

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
tcod.random_new_from_seed(seed, algo=1)[source]

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

tcod.random_restore(rnd, backup)[source]

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.
tcod.random_save(rnd)[source]

Return a copy of a random number generator.

Parameters:rnd (Optional[Random]) – A Random instance, or None to use the default.
Returns:A Random instance with a copy of the random generator.
Return type:Random
tcod.random_set_distribution(rnd, dist)[source]

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

tcod.struct_add_flag(struct, name)[source]
tcod.struct_add_list_property(struct, name, typ, mandatory)[source]
tcod.struct_add_property(struct, name, typ, mandatory)[source]
tcod.struct_add_structure(struct, sub_struct)[source]
tcod.struct_add_value_list(struct, name, value_list, mandatory)[source]
tcod.struct_get_name(struct)[source]
tcod.struct_get_type(struct, name)[source]
tcod.struct_is_mandatory(struct, name)[source]

other

class tcod.ConsoleBuffer(width, height, back_r=0, back_g=0, back_b=0, fore_r=0, fore_g=0, fore_b=0, char=' ')[source]

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

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, fill_fore=True, fill_back=True)[source]

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=0, back_g=0, back_b=0, fore_r=0, fore_g=0, fore_b=0, char=' ')[source]

Clears 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()[source]

Returns a copy of this ConsoleBuffer.

Returns:A new ConsoleBuffer copy.
Return type:ConsoleBuffer
set(x, y, back_r, back_g, back_b, fore_r, fore_g, fore_b, char)[source]

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, y, r, g, b)[source]

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.
  • char (AnyStr) – A single character str or bytes object.
set_fore(x, y, r, g, b, char)[source]

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 tcod.Dice(nb_dices=0, nb_faces=0, multiplier=0, addsub=0)[source]
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.