Docs

Overview

An NPS mod is a folder with a mod.json file at its root. Package the folder contents as .npsmod or .zip for installation.

Mods can use server Python to react to events and work with player data. They can also ship client assets and Lua to replace or extend supported game files and interface behavior.

Quick start

Start with the template, then use the resources bundle when you need game or server references.

The starter template contains a minimal mod.json and one Python file. The resources bundle contains mod_api.py and its dependencies, client Lua, client XML, sample structure and monster .bin files, and the db_structure and db_monster data files.

Layout

mod.json

{
  "id": "my-first-mod",
  "name": "my-first-mod",
  "version": "0.1.0",
  "author": "you",
  "description": "A new NPS mod.",
  "gameVersion": "5.7.0",
  "client": {
    "assets": [],
    "ui": { "buttons": [], "menus": [] }
  },
  "server": {
    "plugins": [],
    "assets": [],
    "python": ["Server/Python/main.py"]
  },
  "permissions": ["server.python"],
  "dependencies": [],
  "enabled": true
}

Keep id unique and stable. Change version when publishing an update so the launcher can offer the new version to players.

Fields

Server API

Python files listed in server.python are loaded by the embedded server. Use event handlers to react to requests and game activity.

import mod_api
from msm_playerdata import load_player, save_player

@mod_api.on_event("command_received")
def on_command(username="", command="", params=None, **_):
    ...  # before the server handles a request

@mod_api.on_event("command_handled")
def on_handled(username="", command="", **_):
    ...  # after the server handles a request

Available event names:

• player_join, player_loaded
• command_received, command_handled, mod_command
• breeding_started, breeding_finished
• fuzing_started, fuzing_finished
• egg_bought, egg_hatched, player_hatch
• monster_collected
• island_bought, structure_bought
• update_properties

Event arguments are passed by keyword. Add **_ or **kwargs to your handler so extra arguments do not break it.

Player data

root, player = load_player(username)   # root is the full save
player["bio"] = "Hello from a mod"
save_player(username, root)            # save the full root object

Currency values have matching _actual fields. The client HUD reads those values first, so use the currency helpers instead of writing a currency field directly.

import mod_api

@mod_api.on_event("mod_command")
def on_mod_command(username="", command="", params=None, player_object=None, **_):
    if (params or {}).get("action") == "give_100k_coins" and player_object is not None:
        mod_api.add_currency(player_object, "coins", 100000)
        mod_api.request_property_update(username)

add_currency and set_currency keep the normal and _actual values in sync. request_property_update updates the HUD immediately. Without it, the saved value is still available after a reload.

Java mods get the property update automatically when using api.commands().addCurrency(...) or setCurrency(...).

Currency keys: coins, diamonds, food, ethereal_currency, keys, relics, egg_wildcards, clubbox_tokens, starpower, and medals.

The launcher setting for functioning currencies controls built in gameplay spending and rewards. It does not block currency changes made directly by a mod.

Player data reference

load_player returns the saved data used by the server. The fields below are documented from the current save format. Saves may contain additional fields.

root and player_object

Island object

Monster object

Structure object

Common event payloads

Events created with mod_api.event(name) include values that are available in the handler that fired them.

Not every event contains every key. Use .get(...) where appropriate and keep a **kwargs catch all in event handlers.

Custom structures & monsters

Adding a structure

structure_id = mod_api.add_new_structure(
    "monument",
    name="NPS Monument",
    description="Tap it, then Collect, for a coin bonus.",
    graphic_file="decoration_birdbath01.bin",
)

The first argument is a key chosen by your mod. NPS maps that key to a stable numeric ID. name is required. Other db_structure fields can be supplied as keyword arguments, for example cost_coins=5000 or view_in_market=1.

Use structure_type="mine" when you want the standard fill timer and ready indicator used by mine type structures.

Adding a monster

monster_id = mod_api.add_new_monster(
    "glimmerbeast",
    common_name="Glimmerbeast",
    genes="DE",
    graphic_file="monster_de.bin",
    view_in_market=1,
    cost_coins=500,
    add_to_island=True,
)

Island Books use a fixed number of slots. Setting add_to_island=True assigns the monster to an existing slot on Plant Island. Pass an island_type integer instead of True to target another island.

Keeping structures in sync

The client keeps a cached copy of structure fields used by the fill bar and ready indicator. After changing one of those fields directly, sync the structure so the client receives the new value.

structure["last_collection"] = 0
mod_api.sync_structure(username, structure, player_object)

