Introduction
Creating a Sandboxels mod means writing JavaScript that adds or changes elements, tools or behaviours in the game. This guide gives you a practical starting path — it does not claim to replace the official modding tutorial, and it does not host your code.
Start with the official tutorial
Use the Sandboxels modding tutorial on the official wiki first. It explains the element format, categories, behaviours and reactions that your mod will use. Skipping it and copying random code is the fastest way to build something that breaks on the next game update.
Build small, test locally
- Start with one element or one tool, not a whole system.
- Test it in the game, alone, before adding more.
- Keep a note of what your mod changes, so players (and future you) can tell whether a conflict is yours.
- Use clear names and avoid overwriting vanilla elements unless that is the point of your mod.
Tools that help creators
Elements Manager (elementsManager.js, by ggod) lets you create and edit custom elements in the game, which is useful for prototyping. It does not replace writing and testing your own mod file, but it can help you learn the element format.
Submitting your mod
Mods submitted to the public repository (github.com/R74nCom/Sandboxels-Mods) are listed on the official mod list. Read that repository's contribution guidelines before submitting, and make sure your submission describes what the mod adds, what it changes, and any known conflicts. This site also accepts submissions for manual review, but it does not publish them automatically and it does not replace the official repository.
Common creator mistakes
- Building a huge mod before testing a small one.
- Not documenting changes, so players cannot debug conflicts.
- Claiming compatibility you have not tested.