NPC scripts

Your first script

ArdaNPCs 1.1.0 scripts are server events with a limited JavaScript API. A trusted administrator with OP level 2 edits them. CustomNPCs scripts cannot simply be pasted unchanged: event names and exposed objects differ.

1. Open the NPC editor and choose Open scripts….
2. Select interact. Paste only the event body, such as api.message("Welcome!");. Do not add a function interact(e) { ... } wrapper.
3. Use Check to validate every event’s syntax. Test simulates the selected event with the administrator as player; it does not change the world, variables, timers, quests or mail.
4. Enable scripts and click Save. Wait for server confirmation. The enabled setting applies to every event on this NPC.
5. Close the editor and trigger a real interaction. Read output and errors with Output.

A test is not a gameplay check: it uses sample values such as event.timer = "test", so it may skip a branch checking your actual ID. Try these examples in a copy of your world first. If an event already contains code, combine the relevant blocks; pasting over the old text replaces it.

Events and context

Common fields are event.type, npcId, npcName, hasPlayer, playerId and playerName. Use the event. prefix for each. Without a player, the ID is empty; check event.hasPlayer before calling player API. All host types also expose event.hostId, hostKind, hostName and ownerNpcId. The API exposes no Minecraft or Java objects.

Common API reference

Use complete namespaced item, effect and sound IDs, such as minecraft:bread. Variable keys and timer names contain 1–48 characters from [A-Za-z0-9_.:-]. A predicate is read-only; changing data, timers, quests or the world raises an error.

Example: healer with a cooldown

Paste this into interact:

if (!event.hasPlayer) return;
if (api.playerGet("heal_wait") === "1") {
    api.message("Please wait before healing again.");
    return;
}
api.playerSet("heal_wait", "1");
api.timer("heal:" + event.playerId, 30, false);
api.heal(8);
api.message("Your wounds are healing.");

Paste this into the same NPC’s timer event:

if (event.hasPlayer && event.timer === "heal:" + event.playerId) {
    api.playerRemove("heal_wait");
}

The first click heals up to 8 health points (4 hearts). A one-shot timer permits the next heal after 30 game seconds. Its name includes the player UUID, so players do not replace each other’s timers. Delivery waits while the NPC is unloaded or the player is offline. One NPC has at most 16 timers including other scripts; this simple example suits small groups.

Example: XP condition

Paste this into predicate:

return event.key === "experienced"
    && event.hasPlayer
    && api.playerLevel() >= 5;

In a dialog or quest condition, select SCRIPT_PREDICATE and the key experienced. Players at XP level 5 or higher pass. Every execution path must return true or false; do not send messages or write data here. For simple numeric variables, use SCRIPT_VARIABLE_MIN with player:name or npc:name.

Example: a manual quest objective

First create a quest on this NPC and add a MANUAL objective with required count 1. Copy the actual quest and objective IDs from the editor; objective IDs are generated automatically. Replace patrani below with the actual quest ID and stopa_les with the actual objective ID. The player must accept the quest. Paste the adjusted code into interact:

if (api.questProgress("patrani", "stopa_les", 1)) {
    api.message("Recording this clue has been queued.");
} else {
    api.message("You do not need this clue right now.");
}

true means queued, not a confirmed write. Check the quest journal after a real interaction. Inactive or completed objectives and locked SEQUENTIAL steps return false; a missing quest or incorrect objective type is a configuration error. Do not replace actual quest state with a custom “finished” variable.

Example: story mail

Paste this into an NPC’s interact event:

if (api.mail("Invitation", "Return to the keeper for your next task.", "chapter1_invitation")) {
    api.message("Mail queued. Check your inbox.");
}

The stable key prevents repeated delivery for the same NPC and player. false can mean an already-used key, a full inbox or a limit; it is not proof of delivery. The recipient is the event player. Scripted items and blocks need an existing owner NPC for both mail and quest progress.

Persistence and limits

• One event: 12,288 characters; all events: 32,768. One execution: 60,000 instructions. NPCs, items and blocks share server budgets, including 64 events per tick.
• Each NPC/instance or instance + player data scope: 64 keys, 1,024 characters per value and 16,384 characters total. The world supports up to 4,096 scopes.
• 16 timers per host and 1,024 total. Timers use game time, survive restarts and do not accumulate missed repetitions.
• Up to 8 external effects and 2 spawned mobs per event. Additional per-minute quotas limit spam.

Code is saved with the NPC configuration; state and timers live in <world>/data/ardanpcs/scripts-state.json. A clone retains the code but has a new UUID and fresh state. Variables and timers commit before world effects; a server crash between these steps may leave an effect unapplied. This is not a single guaranteed transaction across every system.

A faulty event blocks that host’s scripts. Read diagnostics, fix the error and save again. Do not run unreviewed third-party code: the environment is limited but runs in the server process. Java, files, network access, commands, eval, new constructors and parts of ordinary JavaScript are unavailable. Continue to scripted items and blocks or troubleshooting.