tcod.console

libtcod works with a special ‘root’ console. You create this console using the tcod.console_init_root function. Usually after setting the font with console_set_custom_font first.

Example:

# Make sure 'arial10x10.png' is in the same directory as this script.
import tcod
import tcod.event

# Setup the font.
tcod.console_set_custom_font(
    "arial10x10.png",
    tcod.FONT_LAYOUT_TCOD | tcod.FONT_TYPE_GREYSCALE,
)
# Initialize the root console in a context.
with tcod.console_init_root(80, 60, order="F") as root_console:
    root_console.print_(x=0, y=0, string='Hello World!')
    while True:
        tcod.console_flush()  # Show the console.
        for event in tcod.event.wait():
            if event.type == "QUIT":
                raise SystemExit()
    # The libtcod window will be closed at the end of this with-block.
class tcod.console.Console(width: int, height: int, order: str = 'C', buffer: Optional[numpy.ndarray] = None)[source]

A console object containing a grid of characters with foreground/background colors.

width and height are the size of the console (in tiles.)

order determines how the axes of NumPy array attributes are arraigned. order=”F” will swap the first two axes which allows for more intuitive [x, y] indexing.

With buffer the console can be initialized from another array. The buffer should be compatible with the width, height, and order given; and should also have a dtype compatible with Console.DTYPE.

Changed in version 4.3: Added order parameter.

Changed in version 8.5: Added buffer, copy, and default parameters. Arrays are initialized as if the clear method was called.

Changed in version 10.0: DTYPE changed, buffer now requires colors with an alpha channel.

console_c

A python-cffi “TCOD_Console*” object.

DTYPE

A class attribute which provides a dtype compatible with this class.

[("ch", np.intc), ("fg", "(4,)u1"), ("bg", "(4,)u1")]

Example:

>>> buffer = np.zeros(
...     shape=(20, 3),
...     dtype=tcod.console.Console.DTYPE,
...     order="F",
... )
>>> buffer["ch"] = ord(' ')
>>> buffer["ch"][:, 1] = ord('x')
>>> c = tcod.console.Console(20, 3, order="F", buffer=buffer)
>>> print(c)
<                    |
|xxxxxxxxxxxxxxxxxxxx|
|                    >

New in version 8.5.

Changed in version 10.0: Added an alpha channel to the color types.

__bool__() → bool[source]

Returns False if this is the root console.

This mimics libtcodpy behavior.

__enter__() → tcod.console.Console[source]

Returns this console in a managed context.

When the root console is used as a context, the graphical window will close once the context is left as if tcod.console_delete was called on it.

This is useful for some Python IDE’s like IDLE, where the window would not be closed on its own otherwise.

__exit__(*args) → None[source]

Closes the graphical window on exit.

Some tcod functions may have undefined behavior after this point.

__repr__() → str[source]

Return a string representation of this console.

__str__() → str[source]

Return a simplified representation of this consoles contents.

blit(dest: tcod.console.Console, dest_x: int = 0, dest_y: int = 0, src_x: int = 0, src_y: int = 0, width: int = 0, height: int = 0, fg_alpha: float = 1.0, bg_alpha: float = 1.0, key_color: Optional[Tuple[int, int, int]] = None) → None[source]

Blit from this console onto the dest console.

Parameters:
  • dest (Console) – The destination console to blit onto.
  • dest_x (int) – Leftmost coordinate of the destination console.
  • dest_y (int) – Topmost coordinate of the destination console.
  • src_x (int) – X coordinate from this console to blit, from the left.
  • src_y (int) – Y coordinate from this console to blit, from the top.
  • width (int) –

    The width of the region to blit.

    If this is 0 the maximum possible width will be used.

  • height (int) –

    The height of the region to blit.

    If this is 0 the maximum possible height will be used.

  • fg_alpha (float) – Foreground color alpha vaule.
  • bg_alpha (float) – Background color alpha vaule.
  • key_color (Optional[Tuple[int, int, int]]) – None, or a (red, green, blue) tuple with values of 0-255.

Changed in version 4.0: Parameters were rearraged and made optional.

Previously they were: (x, y, width, height, dest, dest_x, dest_y, *)

clear(ch: int = 32, fg: Tuple[int, int, int] = Ellipsis, bg: Tuple[int, int, int] = Ellipsis) → None[source]

Reset all values in this console to a single value.

ch is the character to clear the console with. Defaults to the space character.

fg and bg are the colors to clear the console with. Defaults to white-on-black if the console defaults are untouched.

Note

If fg/bg are not set, they will default to default_fg/default_bg. However, default values other than white-on-back are deprecated.

Changed in version 8.5: Added the ch, fg, and bg parameters. Non-white-on-black default values are deprecated.

draw_frame(x: int, y: int, width: int, height: int, title: str = '', clear: bool = True, fg: Optional[Tuple[int, int, int]] = None, bg: Optional[Tuple[int, int, int]] = None, bg_blend: int = 1) → None[source]

