Create a destructible terrain with Stencyl 3.1 image API

The new release of Stencyl adds a lot of awesome features you can see in the official Stencyl 3.1 release page, and above all an interesting image API which will allow us to explore new options of gameplay.

Today I am showing you how to create a destructible terrain and play with it. We will make something simpler than the Box2D destructible terrain I showed you some time ago, but it’s really effective although I am not using “real” physics.

First, let’s see what we are going to do:

The green actor is moving around the stage, and you can dig holes in the terrain with a mouse click. For the sake of semplicity, holes have a square shape, but they can be any shape you want, since both terrain and holes are images.

Now let’s see how easy is the creation of this prototype thanks to Stencyl’s image API. If you are new to Stencyl, you can start with some of these tutorials.


First, you need to know the path Stencyl uses to save the games. You can find it in File -> Preferences -> Workspace.

Inside your game folder, create a new folder called extras where you will save your images. In the picture, you can see how I created an image for the terrain and an image for the hole to dig.

Before you continue, I have to say some images created with PhotoShop using Save for Web did not work. It’s probably a matter of PhotoShop way of saving, and the same images created with Save as worked with no problems.

Now we have the terrain, we have the images so we can start “coding”.


For the sake of semplicity, I placed all the actions and events in a single scene behavior, which has three events:

Created: executed only once, as soon as the scene is created.

Click: when I click on the scene

Drawing: each time the scene is refreshed

Let’s start with the event called when the scene is created:

We have three local variables here, called attributes in Stencyl: Direction, Terrain and Hole.

Direction just specifies the direction, in pixels, the “player” will’ move at each frame. Setting it at 1 will cause the player to move to the right. Terrain and Hole will store respectively the images of the terrain and the hole I uploaded in extras folder.

With image from file block you just have to specify the relative path (without quotes) and your variables will contain the image itself.

But the only bare image is not enough to have it ready to be used in our games, we’ll need instance of to make it accessible to game events.

Also notice the player actor is also created in this block.

Now let’s see what happens when the player clicks on the stage:

Really easy here, the hole image is used to clear the terrain image. Just think about PhotoShop eraser tool. Clear <image> using <image> block will handle the whole thing.

Finally, the event to handle player movement is not that interesting for the scope of this tutorial, since it just defines some hot spots in the actor to check for collisions again terrain image with get pixel at block.

It basically shares the same concept with my pure JavaScript platform game engine.

I have a couple of ideas about a game to create with this API, and I can’t recommend enough Stencyl for its ease of use. Download the entire project.

  • fgs


    I have several good game engine (source code) written in as3.

    I want to find some place to sell them.

    You can get commission if you can help me to sell them on your web site.

    And you can use the game engines to build games too.

    I’m sure my engines are very good and valuable.

    If you are interest, please reply to


  • Thanks for this tutorial. I will try now

  • Pingback: Creation of a String Avoider game using Stencyl and image API - Emanuele Feronato()

  • Hello,

    I was wondering if you can get natural collision behavior using this method?

    For example, if your Hole is not squared but triangle, would you square slip along the oblique side of the triangle ?

    Or if you add a movement behavior to your player, would it collide with the triangle side and behave depending the angle of the side ?


  • jeremie

    any way you can explain how collisions and movement in image API works.

    the first parts are fine generating and the mouse adding that shape and stuff.

    but the last part the hard part its just like BAM! screen shot, look what i did, bye! newbies like me need a simple worded explanation how and why and what each series of codes do.

    i assume you are just so good at this that you felt it was too childish to elaborate on.

  • I Have Idea…

  • Thanks for this tutorial.

  • Nice Tutorial. Thanks