I saw quite a few posts asking how to do a falling sand/boulder dash behaviour when I was trying to figure it out for a game.
This is the way that me and my brother figured out how to do it in a step by step tutorial for anyone new to image API. Example behaviour at bottom.
Create a Scene Behaviour which I name "sand image behaviour".
Add a When Created event.
Add an attribute of type Image named "screen" and one of type Image Instance named "screen inst".
This gives you the canvas on which the action will occur. Use attach to layer if you don't want your sand to follow the camera in scenes bigger than the screen, or attach to screen if your scene is the size of the screen.
Create an attribute of type Number named "particle size".
This is the size of the sand particles. Really small sizes(smaller than 10) on a scene of 640x480 or greater may cause lag. For a boulder dash game you'll want this size to be bigger.
Either way you should make sure that scene width and height are divisible by particle size to prevent truncated "tiles"
Create another attribute of type Image named "particle" and one of type Color named "particle color".
This gives you the sand particles you'll paint with which will get their movement later. We'll be drawing the sand particles directly onto the "screen" image, which is reflected in the "screen inst" image instance. Everything has to be drawn onto the same image for the collision checking.
Create yet another two Image attributes and one Color attribute named respectively "terrain", "ground" and "terrain color".
These give you immovable particles to paint with and a layer at the bottom that prevents the sand from falling off screen. The "Add" drawing method causes problems with the particle movement, so I use "Normal" instead, I'm not sure what effect the other draw methods might have. If your particles are getting squashed this might be the cause.
Create another two Number attributes named "row number" and "column number".
This will make the loops start from the bottom. If the loops start from the top it will basically do all the movement at once, making the particles jump from their positions to the bottom of the screen instantly. The other number can stay at it's default(0) for now.
Create a Text attribute called "type of click".
This text attribute will serve to cycle between three states(particle, terrain, destroy) for painting your scene. We'll do that in the next two events.
Create a When Control is Pressed event(input - keyboard). I chose action2(default x key). Inside of it put these blocks.
This makes the cycling I mentioned earlier happen when you press the x key. Now to make that cycling actually do something.
Create a When Mouse is Pressed event(input - click).
With this when you click it does different things depending on the value of the Text attribute.
I'll explain some things.
The get pixel block returns a color in number format, 0 for transparent(empty). We're not using those numbers, that's the reason we created those Color attributes earlier.
The floor of (mouse/particle size) x particle size means that you're creating(or destroying) a particle at this "grid space" instead of the exact location of the mouse.
Now let's make it so that it only starts moving when we want. Create a Boolean attribute called "go".
Add another When Control is Pressed event, choose action 1(default z key).
Now it only starts the movement when you press z and you can pause it whenever you want.
Add a Do Every N Seconds event, 0.05 is a good number to make it go not too fast. You can later adjust this time to make it slower or faster, but remember that if it's too fast you'll get lag. Here we'll put in all that we need to actually make the particles act the way we want. First let's just make them fall down and stop when they touch the ground.
Some explanations: The If go means it only starts when "go" is true and we already have an event to change that at will. The two loops(repeat times) check every column at every row for particles.
So if at a specific column and row we have a particle and under that particle is empty space(checking with get pixel) we tell it to do something. Specifically we tell it to erase that particle and draw a new one on the row just under. Now the particles will fall, but to make it a good falling sands behaviour we need the particles to roll like they had physics.
Add this inside the first if get pixel below the second if get pixel. It should look like this.
Now if there is something other than empty space under a particle, it checks the two spaces to the left and right of the space under the particle and then if they're free it moves the particle(again erasing the drawing at it's position and drawing a new one in the intended position) diagonally down and either to the left or right.
If both spaces are free it uses a random number to determine whether to go left or right.
If only one side is free it moves to that side. The conditionals for "column number" inside these movements mean that the particles don't roll off screen when they're at the edges of the scene. And here is the finished behaviour.
Just save this image and on a stencyl project go to File - Import resource and you'll have a behaviour ready to attach to any empty scene. You'll need to modify it extensively to actually make a game out of it, but it should at least point you in the right direction.
Any suggestions on how to improve this behaviour or this tutorial are greatly appreciated.
If you need clarification on anything, please post your questions.
Edit: Updated the behaviour to show keys on the screen. Also forgot to mention you should have a When Drawing event.
I've also added it to the forge with the name "sand image behaviour".
And as mdotedot points out the When Mouse is event can be changed to draggedinstead of pressed.
