Denizen Scripting

Denizen is the primary scripting engine for TerminaCraft. It drives NPC dialogue, cutscenes, custom items, quests, minigames, region events, and server utilities. Scripts are hot-reloadable without restarting the server.

Script directory layout

All scripts live under server/plugins/Denizen/scripts/:

Directory	What goes here
cutscenes/	Camera sequences (opening, HMS intro, midnight finale, etc.)
dialogue/	NPC dialogue engine and shop data
npc/	Per-NPC behaviour (shops, Clock Town interiors, postman, etc.)
entities/	Custom entity definitions (Tatl, Deku Scrub, generics)
items/	Custom item scripts (hookshot, ocarina, bottles, drops)
minigames/	Minigame logic
mobs/	Mob-specific behaviour
music/	Music trigger scripts
regions/	Region-based event handlers
server/	Server utilities (debug tools, gameplay toggle, etc.)
structures/	Building/structure scripts
tools/	Dev tools (not used in production)

Reloading

/ex reload

Reloads all scripts. You must reload after every edit for changes to take effect. There is no auto-reload.

To run a script interactively without a trigger:

/ex run <script_name>

Gameplay flag guard

Any script that should be paused during build sessions must check the flag at the top of its logic:

my_event_handler:
  type: world
  events:
    after player enters notable:my_region:
      - if <server.flag[gameplay_disabled]> stop
      - ... rest of script

This is a hard convention — skip it and your script will fire during builds, which is disruptive.

Dialogue system

The dialogue system (scripts/dialogue/) uses a custom pixel-width line-length calculator to wrap text correctly with the resource pack font. When writing dialogue:

• Dialogue text lives in dialogue_text.dsc as data scripts — one entry per NPC/event.
• The dialogue engine (dialogue.dsc) handles rendering, input, and branching.
• Shop data is in shops_data.dsc.

Do not hardcode dialogue strings inside behaviour scripts — add them to dialogue_text.dsc and reference them by key.

Cutscenes

Cutscenes use Denizen's camera system combined with entity animations. Structure:

my_cutscene:
  type: task
  script:
    - cinematics start
    - camera <player> to <location> time:40
    - animate <npc> animation:wave
    - wait 40t
    - cinematics end

Existing cutscenes (cutscenes/) are good references — opening.dsc and intro.dsc are the most complete.

Custom items

Item scripts live in items/. The items/actions/ and items/transforms/ subdirectories hold use-action and equip-transform handlers. items/data/ holds static item data (names, lore, material).

To give yourself a custom item in-game:

/ex give player item:<item_script_name>

Flags and data

Denizen flags are the primary persistence mechanism. Use server flags for global state, player flags for per-player state:

- flag server my_flag:true
- flag <player> quest_step:3

Notable flags defined on the server are documented in plugins/Denizen/notables.yml.

Useful references

• Denizen beginner's guide
• Denizen meta documentation
• Depenizen docs — cross-plugin tags (MythicMobs, Citizens, etc.)