Console

Initializing the console

Creating the game window

enum TCOD_renderer_t

The available renderers.

Values:

TCOD_RENDERER_GLSL

An OpenGL implementation using a shader.

TCOD_RENDERER_OPENGL

An OpenGL implementation without a shader.

Performs worse than TCOD_RENDERER_GLSL without many benefits.

TCOD_RENDERER_SDL

A software based renderer.

The font file is loaded into RAM instead of VRAM in this implementation.

TCOD_RENDERER_SDL2

A new SDL2 renderer.

Allows the window to be resized.

New in version 1.8.

TCOD_RENDERER_OPENGL2

A new OpenGL 2.0 core renderer.

Allows the window to be resized.

New in version 1.9.

Changed in version 1.11.0: This renderer now uses OpenGL 2.0 instead of 2.1.

TCOD_NB_RENDERERS
TCODLIB_CAPI void TCOD_console_init_root(int w, int h, const char * title, bool fullscreen, TCOD_renderer_t renderer)

Initialize the libtcod graphical engine.

You may want to call TCOD_console_set_custom_font BEFORE calling this function. By default this function loads libtcod’s

terminal.png image from the working directory.
Parameters
  • w: The width in tiles.
  • h: The height in tiles.
  • title: The title for the window.
  • fullscreen: Fullscreen option.
  • renderer: Which renderer to use when rendering the console.

Afterwards TCOD_quit must be called before the program exits.

TCODLIB_CAPI void TCOD_quit(void)

Shutdown libtcod.

This must be called before your program exits.

New in version 1.8.

Using a custom bitmap font

enum TCOD_font_flags_t

These font flags can be OR’d together into a bit-field and passed to TCOD_console_set_custom_font.

Values:

TCOD_FONT_LAYOUT_ASCII_INCOL =1

Tiles are arranged in column-major order.

0 3 6 1 4 7 2 5 8

TCOD_FONT_LAYOUT_ASCII_INROW =2

Tiles are arranged in row-major order.

0 1 2 3 4 5 6 7 8

TCOD_FONT_TYPE_GREYSCALE =4

Converts all tiles into a monochrome gradient.

TCOD_FONT_TYPE_GRAYSCALE =4
TCOD_FONT_LAYOUT_TCOD =8

A unique layout used by some of libtcod’s fonts.

TCOD_FONT_LAYOUT_CP437 =16

Decode a code page 437 tileset into Unicode code-points.

New in version 1.10.

void TCOD_console_set_custom_font(const char *fontFile, int flags, int nb_char_horiz, int nb_char_vertic)

Set a font image to be loaded during initialization.

fontFile will be case-sensitive depending on the platform.

Parameters
  • fontFile: The path to a font image.
  • flags: A TCOD_font_flags_t bit-field describing the font image contents.
  • nb_char_horiz: The number of columns in the font image.
  • nb_char_vertic: The number of rows in the font image.

Using custom characters mapping

void TCOD_console_map_ascii_code_to_font(int asciiCode, int fontCharX, int fontCharY)

Remap a character code to a tile.

X,Y parameters are the coordinate of the tile, not pixel-coordinates.

Parameters
  • asciiCode: Character code to modify.
  • fontCharX: X tile-coordinate, starting from the left at zero.
  • fontCharY: Y tile-coordinate, starting from the top at zero.

void TCOD_console_map_ascii_codes_to_font(int asciiCode, int nbCodes, int fontCharX, int fontCharY)

Remap a series of character codes to a row of tiles.

This function always assigns tiles in row-major order, even if the TCOD_FONT_LAYOUT_ASCII_INCOL flag was set.

Parameters
  • asciiCode: The starting character code.
  • nbCodes: Number of character codes to assign.
  • fontCharX: First X tile-coordinate, starting from the left at zero.
  • fontCharY: First Y tile-coordinate, starting from the top at zero.

void TCOD_console_map_string_to_font(const char *s, int fontCharX, int fontCharY)

