Script mods
Use a small piece of JavaScript to react to what happens in the game: chat commands, kill counters, handing out items, spawning creatures. Scripts run in an isolated sandbox and cannot touch your saves.
Scripts are for "when this happens, do that": count a kill, remind the player every morning, give an item when they type a /command. A script cannot add new items or creatures (that is the job of the data tables), but the two work well together.
What a script can do#
- Listen to events: entering a world, every second, a new day, a kill, taking damage, dying, finishing a craft, a chat command.
- Add chat commands: for example
/kills, up to 16 per mod. - Show a notice: one line in the notification feed on the left.
- Read the current state: health, level, position, day, biome and more (read only).
- Give items and spawn creatures: with conditions, see "Calls that change the world" below.
The safety promise#
- No network (
fetch,XMLHttpRequestandWebSocketdo not exist) and no storage (indexedDBandcachesdo not exist). - No code from text: there is no
evalorFunction, andsetTimeoutonly accepts a function. - The data a script receives is frozen and read only, so it cannot change the game from the inside.
fangjie.state()contains no player name or account. - More than 120 messages in one second, 10 errors within 10 seconds, or no answer for more than 2 seconds (an endless loop, for example) stops the mod. You see "The script of mod "name" had an error and was stopped", and the mod list records the reason.
In the editor#
Under Mod in the left column there is a Script page, which only shows up when the mod has a script. If it is not there, press Add new content at the bottom of the left column and pick Script. The editor creates scripts/main.js for you (a small kill counter) and lists it in mod.json.
You do not write code in the game. The page is for reading up and for debugging:
- Script file: shows the current script path. Show in folder or Open folder lets you edit it in an outside editor. Save, then press Test to use the new version.
- Who needs it: explains what the script can do, based on the range you set in Mod info. With the range set to "only me", the script can show hints and add chat commands but cannot give items or spawn creatures. Change range in Mod info jumps there.
- What you can use: the list of events and calls, with a reminder of the limits. Open website docs opens this page.
- Last test play log: what your script printed and any problems from the last test. It stays here after you come back to the editor. Clear log empties it.
While you test, a Script log button sits at the bottom left of the screen. Open it to see what the script prints and any problems as they happen. The number on its right is how many lines there are.
How to add a script#
- 1Write the script file
There is no code editor inside the game. Press Open folder on the Script page of the mod editor and edit
scripts/main.jsin an outside text editor (you can name it differently; 512 KB at most). The only thing it can use is the global objectfangjie. - 2Register it in mod.json
Add
"script": "scripts/main.js"insidecontent, as in the example below. - 3Pick a scope
If the script only changes your own screen or notices, use
"scope": "client"(nobody else needs the mod). Giving items or spawning creatures needshostoreveryone. - 4Try it
After saving the file, press Test in the mod editor. The script starts when you enter a world and stops when you leave it. Changing the mod set reloads the game.
{
"format": 1,
"id": "my_script",
"name": "My script",
"version": "1.0.0",
"gameApi": { "min": 1 },
"scope": "client",
"content": {
"script": "scripts/main.js"
}
}Events: fangjie.on(event, fn)#
You can attach up to 32 functions per event. The data is read only, and coordinates are rounded to whole blocks.
| Event | Data you receive | When it fires |
|---|---|---|
worldEnter | { worldId, modded } | You enter a world, once per entry |
tick | { day, hour } | Once per second; hour runs from 0 to 24 with one decimal |
dayStart | { day } | The first second of a new in-game day |
enemyKilled | { speciesId, x, y, z, byLocalPlayer, isBoss } | A monster dies. Single player and host: every kill is reported, and byLocalPlayer says whether it was you (or your pet). Joiners: you only receive kills the host credited to you, and byLocalPlayer is always true |
playerDamaged | { amount, sourceSpeciesId? } | You actually lose health (hits, damage over time and environment all count; one event per drop in health) |
playerDeath | {} | You die (being downed in multiplayer does not count) |
itemCrafted | { itemId, count } | You finish crafting or cooking |
chat | { text } | You type a line starting with / in chat that no built-in command handled |
Calls#
| Call | What it does |
|---|---|
fangjie.on(event, fn) | Subscribe to an event. |
fangjie.command(name, fn) | Register the chat command /name. Names use lowercase letters, digits and underscores only, 24 characters at most. If the name clashes with a built-in command or another mod it is not added, and the mod list shows why. The function receives (args, text): args is the arguments split on spaces, text is the whole line. At most 16 commands per mod. |
fangjie.notify(text) | Show one line "Mod name: text" in the notification feed. 120 characters at most; after a burst of 3, one per 2 seconds, and extra ones are dropped. |
fangjie.log(...) | Write a line to the mod log (for development). 20 lines per second at most. console.log goes to the same place. |
fangjie.state() | A read-only snapshot of the current state, refreshed every second: inWorld, day, hour, hp, maxHp, level, playerClass, x, y, z, biome, isHost. |
fangjie.options | The options this world picked for your mod (options in mod.json), read only. |
fangjie.giveItem(itemId, count) | Give yourself an item. Has conditions, see below. |
fangjie.spawn(speciesId, position?) | Spawn one creature near you; position is { x, z } and is pulled back to within 24 blocks of the player. Has conditions, see below. |
Calls that change the world#
giveItem and spawn only work when all three of these hold. Otherwise the mod list shows a note and the call does nothing:
- You are in single player, or you are the host of a multiplayer room.
- The mod scope is
hostoreveryone. Aclientmod can only change your own screen. - The id belongs to the base game, or to this mod's own items and creatures (
<modId>__<localId>). Ids from other mods do not work, and bosses cannot be spawned.
Caps: each mod can give at most 64 items and spawn 20 creatures per minute.
Limits and forbidden things#
| Item | Rule |
|---|---|
| Message rate | At most 120 per second, more than that stops the mod |
| Errors | 10 errors within 10 seconds stops the mod |
| No answer | No answer for more than 2 seconds (an endless loop, for example) stops the mod |
| Notices | 120 characters at most; after a burst of 3, one per 2 seconds |
| Log | 20 lines per second at most |
| Giving and spawning | 64 items and 20 creatures per minute at most, spawned within 24 blocks of the player |
| Commands | 16 per mod at most, names up to 24 characters |
| Script size | 512 KB at most |
| Network and storage | No fetch, XMLHttpRequest, WebSocket, importScripts, indexedDB, caches, Worker, notifications or device APIs |
| Code from text | No eval or Function; setTimeout only accepts a function |
Full example: kill counter#
This is the real script from the "Script" template on the Make Mods page. It counts the monsters you defeat, reminds you at the interval chosen in the options, and /kills shows the current number. You can get the whole template on the downloads page.
let kills = 0;
let bosses = 0;
fangjie.on('worldEnter', () => {
kills = 0;
bosses = 0;
});
fangjie.on('enemyKilled', (e) => {
if (!e.byLocalPlayer) return;
kills += 1;
if (e.isBoss) bosses += 1;
const every = Number(fangjie.options.announceEvery) || 0;
if (every > 0 && kills % every === 0) {
fangjie.notify(`已經打倒 ${kills} 隻了! / ${kills} defeated!`);
}
});
fangjie.command('kills', () => {
fangjie.notify(`這次打倒 ${kills} 隻,其中首領 ${bosses} 隻 / Defeated ${kills} (bosses: ${bosses})`);
});Debugging tips#
- To check whether a line runs, use
fangjie.notify("got here"). You see it on screen right away. - For more detail use
fangjie.log(value)orconsole.log. The text goes to the mod log and does not clutter the screen. - Print an event object with
fangjie.log(e)to see which fields it has. - If a command does nothing, look in the mod list for a note about a name clash.
- If the script was stopped after errors, the mod list records the reason, so fix the script accordingly.
notifydrops messages when you send many, so uselogwhen you need to print a lot.- While you test, the Script log at the bottom left of the screen lists what
logprints and any problems the script hits. Back in the editor, Last test play log on the Script page keeps it.