Console

Note

These docs are incomplete. Several functions and features are better documented by the older 1.6.4 docs which you can find here.

Initializing the console

Creating the game window

enum TCOD_renderer_t

The available renderers.

Values:

enumerator TCOD_RENDERER_GLSL

Alias for TCOD_RENDERER_OPENGL2.

enumerator TCOD_RENDERER_OPENGL

An OpenGL 1.1 implementation.

Performs worse than TCOD_RENDERER_GLSL without many benefits.

enumerator TCOD_RENDERER_SDL

A software based renderer.

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

enumerator TCOD_RENDERER_SDL2

A new SDL2 renderer.

Allows the window to be resized.

You may set SDL_HINT_RENDER_SCALE_QUALITY to determine the tileset upscaling filter. Either nearest or linear. The hint will only take effect if it’s set before this renderer is created.

New in version 1.8.

enumerator TCOD_RENDERER_OPENGL2

A new OpenGL 2.0 core renderer.

Allows the window to be resized.

You may set SDL_HINT_RENDER_SCALE_QUALITY to determine the tileset upscaling filter. Either nearest or linear. The hint will take effect on the next frame.

New in version 1.9.

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

Changed in version 1.16: Now checks the SDL_HINT_RENDER_SCALE_QUALITY hint.

enumerator TCOD_NB_RENDERERS
TCOD_Error 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.

Afterwards TCOD_quit must be called before the program exits.

Returns 0 on success, or -1 on an error, you can check the error with TCOD_sys_get_error()

renderer and vsync settings can be overridden by the TCOD_RENDERER or TCOD_VSYNC environment variables.

Valid case-sensitive options for TCOD_RENDERER are:

  • sdl

  • opengl

  • glsl

  • sdl2

  • opengl2

Valid options for TCOD_VSYNC are 0 or 1.

Changed in version 1.12: Now returns -1 on error instead of crashing.

Changed in version 1.13: Added the TCOD_RENDERER and TCOD_VSYNC overrides.

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.

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:

enumerator TCOD_FONT_LAYOUT_ASCII_INCOL

Tiles are arranged in column-major order.

0 3 6 1 4 7 2 5 8

enumerator TCOD_FONT_LAYOUT_ASCII_INROW

Tiles are arranged in row-major order.

0 1 2 3 4 5 6 7 8

enumerator TCOD_FONT_TYPE_GREYSCALE

Converts all tiles into a monochrome gradient.

enumerator TCOD_FONT_TYPE_GRAYSCALE
enumerator TCOD_FONT_LAYOUT_TCOD

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

enumerator TCOD_FONT_LAYOUT_CP437

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

New in version 1.10.

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

Returns 0 on success, or -1 on an error, you can check the error with TCOD_sys_get_error()

Changed in version 1.12: Now returns -1 on error instead of crashing.

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

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.

bool TCOD_console_is_fullscreen(void)

Return true if the display is full-screen.

Communicate with the window manager

bool TCOD_console_is_active(void)

Return true if the window has keyboard focus.

bool TCOD_console_has_mouse_focus(void)

Return true if the window has mouse focus.

bool TCOD_console_is_window_closed(void)

Return true if the window is closing.

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 *con, TCOD_color_t col)
void TCOD_console_set_default_background(TCOD_Console *con, TCOD_color_t col)
void TCOD_console_set_background_flag(TCOD_Console *con, TCOD_bkgnd_flag_t flag)

Set a consoles default background flag.

Parameters

  • con – A console pointer.

  • flag – One of TCOD_bkgnd_flag_t.

void TCOD_console_clear(TCOD_Console *con)

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

void TCOD_console_put_char(TCOD_Console *con, int x, int y, int c, TCOD_bkgnd_flag_t flag)

Draw a character on a console using the default 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.

  • flag – A TCOD_bkgnd_flag_t flag.

void TCOD_console_put_char_ex(TCOD_Console *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 *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 *con, int x, int y, TCOD_color_t col)

Change the foreground color of a console tile.

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.

  • col – The foreground color to set.