Remap a string of character codes to a row of tiles.

This function always assigns tiles in row-major order, even if the TCOD_FONT_LAYOUT_ASCII_INCOL flag was set.

Parameters
  • s: A null-terminated string.
  • fontCharX: First X tile-coordinate, starting from the left at zero.
  • fontCharY: First Y tile-coordinate, starting from the top at zero.

Fullscreen mode

TCODLIB_CAPI void TCOD_console_set_fullscreen(bool fullscreen)

Set the display to be full-screen or windowed.

Parameters
  • fullscreen: If true the display will go full-screen.

TCODLIB_CAPI bool TCOD_console_is_fullscreen(void)

Return true if the display is full-screen.

Communicate with the window manager

TCODLIB_CAPI bool TCOD_console_is_active(void)

Return true if the window has keyboard focus.

TCODLIB_CAPI bool TCOD_console_has_mouse_focus(void)

Return true if the window has mouse focus.

TCODLIB_CAPI bool TCOD_console_is_window_closed(void)

Return true if the window is closing.

TCODLIB_CAPI void TCOD_console_set_window_title(const char * title)

Change the title string of the active window.

Parameters
  • title: A utf8 string.

libtcod’s Credits

void TCOD_console_credits(void)
void TCOD_console_credits_reset(void)
bool TCOD_console_credits_render(int x, int y, bool alpha)

Drawing on the root console

Basic printing functions

void TCOD_console_set_default_foreground(TCOD_console_t con, TCOD_color_t col)
void TCOD_console_set_default_background(TCOD_console_t con, TCOD_color_t col)
void TCOD_console_set_background_flag(TCOD_console_t con, TCOD_bkgnd_flag_t flag)
void TCOD_console_clear(TCOD_console_t con)

Clear a console to its default colors and the space character code.

void TCOD_console_put_char(TCOD_console_t con, int x, int y, int c, TCOD_bkgnd_flag_t flag)
void TCOD_console_put_char_ex(TCOD_console_t con, int x, int y, int c, TCOD_color_t fore, TCOD_color_t back)

Draw a character on the console with the given colors.

Parameters
  • con: A console pointer.
  • x: The X coordinate, the left-most position being 0.
  • y: The Y coordinate, the top-most position being 0.
  • c: The character code to place.
  • fore: The foreground color.
  • back: The background color. This color will not be blended.

void TCOD_console_set_char(TCOD_console_t con, int x, int y, int c)

Change a character on a console tile, without changing its colors.

Parameters
  • con: A console pointer.
  • x: The X coordinate, the left-most position being 0.
  • y: The Y coordinate, the top-most position being 0.
  • c: The character code to set.

void TCOD_console_set_char_foreground(TCOD_console_t con, int x, int y, TCOD_color_t col)
void TCOD_console_set_char_background(TCOD_console_t con, int x, int y, TCOD_color_t col, TCOD_bkgnd_flag_t flag)
TCODLIB_CAPI void TCOD_console_rect(TCOD_Console * con, int x, int y, int w, int h, bool clear, TCOD_bkgnd_flag_t flag)

Draw a rectangle onto a console.

Parameters
  • con: A console pointer.
  • x: The starting region, the left-most position being 0.
  • y: The starting region, the top-most position being 0.
  • rw: The width of the rectangle.
  • rh: The height of the rectangle.
  • clear: If true the drawing region will be filled with spaces.
  • flag: The blending flag to use.

TCODLIB_CAPI void TCOD_console_hline(TCOD_Console * con, int x, int y, int l, TCOD_bkgnd_flag_t flag)

Draw a horizontal line using the default colors.

This function makes assumptions about the fonts character encoding. It will fail if the font encoding is not

cp437.
Parameters
  • con: A console pointer.
  • x: The starting X coordinate, the left-most position being 0.
  • y: The starting Y coordinate, the top-most position being 0.
  • l: The width of the line.
  • flag: The blending flag.

