This page is out of date

You've reached a page on the Ren'Py wiki. Due to massive spam, the wiki hasn't been updated in over 5 years, and much of the information here is very out of date. We've kept it because some of it is of historic interest, but all the information relevant to modern versions of Ren'Py has been moved elsewhere.

Some places to look are:

Please do not create new links to this page.


This page provides the documentation for the Tile Engine and its Sprite objects. You may wish to read the ../Tile Engine Tutorial/.

Overview

The TileEngine is a Ren'Py object for displaying a tile-based map, in either isometric or straight-grid layout, and putting sprites on it. The basic process of making use of the TileEngine will look like this:

Conventions

All positions are given in (gridx, gridy) tuples. These are converted to screen co-ordinates internally by the TileEngine's GridToScreen() function. The "user" always refers to the game creator who's making use of the TileEngine in their game. The "player" always refers to the person playing that game. This document is aimed at users, not players, and so "you" also refers to the user.

TileEngine object

You create a TileEngine with code like:

e = TileEngine(map = myMap, tilewidth = 64, tileheight = 32, geometry = TileEngine.ISOMETRIC)

Documentation on these parameters follows.

Required parameters:

The 2-dimensional array of tiles. Each tile must be an object (for example, a Struct) with properties lower and upper, each of which can be None, or the filename of an image. The full width of one tile, in pixels. The full height of one tile, in pixels. This should be the base size that will be tiled. It doesn't matter if some of the tile images extend above this height.

Optional parameters:

Whether the map should be displayed in an isometric view or as a straight grid. This should be either TileEngine.ISOMETRIC or TileEngine.STRAIGHT. The desired width of the viewport, in pixels. The desired height of the viewport, in pixels. How many pixels to include at the left and right side of the viewport beyond the map. How many pixels to include above and below the viewport beyond the map. Note that if any of your tiles contain anything that's higher than the tileheight, this will have to be greater than zero for tiles at the top of your map to display fully. Filename of an image to use as the cursor. Whether or not to show a cursor. Note that False leaves mouseless players unable to move. If not None, when the TileEngine is created, the scene will be cleared and this image displayed with (). Which layer to display the map on. The TileEngine automatically adds the layer "tileengine" to in an init block. If a different value is specified here, your code must ensure that layer is in . When Sprites are moved from one map square to another, how long those moves should take. If True, the player can scroll the map by clicking-and-dragging on it. A dictionary mapping keysyms to functions. The functions must be wrapped in ui.returns() or something similar, as the result of calling the function will itself be called after ui.interact finishes. If this is None, the default keymap is used, which is:

To specify an empty keymap (disable keyboard control), use {}.

All of the above parameters are made available as properties of the TileEngine object.

Additional properties:

The following properties are available before a TileEngine is defined: The constant value to supply as the value of the geometry property when creating a TileEngine with isometric geometry. The constant value to supply as the value of the geometry property when creating a TileEngine with straight (orthogonal, square-grid) geometry.

Once a TileEngine is defined, the following properties are available: Size of the map in tiles in the grid X-direction. Size of the map in tiles in the grid Y-direction. Width of the whole map in tiles. Height of the whole map in tiles. A Sprite object representing the cursor, if show_cursor is True. List of the Sprite objects attached to the TileEngine. If show_cursor is true, then the cursor will be in this list. Nine Direction structs are made available. They should be treated as constants. Each struct has properties dx, dy and name. Note that the Directions are different between isometric and straight display. For example, DIR_NW has (dx, dy) of (+1, -1) in a TileEngine with straight geometry, but (0, +1) in one with isometric geometry. In both cases its name property will be "nw". The object for the horizontal scrollbar below the viewport. The object for the vertical scrollbar to the right of the viewport. A struct of functions, all of which are None by default. You can assign functions to any of these, and they'll get called at the appropriate points:

Once a TileEngine's Show() function has been called, the following properties are available: The object representing the displayed viewport.

Functions:

The following functions may be called on a TileEngine object: Display the map and sprites. Let the user view the grid. Calls the engine's Show() function once, and then calls () in a loop to let the user move around using keyboard or mouse. The user can press Escape to leave the view, or click on the button if show_button is True. Parameters: If True, display a button at the top of the screen that the user can click to leave the TileEngine. The text to display on the button. Clear the layer specified in the engine's layer property. Return the Direction struct corresponding to the dx and dy inputs.

Create a Sprite object and add it to the tileengine's sprite list. Parameters: Required. The filename of the image that will be displayed on the grid square equal to this sprite's position. A 2-element tuple consisting of the Sprite's x and y coordinates on the map. If False, this Sprite will not be displayed. If not None, this must be a function, which will be called when the player clicks on the Sprite. If clicked is not None, this is the filename of an image which will be displayed when the player hovers the mouse over the Sprite. Centre the viewport on the specified position. Convert the specified screen position to grid co-ordinates. Convert the specified grid position to screen co-ordinates. The screen co-ordinates returned will be relative to the top-left corner of the viewport, and not necessarily of the actual user's screen. Return True if the specified grid co-ordinates are a valid map square.

Sprite objects

The TileEngine can create Sprite objects. Each Sprite is a graphical object tied to a particular square of the map. When the TileEngine's Show() function is called, each Sprite is displayed between the "upper" and "lower" layer of its corresponding map square. Sprite objects should not be created directly, but by calling the Sprite() function on a TileEngine object.

Functions:

Move the Sprite to the new position.

On the next call to engine.Show(), the Sprite will be displayed as moving smoothly to the new grid position, over the course of engine.movement_duration seconds.

UI functions

The TileEngine provides two functions which can be used to create UI widgets in a consistent style and allowing their contents to be translated. Create a , using styles style.engine_button[text] and style.engine_button_text[text], and translating text if appropriate. Create a containing , using styles style.engine_label[text] and style.engine_label_text[text], and translating text if appropriate. See for how to make your game translate text.

Styles

The following styles are used by the Tile Engine:

In addition to these styles, all the buttons the TileEngine displays, as well as any button displayed by a engine_button() call, will be styled with style.engine_button[yourText] and style.engine_button_text[yourText]; and any label displayed by a engine_label() call will be styled with style.engine_label[yourText] and style.engine_label_text[yourText]. See properties and styles for how to customise styles.