void TCOD_console_set_char_background(TCOD_Console *con, int x, int y, TCOD_color_t col, TCOD_bkgnd_flag_t flag)

Blend a background color onto a console tile.

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.

  • col – The background color to blend.

  • flag – The blend mode to use.

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.

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.

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

Background color blend modes.

Values:

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

String printing alignment

enum TCOD_alignment_t

Print justification options.

Values:

enumerator TCOD_LEFT
enumerator TCOD_RIGHT
enumerator TCOD_CENTER
void TCOD_console_set_alignment(TCOD_Console *con, TCOD_alignment_t alignment)

Set a consoles default alignment.

Parameters

  • con – A console pointer.

  • alignment – One of TCOD_alignment_t

TCOD_alignment_t TCOD_console_get_alignment(TCOD_Console *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.

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.

Returns

The number of lines actually printed.

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.

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.

Returns

The number of lines actually printed.

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.

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.

Returns

The number of lines that would have been printed.

Printing functions using UTF-8

TCOD_Error TCOD_console_printf(TCOD_Console *con, int x, int y, const char *fmt, ...)

Format and print a UTF-8 string to a console.

New in version 1.8.

Changed in version 1.16: Now returns a negative error code on failure.

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

Format and print a UTF-8 string to a console.

New in version 1.8.

Changed in version 1.16: Now returns a negative error code on failure.

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

Format and print a UTF-8 string to a console.

New in version 1.8.

Changed in version 1.16: Now returns a negative error code on failure.

int TCOD_console_printf_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, ...)

Format and print a UTF-8 string to a console.

New in version 1.8.

Changed in version 1.16: Now returns a negative error code on failure.

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

Return the number of lines that would be printed by this formatted string.

New in version 1.8.

Changed in version 1.16: Now returns a negative error code on failure.

TCOD_Error TCOD_console_printf_frame(struct TCOD_Console *con, int x, int y, int w, int h, int empty, TCOD_bkgnd_flag_t flag, const char *fmt, ...)

Print a framed and optionally titled region to a console, using default colors and alignment.

This function uses Unicode box-drawing characters and a UTF-8 formatted string.

New in version 1.8.

Changed in version 1.16: Now returns a negative error code on failure.

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.

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.

Returns

The character code.

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.

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.

Returns

A TCOD_color_t struct with a copy of the foreground color.

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.

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.

Returns

A TCOD_color_t struct with a copy of the background color.

TCOD_color_t TCOD_console_get_default_foreground(TCOD_Console *con)
TCOD_color_t TCOD_console_get_default_background(TCOD_Console *con)
TCOD_bkgnd_flag_t TCOD_console_get_background_flag(TCOD_Console *con)

Return a consoles default background flag.

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.

Returns

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.

Returns

The current fading color.

ASCII constants

enum TCOD_chars_t

Values:

