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 to manage rendering contexts and TCOD::Tileset to load custom fonts to display. TCOD::Event 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, which can also be used by TCOD::Path 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 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, 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 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.

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

This distribution bundles some data to make development simpler.

You can make use of this data with a distribution like File::Share, 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:

<font_name><font_size>_<type>_<layout>.png

<type>   : aa 32 bits png with alpha channel
           gs 24 bits or greyscale PNG

<layout> : 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

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.

To install TCOD, copy and paste the appropriate command in to your terminal.

cpanm

cpanm TCOD

CPAN shell

perl -MCPAN -e shell
install TCOD

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)