Scripted items and blocks

From program to item

Scripted items and blocks use the same event-body format and API as NPCs. Use the new IDs arda_npcs:script_focus and arda_npcs:script_anchor; retired legacy entries are not working replacements.

1. As an OP level 2 administrator, open the NPC editor and Items and blocks.
2. Choose New, enter a short program ID and name, and select kind item or block. A saved program’s kind is immutable; use a new ID for a different kind.
3. Set the tick interval in seconds (1–3600). Select an event and paste its body without a wrapping function.
4. Use the syntax check and, optionally, Test. Testing does not persist data or apply world, quest or mail effects.
5. Programs start disabled. Enable the program, choose Save and wait for confirmation.
6. Hold exactly one matching script_focus or script_anchor from the ArdaNPCs creative group in your main hand. Use Bind held item. Save all program changes before binding.
7. For a block program, place the assigned block. Binding and placement create verified instances; program source stays on the server.

When programs run

Items in chests, other inventory slots, on the ground or with offline players do not run ticks or timers. Timers wait for an eligible host and any associated player. Blocks do not keep chunks loaded. Item init means first observation of an instance in the server process, not a fresh item every time it is equipped.

api.cancel() consumes a player interaction. Without it, Minecraft may continue from block use to the item’s general use event. The break event reports removal; cancelling there does not restore the breaking block. A broken anchor drops a clean, unassigned item, and its old timers do not transfer to a new placement.

Example: a chime focus

Program kind item, event use:

api.message("The focus glows.");
api.sound("minecraft:block.amethyst_block.chime", 0.4, 1.0);
api.cancel();

Save and bind the program to a script_focus, hold it in your main hand and use it in the air. You hear a sound and receive a message; this example does not create an actual light source.

Example: a chiming block

Program kind block, event place:

api.timer("chime", 30, true);

In the same program’s timer event:

if (event.timer === "chime") {
    api.sound("minecraft:block.amethyst_block.chime", 0.3, 0.8);
}

Bind the program to an anchor and place it. While the block is loaded and the player who placed it is online, it chimes approximately every 30 game seconds. A timer created in place remembers that player, so it waits while they are offline even in a loaded chunk. The timer survives restarts; missed repetitions do not accumulate.

Context and owner NPC

event.hostKind is item or block. event.hostId identifies the instance; event.npcId and npcName are empty for these hosts. Block use adds blockX, blockY, blockZ, blockId and side. Entity use adds text-only targetId, targetType and targetName, not an entity object.

Mail and questProgress require the owner NPC UUID field to reference an existing NPC, plus a current player. The quest must belong to that NPC. Get actual host coordinates with api.hostX(), hostY() and hostZ(); use api.playerX() and its counterparts for the player.

Managing instances

Reload a saved program through the program list. Reload first if a revision conflict occurs. In the instance list, select a UUID to inspect diagnostics or revoke it to stop execution. A real handover preserves item state; a copy receives its own identity and fresh data. Player variables remain separate by player UUID.

The limits are 128 programs and 2,048 issued instances. Source, data, timers and execution/effect quotas follow the shared script limits. Every binding creates a new instance, so do not bind again just to transfer an item between players.