User Manual

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

• For mouse and keyboard users, the left mouse button (LMB) is used for drawing, while the right mouse button (RMB) is used for erasing. You can draw a straight line or a rectangle, you can hold the shift or ctrl key while dragging the LMB or RMB. To prevent elements from being redrawn, you can hold the alt key while drawing. To fill an area, hold both the ctrl and shift keys while using the LMB or RMB. Additionally, the middle mouse button can be used to create a meteor.

  

  

  

  

• On a touch screen device, touch input or dragging can be used to draw with the primary brush. Simply touch and drag your finger on the screen to create elements.

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

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.

Scripting

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:

• sandGame - instance of SandGame.
• brushes - list of brushes as a map.

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

// spawn fire after each iteration = fire source
sandGame.addOnProcessed(() => {
    sandGame.graphics().drawRectangle(60, 50, 100, 55, brushes.fire);
});

// bigger fire
sandGame.addOnProcessed(() => {
    sandGame.graphics().drawRectangle(120, 50, 170, 55, brushes.fire);
    sandGame.graphics().drawRectangle(120, 50, 170, 55, brushes.effect_temp_255);
});

// control processing manually
sandGame.stopProcessing();
for (let i = 0; i < 1000; i++) {
    sandGame.doProcessing();  // perform one iteration now
}
sandGame.startProcessing();

Scenarios

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.

Modifications

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.