untdl

Package untdl |
[frames] | no frames]

# Package untdl

source code

The documentation for python-untdl. A fork of tdl (A Pythonic port of libtcod).

# Getting Started

Once the library is imported you can load the font you want to use with `untdl.setFont`. This is optional and when skipped will use a decent default font.

After that you call untdl.init to set the size of the window and get the root console in return. This console is the canvas to what will appear on the screen.

# Indexing Consoles

For most methods taking a position you can use Python-style negative indexes to refer to the opposite side of a console with (-1, -1) starting at the bottom right. You can also check if a point is part of a console using containment logic i.e. ((x, y) in console).

You may also iterate over a console using a for statement. This returns every x,y coordinate available to draw on but it will be extremely slow to actually operate on every coordinate individually. Try to minimize draws by using an offscreen Console, only drawing what needs to be updated, and using Console.blit.

# Drawing

Once you have the root console from untdl.init you can start drawing on it using a method such as `Console.drawChar`. When using this method you can have the char parameter be an integer or a single character string.

The fgcolor and bgcolor parameters expect a three item list [red, green, blue] with integers in the 0-255 range with [0, 0, 0] being black and [255, 255, 255] being white. Or instead you can use None in the place of any of the three parameters to tell the library to not overwrite colors. After the drawing functions are called a call to untdl.flush will update the screen.

Version: 1.1.6r81-0.1.3

License: New BSD License

Submodules
untdl.event: This module handles user input. untdl.map: Rogue-like map utility's such as line-of-sight, field-of-view, and path-finding. untdl.noise: This module provides advanced noise generation.

Classes
| Console Contains character and color data and can be drawn to.
| TDLError The catch all for most unTDL specific errors.
| Window A Window contains a small isolated part of a Console.
| _MetaConsole Contains methods shared by both the Console and Window classes.

Functions
flush() Make all changes visible and update the screen. | source code
force_resolution(width, height) Change the fullscreen resolution | source code
int |
get_fps() Return the current frames per second of the running program set by set_fps | source code
boolean |
get_fullscreen() Returns True if program is fullscreen. | source code
Console |
init(width, height, title=None, fullscreen=False, renderer=`'``SDL``'`) Start the main console with the given width and height and return the root console. | source code
None |
map_ascii_codes_to_font(first_ascii_code, num_codes, font_char_x, font_char_y) Maps characters in the bitmap font to ASCII codes. | source code
screenshot(path=None) Capture the screen and save it as a png file | source code
set_font(path, columns=None, rows=None, column_first=False, greyscale=False, alt_layout=False) Changes the font to be used for this session. | source code
set_fps(frame_rate) Set the maximum frame rate. | source code
set_fullscreen(fullscreen) Changes the fullscreen state. | source code
set_title(title) Change the window title. | source code

Function Details

### flush() | source code
Make all changes visible and update the screen. Remember to call this function after drawing operations. Calls to flush will enforce the frame rate limit set by untdl.set_fps. This function can only be called after untdl.init

### force_resolution(width, height) | source code
Change the fullscreen resolution Parameters: `width` (int) `height` (int)

### get_fps() | source code
Return the current frames per second of the running program set by set_fps Returns: int Returns the frameRate set by set_fps. If set to no limit, this will return 0.

### get_fullscreen() | source code
Returns True if program is fullscreen. Returns: boolean Returns True if the window is in fullscreen mode. Otherwise returns False.

### init(width, height, title=None, fullscreen=False, renderer=`'``SDL``'`) | source code
Start the main console with the given width and height and return the root console. Call the consoles drawing functions. Then remember to use untdl.flush to make what's drawn visible on the console. Parameters: `width` (int) - width of the root console (in tiles) `height` (int) - height of the root console (in tiles) `title` (string) - Text to display as the window title. If left None it defaults to the running scripts filename. `fullscreen` (boolean) - Can be set to True to start in fullscreen mode. `renderer` (string) - Can be one of 'GLSL', 'OPENGL', or 'SDL'. Due to way Python works you're unlikely to see much of an improvement by using 'GLSL' or 'OPENGL' as most of the time Python is slow interacting with the console and the rendering itself is pretty fast even on 'SDL'. Returns: Console The root console. Only what is drawn on the root console is what's visible after a call to untdl.flush. After the root console is garbage collected, the window made by this function will close.

### map_ascii_codes_to_font(first_ascii_code, num_codes, font_char_x, font_char_y) | source code
Maps characters in the bitmap font to ASCII codes. This should be called after untdl.init You can dynamically change the characters mapping at any time, allowing to use several fonts in the same screen. Parameters: `first_ascii_code` (int) - First ascii code to map. `num_codes` (int) - Number of consecutive ascii codes to map. `font_char_x` (int) - Coordinate of the character in the bitmap font (in characters, not pixels) corresponding to the first ASCII code. `font_char_y` (int) - Coordinate of the character in the bitmap font (in characters, not pixels) corresponding to the first ASCII code. Returns: None

### screenshot(path=None) | source code
Capture the screen and save it as a png file Parameters: `path` (string) - The file path to save the screenshot. If path is None then the image will be placed in the current folder with the names: screenshot001.png, screenshot002.png, ...

### set_font(path, columns=None, rows=None, column_first=False, greyscale=False, alt_layout=False) | source code
Changes the font to be used for this session. This should be called before untdl.init If the font specifies its size in its filename (i.e. font_NxN.png) then this function can auto-detect the tileset formatting and the parameters columns and rows can be left None. While it's possible you can change the font mid program it can sometimes break in rare circumstances. So use caution when doing this. Parameters: `path` (string) - Must be a string file path where a bmp or png file is found. `columns` (int) - Number of columns in the tileset. Can be left None for auto-detection. `rows` (int) - Number of rows in the tileset. Can be left None for auto-detection. `column_first` (boolean) - Defines if the character order goes along the rows or columns. It should be True if the character codes 0-15 are in the first column. And should be False if the characters 0-15 are in the first row. `greyscale` (boolean) - Creates an anti-aliased font from a greyscale bitmap. Otherwise it uses the alpha channel for anti-aliasing. Unless you actually need anti-aliasing from a font you know uses a smooth greyscale channel you should leave this on False. `alt_layout` (boolean) - An alternative layout with space in the upper left corner. The column parameter is ignored if this is True, find examples of this layout in the font/libtcod/ directory included with the python-untdl source. Raises: `TDLError` - Will be raised if no file is found at path or if auto- detection fails. Note: A png file that's been optimized can fail to load correctly on MAC OS X creating a garbled mess when rendering. Don't use a program like optipng or just use bmp files instead if you want your program to work on macs.

### set_fps(frame_rate) | source code
Set the maximum frame rate. Parameters: `frame_rate` (int) - Further calls to untdl.flush will limit the speed of the program to run at <frame_rate> frames per second. Can also be set to 0 to run without a limit. Defaults to None.

### set_fullscreen(fullscreen) | source code
Changes the fullscreen state. Parameters: `fullscreen` (boolean)

### set_title(title) | source code
Change the window title. Parameters: `title` (string)