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_NB_RENDERERS¶

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.

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.

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¶

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_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)¶

Set a consoles default background flag.

Parameters

con: A console pointer.
flag: One of TCOD_bkgnd_flag_t.

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

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_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)¶

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_t 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_t 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_t 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_t 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)¶

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_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¶

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

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

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.

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.

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.

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

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)¶: 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.

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

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.

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

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.

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

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

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

Blit from one console to another.

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

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_t con, TCOD_color_t col)¶

Console¶

Initializing the console¶

Creating the game window¶

Using a custom bitmap font¶

Using custom characters mapping¶

Fullscreen mode¶

Communicate with the window manager¶

libtcod’s Credits¶

Drawing on the root console¶

Basic printing functions¶

Background effect flags¶

String printing alignment¶

Printing functions using 8-bit encodings¶

Printing functions using UTF-8¶

Printing functions using wchar_t¶

Reading the content of the console¶

Screen fading functions¶

ASCII constants¶

Flushing the root console¶

Handling user input¶

Blocking user input¶

Non blocking user input¶

Keyboard event structure¶

Key codes¶

Mouse event structure¶

Using off-screen consoles¶

Creating and deleting off-screen consoles¶

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

Loading an offscreen console from a .asc file¶

Loading an offscreen console from a .apf file¶

Saving a console to a .asc file¶

Saving a console to a .apf file¶

Working with REXPaint .xp files¶

Blitting a console on another one¶

Define a blit-transparent color¶

Working with REXPaint `.xp` files¶