Mods are a feature of the full game, not the demo. They open when the full game launches, and details may change before then.

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:

text
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#

text
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:

ItemRule
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 filesAt most 200 files per mod
Total sizeAt most 32 MB per mod
One JSON fileAt most 2 MB, and not nested too deeply
Script fileAt most 512 KB
mod.jsonAt most 64 KB
Content pathsRelative 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.

mod.json
{
  "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"
  }
}
FieldRequired?What it meansAllowed values
formatYesVersion of the file formatAlways 1
idYesThe mod’s id, a name no other mod sharesSee "Naming rules" below
nameYesThe mod’s display name1 to 128 characters
namesNoThe name in other languagesFor example { "zh-TW": "...", "zh-CN": "..." }; language codes look like en or zh-TW
versionYesVersion numberNumbers separated by dots, like 1.0.0, up to four parts. See "Versions" below
authorNoAuthor nameUp to 64 characters
description, descriptionsNoA short summary, and other-language versionsUp to 1000 characters
gameApiYesWhich version of the game’s mod interface you needWrite { "min": 1 } for now
scopeYesWho has to install the modclient, host, everyone. See "Scope" below
dependsOnNoOther mods that must be installed firstUp to 16. See "Dependencies" below
optionsNoChoices the host makes when creating a worldUp to 32. See "Options" below
contentYesFile paths of the content tables, all optionalitems 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 id of 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 as frost_blade.
  • The game adds your mod id for you. After loading, frost_blade is really frost_pack__frost_blade, so it can never clash with another mod. Always write just the local id. Never write frost_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 asMeaning
frost_bladeFirst 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_oreA base game id. Base game creature ids are in capitals (ZOMBIE, FROST_WOLF), item ids are lowercase
@icepack/frost_shardfrost_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):

json
"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_shard for mods listed in dependsOn.

Scope: who has to install it#

scope decides whether the people you play with must install the mod:

`scope`Name in the gameMeaning
clientOnly youOnly changes what you see (for example translations or an interface script). Teammates do not need it
hostHost onlyOnly the host needs it. Players who join do not
everyoneEveryone needs itEveryone 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 seesFields to writeValue
toggleA switchdefaulttrue or false
numberA number slidermin, max, step (optional), defaultA number. min must be below max, default between them, and step no larger than max - min
choiceA drop-downchoices (1 to 32, each with a value and a label), defaultOne of the values, which can be text (up to 64 characters) or a number
Option fieldRequired?What it meansAllowed values
keyYesThe code name that data files use to point at this optionStarts with a letter; only letters, digits and underscores; up to 32 characters; no repeats
label, labelsYesThe name the player sees, and other languages1 to 64 characters
hintNoA line of small printUp to 200 characters
typeYesThe typetoggle number choice
defaultYesThe default valueDepends 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 asMeaning
{ "$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:

data/items.json
[
  {
    "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:

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:

json
"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:

i18n/en.json
{
  "frost_pack__hello": "Hello, frostlands"
}

Common mistakes#

  • An id with capitals, spaces or non-English letters, or only 1 or 2 characters, or containing __.
  • A version such as v1.0 or 1.0-beta. Only numbers and dots.
  • A content path 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 default that is outside its range or not in its choices.
  • A file type that is not allowed in the folder (such as .zip, .exe or a shortcut).
  • Writing the mod id and __ in front of an entry id yourself.