AdvancedScriptsMod

📄Overview

Scripts are plain-text .script files placed inside the scripts/ folder at the root of your server directory. Each script runs on its own background thread, so blocking calls like wait() never stall the server. Subdirectories are supported and are used for import paths.

🏷Annotations

Annotations must appear as the very first non-blank, non-comment line of the file.

@PREPARE
# This script runs automatically at server start
print("Server ready!")
global_var = 42

🔣Types & Variables

x = 10
x += 5
items = [1, 2, 3]
items[0] = 99
data = {"hp": 20}
data["hp"] = 18

➕Operators

🔀Control Flow

if / elif / else

if hp < 5:
    print("critical!")
elif hp < 10:
    print("low health")
else:
    print("fine")

for

for i in range(5):
    print(i)
for name, score in [["Alice", 10], ["Bob", 5]]:
    print(name, score)

while / break / continue / pass

count = 0
while count < 3:
    count += 1
    wait(20)

📦Functions

def greet(player, msg="Welcome!"):
    /say {player}: {msg}

def add(a, b):
    return a + b

result = add(3, 4)   # 7

🪄Macros (@macro)

A macro runs inside the caller's scope. Variables assigned inside a macro are set directly on the caller.

@macro
def GIVE_DIAMOND(player):
    /give {player} minecraft:diamond 64
    gave_diamond = True

GIVE_DIAMOND("Steve")
print(gave_diamond)   # True

📥Import System

🔧Preprocessor (#define)

#define MAX_HP 20
#define SPAWN_MSG "Spawning entity now"
hp = MAX_HP        # becomes: hp = 20
print(SPAWN_MSG)

💬F-Strings

name = "Steve"
hp   = 18
msg  = f"Player {name} has {hp} HP ({hp / 20 * 100}%)"
/say Hello, {name}!
/give {name} minecraft:apple {hp * 2}

🌐Scope & global

counter = 0
def increment():
    global counter
    counter += 1
increment()
print(counter)   # 1

🔩Built-in Functions

📋List Methods

📂Dict Methods

🔤String Methods

🗃Database Functions

The script engine includes a lightweight JSON-based key-value store. Each table is a separate file saved at scripts/data/<table>.json. No SQL, no setup — just read and write values by key.

Basic usage

# Write values
db_set("players", "Steve_kills", 42)
db_set("players", "Steve_coins", 100)

# Read values (with optional default)
kills = db_get("players", "Steve_kills")          # 42
coins = db_get("players", "Steve_money", 0)       # 0  (default)

# Existence checks
db_exist("players")                                  # True
db_has("players", "Steve_kills")                    # True

# Enumerate
print(db_keys("players"))                            # ["Steve_kills", "Steve_coins"]
print(db_all("players"))                             # {"Steve_kills": 42, "Steve_coins": 100}
print(db_tables())                                    # ["players"]

# Cleanup
db_delete("players", "Steve_kills")
db_clear("players")                                   # empties the table
db_drop("players")                                    # deletes the file

Example — coin economy

@PREPARE
while True:
    for name in player_list():
        if not db_has("economy", name + "_coins"):
            db_set("economy", name + "_coins", 0)
        coins = db_get("economy", name + "_coins", 0)
        db_set("economy", name + "_coins", coins + 1)
        /tell {name} §6+1 coin! Total: {coins + 1}
    wait(6000)   # 5 minutes

⚔Server Commands

Any line starting with / is executed as a server command (permission level 4). Expressions inside {} are evaluated before execution.

player = "Steve"
/gamemode creative {player}
/give {player} minecraft:diamond_sword 1
/tp {player} 0 64 0

🧍Player Functions

Presence & Count

Stats

Position & Rotation

State Flags

Inventory

🌍World Functions

🖥Server Functions

🧱Block Functions

🐉Entity Functions

All entity functions accept a standard Minecraft entity selector: "@e", "@e[type=zombie]", "@e[limit=1,sort=nearest]", etc.

🗄NBT Snapshots

player_nbt(name) fields

nbt = player_nbt("Steve")
print(nbt["Health"], nbt["XpLevel"])
tag = player_nbt_tag("Steve", "Dimension")

🏆Scoreboard Functions

These functions read and write Minecraft scoreboard objectives and scores directly, without needing to dispatch /scoreboard commands. All target parameters accept either a player name ("Steve") or any entity selector ("@a[tag=active]").

Read & Write

Objective Management

Criteria reference

Example — Setup on server start

@PREPARE
if not score_exists("kills"):
    score_create("kills", "playerKillCount", "☠ Kill Tracker")
score_display("sidebar", "kills")

Example — Milestone title with score_test

while True:
    for p in player_list():
        if score_test(p, "kills", 5, 5):
            /title {p} actionbar [{"text":"5 Kill Streak!","color":"gold","bold":true}]
        if score_test(p, "kills", 25, 25):
            /title {p} title [{"text":"CHAMPION","color":"red","bold":true}]
            /say {p} ha raggiunto 25 kill!
    wait(60)

Example — Leaderboard announce with score_get_all

scores = score_get_all("kills")
best  = None
top   = -1
for p in scores:
    if scores[p] > top:
        top  = scores[p]
        best = p
if best != None:
    /say Leader: {best} with {top} kill!

Example — Reset all scores

for p in player_list():
    score_set(p, "kills", 0)
/say All scores resetted!

Example — Switch sidebar objective

# Hide current sidebar, show deaths instead
score_display("sidebar", "")       # clear
score_display("sidebar", "deaths") # show deaths

🧵Threading & Lifecycle

# /scripts reload  — clears module cache and runs all @PREPARE scripts
# /scripts run events/greet
# /scripts stop events/greet
# /scripts stopall

⚡Module Cache

Imported modules are parsed once and stored in a thread-safe cache. Subsequent import statements reuse the cached module without re-reading the file.

📚Examples

Auto-broadcast & loop

@PREPARE
messages = ["Welcome!", "Visit our Discord!", "Type /help"]
idx = 0
while True:
    /say {messages[idx]}
    idx = (idx + 1) % len(messages)
    wait(1200)

Low-health warning system

def check_players():
    for name in player_list():
        hp = player_health(name)
        if hp < 4:
            /title {name} actionbar {"§cCritical HP: " + str(int(hp)) + "♥"}

while True:
    check_players()
    wait(10)

Entity janitor

MAX_ZOMBIES = 20
while True:
    cnt = entity_count("@e[type=zombie]")
    if cnt > MAX_ZOMBIES:
        /kill @e[type=zombie,sort=furthest,limit={cnt - MAX_ZOMBIES}]
        /say Cleared {cnt - MAX_ZOMBIES} excess zombies.
    wait(600)

Library + importer pattern

# lib/rewards.script
@LIBRARY
def give_starter_kit(player):
    /give {player} minecraft:iron_sword 1
    /give {player} minecraft:bread 16

# welcome.script
from lib.rewards import give_starter_kit
for name in player_list():
    give_starter_kit(name)