TCODLIB_CAPI void TCOD_console_vline(TCOD_Console * con, int x, int y, int l, TCOD_bkgnd_flag_t flag)

Draw a vertical line using the default colors.

This function makes assumptions about the fonts character encoding. It will fail if the font encoding is not

cp437.
Parameters
  • con: A console pointer.
  • x: The starting X coordinate, the left-most position being 0.
  • y: The starting Y coordinate, the top-most position being 0.
  • l: The height of the line.
  • flag: The blending flag.

void TCOD_console_print_frame(TCOD_console_t con, int x, int y, int w, int h, bool empty, TCOD_bkgnd_flag_t flag, const char *fmt, ...)

Background effect flags

enum TCOD_bkgnd_flag_t

Values:

TCOD_BKGND_NONE
TCOD_BKGND_SET
TCOD_BKGND_MULTIPLY
TCOD_BKGND_LIGHTEN
TCOD_BKGND_DARKEN
TCOD_BKGND_SCREEN
TCOD_BKGND_COLOR_DODGE
TCOD_BKGND_COLOR_BURN
TCOD_BKGND_ADD
TCOD_BKGND_ADDA
TCOD_BKGND_BURN
TCOD_BKGND_OVERLAY
TCOD_BKGND_ALPH
TCOD_BKGND_DEFAULT

String printing alignment

enum TCOD_alignment_t

Print justification options.

Values:

TCOD_LEFT
TCOD_RIGHT
TCOD_CENTER
void TCOD_console_set_alignment(TCOD_console_t con, TCOD_alignment_t alignment)
TCOD_alignment_t TCOD_console_get_alignment(TCOD_console_t con)

Return a consoles default alignment.

Printing functions using 8-bit encodings

void TCOD_console_print(TCOD_Console *con, int x, int y, const char *fmt, ...)

Print a string on a console, using default colors and alignment.

Parameters
  • con: A console pointer.
  • x: The starting X coordinate, the left-most position being 0.
  • y: The starting Y coordinate, the top-most position being 0.
  • fmt: A format string as if passed to printf.
  • ...: Variadic arguments as if passed to printf.

void TCOD_console_print_ex(TCOD_Console *con, int x, int y, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt, ...)

Print a string on a console, using default colors.

Parameters
  • con: A console pointer.
  • x: The starting X coordinate, the left-most position being 0.
  • y: The starting Y coordinate, the top-most position being 0.
  • flag: The blending flag.
  • alignment: The font alignment to use.
  • fmt: A format string as if passed to printf.
  • ...: Variadic arguments as if passed to printf.

int TCOD_console_print_rect(TCOD_Console *con, int x, int y, int w, int h, const char *fmt, ...)

Print a string on a console constrained to a rectangle, using default colors and alignment.

Return
The number of lines actually printed.
Parameters
  • con: A console pointer.
  • x: The starting X coordinate, the left-most position being 0.
  • y: The starting Y coordinate, the top-most position being 0.
  • w: The width of the region. If 0 then the maximum width will be used.
  • h: The height of the region. If 0 then the maximum height will be used.
  • fmt: A format string as if passed to printf.
  • ...: Variadic arguments as if passed to printf.

int TCOD_console_print_rect_ex(TCOD_Console *con, int x, int y, int w, int h, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt, ...)

Print a string on a console constrained to a rectangle, using default colors.

Return
The number of lines actually printed.
Parameters
  • con: A console pointer.
  • x: The starting X coordinate, the left-most position being 0.
  • y: The starting Y coordinate, the top-most position being 0.
  • w: The width of the region. If 0 then the maximum width will be used.
  • h: The height of the region. If 0 then the maximum height will be used.
  • flag: The blending flag.
  • alignment: The font alignment to use.
  • fmt: A format string as if passed to printf.
  • ...: Variadic arguments as if passed to printf.

int TCOD_console_get_height_rect(TCOD_Console *con, int x, int y, int w, int h, const char *fmt, ...)

Return the number of lines that would be printed by the.

