# Overview

The whole dungeon mechanic defined by custom user written scripts. This script system is very flexible and allows you to make every dungeon really unique.

Scripts are executed at specific Events in the dungeon to which they are tied, such as Dungeon Tick, Mob Spawn, Player Death, etc.

Scripts can execute multiple Actions and have various Conditions to run.

As you probably already know, a dungeon has a set of Stages and Levels.

They are listeners of the dungeon events. This means that this is where you will write your scripts - in their config files.

Level scripts are useful (but not necessary!) for global events regardless of the dungeon's stage.

Example:

• Kill Rewards
• Revive Dead Players

You can have multiple levels with scripts in a dungeon, but only current dungeon's level will listen to dungeon's events and execute its scripts.

This means that unless dungeon's level changed using the Set Level script action, the dungeon's Start Level will be used.

Stage scripts are useful (but not necessary!) for dungeon progression, local events, rounds, waves, etc.

Example:

• Stage 1: Zombies
• Stage 2: Spiders
• Stage 3: Boss

You can have multiple stages with scripts in a dungeon, but only current dungeon's stage will listen to dungeon's events and execute its scripts.

This means that unless dungeon's stage changed using the Set Stage script action, the dungeon's Start Stage will be used.

Every Stage and Level config file should have the EventHandlers section. This is where you write your scripts.

Script syntax is pretty simple:

EventHandlers:
  onTick:
    Event: DUNGEON_TICK
    Conditions: {}
    Actions: {}
  onEnd:
    Event: STAGE_FINISHED
    Conditions: {}
    Actions: {}

Let's break down the example above:

• All scripts go under the EventHandlers section.
• The onTick and onEnd are script names. It can be whatever you want, just keep it unique for each script.
• The Event setting defines the dungeon event that will trigger the script.
• The Conditions section defines conditions that can be used in script actions.
• The Actions section defines actions the script will execute.

Script conditions go under the Conditions script's section:

onTick:
  Event: DUNGEON_TICK
  Conditions:
    interval:
      Type: tick_interval
      Interval: 5
    alive_mobs:
      Type: alive_mob_amount
      MobId: 'ada:spider'
      Operator: <=
      Value: 0

• The interval and alive_mobs are condition names. It can be whatever you want, just keep it unique for each condition.
• The Type setting defines condition type.
• Extra condition options go right under the Type setting.

It's not necessary to define conditions for your scripts if not required! You can remove the Conditions section at all or make it empty:

Conditions: {}

Script actions go straight under the Actions script's section:

Actions:
  spawn_zombies:
    Type: spawn_mob
    RunIf: 'my_first_condition || my_other_condition'
    MobId: 'ada:spider'
    SpawnerId: spiders
    Amount:
      Initial:
        Min: 1
        Max: 1
      Scalers:
        PLAYER_AMOUNT:
          Value: 1
          Type: PLAIN

Let's break down the example above:

• The spawn_zombies is an action name. It can be whatever you want, just keep it unique for each action. You can add as many actions as you want.
• The Type setting defines action type.
• The RunIf setting defines a boolean expression with condition names. The action will run only if all conditions are met. You can remove this setting if no conditions are required.
• Extra action options go right under the Type setting.

Full script example:

• onTick script that spawns 1 (+1 per player) spider every 5 dungeon ticks (5 real seconds) if there are no alive spiders.
• onEnd script that marks the dungeon as completed and initializes the end countdown when all stage tasks are completed.

EventHandlers:
  onTick:
    Event: DUNGEON_TICK
    Conditions:
      is_5th_second:
        Type: tick_interval
        Interval: 5
      no_alive_mobs:
        Type: alive_mob_amount
        MobId: 'ada:spider'
        Operator: <=
        Value: 0
    Actions:
      spawn_zombies:
        RunIf: 'is_5th_second && no_alive_mobs'
        Type: spawn_mob
        MobId: 'ada:spider'
        SpawnerId: spiders
        Amount:
          Initial:
            Min: 1
            Max: 1
          Scalers:
            PLAYER_AMOUNT:
              Value: 1
              Type: PLAIN
  onEnd:
    Event: STAGE_FINISHED
    Actions:
      ending:
        Type: dungeon_end
        Countdown: 10
        Victory: true