Modding tutorial

Modding allows players to create their own elements with custom behaviors in Sandboxels and share them with other players. This tutorial will walk you through the basics of modding the game by creating a simple element, with no JavaScript knowledge required (though concepts of it are discussed)

Installing the game locally

Before getting to the process of writing mods, it is strongly recommended to download the game locally first to be able to test and debug in your computer. It can be downloaded from GitHub through this link. Once unzipped, the game can be launched by clicking on index.html and mods can be placed inside the mods folder.

It is also recommended to download a text editor like Notepad++ to assist in coding. While the Notepad that comes with Windows can be used for coding, using a text editor makes it easier due to features like text highlighting, auto-indentation of code, and autocomplete that may be used.

Creating a mod and an element

In the mods folder, create a JavaScript file. In Windows, this can be done by creating a text file, then replacing the .txt extension with .js with file name extensions turned on (if they're off, it is most likely still a text file). The resulting file should be named like name_of_mod.js. When loading Sandboxels, you may now load in the mod through the mods menu like you would any other mod by typing its name in the mod manager menu.

You may notice that there is nothing new in the game, as no elements have been created. To create an element, follow the template below:

elements.hello_world = {
	color: "#ff0000",
	behavior: behaviors.WALL,
	category: "land",
	state: "solid",
};

What does it do?

• elements.hello_world creates a new element named "Hello World". The braces contain all the information this element uses.
• color: "#ff0000" states that the color of this element should be red. Colors are defined through hex codes, which you can get using Google's color picker.
• behavior: behaviors.WALL states that it should act like a wall. There are many kinds of behaviors, which will be discussed later on.
• category: "land" states that this element should belong in the Land category. You may opt to use one of the categories in the vanilla game or create one yourself, in which case a new category will be created.
• state: "solid" states that this element is a solid.
• Finally, the closing braces }; note that the element definition is over. Without this, your mod will fail to run.

Now, if you reload the game, you can find the Hello World element which you can place around the canvas. If you don't, check the console for any errors (while its location may depend on the browser you are using, it is usually accessible in the same place Inspect Element is). There should be some errors and warnings that pop up, but all you need to check are ones coming from your mod instead of from index.html. If there is one, your mod has failed to load likely due to a syntax error.

Common errors include:

• For text inputs, forgetting to include quotes. Any text input (also known as a string) to any property has to include quotes. This, however, does not apply to behavior as you are inserting a variable defined by the base game itself in this spot.
• Forgetting a comma. Commas are used to separate properties (creating a new line does not count), so you need to include one after every property filled in. However, including a comma after your last element does not cause an error, so you may keep one there so you don't forget to add a comma in when adding additional properties.
• If you misspell one of the property names, it will be treated as if it didn't have this property in the first place.

Behaviors

Main article: Behaviors

While the element exists now, it's boring if all you could make are stationary walls. Fortunately, there are other behaviors you can use to dictate how your element moves, and you can also create your own. All default behaviors are prefixed with behaviors. and written in all-caps.

Behavior name	Description	Example
behaviors.POWDER	Element drops like a powder	Sand
behaviors.STURDYPOWDER	Element falls when not supported by something underneath	Mud
behaviors.AGPOWDER	Element drops like a powder, however with reversed gravity	Antipowder
behaviors.LIQUID	Element flows around like a liquid	Water
behaviors.SUPERFLUID	Element flows like a superfluid or a liquid that flows smoothly with zero viscosity	Liquid Light
behaviors.AGLIQUID	Element flows around like a liquid, however with reversed gravity	Antifluid
behaviors.WALL	Element is completely stationary	Wall
behaviors.GAS	Element flows like gas	Oxygen
behaviors.DGAS	Element flows around like gas, however deletes itself after a while	Smoke
behaviors.SUPPORT	Element falls when not supported by anything beside it	Mudstone
behaviors.SUPPORTPOWDER	Element falls like powder when not supported by anything beside it	Packed Snow
behaviors.FOAM	Element falls slowly and vanishes after a while	Foam
behaviors.BUBBLE	Element falls very slowly and vanishes after a while	Bubble
behaviors.MOLTEN	Element flows very slowly and produces fire	Molten Dirt
behaviors.BOUNCY	Element bounces around the screen	Laser

Properties

Main article: Element properties

The properties of its element define what it is like and what sets it apart from other elements. Above, the color, behavior, category, and state values are its properties. There are many other properties you may use, such as the following:

Property name	Data type	Description
tempHigh	Number	The temperature at which this element melts or turns into another
stateHigh	Element name (string)	The element which this element turns into when at its melting point
tempLow	Number	The temperature at which this element freezes or turns into another
stateLow	Element name (string)	The element which this element turns into when at its freezing point
density	Number	The density of this element in kg/m3
hidden	Boolean	Whether to hide this element from the element toolbar
hardness	Number	The hardness of a material from 0 to 1
breakInto	Element name (string)	The element that this element will turn into when broken
burn	Number	The likelihood of this material to burn from 0 to 100
burnTime	Number	How long this element can burn in ticks
burnInto	Element name (string)	The elements this element turns into after burning
reactions	Object	The reactions of this element

Reactions

Reactions determine what happens when an element touches another element. They are determined by a list of elements, which defines what elements it turns into. See the following code, which includes some of Water's reactions.

    reactions: {
        "dirt": { elem1: null, elem2: "mud" },
        "sand": { elem1: null, elem2: "wet_sand" },
        "clay_soil": { elem1: null, elem2: "clay" },
        "salt": { elem1: "salt_water", elem2: null },
        "sugar": { elem1: "sugar_water", elem2: null },
        "dust": { elem1: "dirty_water", elem2: null },
        "ash": { elem1: "dirty_water", elem2: null },
        "rock": { elem2: "wet_sand" },
        "ruins": { elem2: "rock" },
        "mudstone": { elem2: "mud" },
    },

In here, elem1 refers to what the element itself turns into, in this case Water. elem2 refers to what the element it reacts with will turn into, which includes Dirt, Sand, Clay Soil, and others. If what is written is null, the element disappears. That means that in this code, when Water reacts with Dirt, the water disappears and the dirt will turn into Mud, while if it reacts with Salt instead, the water turns into Salt Water instead and the salt will disappear. If there is nothing written about a certain element, it implies it will stay the same instead of changing, in this case Rock will turn to Wet Sand when reacting with Water while the Water won't change.

As it is a property, reactions are written along with the other properties. Suppose you have a test powder, and you want to turn both elements into oil when it touches water. It can be written as such:

elements.hello_world = {
	color: "#ff0000",
	behavior: behaviors.POWDER,
	category: "land",
	state: "solid",
	reactions: {
		"water": { elem1: "oil", elem2: "oil" },
	}
};

Note the comma after the reaction. Like after an element property, you need a comma after a reaction when other reactions follow after it. This comma isn't necessary, but it's good to have one so you don't have to go back and add one if you're adding more reactions.

Putting it online

To put the mod online to allow other players to play with it in the site, you firstly need a GitHub account. Once you have logged in or registered, create a fork in the Sandboxels GitHub repository. This will create a copy of the Sandboxels code under your name, where you can put your mods in. After uploading them, you may then open a pull request (from the Contribute button) to allow the developers to merge your mod to the main repository. Once this pull request is accepted, the mod will be available for use in the website.

Advanced modding

This tutorial only covers the basics of modding. For more, click on one of the links below.

• Element properties
• Element behavior
• Advanced reactions
• Basics of JavaScript
• Using tick
• Debugging
• Mod interactions
• Advanced functions

• List of reaction properties
• List of pixel functions