Return
The number of lines that would have been printed.
Parameters
  • con: A console pointer.
  • x: The starting X coordinate, the left-most position being 0.
  • y: The starting Y coordinate, the top-most position being 0.
  • w: The width of the region. If 0 then the maximum width will be used.
  • h: The height of the region. If 0 then the maximum height will be used.
  • fmt: A format string as if passed to printf.
  • ...: Variadic arguments as if passed to printf.

Printing functions using UTF-8

Warning

doxygenfunction: Cannot find function “TCOD_console_printf” in doxygen xml output for project “libtcod” from directory: doxyxml/

Warning

doxygenfunction: Cannot find function “TCOD_console_printf_ex” in doxygen xml output for project “libtcod” from directory: doxyxml/

Warning

doxygenfunction: Cannot find function “TCOD_console_printf_rect” in doxygen xml output for project “libtcod” from directory: doxyxml/

Warning

doxygenfunction: Cannot find function “TCOD_console_printf_rect_ex” in doxygen xml output for project “libtcod” from directory: doxyxml/

Warning

doxygenfunction: Cannot find function “TCOD_console_get_height_rect_fmt” in doxygen xml output for project “libtcod” from directory: doxyxml/

Warning

doxygenfunction: Cannot find function “TCOD_console_printf_frame” in doxygen xml output for project “libtcod” from directory: doxyxml/

Printing functions using wchar_t

Note

These functions say they are UTF, however they will behave as UCS2 or UCS4 depending on the platform.

void TCOD_console_print_utf(TCOD_Console *con, int x, int y, const wchar_t *fmt, ...)

Deprecated since version 1.8: Use TCOD_console_printf instead.

void TCOD_console_print_ex_utf(TCOD_Console *con, int x, int y, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const wchar_t *fmt, ...)

Deprecated since version 1.8: Use TCOD_console_printf_ex instead.

int TCOD_console_print_rect_utf(TCOD_Console *con, int x, int y, int w, int h, const wchar_t *fmt, ...)
int TCOD_console_print_rect_ex_utf(TCOD_Console *con, int x, int y, int w, int h, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const wchar_t *fmt, ...)

Deprecated since version 1.8: Use TCOD_console_printf_rect_ex instead.

int TCOD_console_get_height_rect_utf(TCOD_Console *con, int x, int y, int w, int h, const wchar_t *fmt, ...)

Deprecated since version 1.8.

Reading the content of the console

int TCOD_console_get_width(const TCOD_Console *con)

Return the width of a console.

int TCOD_console_get_height(const TCOD_Console *con)

Return the height of a console.

int TCOD_console_get_char(const TCOD_Console *con, int x, int y)

Return a character code of a console at x,y.

Return
The character code.
Parameters
  • con: A console pointer.
  • x: The X coordinate, the left-most position being 0.
  • y: The Y coordinate, the top-most position being 0.

TCOD_color_t TCOD_console_get_char_foreground(const TCOD_Console *con, int x, int y)

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

Return
A TCOD_color_t struct with a copy of the foreground color.
Parameters
  • con: A console pointer.
  • x: The X coordinate, the left-most position being 0.
  • y: The Y coordinate, the top-most position being 0.

TCOD_color_t TCOD_console_get_char_background(const TCOD_Console *con, int x, int y)

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

Return
A TCOD_color_t struct with a copy of the background color.
Parameters
  • con: A console pointer.
  • x: The X coordinate, the left-most position being 0.
  • y: The Y coordinate, the top-most position being 0.

TCOD_color_t TCOD_console_get_default_foreground(TCOD_console_t con)
TCOD_color_t TCOD_console_get_default_background(TCOD_console_t con)
TCOD_bkgnd_flag_t TCOD_console_get_background_flag(TCOD_console_t con)

Screen fading functions

void TCOD_console_set_fade(uint8_t val, TCOD_color_t fade)

Fade the color of the display.

Parameters
  • val: Where at 255 colors are normal and at 0 colors are completely faded.
  • fadecol: Color to fade towards.

