# 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:
      Validate: ALL
      List: {}
    Actions: {}
  onEnd:
    Event: STAGE_FINISHED
    Conditions:
      Validate: ALL
      List: {}
    Actions: {}

Let's break down the example above:

• All scripts go exactly under the EventHandlers section. You can add as many scripts as you want.
• The onTick and onEnd are script names. It can be whatever you want, just keep it unique for each script.
• The Event setting specifies the dungeon event that will trigger the script.
• The Conditions section defines conditions required for the script to run. Can be empty.
• The Actions section defines actions the script will execute when all conditions are met.
• There are no conditions or actions in this example to make it easier for you to learn the basic syntax of the script.

Script conditions go under the Conditions script's section:

Conditions:
  Validate: ALL
  List:
    interval:
      Type: tick_interval
      Interval: 5
    alive_mobs:
      Type: alive_mob_amount
      MobId: 'ada:spider'
      Operator: <=
      Value: 0

Let's break down the example above:

• The Validate setting defines validation type. It can be: ALL, ANY or NONE. So, either all, any or none of the conditions must be met for the script to run.
• Actual conditions go under the List section. You can add as many conditions as you want.
• The interval and alive_mobs are condition names. It can be whatever you want, just keep it unique for each condition.
• The Type setting of the condition defines condition.
• All condition options under the Type are unique per each Condition.

To make script run with no conditions, make the List or Conditions section empty:

Conditions:
  Validate: ALL
  List: {}

Conditions: {}

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

    Actions:
      spawn_zombies:
        Type: spawn_mob
        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:

• You can add as many actions as you want.
• The spawn_zombies is action name. It can be whatever you want, just keep it unique for each action.
• The Type setting of the action defines action.
• All action options under the Type are unique per each Action.

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:
      Validate: ALL
      List:
        interval:
          Type: tick_interval
          Interval: 5
        alive_mobs:
          Type: alive_mob_amount
          MobId: 'ada:spider'
          Operator: <=
          Value: 0
    Actions:
      spawn_zombies:
        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
    Conditions:
      Validate: ALL
      List: {}
    Actions:
      ending:
        Type: dungeon_end
        Countdown: 10
        Victory: true