sync_structure syncs last_collection by default. Pass additional field names as positional arguments when needed.

allocate_id

my_id = mod_api.allocate_id(namespace, key)

Returns a stable custom numeric ID at or above 9000 for a namespace and key. Structure and monster helpers use this internally. Use it when another custom object also needs a stable ID.

Client to server commands

Lua can send a mod action to the server with the NPS HUD carrier format. Use this for actions such as rewards, cooldown checks, or currency charges.

Client, Lua:

game.setPlayerDisplayName("NPSHUD:<your-mod-id>:<action-name>:<payload>")

The request is intercepted by the server and the original player display name is restored.

Server, Python:

import mod_api

@mod_api.on_hud_prompt("your-mod-id", "action-name")
def _on_action(username="", value="", player_object=None, root=None, **_):
    mod_api.add_currency(player_object, "coins", 500)
    return "Bonus collected: +500 coins."

on_hud_prompt(mod_id, action_id) matches the corresponding NPS HUD prefix. The callback receives username, value, player_object, and root. A returned string is shown as a native popup.

NPS.request - a more direct way to send commands

Every mod script also gets a global NPS table, injected automatically - nothing to require or set up. NPS.request(command, params) sends a real command straight to the server, without the display-name carrier trick:

NPS.request("gs_finish_structure", { user_structure_id = userStructureId })

Three shortcuts for common actions build on top of it:

NPS.official.breed(structureId, leftUserMonsterId, rightUserMonsterId)
NPS.official.finishStructure(userStructureId)
NPS.official.finishObstacle(userStructureId)