uint8_t TCOD_console_get_fade(void)

Return the fade value.

Return
At 255 colors are normal and at 0 colors are completely faded.

TCOD_color_t TCOD_console_get_fading_color(void)

Return the fade color.

Return
The current fading color.

ASCII constants

enum TCOD_chars_t

Values:

TCOD_CHAR_HLINE =196
TCOD_CHAR_VLINE =179
TCOD_CHAR_NE =191
TCOD_CHAR_NW =218
TCOD_CHAR_SE =217
TCOD_CHAR_SW =192
TCOD_CHAR_TEEW =180
TCOD_CHAR_TEEE =195
TCOD_CHAR_TEEN =193
TCOD_CHAR_TEES =194
TCOD_CHAR_CROSS =197
TCOD_CHAR_DHLINE =205
TCOD_CHAR_DVLINE =186
TCOD_CHAR_DNE =187
TCOD_CHAR_DNW =201
TCOD_CHAR_DSE =188
TCOD_CHAR_DSW =200
TCOD_CHAR_DTEEW =185
TCOD_CHAR_DTEEE =204
TCOD_CHAR_DTEEN =202
TCOD_CHAR_DTEES =203
TCOD_CHAR_DCROSS =206
TCOD_CHAR_BLOCK1 =176
TCOD_CHAR_BLOCK2 =177
TCOD_CHAR_BLOCK3 =178
TCOD_CHAR_ARROW_N =24
TCOD_CHAR_ARROW_S =25
TCOD_CHAR_ARROW_E =26
TCOD_CHAR_ARROW_W =27
TCOD_CHAR_ARROW2_N =30
TCOD_CHAR_ARROW2_S =31
TCOD_CHAR_ARROW2_E =16
TCOD_CHAR_ARROW2_W =17
TCOD_CHAR_DARROW_H =29
TCOD_CHAR_DARROW_V =18
TCOD_CHAR_CHECKBOX_UNSET =224
TCOD_CHAR_CHECKBOX_SET =225
TCOD_CHAR_RADIO_UNSET =9
TCOD_CHAR_RADIO_SET =10
TCOD_CHAR_SUBP_NW =226
TCOD_CHAR_SUBP_NE =227
TCOD_CHAR_SUBP_N =228
TCOD_CHAR_SUBP_SE =229
TCOD_CHAR_SUBP_DIAG =230
TCOD_CHAR_SUBP_E =231
TCOD_CHAR_SUBP_SW =232
TCOD_CHAR_SMILIE = 1
TCOD_CHAR_SMILIE_INV = 2
TCOD_CHAR_HEART = 3
TCOD_CHAR_DIAMOND = 4
TCOD_CHAR_CLUB = 5
TCOD_CHAR_SPADE = 6
TCOD_CHAR_BULLET = 7
TCOD_CHAR_BULLET_INV = 8
TCOD_CHAR_MALE = 11
TCOD_CHAR_FEMALE = 12
TCOD_CHAR_NOTE = 13
TCOD_CHAR_NOTE_DOUBLE = 14
TCOD_CHAR_LIGHT = 15
TCOD_CHAR_EXCLAM_DOUBLE = 19
TCOD_CHAR_PILCROW = 20
TCOD_CHAR_SECTION = 21
TCOD_CHAR_POUND = 156
TCOD_CHAR_MULTIPLICATION = 158
TCOD_CHAR_FUNCTION = 159
TCOD_CHAR_RESERVED = 169
TCOD_CHAR_HALF = 171
TCOD_CHAR_ONE_QUARTER = 172
TCOD_CHAR_COPYRIGHT = 184
TCOD_CHAR_CENT = 189
TCOD_CHAR_YEN = 190
TCOD_CHAR_CURRENCY = 207
TCOD_CHAR_THREE_QUARTERS = 243
TCOD_CHAR_DIVISION = 246
TCOD_CHAR_GRADE = 248
TCOD_CHAR_UMLAUT = 249
TCOD_CHAR_POW1 = 251
TCOD_CHAR_POW3 = 252
TCOD_CHAR_POW2 = 253
TCOD_CHAR_BULLET_SQUARE = 254