enumerator TCOD_CHAR_HLINE
enumerator TCOD_CHAR_VLINE
enumerator TCOD_CHAR_NE
enumerator TCOD_CHAR_NW
enumerator TCOD_CHAR_SE
enumerator TCOD_CHAR_SW
enumerator TCOD_CHAR_TEEW
enumerator TCOD_CHAR_TEEE
enumerator TCOD_CHAR_TEEN
enumerator TCOD_CHAR_TEES
enumerator TCOD_CHAR_CROSS
enumerator TCOD_CHAR_DHLINE
enumerator TCOD_CHAR_DVLINE
enumerator TCOD_CHAR_DNE
enumerator TCOD_CHAR_DNW
enumerator TCOD_CHAR_DSE
enumerator TCOD_CHAR_DSW
enumerator TCOD_CHAR_DTEEW
enumerator TCOD_CHAR_DTEEE
enumerator TCOD_CHAR_DTEEN
enumerator TCOD_CHAR_DTEES
enumerator TCOD_CHAR_DCROSS
enumerator TCOD_CHAR_BLOCK1
enumerator TCOD_CHAR_BLOCK2
enumerator TCOD_CHAR_BLOCK3
enumerator TCOD_CHAR_ARROW_N
enumerator TCOD_CHAR_ARROW_S
enumerator TCOD_CHAR_ARROW_E
enumerator TCOD_CHAR_ARROW_W
enumerator TCOD_CHAR_ARROW2_N
enumerator TCOD_CHAR_ARROW2_S
enumerator TCOD_CHAR_ARROW2_E
enumerator TCOD_CHAR_ARROW2_W
enumerator TCOD_CHAR_DARROW_H
enumerator TCOD_CHAR_DARROW_V
enumerator TCOD_CHAR_CHECKBOX_UNSET
enumerator TCOD_CHAR_CHECKBOX_SET
enumerator TCOD_CHAR_RADIO_UNSET
enumerator TCOD_CHAR_RADIO_SET
enumerator TCOD_CHAR_SUBP_NW
enumerator TCOD_CHAR_SUBP_NE
enumerator TCOD_CHAR_SUBP_N
enumerator TCOD_CHAR_SUBP_SE
enumerator TCOD_CHAR_SUBP_DIAG
enumerator TCOD_CHAR_SUBP_E
enumerator TCOD_CHAR_SUBP_SW
enumerator TCOD_CHAR_SMILIE
enumerator TCOD_CHAR_SMILIE_INV
enumerator TCOD_CHAR_HEART
enumerator TCOD_CHAR_DIAMOND
enumerator TCOD_CHAR_CLUB
enumerator TCOD_CHAR_SPADE
enumerator TCOD_CHAR_BULLET
enumerator TCOD_CHAR_BULLET_INV
enumerator TCOD_CHAR_MALE
enumerator TCOD_CHAR_FEMALE
enumerator TCOD_CHAR_NOTE
enumerator TCOD_CHAR_NOTE_DOUBLE
enumerator TCOD_CHAR_LIGHT
enumerator TCOD_CHAR_EXCLAM_DOUBLE
enumerator TCOD_CHAR_PILCROW
enumerator TCOD_CHAR_SECTION
enumerator TCOD_CHAR_POUND
enumerator TCOD_CHAR_MULTIPLICATION
enumerator TCOD_CHAR_FUNCTION
enumerator TCOD_CHAR_RESERVED
enumerator TCOD_CHAR_HALF
enumerator TCOD_CHAR_ONE_QUARTER
enumerator TCOD_CHAR_COPYRIGHT
enumerator TCOD_CHAR_CENT
enumerator TCOD_CHAR_YEN
enumerator TCOD_CHAR_CURRENCY
enumerator TCOD_CHAR_THREE_QUARTERS
enumerator TCOD_CHAR_DIVISION
enumerator TCOD_CHAR_GRADE
enumerator TCOD_CHAR_UMLAUT
enumerator TCOD_CHAR_POW1
enumerator TCOD_CHAR_POW3
enumerator TCOD_CHAR_POW2
enumerator TCOD_CHAR_BULLET_SQUARE

Flushing the root console

TCOD_Error TCOD_console_flush(void)

Render and present the root console to the active display.

int TCOD_sys_accumulate_console(const TCOD_Console *console)

Render a console over the display.

console can be any size, the active render will try to scale it to fit the screen.

The function will only work for the SDL2/OPENGL2 renderers.

Unlike TCOD_console_flush() this will not present the display. You will need to do that manually, likely with the SDL API.

Returns 0 on success, or a negative number on a failure such as the incorrect renderer being active.

New in version 1.11.

See also

TCOD_sys_get_sdl_window() TCOD_sys_get_sdl_renderer()

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!

Parameters

flush – If 1 then the event queue will be cleared before waiting for the next event. This should always be 0.

Returns

A TCOD_key_t struct with the most recent key data.

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.

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.

Returns

A TCOD_event_t flag showing which event was actually processed.

Non blocking user input

TCOD_key_t TCOD_console_check_for_keypress(int flags)

Return immediately with a recently pressed key.

Parameters

flags – A TCOD_event_t bit-field, for example: TCOD_EVENT_KEY_PRESS

Returns

A TCOD_key_t struct with a recently pressed key. If no event exists then the vk attribute will be TCODK_NONE