Other real globals the same injection provides: NPS.log(message) (writes to the mod's own log), NPS.command(name) and NPS.button(manager, id, image, label, command) (wraps a ContextBar button insert), and a same-process event bus, NPS.on(event, fn) / NPS.emit(event, ...), for one mod's script to react to another's without either knowing about the other's globals.

ContextBar buttons

The ContextBar is the row of buttons shown when a structure or monster is selected. Mods can reuse an unused slot in that row for a custom action.

Button API

ContextBar behavior is defined in assets/scripts/ContextBar.lua. The resources bundle includes the stock scripts and a workflow for decompiling Lua bytecode.

java -jar unluac.jar scripts/ContextBar.lua > ContextBar_decompiled.lua

Structure types use functions such as mine_oninit and sellable_decoration_oninit to configure their button set with methods including setButtonImg, setButtonLabel, setButtonFunction, and changeButton.

Override setup

Point menus/contextbar.xml at your script:

<script src="scripts/nps_context_bar.lua" />

Load the stock module, wrap the function you need, then return the same module.

local ContextBar = include("ContextBar")

local origMineOninit = ContextBar.mine_oninit
ContextBar.mine_oninit = function(element)
  origMineOninit(element)
  local context = game.worldContext()
  local selectedObject = context and context:selectedObject()
  if selectedObject == nil or selectedObject:entityId() ~= YOUR_ENTITY_ID then
    return
  end
  manager:changeButton("btn_sell", "collect_diamond_bag_alone", "MY_LABEL", "my_button_function")
end

function ContextBar.my_button_function(element)
  -- custom action
end

return ContextBar

Available slots for mine type structures

• btn_sell is available when sellable=0.
• btn_upgrade is available when the structure does not use a normal upgrade.

changeButton

manager:changeButton(buttonId, icon, labelKey, functionName)

To use a sprite from another sheet:

manager:setButtonImgWithSheet(buttonId, spriteName, sheetPath)

Sprite names can be found in xml_resources/*.xml by searching for <sprite n="...">.

Confirmation dialog

game.displayConfirmation("MY_CONFIRM_ID", "Are you sure?")

element:SetupGenericListener(game.engineReceiver(), "game::msg::MsgConfirmationSubmission", "gotMyConfirmation")

function ContextBar.gotMyConfirmation(element, msg)
  if msg.choice ~= true then return end
  if msg.messageID == "MY_CONFIRM_ID" then
    -- confirmed
  end
end

Launcher UI

A mod can add a tab under Mods in the launcher drawer. Tabs can contain text, buttons, text fields, file upload controls, images, and dividers. Launcher tabs are defined in Python and require server.python permission.

import mod_api

tab = mod_api.launcher_tab("Better Editor", icon="\U0001F6E0")

def on_click(username, value):
    tab.text("Clicked by " + username + ", form=" + str(value))

def on_upload(username, value):
    tab.text("Got " + value["filename"] + " (" + str(value["size"]) + " bytes)")

@tab.on_open
def build(username):
    tab.text("Welcome, " + username)
    tab.text_field("Note", value="type here")
    tab.button("Click me", on_click=on_click)
    tab.upload_file("Upload a file", on_upload=on_upload)
    tab.divider()
    tab.image("data:image/png;base64,....")

UI calls append elements to the current tab. @tab.on_open clears and rebuilds the tab each time it opens. Use mod_api.cache_get and mod_api.cache_set for data that should persist between visits.

Elements

Client capabilities

client.assets

Client assets replace or add complete files through the game download manifest. Changes are applied when the client starts and downloads the asset.

"client": {
  "assets": [
    { "source": "Client/Assets/menu_templates/some_menu.xml", "target": "assets/menu_templates/some_menu.xml" }
  ]
}

Shipping Lua

Lua is shipped through client.assets. A menu XML selects the Lua file with its <script src="..."/> entry, so a mod can replace that XML and point it at a custom script.

"client": {
  "assets": [
    "Client/Assets/menus/contextbar.xml",
    "Client/Assets/scripts/nps_context_bar.lua"
  ]
}

Custom scripts can load the stock module with include(...), wrap only the functions they need, and return the same module. See ContextBar buttons for an example.

game table

Client Lua can access the same global game table used by stock menu scripts. This includes functions such as game.GetMonster(id) and game.activateBoxMonster(...).

Client events

Stock menus listen for engine events through SetupGenericListener.

self:SetupGenericListener(game.engineReceiver(), "game::msg::MsgPlayerUpdated", "gotMsgPlayerUpdated")

function gotMsgPlayerUpdated(self, msg)
  -- handle the event
end

SetupGenericListener is called on a menu or element instance. It is available when your script wraps an existing menu module and receives that menu instance as self or element.

Permissions

List the capabilities used by the mod in mod.json. Missing required permissions can block installation or prevent the related feature from loading.

Declare the permissions the mod uses and no others.

Reference downloads

The resources bundle contains server and client files useful while building mods.

Cookbook

Small examples for common mod tasks.

Give a reward on login

import mod_api

@mod_api.on_event("player_join")
def on_join(username="", player_object=None, **_):
    if player_object is None:
        return
    mod_api.add_currency(player_object, "coins", 500)
    mod_api.request_property_update(username)

React to a game command

import mod_api

@mod_api.on_event("gs_collect_monster")
def on_collect(username="", params=None, result=None, **_):
    print("collect_monster result:", result)

Show save data in a launcher tab

import json
import mod_api
from msm_playerdata import load_player

tab = mod_api.launcher_tab("My Save", icon="\U0001F4C4")

def on_click(username, value):
    _, player = load_player(username)
    tab.clear()
    tab.text(json.dumps(player, indent=2)[:4000])

@tab.on_open
def build(username):
    tab.button("Dump my save", on_click=on_click)

Structure with a custom ContextBar action

Register the structure in Python:

import mod_api

STRUCTURE_ID = mod_api.add_new_structure(
    "monument",
    name="NPS Monument",
    structure_type="mine",
    graphic_file="decoration_birdbath01.bin",
    cost_coins=5000,
    view_in_market=1,
    extra={"time": 5, "diamonds": 1},
)

@mod_api.on_hud_prompt("your-mod-id", "collect")
def on_collect(username="", value="", player_object=None, root=None, **_):
    mod_api.add_currency(player_object, "coins", 500)
    return "Monument bonus collected: +500 coins."

Trigger the action from the ContextBar Lua:

function ContextBar.nps_collect_monument(element)
  game.setPlayerDisplayName("NPSHUD:your-mod-id:collect:1")
end

Common mistakes

Deploying a mod

Packaging and local installation currently use a zip and copy workflow.

1. Zip the mod contents so mod.json is at the archive root. Name the file <your-mod-id>.npsmod or use a normal .zip extension.
2. Install it through the launcher, or copy it with adb:

   adb push yourmod.npsmod /sdcard/yourmod.npsmod
   adb shell run-as com.nextstars.nps cp /sdcard/yourmod.npsmod files/nps_server/mods/yourmod.npsmod

3. Restart the launcher server after Python changes. Restart the game client after client asset or Lua changes.

Game command reference

This table lists the commands handled by the embedded server, the handler used for each command, and the request parameter names read by that handler. An (inline) entry means the command logic is defined directly in the dispatch table.