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.
Using shift Using ctrl Using ctrl + shift Using alt -
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 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.
Snapshots
A snapshot refers to the saved content of the canvas. It can be created using the Export button. Creating a snapshot which 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.
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 a bit. On the other hand, nobody ever reads the documentation anyway.
Be aware that running scripts from untrusted sources can pose a security risk.
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 are basically a configuration (including callbacks, etc.) that is passed to the engine during its initialization phase. Scenario can define its 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 (outdated a bit). The main.js file is important as it defines the API.
Useful tools:
Easy Start
A custom scenario can be easily developed in the Scenario IDE.
Serious Development
(under reconstruction)To create a custom scenario, follow these steps:
- Create a repository from the template by clicking on 'Use this template'.
- Continue with the instructions in the readme.
- Optionally watch this video: Sand Saga scenario development
Publication Process
If you have an interesting and unique scenario that you want to be published on sandsaga.com, follow these steps:
- Test it thoroughly.
- Write ideally on Discord, channel #content-creation, attach sources or a link to GitHub repository (better).
- The scenario will have to pass a review.
- 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).