Modding tutorial

From Sandboxels Wiki
Jump to navigation Jump to search

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.


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


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 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.

  • List of reaction properties
  • List of pixel functions