Flushing the root console

void TCOD_console_flush(void)

Render and present the root console to the active display.

Handling user input

Blocking user input

TCOD_key_t TCOD_console_wait_for_keypress(bool flush)

Wait for a key press event, then return it.

Do not solve input lag issues by arbitrarily dropping events!

Return
A TCOD_key_t struct with the most recent key data.
Parameters
  • flush: If 1 then the event queue will be cleared before waiting for the next event. This should always be 0.

TCOD_event_t TCOD_sys_wait_for_event(int eventMask, TCOD_key_t *key, TCOD_mouse_t *mouse, bool flush)

Wait for a specific type of event.

This function also returns when the SDL window is being closed.

Return
A TCOD_event_t flag showing which event was actually processed.
Parameters
  • eventMask: A bit-mask of TCOD_event_t flags.
  • key: Optional pointer to a TCOD_key_t struct.
  • mouse: Optional pointer to a TCOD_mouse_t struct.
  • flush: This should always be false.

Non blocking user input

TCOD_key_t TCOD_console_check_for_keypress(int flags)

Return immediately with a recently pressed key.

Return
A TCOD_key_t struct with a recently pressed key. If no event exists then the vk attribute will be TCODK_NONE
Parameters
  • flags: A TCOD_event_t bit-field, for example: TCOD_EVENT_KEY_PRESS

bool TCOD_console_is_key_pressed(TCOD_keycode_t key)
TCOD_event_t TCOD_sys_check_for_event(int eventMask, TCOD_key_t *key, TCOD_mouse_t *mouse)

Check for a specific type of event.

Return
A TCOD_event_t flag showing which event was actually processed.
Parameters
  • eventMask: A bit-mask of TCOD_event_t flags.
  • key: Optional pointer to a TCOD_key_t struct.
  • mouse: Optional pointer to a TCOD_mouse_t struct.
  • flush: This should always be false.

TCOD_mouse_t TCOD_mouse_get_status(void)

Return a copy of the current mouse state.

Keyboard event structure

enum TCOD_key_status_t

Values:

TCOD_KEY_PRESSED =1
TCOD_KEY_RELEASED =2
struct TCOD_key_t

Key codes

enum TCOD_keycode_t

Values:

TCODK_NONE
TCODK_ESCAPE
TCODK_BACKSPACE
TCODK_TAB
TCODK_ENTER
TCODK_SHIFT
TCODK_CONTROL
TCODK_ALT
TCODK_PAUSE
TCODK_CAPSLOCK
TCODK_PAGEUP
TCODK_PAGEDOWN
TCODK_END
TCODK_HOME
TCODK_UP
TCODK_LEFT
TCODK_RIGHT
TCODK_DOWN
TCODK_PRINTSCREEN
TCODK_INSERT
TCODK_DELETE
TCODK_LWIN
TCODK_RWIN
TCODK_APPS
TCODK_0
TCODK_1
TCODK_2
TCODK_3
TCODK_4
TCODK_5
TCODK_6
TCODK_7
TCODK_8
TCODK_9
TCODK_KP0
TCODK_KP1
TCODK_KP2
TCODK_KP3
TCODK_KP4
TCODK_KP5
TCODK_KP6
TCODK_KP7
TCODK_KP8
TCODK_KP9
TCODK_KPADD
TCODK_KPSUB
TCODK_KPDIV
TCODK_KPMUL
TCODK_KPDEC
TCODK_KPENTER
TCODK_F1
TCODK_F2
TCODK_F3
TCODK_F4
TCODK_F5
TCODK_F6
TCODK_F7
TCODK_F8
TCODK_F9
TCODK_F10
TCODK_F11
TCODK_F12
TCODK_NUMLOCK
TCODK_SCROLLLOCK
TCODK_SPACE
TCODK_CHAR
TCODK_TEXT

