User Manual

This manual is another way to gather information about the game, in addition to the tutorial scenarios.

Installation

For a better user experience, Sand Saga can be installed.

• The installation is handled by the browser and works because the website is Progressive Web App (PWA) compliant.
• You will get a desktop icon. The app will appear among others in the Start menu, Control Panel, etc.
• You can open .sgjs files by double-clicking them.
• It still requires an internet connection to work.

On a desktop All major browsers except Firefox support installation. Some features may be missing in Safari.

On a smartphone / tablet In Chrome for Android, a notification about the installation option will pop up automatically. In up-to-date mobile Safari, installation should also work (though possibly with limitations), but manual action in the options is required.

Controls

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

On a desktop 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 smartphone / tablet 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.

Game Concepts

Scenarios A scenario is a predefined setup that directs how players engage with the game. Scenarios include tutorials (teach basic mechanics), missions (focused objectives), challenges (problem-solving tasks), sandbox scenarios (freeform creation), and others (miscellaneous gameplay modes).

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.

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.

* This only applies to sandbox scenarios.

[more advanced]

Content Creation

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

Resources

Resources for can be imported directly using the Import button or by dragging and dropping. Some kinds of resources can be published on the Workshop. Please note that import may be disabled in certain scenarios to prevent cheating.

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

Themes

Themes allow customization of the Sandbox without programming, specifically in a declarative way. This is still a new concept, so the options are limited. They are created using the Theme Designer. In the future, there will be a Workshop category for themes.

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.

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 (Modifications)

Scenario can define its own tools, templates, scenes, objectives, and customize various settings. The scenario itself is basically a configuration (including callbacks, etc.) that is passed to the engine during its initialization phase. This is how all the basic scenarios that you can see on the main page work, from tutorials to sandboxes.

How to Start

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

Publication Process

If you have an interesting and unique scenario that you want to be published on sandsaga.com, 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).