Draw a framed rectangle with an optional title.

x and y are the starting tile, with 0,0 as the upper-left corner of the console. You can use negative numbers if you want to start printing relative to the bottom-right corner, but this behavior may change in future versions.

width and height determine the size of the frame.

title is a Unicode string.

If clear is True than the region inside of the frame will be cleared.

fg and bg are the foreground text color and background tile color respectfully. This is a 3-item tuple with (r, g, b) color values from 0 to 255. These parameters can also be set to None to leave the colors unchanged.

bg_blend is the blend type used by libtcod.

New in version 8.5.

Changed in version 9.0: fg and bg now default to None instead of white-on-black.

draw_rect(x: int, y: int, width: int, height: int, ch: int, fg: Optional[Tuple[int, int, int]] = None, bg: Optional[Tuple[int, int, int]] = None, bg_blend: int = 1) → None[source]

Draw characters and colors over a rectangular region.

x and y are the starting tile, with 0,0 as the upper-left corner of the console. You can use negative numbers if you want to start printing relative to the bottom-right corner, but this behavior may change in future versions.

width and height determine the size of the rectangle.

ch is a Unicode integer. You can use 0 to leave the current characters unchanged.

fg and bg are the foreground text color and background tile color respectfully. This is a 3-item tuple with (r, g, b) color values from 0 to 255. These parameters can also be set to None to leave the colors unchanged.

bg_blend is the blend type used by libtcod.

New in version 8.5.

Changed in version 9.0: fg and bg now default to None instead of white-on-black.

get_height_rect(x: int, y: int, width: int, height: int, string: str) → int[source]

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

Parameters:
  • x (int) – The x coordinate from the left.
  • y (int) – The y coordinate from the top.
  • width (int) – Maximum width to render the text.
  • height (int) – Maximum lines to render the text.
  • string (str) – A Unicode string.
Returns:

The number of lines of text once word-wrapped.

Return type:

int

hline(x: int, y: int, width: int, bg_blend: int = 13) → None[source]

Draw a horizontal line on the console.

This always uses ord(‘─’), the horizontal line character.

Parameters:
  • x (int) – The x coordinate from the left.
  • y (int) – The y coordinate from the top.
  • width (int) – The horizontal length of this line.
  • bg_blend (int) – The background blending flag.

Deprecated since version 8.5: Console methods which depend on console defaults have been deprecated. Use Console.draw_rect instead, calling this function will print a warning detailing which default values need to be made explicit.

print(x: int, y: int, string: str, fg: Optional[Tuple[int, int, int]] = None, bg: Optional[Tuple[int, int, int]] = None, bg_blend: int = 1, alignment: int = 0) → None[source]

Print a string on a console with manual line breaks.

x and y are the starting tile, with 0,0 as the upper-left corner of the console. You can use negative numbers if you want to start printing relative to the bottom-right corner, but this behavior may change in future versions.

string is a Unicode string which may include color control characters. Strings which are too long will be truncated until the next newline character "\n".

fg and bg are the foreground text color and background tile color respectfully. This is a 3-item tuple with (r, g, b) color values from 0 to 255. These parameters can also be set to None to leave the colors unchanged.

bg_blend is the blend type used by libtcod.

alignment can be tcod.LEFT, tcod.CENTER, or tcod.RIGHT.

New in version 8.5.

Changed in version 9.0: fg and bg now default to None instead of white-on-black.

print_(x: int, y: int, string: str, bg_blend: int = 13, alignment: Optional[int] = None) → None[source]

Print a color formatted string on a console.

Parameters:
  • x (int) – The x coordinate from the left.
  • y (int) – The y coordinate from the top.
  • string (str) – A Unicode string optionally using color codes.
  • bg_blend (int) – Blending mode to use, defaults to BKGND_DEFAULT.
  • alignment (Optional[int]) – Text alignment.

Deprecated since version 8.5: Console methods which depend on console defaults have been deprecated. Use Console.print instead, calling this function will print a warning detailing which default values need to be made explicit.

print_box(x: int, y: int, width: int, height: int, string: str, fg: Optional[Tuple[int, int, int]] = None, bg: Optional[Tuple[int, int, int]] = None, bg_blend: int = 1, alignment: int = 0) → int[source]

Print a string constrained to a rectangle and return the height.

x and y are the starting tile, with 0,0 as the upper-left corner of the console. You can use negative numbers if you want to start printing relative to the bottom-right corner, but this behavior may change in future versions.

width and height determine the bounds of the rectangle, the text will automatically be word-wrapped to fit within these bounds.

string is a Unicode string which may include color control characters.

fg and bg are the foreground text color and background tile color respectfully. This is a 3-item tuple with (r, g, b) color values from 0 to 255. These parameters can also be set to None to leave the colors unchanged.

bg_blend is the blend type used by libtcod.

