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 is a tutorial on how to use the Tile Engine.

Put the file in place

First, you'll need to copy tileengine.rpy into your game directory.

Define the images

Then you'll need to define Ren'Py images for all your sprites and tiles of your map. These are normal Ren'Py Image statements, in an init: block of your game. If you want to use a cursor, define that too. The TileEngine provides some sample cursors for common tile sizes, or you can of course create your own.

init:
  image terrain road  = Image("tile-road.png")
  image terrain grass = Image("tile-grass.png")
  image terrain rocks = Image("tile-rocks.png")
  image terrain tree  = Image("tile-tree.png")
  image cursor = Image("cursor-iso64x32.png")

Define the tiles and map

Next you need to define the tiles that make up your map. Each one contains a "lower" tile and an "upper" tile. All the "lower" tiles will be shown behind all the "upper" tiles. Each one is defined on one line, like this:

python:
  road  = Struct(lower="terrain road",  upper="")
  grass = Struct(lower="terrain grass", upper="")
  rocks = Struct(lower="terrain rocks", upper="")
  tree  = Struct(lower="terrain grass", upper="terrain tree")

Note that in this example, the tile "tree" includes some grass as the flat sprite, plus a tree to be displayed on top of the grass. And finally, you'll need to define your map. This is simply a two-dimensional array of copies of these tiles.

  import copy
  c = copy.copy
  map = [
   [c(grass), c(grass), c(tree),  c(road)],
   [c(rocks), c(grass), c(grass), c(road)],
   [c(grass), c(tree),  c(grass), c(road)],
   [c(road),  c(road),  c(road),  c(road)]]

Create the TileEngine object

Now you're ready to create the TileEngine. This is done like this:

e = TileEngine(geometry=TileEngine.ISOMETRIC, map=map, tilewidth=64, tileheight=32, screenwidth=800, screenheight=600, show_cursor=True)

The map, tilewidth and tileheight parameters are required. screenwidth, screenheight, and show_cursor are optional parameters. There are a number of other optional parameters you can also include: see the full documentation for details.

Now, if you wanted, you could show the TileEngine once, using e.Show(), which just displays it once and carries on with your game script immediately afterwards:

bob "Let's have a look at the map."
$ e.Show()
bob "Yes, look, there's road along two sides."

Or you could use its View() function to view it in a loop with a "Dismiss" button, to let the player scroll around a map:

bob "Let's have a good long look at the map."
$ e.View()
bob "Yes, look, there's road along two sides."

But it won't do much without any sprites on the map.

Create Sprites

So you'll want to call e.Sprite() to add sprites. Sprites have a spritename, which is the name of a Ren'Py Image (or other Displayable) to be shown; a position, which is the position on the grid where the Sprite will be shown; and a visible property, which defaults to True, but you can set to False to hide the Sprite for any reason. The simplest way to call Sprite() is like this:

s = e.Sprite(myName)

This won't display the sprite, since you haven't told the TileEngine where to show it. It'll just create it, ready for you to specify its position later. If you already know the position on the grid where you want the Sprite to appear, you'll probably want to provide the position:

s = e.Sprite(spritename=myName, position=(3,2))

Note that the position is in grid squares. The TileEngine will automatically convert that to screen co-ordinates, and ensure that sprites lower down the screen appear in front of ones higher up.

Move Sprites

So you've got your Sprite object, s. What can you do with it? Well, it's got properties spritename, position, and visible, some or all of which you'll have supplied when you created it. You can update those properties at any time, and the Sprite will automatically be redrawn with its new position or properties when you show the TileEngine. It's as simple as:

 $ s.position = (4, 2)
 $ e.Show() # moves the sprite instantly to its new position

Alternatively, you can call the Sprite's MoveTo() function to make it move smoothly from where it is now to the new position:

python:
  s.MoveTo((4, 2))
  e.Show() # moves the sprite smoothly to its new position 

The move will by default take 0.5 seconds. You can change this by setting e.movement_duration. This is one setting, global to all the sprites in the TileEngine, because they all move at once, during the Show() call. You can make several sprites all move at once like this:

python:
  s1.MoveTo((4, 2))
  s2.MoveTo((0, 0))
  s3.MoveTo((4, 4))
  e.Show() # moves all three sprites smoothly to their new positions 

Click Sprites

The other thing that sprites can do is respond to mouse clicks, if you supply a function in the clicked parameter. This function might be , to make the game jump to a Ren'Py label; or it could be many other things, including a custom function you've defined yourself. Don't worry about wrapping it in - the Sprite does that for you.

python:
  s1 = e.Sprite(name="pyramid", position=(3,2), clicked=ui.jumps("viewpyramid")
  s2 = e.Sprite(name="sphinx",  position=(5,8), clicked=ui.jumps("viewsphinx")
  e.Show() 

label viewpyramid:
  bob "It's all pointy!"

label viewsphinx:
  bob "Where's its nose?"