Mouse event structure

struct TCOD_mouse_t

Using off-screen consoles

Creating and deleting off-screen consoles

TCOD_console_t TCOD_console_new(int w, int h)

Return a new console with a specific number of columns and rows.

Return
A pointer to the new console, or NULL on error.
Parameters
  • w: Number of columns.
  • h: Number of columns.

void TCOD_console_delete(TCOD_console_t console)

Creating an off-screen console from any .asc/.apf/.xp file

TCOD_console_t TCOD_console_from_file(const char *filename)

Loading an offscreen console from a .asc file

bool TCOD_console_load_asc(TCOD_console_t con, const char *filename)

Loading an offscreen console from a .apf file

bool TCOD_console_load_apf(TCOD_console_t con, const char *filename)

Saving a console to a .asc file

bool TCOD_console_save_asc(TCOD_console_t con, const char *filename)

Saving a console to a .apf file

bool TCOD_console_save_apf(TCOD_console_t con, const char *filename)

Working with REXPaint .xp files

REXPaint gives special treatment to tiles with a magic pink {255, 0, 255} background color. You can processes this effect manually or by setting TCOD_console_set_key_color() to TCOD_fuchsia.

libtcodpy.console_from_xp(filename)
TCODLIB_CAPI TCOD_console_t TCOD_console_from_xp(const char * filename)

Return a new console loaded from a REXPaint .xp file.

Return
A new TCOD_console_t object. New consoles will need to be deleted with a call to :any:TCOD_console_delete. Returns NULL on an error.
Parameters
  • filename: A path to the REXPaint file.

libtcodpy.console_load_xp(con, filename)
bool TCODConsole::loadXp(const char *filename)
TCODLIB_CAPI bool TCOD_console_load_xp(TCOD_Console * con, const char * filename)
libtcodpy.console_save_xp(con, filename, compress_level=-1)
bool TCODConsole::saveXp(const char *filename, int compress_level)
TCODLIB_CAPI bool TCOD_console_save_xp(const TCOD_Console * con, const char * filename, int compress_level)

Save a console as a REXPaint .xp file.

The REXPaint format can support a 1:1 copy of a libtcod console.

Return
true when the file is saved succesfully, or false when an issue is detected.
Parameters
  • con: The console instance to save.
  • filename: The filepath to save to.
  • compress_level: A zlib compression level, from 0 to 9. 1=fast, 6=balanced, 9=slowest, 0=uncompressed.

libtcodpy.console_list_from_xp(filename)
TCODLIB_CAPI TCOD_list_t TCOD_console_list_from_xp(const char * filename)

Return a list of consoles from a REXPaint file.

This function can load a REXPaint file with variable layer shapes, which would cause issues for a function like TCOD_console_list_from_xp.

Return
Returns a TCOD_list_t of TCOD_console_t objects. Or NULL on an error. You will need to delete this list and each console individually.
Parameters
  • filename: A path to the REXPaint file.

libtcodpy.console_list_save_xp(console_list, filename, compress_level)
TCODLIB_CAPI bool TCOD_console_list_save_xp(TCOD_list_t console_list, const char * filename, int compress_level)

Save a list of consoles to a REXPaint file.

This function can save any number of layers with multiple different sizes.

Return
true on success, false on a failure such as not being able to write to the path provided.
Parameters
  • console_list: A TCOD_list_t of TCOD_console_t objects.
  • filename: Path to save to.
  • compress_level: zlib compression level.

The REXPaint tool only supports files with up to 9 layers where all layers are the same size.

Blitting a console on another one

void TCOD_console_blit(TCOD_console_t src, int xSrc, int ySrc, int wSrc, int hSrc, TCOD_console_t dst, int xDst, int yDst, float foreground_alpha, float background_alpha)

Define a blit-transparent color

void TCOD_console_set_key_color(TCOD_console_t con, TCOD_color_t col)