alignment can be tcod.LEFT, tcod.CENTER, or tcod.RIGHT.

Returns the actual height of the printed area.

New in version 8.5.

Changed in version 9.0: fg and bg now default to None instead of white-on-black.

print_frame(x: int, y: int, width: int, height: int, string: str = '', clear: bool = True, bg_blend: int = 13) → None[source]

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.

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

Parameters:
  • x (int) – The x coordinate from the left.
  • y (int) – The y coordinate from the top.
  • width (int) – The width if the frame.
  • height (int) – The height of the frame.
  • string (str) – A Unicode string to print.
  • clear (bool) – If True all text in the affected area will be removed.
  • bg_blend (int) – The background blending flag.

Changed in version 8.2: Now supports Unicode strings.

Deprecated since version 8.5: Console methods which depend on console defaults have been deprecated. Use Console.draw_frame instead, calling this function will print a warning detailing which default values need to be made explicit.

print_rect(x: int, y: int, width: int, height: int, string: str, bg_blend: int = 13, alignment: Optional[int] = None) → int[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.

Parameters:
  • x (int) – The x coordinate from the left.
  • y (int) – The y coordinate from the top.
  • width (int) – Maximum width to render the text.
  • height (int) – Maximum lines to render the text.
  • string (str) – A Unicode string.
  • bg_blend (int) – Background blending flag.
  • alignment (Optional[int]) – Alignment flag.
Returns:

The number of lines of text once word-wrapped.

Return type:

int

Deprecated since version 8.5: Console methods which depend on console defaults have been deprecated. Use Console.print_box instead, calling this function will print a warning detailing which default values need to be made explicit.

put_char(x: int, y: int, ch: int, bg_blend: int = 13) → None[source]

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

Parameters:
  • x (int) – The x coordinate from the left.
  • y (int) – The y coordinate from the top.
  • ch (int) – Character code to draw. Must be in integer form.
  • bg_blend (int) – Blending mode to use, defaults to BKGND_DEFAULT.
rect(x: int, y: int, width: int, height: int, clear: bool, bg_blend: int = 13) → None[source]

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

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

Parameters:
  • x (int) – The x coordinate from the left.
  • y (int) – The y coordinate from the top.
  • width (int) – Maximum width to render the text.
  • height (int) – Maximum lines to render the text.
  • clear (bool) – If True all text in the affected area will be removed.
  • bg_blend (int) – Background blending flag.

Deprecated since version 8.5: Console methods which depend on console defaults have been deprecated. Use Console.draw_rect instead, calling this function will print a warning detailing which default values need to be made explicit.

set_key_color(color: Optional[Tuple[int, int, int]]) → None[source]

Set a consoles blit transparent color.

color is the (r, g, b) color, or None to disable key color.

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

vline(x: int, y: int, height: int, bg_blend: int = 13) → None[source]

Draw a vertical line on the console.

This always uses ord(‘│’), the vertical line character.

Parameters:
  • x (int) – The x coordinate from the left.
  • y (int) – The y coordinate from the top.
  • height (int) – The horozontal length of this line.
  • bg_blend (int) – The background blending flag.

Deprecated since version 8.5: Console methods which depend on console defaults have been deprecated. Use Console.draw_rect instead, calling this function will print a warning detailing which default values need to be made explicit.

bg

A uint8 array with the shape (height, width, 3).

You can change the consoles background colors by using this array.

Index this array with console.bg[i, j, channel]  # order='C' or console.bg[x, y, channel]  # order='F'.

ch

An integer array with the shape (height, width).

You can change the consoles character codes by using this array.

Index this array with console.ch[i, j]  # order='C' or console.ch[x, y]  # order='F'.

default_alignment

The default text alignment.

Type:int
default_bg

The default background color.

Type:Tuple[int, int, int]
default_bg_blend

The default blending mode.

Type:int
default_fg

The default foreground color.

Type:Tuple[int, int, int]
fg

A uint8 array with the shape (height, width, 3).

You can change the consoles foreground colors by using this array.

Index this array with console.fg[i, j, channel]  # order='C' or console.fg[x, y, channel]  # order='F'.

height

The height of this Console. (read-only)

Type:int
tiles

An array of this consoles tile data.

This acts as a combination of the ch, fg, and bg attributes. Colors include an alpha channel but how alpha works is currently undefined.

Example::
>>> con = tcod.console.Console(10, 2, order="F")
>>> con.tiles[0, 0] = (
...     ord("X"),
...     (*tcod.white, 255),
...     (*tcod.black, 255),
... )
>>> con.tiles[0, 0]
(88, [255, 255, 255, 255], [  0,   0,   0, 255])

New in version 10.0.

width

The width of this Console. (read-only)

Type:int
tcod.console.get_height_rect(width: int, string: str) → int[source]

Return the number of lines which would be printed from these parameters.

width is the width of the print boundary.

string is a Unicode string which may include color control characters.

New in version 9.2.