bool TCOD_console_is_key_pressed(TCOD_keycode_t key)

Return True if the libtcod keycode is held.

Deprecated since version 1.16: You should instead use SDL_GetKeyboardState to check if keys are held.

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.

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.

Returns

A TCOD_event_t flag showing which event was actually processed.

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:

enumerator TCOD_KEY_PRESSED
enumerator TCOD_KEY_RELEASED
struct TCOD_key_t

Key codes

enum TCOD_keycode_t

Values:

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

Mouse event structure

struct TCOD_mouse_t

Events from SDL2

TCOD_event_t tcod::sdl2::process_event(const union SDL_Event &in, TCOD_key_t &out) noexcept

Parse an SDL_Event into a key event and return the relevant TCOD_event_t.

Returns TCOD_EVENT_NONE if the event wasn’t keyboard related.

New in version 1.11.

TCOD_event_t TCOD_sys_process_key_event(const union SDL_Event *in, TCOD_key_t *out)

Parse an SDL_Event into a key event and return the relevant TCOD_event_t.

Returns TCOD_EVENT_NONE if the event wasn’t keyboard related.

New in version 1.11.

TCOD_event_t tcod::sdl2::process_event(const union SDL_Event &in, TCOD_mouse_t &out) noexcept

Parse an SDL_Event into a mouse event and return the relevant TCOD_event_t.

Returns TCOD_EVENT_NONE if the event wasn’t mouse related.

New in version 1.11.

TCOD_event_t TCOD_sys_process_mouse_event(const union SDL_Event *in, TCOD_mouse_t *out)

Parse an SDL_Event into a mouse event and return the relevant TCOD_event_t.

Returns TCOD_EVENT_NONE if the event wasn’t mouse related.

New in version 1.11.

Using off-screen consoles

Creating and deleting off-screen consoles

TCOD_Console *TCOD_console_new(int w, int h)

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

Parameters

  • w – Number of columns.

  • h – Number of columns.

Returns

A pointer to the new console, or NULL on error.

void TCOD_console_delete(TCOD_Console *console)

Delete a console.

If the console being deleted is the root console, then the display will be uninitialized.

Parameters

con – A console pointer.

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)
TCOD_console_t TCOD_console_from_xp(const char *filename)

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

Parameters

[in] filename – A path to the REXPaint file.

Returns

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.

libtcodpy.console_load_xp(con, filename)
bool TCODConsole::loadXp(const char *filename)
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)
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.

Parameters

  • [in] con – The console instance to save.

  • [in] filename – The filepath to save to.

  • [in] compress_level – A zlib compression level, from 0 to 9. 1=fast, 6=balanced, 9=slowest, 0=uncompressed.

Returns

true when the file is saved successfully, or false when an issue is detected.

libtcodpy.console_list_from_xp(filename)
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.

Parameters

[in] filename – A path to the REXPaint file.

Returns

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.

libtcodpy.console_list_save_xp(console_list, filename, compress_level)
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.

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

Parameters

  • [in] console_list – A TCOD_list_t of TCOD_console_t objects.

  • [in] filename – Path to save to.

  • [in] compress_level – zlib compression level.

Returns

true on success, false on a failure such as not being able to write to the path provided.

Blitting a console on another one

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

Blit from one console to another.

If the source console has a key color, this function will use it.

Changed in version 1.16: Blits can now handle per-cell alpha transparency.

Parameters

  • srcCon – Pointer to the source console.

  • xSrc – The left region of the source console to blit from.

  • ySrc – The top region of the source console to blit from.

  • wSrc – The width of the region to blit from. If 0 then it will fill to the maximum width.

  • hSrc – The height of the region to blit from. If 0 then it will fill to the maximum height.

  • dstCon – Pointer to the destination console.

  • xDst – The left corner to blit onto the destination console.

  • yDst – The top corner to blit onto the destination console.

  • foreground_alpha – Foreground blending alpha.

  • background_alpha – Background blending alpha.

Define a blit-transparent color

void TCOD_console_set_key_color(TCOD_Console *con, TCOD_color_t col)