# NAME TCOD - FFI bindings for libtcod # SYNOPSIS use TCOD; use File::Share 'dist_file'; use constant { WIDTH => 80, HEIGHT => 60, }; my $tileset = TCOD::Tileset->load_tilesheet( path => dist_file( TCOD => 'fonts/dejavu10x10_gs_tc.png' ), columns => 32, rows => 8, charmap => TCOD::CHARMAP_TCOD, ); my $context = TCOD::Context->new( columns => WIDTH, rows => HEIGHT, tileset => $tileset, ); my $console = $context->new_console; while (1) { $console->clear; $console->print( 0, 0, 'Hello World!' ); $context->present( $console ); my $iter = TCOD::Event::wait; while ( my $event = $iter->() ) { $context->convert_event($event); print $event->as_string . "\n"; exit if $event->type eq 'QUIT'; } } # DESCRIPTION TCOD offers Perl bindings to libtcod, a library for developing roguelike games. If you're getting started, see [TCOD::Context](https://metacpan.org/pod/TCOD%3A%3AContext) to manage rendering contexts and [TCOD::Tileset](https://metacpan.org/pod/TCOD%3A%3ATileset) to load custom fonts to display. [TCOD::Event](https://metacpan.org/pod/TCOD%3A%3AEvent) can be used to interact with input and system events. If you want to calculate line-of-sight within a map you can use [TCOD::Map](https://metacpan.org/pod/TCOD%3A%3AMap), which can also be used by [TCOD::Path](https://metacpan.org/pod/TCOD%3A%3APath) for path-finding. ## On Stability This distribution is currently **experimental**, and as such, its API might still change without warning. Any change, breaking or not, will be noted in the change log, so if you wish to use it, please pin your dependencies and make sure to check the change log before upgrading. # FUNCTIONS ## get\_error $string = TCOD::get_error; Get the current error message, if any. Some functions (eg. [TCOD::Context::new](https://metacpan.org/pod/TCOD%3A%3AContext#new) will set this string on error. When an error is indicated, you can use this method to retrieve the error. The string returned by this function is only meaningful if an error has been indicated by some other function, and will only remain meaningful until a new function that uses this mechanism is called. # ENUMS The enums listed below are available as constants like the ones defined using [constant](https://metacpan.org/pod/constant), which means the same caveats apply here. To provide introspection into the values of the enums, they are also made available as package variables with the names of each enum. This makes it possible to get the name of a value in a given enum with code like the following: say $TCOD::Alignment{ TCOD::LEFT }; # Prints 'LEFT' ## Alignment - TCOD::LEFT - TCOD::RIGHT - TCOD::CENTER ## Charmap - TCOD::CHARMAP\_TCOD - TCOD::CHARMAP\_CP437 ## Renderer - TCOD::RENDERER\_GLSL - TCOD::RENDERER\_OPENGL - TCOD::RENDERER\_SDL - TCOD::RENDERER\_SDL2 - TCOD::RENDERER\_OPENGL2 - TCOD::NB\_RENDERERS ## BackgroundFlag This flag is used by most functions that modify a cell background colour. It defines how the console's current background color is used to modify the cell's existing background color. See the documentation for [TCOD::Color](https://metacpan.org/pod/TCOD%3A%3AColor#COLOR-ARITHMETIC) for details on how color arithmetic works when referenced below. When equations are listed below, these are applied to each individual component in turn, with `new` being the component for the new color, `old` being the one for the current one, and `white` standing in for the maximum value for a color component (255). - TCOD::BKGND\_NONE The cell's background is not modified. - TCOD::BKGND\_SET The cell's background is replaced with the new color. - TCOD::BKGND\_MULTIPLY The cell's background is multiplied with the new color. - TCOD::BKGND\_LIGHTEN Each of the components of the cell's background is replaced with the respective component of the new color if it is lighter. - TCOD::BKGND\_DARKEN Each of the components of the cell's background is replaced with the respective component of the new color if it is darker. - TCOD::BKGND\_SCREEN The cell's background color is modified according to the following operation: white - ( white - old ) * ( white - new ) - TCOD::BKGND\_COLOR\_DODGE The cell's background color is modified according to the following operation: new / ( white - old ) - TCOD::BKGND\_COLOR\_BURN The cell's background color is modified according to the following operation: white - ( white - old ) / new - TCOD::BKGND\_ADD The new color is added to the cell's background. - TCOD::BKGND\_ADDALPHA Use this as a macro with a float parameter between 0 and 1. The cell's background color is modified according to the following operation: old + alpha * new - TCOD::BKGND\_BURN The cell's background color is modified according to the following operation: old + new - white - TCOD::BKGND\_OVERLAY The cell's background color is modified according to the following operation: 2 * new * old # if the component is >= 128 white - 2 * ( white - new ) * ( white - old ) # if the component is < 128 - TCOD::BKGND\_ALPHA Use this as a macro with a float parameter between 0 and 1. The cell's background color is modified according to the following operation: ( 1 - alpha ) * old + alpha * ( new - old ) - TCOD::BKGND\_DEFAULT Use the console's default background flag. See [TCOD::Console::set\_background\_flag](https://metacpan.org/pod/TCOD%3A%3AConsole#set_background_flag). ## ColorControl - TCOD::COLCTRL\_1 - TCOD::COLCTRL\_2 - TCOD::COLCTRL\_3 - TCOD::COLCTRL\_4 - TCOD::COLCTRL\_5 - TCOD::COLCTRL\_NUMBER - TCOD::COLCTRL\_FORE\_RGB - TCOD::COLCTRL\_BACK\_RGB - TCOD::COLCTRL\_STOP ## Keycode - TCOD::K\_NONE - TCOD::K\_ESCAPE - TCOD::K\_BACKSPACE - TCOD::K\_TAB - TCOD::K\_ENTER - TCOD::K\_SHIFT - TCOD::K\_CONTROL - TCOD::K\_ALT - TCOD::K\_PAUSE - TCOD::K\_CAPSLOCK - TCOD::K\_PAGEUP - TCOD::K\_PAGEDOWN - TCOD::K\_END - TCOD::K\_HOME - TCOD::K\_UP - TCOD::K\_LEFT - TCOD::K\_RIGHT - TCOD::K\_DOWN - TCOD::K\_PRINTSCREEN - TCOD::K\_INSERT - TCOD::K\_DELETE - TCOD::K\_LWIN - TCOD::K\_RWIN - TCOD::K\_APPS - TCOD::K\_0 - TCOD::K\_1 - TCOD::K\_2 - TCOD::K\_3 - TCOD::K\_4 - TCOD::K\_5 - TCOD::K\_6 - TCOD::K\_7 - TCOD::K\_8 - TCOD::K\_9 - TCOD::K\_KP0 - TCOD::K\_KP1 - TCOD::K\_KP2 - TCOD::K\_KP3 - TCOD::K\_KP4 - TCOD::K\_KP5 - TCOD::K\_KP6 - TCOD::K\_KP7 - TCOD::K\_KP8 - TCOD::K\_KP9 - TCOD::K\_KPADD - TCOD::K\_KPSUB - TCOD::K\_KPDIV - TCOD::K\_KPMUL - TCOD::K\_KPDEC - TCOD::K\_KPENTER - TCOD::K\_F1 - TCOD::K\_F2 - TCOD::K\_F3 - TCOD::K\_F4 - TCOD::K\_F5 - TCOD::K\_F6 - TCOD::K\_F7 - TCOD::K\_F8 - TCOD::K\_F9 - TCOD::K\_F10 - TCOD::K\_F11 - TCOD::K\_F12 - TCOD::K\_NUMLOCK - TCOD::K\_SCROLLLOCK - TCOD::K\_SPACE - TCOD::K\_CHAR - TCOD::K\_TEXT ## Char - TCOD::CHAR\_HLINE - TCOD::CHAR\_VLINE - TCOD::CHAR\_NE - TCOD::CHAR\_NW - TCOD::CHAR\_SE - TCOD::CHAR\_SW - TCOD::CHAR\_TEEW - TCOD::CHAR\_TEEE - TCOD::CHAR\_TEEN - TCOD::CHAR\_TEES - TCOD::CHAR\_CROSS - TCOD::CHAR\_DHLINE - TCOD::CHAR\_DVLINE - TCOD::CHAR\_DNE - TCOD::CHAR\_DNW - TCOD::CHAR\_DSE - TCOD::CHAR\_DSW - TCOD::CHAR\_DTEEW - TCOD::CHAR\_DTEEE - TCOD::CHAR\_DTEEN - TCOD::CHAR\_DTEES - TCOD::CHAR\_DCROSS - TCOD::CHAR\_BLOCK1 - TCOD::CHAR\_BLOCK2 - TCOD::CHAR\_BLOCK3 - TCOD::CHAR\_ARROW\_N - TCOD::CHAR\_ARROW\_S - TCOD::CHAR\_ARROW\_E - TCOD::CHAR\_ARROW\_W - TCOD::CHAR\_ARROW2\_N - TCOD::CHAR\_ARROW2\_S - TCOD::CHAR\_ARROW2\_E - TCOD::CHAR\_ARROW2\_W - TCOD::CHAR\_DARROW\_H - TCOD::CHAR\_DARROW\_V - TCOD::CHAR\_CHECKBOX\_UNSET - TCOD::CHAR\_CHECKBOX\_SET - TCOD::CHAR\_RADIO\_UNSET - TCOD::CHAR\_RADIO\_SET - TCOD::CHAR\_SUBP\_NW - TCOD::CHAR\_SUBP\_NE - TCOD::CHAR\_SUBP\_N - TCOD::CHAR\_SUBP\_SE - TCOD::CHAR\_SUBP\_DIAG - TCOD::CHAR\_SUBP\_E - TCOD::CHAR\_SUBP\_SW - TCOD::CHAR\_SMILIE - TCOD::CHAR\_SMILIE\_INV - TCOD::CHAR\_HEART - TCOD::CHAR\_DIAMOND - TCOD::CHAR\_CLUB - TCOD::CHAR\_SPADE - TCOD::CHAR\_BULLET - TCOD::CHAR\_BULLET\_INV - TCOD::CHAR\_MALE - TCOD::CHAR\_FEMALE - TCOD::CHAR\_NOTE - TCOD::CHAR\_NOTE\_DOUBLE - TCOD::CHAR\_LIGHT - TCOD::CHAR\_EXCLAM\_DOUBLE - TCOD::CHAR\_PILCROW - TCOD::CHAR\_SECTION - TCOD::CHAR\_POUND - TCOD::CHAR\_MULTIPLICATION - TCOD::CHAR\_FUNCTION - TCOD::CHAR\_RESERVED - TCOD::CHAR\_HALF - TCOD::CHAR\_ONE\_QUARTER - TCOD::CHAR\_COPYRIGHT - TCOD::CHAR\_CENT - TCOD::CHAR\_YEN - TCOD::CHAR\_CURRENCY - TCOD::CHAR\_THREE\_QUARTERS - TCOD::CHAR\_DIVISION - TCOD::CHAR\_GRADE - TCOD::CHAR\_UMLAUT - TCOD::CHAR\_POW1 - TCOD::CHAR\_POW3 - TCOD::CHAR\_POW2 - TCOD::CHAR\_BULLET\_SQUARE ## FontFlag - TCOD::FONT\_LAYOUT\_ASCII\_INCOL - TCOD::FONT\_LAYOUT\_ASCII\_INROW - TCOD::FONT\_TYPE\_GREYSCALE - TCOD::FONT\_TYPE\_GRAYSCALE - TCOD::FONT\_LAYOUT\_TCOD - TCOD::FONT\_LAYOUT\_CP437 ## FOV - TCOD::FOV\_BASIC - TCOD::FOV\_DIAMOND - TCOD::FOV\_SHADOW - TCOD::FOV\_PERMISSIVE\_0 - TCOD::FOV\_PERMISSIVE\_1 - TCOD::FOV\_PERMISSIVE\_2 - TCOD::FOV\_PERMISSIVE\_3 - TCOD::FOV\_PERMISSIVE\_4 - TCOD::FOV\_PERMISSIVE\_5 - TCOD::FOV\_PERMISSIVE\_6 - TCOD::FOV\_PERMISSIVE\_7 - TCOD::FOV\_PERMISSIVE\_8 - TCOD::FOV\_RESTRICTIVE - TCOD::FOV\_SYMMETRIC\_SHADOWCAST - TCOD::NB\_FOV\_ALGORITHMS ## RandomAlgo - TCOD::RNG\_MT - TCOD::RNG\_CMWC ## Distribution These values are used by [TCOD::Random](https://metacpan.org/pod/TCOD%3A%3ARandom) to generate random numbers. - TCOD::DISTRIBUTION\_LINEAR This is the default distribution. It will return a number from a range min-max. The numbers will be evenly distributed, ie, each number from the range has the exact same chance of being selected. - TCOD::DISTRIBUTION\_GAUSSIAN This distribution does not have minimum and maximum values. Instead, a mean and a standard deviation are used. The mean is the central value. It will appear with the greatest frequency. The farther away from the mean, the less the probability of appearing the possible results have. Although extreme values are possible, 99.7% of the results will be within the radius of 3 standard deviations from the mean. So, if the mean is 0 and the standard deviation is 5, the numbers will mostly fall in the (-15,15) range. - TCOD::DISTRIBUTION\_GAUSSIAN\_RANGE This one takes minimum and maximum values. Under the hood, it computes the mean (which falls right between the minimum and maximum) and the standard deviation and applies a standard Gaussian distribution to the values. The difference is that the result is always guaranteed to be in the min-max range. - TCOD::DISTRIBUTION\_GAUSSIAN\_INVERSE Essentially, this is the same as `TCOD::DISTRIBUTION_GAUSSIAN`. The difference is that the values near +3 and -3 standard deviations from the mean have the highest possibility of appearing, while the mean has the lowest. - TCOD::DISTRIBUTION\_GAUSSIAN\_RANGE\_INVERSE Essentially, this is the same as `TCOD::DISTRIBUTION_GAUSSIAN_RANGE`, but the min and max values have the greatest probability of appearing, while the values between them, the lowest. ## NoiseType - TCOD::NOISE\_PERLIN - TCOD::NOISE\_SIMPLEX - TCOD::NOISE\_WAVELET - TCOD::NOISE\_DEFAULT ## Event - TCOD::EVENT\_NONE - TCOD::EVENT\_KEY\_PRESS - TCOD::EVENT\_KEY\_RELEASE - TCOD::EVENT\_MOUSE\_MOVE - TCOD::EVENT\_MOUSE\_PRESS - TCOD::EVENT\_MOUSE\_RELEASE - TCOD::EVENT\_KEY - TCOD::EVENT\_MOUSE - TCOD::EVENT\_ANY # SHARE DATA This distribution bundles some data to make development simpler. You can make use of this data with a distribution like [File::Share](https://metacpan.org/pod/File%3A%3AShare), like in this example: use File::Share 'dist_file'; my $path = dist_file TCOD => 'fonts/dejavu10x10_gs_tc.png'; The `fonts` directory contains antialiased fonts that can be used with TCOD. The names of the font files are of the form: __.png : aa 32 bits png with alpha channel gs 24 bits or greyscale PNG : as standard ASCII layout ro standard ASCII layout in row tc TCOD layout The `terminal8x8` font is provided is every possible format as en example. The structure of shared files is reproduced below. share └── fonts ├── dejavu10x10_gs_tc.png ├── dejavu12x12_gs_tc.png ├── dejavu16x16_gs_tc.png ├── dejavu8x8_gs_tc.png ├── dejavu_wide12x12_gs_tc.png ├── dejavu_wide16x16_gs_tc.png ├── terminal10x10_gs_tc.png ├── terminal10x16_gs_ro.png ├── terminal10x16_gs_tc.png ├── terminal10x18_gs_ro.png ├── terminal12x12_gs_ro.png ├── terminal16x16_gs_ro.png ├── terminal7x7_gs_tc.png ├── terminal8x12_gs_ro.png ├── terminal8x12_gs_tc.png ├── terminal8x14_gs_ro.png ├── terminal8x8_aa_ro.png ├── terminal8x8_aa_tc.png ├── terminal8x8_gs_ro.png ├── terminal8x8_gs_tc.png └── ucs-fonts └── 4x6.bdf # SEE ALSO - [TCOD::Color](https://metacpan.org/pod/TCOD%3A%3AColor) - [TCOD::ColorRGBA](https://metacpan.org/pod/TCOD%3A%3AColorRGBA) - [TCOD::Console](https://metacpan.org/pod/TCOD%3A%3AConsole) - [TCOD::Context](https://metacpan.org/pod/TCOD%3A%3AContext) - [TCOD::Dijkstra](https://metacpan.org/pod/TCOD%3A%3ADijkstra) - [TCOD::Event](https://metacpan.org/pod/TCOD%3A%3AEvent) - [TCOD::Image](https://metacpan.org/pod/TCOD%3A%3AImage) - [TCOD::Key](https://metacpan.org/pod/TCOD%3A%3AKey) - [TCOD::Map](https://metacpan.org/pod/TCOD%3A%3AMap) - [TCOD::Mouse](https://metacpan.org/pod/TCOD%3A%3AMouse) - [TCOD::Noise](https://metacpan.org/pod/TCOD%3A%3ANoise) - [TCOD::Path](https://metacpan.org/pod/TCOD%3A%3APath) - [TCOD::Random](https://metacpan.org/pod/TCOD%3A%3ARandom) - [TCOD::Sys](https://metacpan.org/pod/TCOD%3A%3ASys) - [TCOD::Tileset](https://metacpan.org/pod/TCOD%3A%3ATileset) Also, these other external resources might be useful: - [libtcod](https://github.com/libtcod/libtcod) - [rogueliketutorials.com](https://rogueliketutorials.com) - [/r/roguelikedev](https://www.reddit.com/r/roguelikedev) - [RogueBasin](http://roguebasin.com) # 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.