NAME
TCOD::Console - Terminal emulator for rendering game screens
SYNOPSIS
use TCOD;
TCOD::Console::init_root( 10, 10, 'Test', 0, TCOD::RENDERER_SDL );
my $start = TCOD::Console->new( 10, 10 );
$start->print( 1, 1, 'X' );
my $end = TCOD::Console->new( 10, 10 );
$end->print( 8, 8, 'X' );
for ( 1 .. 255 ) {
$start->blit( 0, 0, 10, 10, undef, 0, 0, 1, 1 );
$end->blit( 0, 0, 10, 10, undef, 0, 0, $_ / 255, $_ / 255 );
TCOD::Console::flush;
TCOD::Sys::sleep_milli(5);
}DESCRIPTION
This class represents a terminal emulator for rendering text-based games.
METHODS
new
$console = TCOD::Console->new( $width, $height );You can create as many off-screen consoles as you want by using this function. You can draw on them as you would do with the root console, but you cannot flush them to the screen. Else, you can blit them on other consoles, including the root console. See blit.
This function returns a TCOD::Console object that can be used as a target in most console drawing functions.
from_file
$console = TCOD::Console->from_file( $path );You can create an offscreen console from a .asc or .apf file created with Ascii Paint with this constructor
save_asc
$bool = $console->save_asc( $path );You can save data from a console to Ascii Paint format with this function. The function returns false if it couldn't write the file. This is the only ASC function that works also with the root console!
save_apf
$bool = $console->save_apf( $path );You can save data from a console to Ascii Paint format with this function. The function returns false if it couldn't write the file. This is the only ASC function that works also with the root console!
blit
$console->blit(
$source_x,
$source_y,
$source_width,
$source_height,
$target,
$target_x,
$target_y,
$foreground_alpha,
$background_alpha,
);This function allows you to blit a rectangular area of the source console at a specific position on a destination console. It can also simulate alpha transparency with foreground and background alpha parameters.
set_key_color
$console->set_key_color( $color );This function defines a transparent background color for this console. All cells with this background color are ignored when calling blit. You can use it to blit only some parts of the console.
clear
$console->clear;Reset all the cells in a console. After calling this method, all cells will have their foreground and background colors set to the console's current defaults (see set_default_foreground and friends), and their ASCII code set to 32 (a blank space).
get_width
$width = $console->get_width;Get the width of the console.
get_height
$height = $console->get_height;Get the height of the console.
set_background_flag
$console->set_background_flag( $flag );Set the background mode for the console. The value of $flag should be a member of the BackgroundFlag enum, determines how the background color is modified.
get_background_flag
$flag = $console->get_background_flag;Get the console's default background flag. It will be a value from the BackgroundFlag enum.
set_alignment
$console->set_alignment( $alignment );Set the alignment for the console. The value of $alignment should be a member of the Alignment enum.
get_alignment
$alignment = $console->get_alignment;Get the console's default alignment flag. It will be a value from the Alignment enum.
set_char_background
$console->set_char_background( $x, $y, $color, $flag );Set the background color of a cell, leaving other properties (foreground color and ASCII code) unchanged. The value of $flag, which should be a member of the BackgroundFlag enum, determines how the background color is modified.
get_char_background
$color = $cosole->get_char_background( $x, $y );Get the background color of a cell.
set_char_foreground
$console->set_char_foreground( $x, $y, $color, $flag );Set the foreground color of a cell, leaving other properties (background color and ASCII code) unchanged. The value of $flag, which should be a member of the BackgroundFlag enum, determines how the background color is modified.
get_char_foreground
$color = $cosole->get_char_foreground( $x, $y );Get the foreground color of a cell.
set_default_background
$console->set_default_background( $color );Change the default background color for a console. This is used by several of the drawing functions described in this document.
get_default_background
$color = $console->get_default_background;Get the default background color for a console. This is used by several of the drawing functions described in this document.
set_default_foreground
$console->set_default_foreground( $color );Change the default foreground color for a console. This is used by several of the drawing functions described in this document.
get_default_foreground
$color = $console->get_default_foreground;Get the default foreground color for a console. This is used by several of the drawing functions described in this document.
set_char
$console->set_char( $x, $y, $char_code );Set the character at the specified coordinate to the specified character without changing its colors.
The character is passed as an integer code, like one returned by ord or one of the values in the Char enum.
get_char
$char_code = $console->get_char( $x, $y );Return the character at the specified position in the console.
The character is returned as an integer code, like one returned by ord or one of the values in the Char enum.
put_char
$console->put_char( $x, $y, $char_code, $background_flag );Draw a character on a console using the default colors.
The character is passed as an integer code, like one returned by ord or one of the values in the Char enum.
The value in $background_flag determines the behaviour of the background, and should be one of the values in the BackgroundFlag enum.
put_char_ex
$console->put_char_ex(
$x,
$y,
$char_code,
$foreground_color,
$background_color,
);Draw a character on a console using the default colors.
The character is passed as an integer code, like one returned by ord or one of the values in the Char enum.
$console->print( $x, $y, $str );
$console->print_ex( $x, $y, $flag, $align, $str );
$console->print_rect( $x, $y, $w, $h, $str );
$console->print_rect_ex( $x, $y, $w, $h, $flag, $align, $str );
$console->print_utf( $x, $y, $str );
$console->print_ex_utf( $x, $y, $flag, $align, $str );
$console->print_rect_utf( $x, $y, $w, $h, $str );
$console->print_rect_ex_utf( $x, $y, $w, $h, $flag, $align, $str );Print a string to the console. The different flavours of this function allow you to set the position of the text to print ( using the $x and $y coordinates), the dimensions of a box to print it in when it should wrap (with $w and $h), the background flag to determine the behaviour of the background (with $flag, which must be a value in the BackgroundFlag enum), the alignment of the text (with $align, which must be a value in the Alignment enum).
In all cases, the final value is a string to print. To print UTF-8 strings, use "decode" in Encode and use the functions ending in _utf.
The string can contain the %c sequence to work as a control code placeholders, which will be replaced with any control codes passed in as additional arguments to these functions, in a manner similar to the printf family of functions.
Note that, for now, these Perl bindings allow only two such additional codes.
See set_color_control for how to define the value of these codes.
print_frame
$console->print_frame( $x, $y, $w, $h, $clear, $flag, $str );This function calls the rect function using the supplied parameters, then draws a rectangle with the console's default foreground color.
The value of $str is printed on the top of the rectangle, using inverted colors.
get_height_rect
$height = $console->get_height_rect( $x, $y, $w, $h, $string );
$height = $console->get_height_rect_utf( $x, $y, $w, $h, $string );Returns the expected height of an autowrapped string without actually printing the string with one of the print_rect family of functions.
rect
$console->rect( $x, $y, $w, $h, $clear, $flag );Fills a rectngle in the console with the specified position and dimensions.
The background color for every cell inside the rectangle will be adjusted with the default background color of the console (the value in $flag will determine what effect this wil have on the cell's color).
If $clear is set to a true value, their ASCII code will be set to 32 (space).
hline
$console->hline( $x, $y, $length, $flag );Draws a horizontal line in the console, using ASCII code 196 (TCOD::CHAR_HLINE), and the console's default background/foreground colors.
vline
$console->vline( $x, $y, $length, $flag );Draws an vertical line in the console, using ASCII code 179 (TCOD::CHAR_VLINE), and the console's default background/foreground colors.
FUNCTIONS
init_root
TCOD::Console::init_root(
$width,
$height,
$title,
$fullscreen,
$renderer,
);Initialise the global game window.
The width and height parameters specify the dimensions of the screen in characters. The size of the window in pixels will depend on the font used. The default font uses characters that are 8x8 pixels. See set_custom_font for how to change this font after creation.
The title will be displayed on top of the window, except when in fullscreen mode. See set_window_title for how to change this after creation.
The window will be created in fullscreen if the value of $fullscreen is true. See set_fullscreen and is_fullscreen for ways to modify this after creation.
The renderer will be one of the elements of the Renderer enum. If you select a renderer that is not supported by the player's machine, the underlying library will scan the lower renderers until it finds a working one.
On recent video cards, GLSL (enabled with TCOD::RENDERER_GLSL) results in up to 900% increase of framerates in the true color sample compared to SDL renderer.
Whatever renderer you use, it can always be overridden by the player through the libtcod.cfg file.
You can dynamically change the renderer after calling this function with TCOD::Sys::set_renderer. You can also read the current renderer with TCOD::Sys::get_renderer. This might be different from the one you set when calling this function in case it's not supported on the player's computer.
set_custom_font
TCOD::Console::set_custom_font(
$string,
$flags,
$horizontal_chars,
$vertical_chars,
);This function allows you to use a bitmap font (PNG or BMP) with custom character size or layout.
It should be called before initializing the root console with init_root.
Once this function is called, you can define your own custom mappings using mapping functions
The value in $flags will be a combination of a layout and a type from the FontFlag enum. The last two parameters determine the number of characters in the font along both axes. If set to 0, these will be deduced from the layout flag.
map_ascii_code_to_font
TCOD::Console::map_ascii_code_to_font( $code, $x, $y );Maps a single ASCII code to a character in the current font.
map_ascii_codes_to_font
TCOD::Console::map_ascii_codes_to_font(
$range_start,
$range_length,
$x,
$y,
);Maps consecutive ASCII codes to characters in the current font. The coordinate provided (in characters) corresponds to the first character in the range.
map_string_to_font
TCOD::Console::map_string_to_font( $string, $x, $y );Maps the ASCII codes in a string to consecutive characters in the current font. The coordinate provided (in characters) corresponds to the first character in the range.
is_fullscreen
TCOD::Console::is_fullscreen;Returns true if the current mode is fullscreen.
set_fullscreen
TCOD::Console::set_fullscreen( $bool );Enable or disable fullscreen mode.
set_window_title
TCOD::Console::set_window_title( $title );This function dynamically changes the title of the game window.
is_window_closed
$bool = TCOD::Console::is_window_closed;When you start the program, this returns false. Once a "close window" event has been sent by the window manager, it will always return true. You're supposed to cleanly exit the game.
has_mouse_focus
$bool = TCOD::Console::has_mouse_focus;Returns true if the mouse cursor is inside the game window area and the game window is the active application.
is_active
$bool = TCOD::Console::is_active;Returns false if the game window is not the active window or is iconified.
credits
TCOD::Console::credits;Render a credits screen with the message "Powered by libtcod $VERSION", with the current libtcod version you are running. This can be shown during startup by calling after init_root.
The credits screen can be skipped by pressing any key.
credits_render
$bool = TCOD::Console::credits_render( $x, $y, $alpha );Render the credits message on top of an existing screen at the specified coordinates. If $alpha is set to a true value, the credits will be rendered transparently on the existing screen. For this to work, this function must be called between your screen rendering code and the console flush.
Returns true when the credits screen is finished.
credits_reset
TCOD::Console::credits_reset;When using credits_render, you can restart the credits animation from the beginning before it's finished by calling this function.
flush
TCOD::Console::flush;Once the root console is initialized, you can use one of the printing functions to change the background colors, the foreground colors or the ASCII characters on the console.
Once you've finished rendering the root console, you have to actually apply the updates to the screen with this function.
set_fade
TCOD::Console::set_fade( $fade, $color );This function defines the fading parameters, allowing you to fade the game screen to/from a color. Once they are defined, the fading parameters are valid until changed (with another call to this function). You don't have to call this function for each rendered frame.
get_fade
$fade = TCOD::Console::get_fade;Get the current fade amount. See set_fade for how this is set.
get_fading_color
$color = TCOD::Console::get_fading_color;Get the current fade color. See set_fade for how this is set.
set_color_control
TCOD::Console::set_color_control(
$code,
$foreground_color,
$background_color,
);If you want to draw a string using different colors for each word, the basic solution is to call a string printing function several times, changing the default colors between each call.
An arguably simpler way to do this is to use "color control codes" in your string, which allows you to draw a string using different colors in a single call.
A color control code is associated with a foreground and background color set. If you insert this code in your string, the next characters will use the colors associated with the color control code.
There are 5 predefined color control codes:
TCOD::COLCTRL_1
TCOD::COLCTRL_2
TCOD::COLCTRL_3
TCOD::COLCTRL_4
TCOD::COLCTRL_5
This function allows you to associate a control code to a color set.
To go back to the console's default colors, insert in your string the color stop control code: TCOD::COLCTRL_STOP.
You can also use any color without assigning it to a control code, using the generic control codes: TCOD::COLCTRL_FORE_RGB and TCOD::COLCTRL_BACK_RGB.
These controls respectively change the foreground and background color used to print the string characters. In the string, you must insert the red, green, and blue components of the color as numbers between 1 and 255 immediately after this code. Note that using 0 in this context is not allowed, because it represents the end of the string in C/C++.
check_for_keypress
# Deprecated
$key = TCOD::Console::check_for_keypress( $mask );Return immediately with a TCOD::Key populated with data from a recently pressed key.
The current recommendation, however, is to use SDL functions directly to check the keyboard state. Consider that option if available.
is_key_pressed
# Deprecated
$bool = TCOD::Console::is_key_pressed( $keycode );Given a keycode from the Keycode enum, this function returns true if the key is currently pressed.
A better way to check for user input is to use TCOD::Sys::check_for_event.
The current best recommendation, however, is to use SDL functions directly to check the keyboard state. Consider that option if available.
SEE ALSO
COPYRIGHT AND LICENSE
Copyright 2021 José Joaquín Atria
This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.