User Manual

Sand Saga can be played using either a mouse and keyboard or a touch screen

Canvas Modes There are three modes: boxed, fall-through, and erasing. The boxed mode confines the elements within the boundaries of the canvas. The erasing mode automatically removes elements when they reach the bottom of the canvas. The fall-through mode creates a continuous cycle where elements repeatedly fall from the top to the bottom.

Sandbox Scenarios

Sandbox scenarios provides further options.

Canvas Size and Scale By default, the canvas size and the scale (element size) are calculated automatically based on the screen dimensions and other parameters. By increasing the element size, fewer elements will appear on the canvas, which improves performance but also leads to a more pixelated appearance. On the other hand, if the element size is decreased, more elements will populate the canvas, providing a finer level of detail, but potentially impacting performance. The Performance metric is a good indicator.

Exporting/Importing Canvas content can be exported (downloaded) for later use. These exports can then be opened or seamlessly placed into another canvas.

Image Templates By importing a JPG/PNG... image (in the same way as an exported canvas), it is possible to create a template that can be placed onto the canvas. This feature enables to incorporate custom graphics.

Scripting [advanced] By pressing F12, you can open the browser’s developer tools. Here, in the console, you can programmatically manipulate the canvas.

[more advanced]

Content Creation

For creative individuals, there are additional possibilities. They are ordered from less technical to more technical.


Resources for Sand Game JS can be imported directly using the Import button or by dragging and dropping. In the future, a workshop might be available for them. Please note that import may be disabled in certain scenarios to prevent cheating.

There are two types of resources: snapshots and tool definitions.


A snapshot refers to the saved content of the canvas. It can be created using the Export button. Creating a snapshot whitch is interesting for other players is the simplest and most basic way of creating content. There is an ongoing effort to maintain backward compatibility. In the current version, it is still possible to open even the oldest created snapshots.

Examples can be found here.

Tool Definitions

Currently, tool definitions are limited to template tools. In the future, it will be possible to define brush tools declaratively.

Examples can be found here.


With scripting, you can manipulate the canvas and control processing. If you create something interesting, you can create a GitHub gist or a repository and share the link on our Discord server. Currently, there is no comprehensive documentation available, so you may need to experiment more or look into the source codes. On the other hand, nobody ever reads the documentation anyway.

To begin with scripting, press F12 to open the developer tools and navigate to the console. Please note that scripting may be disabled in certain scenarios to prevent cheating.

You have access to the following global variables:

Here are a few examples of what you can do...

// spawn fire after each iteration = fire source
sandGame.addOnProcessed(() => {, 50, 100, 55,;
// bigger fire
sandGame.addOnProcessed(() => {, 50, 170, 55,;, 50, 170, 55, brushes.effect_temp_255);
// control processing manually
for (let i = 0; i < 1000; i++) {
    sandGame.doProcessing();  // perform one iteration now


Scenarios are like lightweight modifications. They function by using Sand Game JS as a library and can define their own tools, templates, scenes, objectives, and customize various settings. This is how all the basic scenarios that you can see on the main page work, from tutorials to sandboxes. Currently, there is no comprehensive documentation available, so you may need to experiment more or look into the source codes. The main.js file is important as it defines the API.

Easy Start

A custom scenario can be easily developed in the Scenario IDE.

Serious Development

To create a custom scenario, follow these steps:

  1. Create a repository from the template by clicking on 'Use this template'.
  2. Continue with the instructions in the readme.

Publication Process

If you have an interesting and unique scenario that you want to be published on, follow these steps:

  1. Test it thoroughly.
  2. Write ideally on Discord, channel #content-creation, attach sources or a link to GitHub repository (better).
  3. The scenario will have to pass a review.
  4. I will assemble the scenario myself and deploy it.

It might be a good idea to grant me push access to the repository (by adding me as a collaborator). This way, I can promptly address any deployment-related issues or potential future compatibility issues (I care about popular scenarios).


Modifications are essentially forks of the Sand Game JS. You can change everything.

To start with mod development, fork the Sand Game JS on GitHub. You should be also aware of the Sand Game JS license.

The same procedure applies for publication as with scenarios.