Mod folder and mod.json
Where the mod folder lives, what goes inside it, and how to fill in every field of mod.json, the mod’s ID card.
This is the first page of the "Advanced: editing files by hand" group. The mod editor writes everything described below for you, so most people never need this page. Read on if you want to edit files with an outside text editor, or understand what the editor wrote for you.
A mod is just a folder. It must contain one file called mod.json, which is the mod’s ID card: its name, its version, who has to install it, its options, and where its content files are. A field is one setting inside a file, such as name or version.
Mods only work in the desktop (Steam) version. If you start from a template, the game builds the whole folder and mod.json for you. This page is here so you can read it and change it with confidence.
Where the mods folder is#
The easy way: open Workshop on the title screen, go to the Make Mods tab and press Open mods folder (or press Open folder inside the editor to open just that mod's folder). It opens in your file manager (Explorer or Finder). The folder is created the first time it is needed, with a README.txt inside. Each mod is a subfolder of it. The real locations are:
Windows %APPDATA%\FangjieShatteredAltars\mods-dev
(usually C:\Users\YourName\AppData\Roaming\FangjieShatteredAltars\mods-dev)
macOS ~/Library/Application Support/FangjieShatteredAltars/mods-dev
Linux ~/.config/FangjieShatteredAltars/mods-dev- A subfolder name may only use English letters, digits, underscores and dashes, must start with a letter or digit, and can be up to 64 characters. It does not have to match the mod’s
id. - Mods you make here are labelled "Local (in progress)" in the mod list.
- When you save a file, the game checks the mod again by itself and shows "Ready" or "N problem(s)" next to it, explaining in plain words which file, which entry and which field is wrong. You do not need to restart the game.
- To play with your changes, press Test on the Make Mods page or at the top of the editor. The game reloads with only this mod (and the mods it needs). Press it again after each edit.
What goes inside the folder#
my_mod/
mod.json the mod's ID card (the only required file)
data/
items.json content tables; pick any file name, and list the path in mod.json under content
recipes.json
buffs.json
models/
frost_whistle.json voxel models (how an item looks)
i18n/
zh-TW.json translations, simple "key: text"
en.json
scripts/
main.js a small program (content.script points at it)
preview.png Workshop preview image (optional)Only mod.json is required; add the rest as you need it. You can name folders and files however you like as long as the paths in mod.json match. The rules:
| Item | Rule |
|---|---|
| Allowed file types | .json, .js, .png, .md, .txt. Shortcuts, links or other file types stop the mod from loading |
Files starting with . | (.DS_Store, .git and similar) are ignored: no error, and they are never uploaded |
| Number of files | At most 200 files per mod |
| Total size | At most 32 MB per mod |
| One JSON file | At most 2 MB, and not nested too deeply |
| Script file | At most 512 KB |
mod.json | At most 64 KB |
| Content paths | Relative paths to files inside the mod folder; they cannot leave the folder. Content tables must be .json, the script must be .js |
The fields of mod.json#
Here is a complete mod.json that uses most of the fields. It declares three options (explained below) and points at two content files, whose contents are the examples further down this page.
{
"format": 1,
"id": "frost_pack",
"name": "Frost Supplies",
"names": { "zh-TW": "霜原補給", "zh-CN": "霜原补给" },
"version": "1.0.0",
"author": "Your name",
"description": "A frost blade, a tonic buff and a small whistle you can switch on.",
"descriptions": { "zh-TW": "一把霜刃、一個強化藥增益,和一個可以開關的小哨子。" },
"gameApi": { "min": 1 },
"scope": "everyone",
"options": [
{ "key": "bladePower", "label": "Frost Blade power", "labels": { "zh-TW": "霜刃攻擊力" },
"hint": "The original is 34", "type": "number", "min": 10, "max": 60, "step": 2, "default": 34 },
{ "key": "tonicBonus", "label": "Frost ward bonus", "labels": { "zh-TW": "霜護加成" }, "type": "choice", "default": 8,
"choices": [
{ "value": 4, "label": "Weak", "labels": { "zh-TW": "弱" } },
{ "value": 8, "label": "Normal", "labels": { "zh-TW": "普通" } },
{ "value": 12, "label": "Strong", "labels": { "zh-TW": "強" } }
] },
{ "key": "extraWhistle", "label": "Add a whistle", "labels": { "zh-TW": "多一個小哨子" }, "type": "toggle", "default": false }
],
"content": {
"items": "data/items.json",
"buffs": "data/buffs.json"
}
}| Field | Required? | What it means | Allowed values |
|---|---|---|---|
format | Yes | Version of the file format | Always 1 |
id | Yes | The mod’s id, a name no other mod shares | See "Naming rules" below |
name | Yes | The mod’s display name | 1 to 128 characters |
names | No | The name in other languages | For example { "zh-TW": "...", "zh-CN": "..." }; language codes look like en or zh-TW |
version | Yes | Version number | Numbers separated by dots, like 1.0.0, up to four parts. See "Versions" below |
author | No | Author name | Up to 64 characters |
description, descriptions | No | A short summary, and other-language versions | Up to 1000 characters |
gameApi | Yes | Which version of the game’s mod interface you need | Write { "min": 1 } for now |
scope | Yes | Who has to install the mod | client, host, everyone. See "Scope" below |
dependsOn | No | Other mods that must be installed first | Up to 16. See "Dependencies" below |
options | No | Choices the host makes when creating a world | Up to 32. See "Options" below |
content | Yes | File paths of the content tables, all optional | items recipes dishes fish crops buffs loot rules patches species spawns directorEvents dialogue quests blueprints, each a .json path. Also i18n (language to file) and script (a .js path) |
Naming rules#
- Mod id (
id): 3 to 32 characters, starting with a lowercase letter, using only lowercase letters, digits and underscores, and never two underscores in a row (__). Do not change it after publishing; a changed id is a different mod. - Entry ids (the
idof each item, recipe, buff and so on) are called local ids: they start with a lowercase letter or digit, use only lowercase letters, digits and underscores, and are up to 48 characters, such asfrost_blade. - The game adds your mod id for you. After loading,
frost_bladeis reallyfrost_pack__frost_blade, so it can never clash with another mod. Always write just the local id. Never writefrost_pack__yourself, and do not put__inside a local id. - An id cannot repeat within one file, and different kinds of thing (items, recipes, dishes and so on) each have their own set of names.
When a data file points at something (a recipe’s material, a dropped item, a quest target) there are three ways to write it:
| Written as | Meaning |
|---|---|
frost_blade | First look for this local id in your own mod; if it is not there, treat it as a base game id (such as iron_ore or wood) |
iron_ore | A base game id. Base game creature ids are in capitals (ZOMBIE, FROST_WOLF), item ids are lowercase |
@icepack/frost_shard | frost_shard from another mod, icepack. That mod must be listed in your dependsOn |
Versions#
A version is numbers separated by dots, up to four parts, such as 1, 1.2, 1.2.3 or 1.2.3.4. Versions are compared part by part as numbers, so 1.10 is newer than 1.9, and 1.2 equals 1.2.0. Raise version every time you update the mod (for example 1.0.0 to 1.0.1) so subscribers receive the new one.
Dependencies: needing another mod#
If your mod uses things from another mod, list it in dependsOn. Each entry has an id, and may add minVersion (the oldest version you accept) and workshopId (the Steam Workshop item number, written as text, so a missing mod can be subscribed to automatically):
"dependsOn": [
{ "id": "icepack", "minVersion": "1.0.0", "workshopId": "3123456789" }
]- Up to 16 entries. A mod cannot depend on itself, and cannot list the same mod twice.
- If a needed mod is missing, too old or fails to load, your mod is skipped and the game tells you in plain words which one is missing.
- Two mods that need each other cannot be put in order, so neither loads.
- You can only write things like
@icepack/frost_shardfor mods listed independsOn.
Scope: who has to install it#
scope decides whether the people you play with must install the mod:
| `scope` | Name in the game | Meaning |
|---|---|---|
client | Only you | Only changes what you see (for example translations or an interface script). Teammates do not need it |
host | Host only | Only the host needs it. Players who join do not |
everyone | Everyone needs it | Everyone playing together needs the same version and options. It downloads automatically when joining |
Options: let the host tune it#
Options let one mod play in different ways, such as "Frost Blade power" or "Add a whistle". The host picks them when creating a world, and everyone playing uses the same values. Declare them in options in mod.json. There are three types:
| `type` | The player sees | Fields to write | Value |
|---|---|---|---|
toggle | A switch | default | true or false |
number | A number slider | min, max, step (optional), default | A number. min must be below max, default between them, and step no larger than max - min |
choice | A drop-down | choices (1 to 32, each with a value and a label), default | One of the values, which can be text (up to 64 characters) or a number |
| Option field | Required? | What it means | Allowed values |
|---|---|---|---|
key | Yes | The code name that data files use to point at this option | Starts with a letter; only letters, digits and underscores; up to 32 characters; no repeats |
label, labels | Yes | The name the player sees, and other languages | 1 to 64 characters |
hint | No | A line of small print | Up to 200 characters |
type | Yes | The type | toggle number choice |
default | Yes | The default value | Depends on the type, see the table above |
If a chosen option value is not allowed (outside min to max, or not in choices), the game uses the default instead.
Using options in data files: $option and $if#
Any single value in a data file can be replaced with { "$option": "key" }, which is swapped for the value chosen for this world when it loads. An entry in a list can carry "$if", and is dropped completely when the condition is not met:
| Written as | Meaning |
|---|---|
{ "$option": "bladePower" } | Replaced by the value of the option bladePower |
"$if": { "option": "extraWhistle" } | Keep this entry only when the option is on (true) |
"$if": { "option": "tonicBonus", "equals": 12 } | Keep it only when the option equals 12 |
"$if": { "option": "tonicBonus", "notEquals": 4 } | Keep it only when the option does not equal 4 |
In this items table the blade’s attack power follows bladePower, and the whistle only exists when extraWhistle is on. It goes in data/items.json and works with the mod.json above:
[
{
"id": "frost_blade",
"name": "Frost Blade",
"names": { "zh-TW": "霜刃" },
"type": "WEAPON",
"rarity": "RARE",
"color": "#9fd8ff",
"stats": { "power": { "$option": "bladePower" }, "tempo": 8 },
"voxels": [
{ "x": 0, "y": 0, "z": 0, "color": "#3a4a5c" },
{ "x": 0, "y": 1, "z": 0, "color": "#9fd8ff" },
{ "x": 0, "y": 2, "z": 0, "color": "#9fd8ff" }
]
},
{
"$if": { "option": "extraWhistle" },
"id": "frost_whistle",
"name": "Frost Whistle",
"names": { "zh-TW": "霜哨" },
"type": "MATERIAL",
"color": "#cfe8ff",
"voxels": [
{ "x": 0, "y": 0, "z": 0, "color": "#cfe8ff" },
{ "x": 1, "y": 0, "z": 0, "color": "#9fd8ff" }
]
}
]Drop-down options work the same way. In this buffs table, the max health bonus of Frost ward follows tonicBonus (4, 8 or 12), and a stronger extra buff only appears when "Strong" is picked. It goes in data/buffs.json:
[
{
"id": "frost_ward",
"slot": "tonic",
"name": "Frost ward",
"names": { "zh-TW": "霜護" },
"effects": { "maxHpPct": { "$option": "tonicBonus" }, "frostResistPct": 15 }
},
{
"$if": { "option": "tonicBonus", "equals": 12 },
"id": "frost_surge",
"slot": "tonic",
"name": "Frost surge",
"names": { "zh-TW": "霜湧" },
"effects": { "moveSpeedPct": 5 }
}
]Translation files (i18n)#
Most content tables let you write names in each language right in the entry (name and names), so you do not need a translation file. For more text, map languages to files under content.i18n:
"i18n": { "zh-TW": "i18n/zh-TW.json", "en": "i18n/en.json" }A file is a flat list of "key: text". Start every key with <mod id>__ so it cannot clash with the game or another mod. You cannot override the game’s own text; such lines are skipped with a warning:
{
"frost_pack__hello": "Hello, frostlands"
}Common mistakes#
- An
idwith capitals, spaces or non-English letters, or only 1 or 2 characters, or containing__. - A
versionsuch asv1.0or1.0-beta. Only numbers and dots. - A
contentpath that points at a missing file, a content table that is not.json, a script that is not.js, or a path that leaves the folder (../). - An unknown table name inside
content. The game says it is not a known content table. - An option
defaultthat is outside its range or not in its choices. - A file type that is not allowed in the folder (such as
.zip,.exeor a shortcut). - Writing the mod id and
__in front of an entryidyourself.
Related pages#
- Quick start: your first mod in ten minutes.
- Templates: eight starting points with the folder already built.
- Items, Recipes, Rule packs: how to write each content table.
- Multiplayer: how scope and options work in a room.
- Publish: put your mod on the Workshop.