New and Modified Level Script Commands

Introduction

KeeperFX has new and updated 'level script commands'. To use the new commands include the LEVEL_VERSION command in your script, or KeeperFX will interpret the level as a classic DK map.

This page can be treated as an addendum to the Dungeon Keeper Script Commands Reference.

KeeperFX Script Parameters and Variables

Players

There are six players in the game. Each has a number and colour.

Player	Player Command	Colour	Number
Player 1 (single player)	PLAYER0	RED	0
Player 2 (enemy)	PLAYER1	BLUE	1
Player 3 (enemy)	PLAYER2	GREEN	2
Player 4 (enemy)	PLAYER3	YELLOW	3
Hero Dungeon	PLAYER_GOOD	WHITE	4
Neutral	PLAYER_NEUTRAL	no colour/multicoloured	5
All Players	ALL_PLAYERS

Neutral is used for creatures and rooms that have not been claimed by any players, e.g. unclaimed Portals and bonus creatures hidden on the level. The name PLAYER_NEUTRAL is added as a new possible player name, but it works only on some specific commands. Use it for example to place units or modify slabs. As Neutral players have no dungeon, you cannot query information relating to the neutral dungeon structure, for example how many neutral units there are.

The player numbers start at 0 and not 1. The [target player] variables found in the script take the number. Other commands accept the 'player command' or 'colour'.

The main (red) player is player 0 and the one you will almost always use for single player games. KeeperFX allows campaigns played from a different perspective, and multiplayer games will have the client players have non-red colours too.

Creatures

All the creatures in the Dungeon Keeper have special names which you have to use when referring to them in the script. The following list shows you their proper name and the script name you should use.

Creatures	Heroes
Name Command Imp IMP Horned Reaper HORNY Skeleton SKELETON Troll TROLL Dragon DRAGON Demonspawn DEMONSPAWN Fly FLY Dark Mistress DARK_MISTRESS Warlock SORCEROR Bile Demon BILE_DEMON Beetle BUG Vampire VAMPIRE Spider SPIDER Hellhound HELL_HOUND Ghost GHOST Tentacle TENTACLE Orc ORC Druid DRUID	Name Command Wizard WIZARD Barbarian BARBARIAN Archer ARCHER Monk MONK Dwarf DWARFA Knight KNIGHT Avatar AVATAR Tunneller Dwarf TUNNELLER Witch WITCH Giant GIANT Fairy FAIRY Thief THIEF Samurai SAMURAI Time Mage TIME_MAGE -- -- -- -- -- -- -- --

The ANY_CREATURE command may be used on [creature] parameters to target a random creature type.

Criterion

There's criteria, to be used on spells like LEVEL_UP_CREATURE, that select a specific creature.

criterion	description
ANYWHERE	Creature anywhere on the level
AT_ACTION_POINT[#]	Unit at specified action point
MOST_EXPERIENCED	Highest level creature
MOST_EXP_WANDERING	Highest level idle creature
MOST_EXP_WORKING	Highest level working creature
MOST_EXP_FIGHTING	Highest level creature in combat
LEAST_EXPERIENCED	Lowest level creature
LEAST_EXP_WANDERING	Lowest level idle creature
LEAST_EXP_WORKING	Lowest level working creature
LEAST_EXP_FIGHTING	Lowest level creature in combat
NEAR_OWN_HEART	Creature close to friendly dungeon heart
NEAR_ENEMY_HEART	Creature close to enemy dungeon heart
ON_ENEMY_GROUND	Creature on enemy tile
ON_FRIENDLY_GROUND	Creature on friendly tile
ON_NEUTRAL_GROUND	Unit on neutral ground, like dirt, water and neutral tiles.

Example:

REM Red units that reach action point 3 turn blue
NEXT_COMMAND_REUSABLE
CHANGE_CREATURE_OWNER(PLAYER0,ANY_CREATURE,AT_ACTION_POINT[3],PLAYER1)

Location

Script commands with the [location] variable, called [where] in the old documentation, accepts the following commands:

Command	Description
Positive number	Action Point of that number
Negative number	Hero Gate with that number
Player name	Dungeon Heart of the player
LAST_EVENT	Last triggered Custom Mystery box or sacrificed unit
COMBAT	The location of the last battle

KeeperFX Command list

ADD_BONUS_TIME

Add or remove turns to the Bonus Level timer. Allows negative values.

ADD_BONUS_TIME([turns])

ADD_GOLD_TO_PLAYER

Allows to add some off-map gold as a reward to a player. Example:

ADD_GOLD_TO_PLAYER(PLAYER0,5000)

ADD_HEART_HEALTH

Restores or drains health from a players Dungeon Heart. Can't exceed the standard max health value.

ADD_HEART_HEALTH([player],[health],[warning])

Where:

[player] - The player’s name, e.g. PLAYER1.

[health] - The hitpoints to restore. Use negative values to take away health. Full heart is 30000 hitpoints.

[warning] - Set to 1 to give a 'heart is under attack' warning when removing hitpoints. Keep it at 0 to do not. You want 0 when you use it against computer players.

ADD_OBJECT_TO_LEVEL

Place any object at a specific place on the map.

ADD_OBJECT_TO_LEVEL([object],[location],[property],[player]*)

Where:

[object] - The object name from fxdata\objects.cfg

[location] - The location you want the object to spawn.

[property] - If the objects has properties, set it. For Gold, it's the amount. If you use SPECBOX_CUSTOM to place the mystery box, it's the box number in the BOX#_ACTIVATED variable.

[player]* - When used it sets the owner of the object. Leave empty or set to PLAYER_NEUTRAL to get unowned object.

ADD_TO_FLAG

Adds a numeric value to the current flag value.

ADD_TO_FLAG([player],[flag],[a])

where:

[player] - The player’s name, e.g. PLAYER1.

[flag] - The flag’s name to which you'll add the value, e.g. FLAG1, CAMPAIGN_FLAG2, BOX0_ACTIVATED

[a] - The amount added. This may be a positive or negative value, e.g. -1

Can be used to count the amount of loops, or give different weights to certain events. The values can be very large and may be negative. Example:

REM Spawn troll 3 times.
IF(PLAYER0,FLAG2 <= 3)
    IF(PLAYER_GOOD,TIMER1 >= 100)
        NEXT_COMMAND_REUSABLE
        ADD_CREATURE_TO_LEVEL(PLAYER0,TROLL,PLAYER0,1,1,0)
        NEXT_COMMAND_REUSABLE
        ADD_TO_FLAG(PLAYER0,FLAG2,1)
        NEXT_COMMAND_REUSABLE
        SET_TIMER(PLAYER_GOOD,TIMER1)
    ENDIF
ENDIF
REM If player has a lair the troll spawns two more times.
IF(PLAYER0,LAIR >= 1)
    ADD_TO_FLAG(PLAYER0,FLAG2,-2)
ENDIF

ADD_TO_PARTY

This command adds a unit to a party, like it did in the original game. It comes with more objectives, and can now be used inside an IF-statement. The party leader - the unit with the highest level, or most power when equal - is the one which will follow an objective, the others will follow the leader.

ADD_TO_PARTY([party name],[creature],[experience],[gold],[objective],[countdown])

These are the possible objectives:

objective	description
ATTACK_DUNGEON_HEART	Attack the nearest Dungeon Heart.
ATTACK_ENEMIES	Attack any enemies.
ATTACK_ROOMS	Attack the nearest rooms.
DEFEND_HEART	Go to own heart and defend it until destroyed.
DEFEND_LOCATION	Never do any objective.
DEFEND_PARTY	Will not do any objective so will not assume party leadership.
DEFEND_ROOMS	Defend nearest owned room, not counting portals, hearts or bridges.
SABOTAGE_ROOMS	Attacks the nearest rooms. Will avoid combat if it can.
SNIPE_DUNGEON_HEART	Attack the nearest Dungeon Heart, and will totally ignore anything else.
STEAL_GOLD	Steal gold from the Treasure Room until unit carries 1000 gold. Will avoid combat if it can.
STEAL_SPELLS	Go to Library and steal one spell book. Will avoid combat if it can.

ADD_TO_TIMER

Add or remove turns to the Script timer. Allows negative values.

ADD_TO_TIMER([player],[timer],[turns])

ALLY_PLAYERS

Sets up an alliance between two players. The difference to original DK is that this command takes 3 parameters - 2 are players, and third one is the status of the alliance. Note that computer players will not break the alliance by themselves, but human player may do so. So this command is mostly for controlling the computer players behavior. Example:

ALLY_PLAYERS([player],[player],[state])

Where:

[player] - The player’s name, e.g. PLAYER1, which gets the alliance set.

[state] - What happens to the alliance, it can have the following values:

• 0: Players are enemies, but may change that. Computer Players never will.
• 1: Players are allied, but may change that. Computer Players never will.
• 2: Players are enemies, and cannot change this.
• 3: Players are allied, and cannot change this.

Example:

REM The Blue and Green keepers will not attack each other.
ALLY_PLAYERS(PLAYER1,PLAYER2,1)

Note that if you enable KeeperFX commands with LEVEL_VERSION, old ALLY_PLAYERS commands (without the extra parameter) will no longer work. Add a '1' to fix this.

BONUS_LEVEL_TIME

Sets time to be displayed on "bonus timer" - on-screen time field, used mostly for bonus levels. But now this command can be used to show bonus timer in any level, and may show clocktime instead of turns. Setting game turns to 0 will hide the timer.

BONUS_LEVEL_TIME([turns],[clocktime]*)

Where:

[turns] - The amount of game turns the timer will count down from. That's 20 per second.

[clocktime]* - Set to 1 to display the countdown in hours/minutes/seconds. Set to 0 or don't add the param to display turns.

Example:

BONUS_LEVEL_TIME(12000)

CHANGE_CREATURES_ANNOYANCE

Can set, increase or decrease the happiness level of all your units.

CHANGE_CREATURES_ANNOYANCE([player],[creature],[operation],[annoyance])

Where:

[player] - The player’s name, e.g. PLAYER1.

[creature] - The creature name, e.g. BILE_DEMON. Includes ANY_CREATURE.

[operation] - Can be SET, INCREASE, DECREASE, MULTIPLY. SET replaces original value, the other three modify it.

[annoyance] - The value to set/increase/decrease. Check the unit configs (like imp.cfg and horny.cfg) to see useful values.

Example:

REM Warlocks become happy from seeing a vampire sacrificed, other vampires hate it.
IF(PLAYER0,SACRIFICED[VAMPIRE] >= 1)
  CHANGE_CREATURES_ANNOYANCE(PLAYER0,VAMPIRE,INCREASE,1000)
  CHANGE_CREATURES_ANNOYANCE(PLAYER0,SORCEROR,SET,0)
ENDIF

CHANGE_CREATURE_OWNER

Changes the owner of given creature based on given criterion.

  CHANGE_CREATURE_OWNER([player_from],[creature],[criterion],[player_to])

where:

[player_from] - The player who owns creatures to be affected.

[creature] - Creature model to be searched.

[criterion] - Creature selection criterion.

[player_to] - The player who will receive the creature.

Example:

REM If the player has too many heroes in his army, the barbarians will escape when possible.
IF_CONTROLS(PLAYER0,GOOD_CREATURES >= 20)
	NEXT_COMMAND_REUSABLE
	CHANGE_CREATURE_OWNER(PLAYER0,BARBARIAN,ON_ENEMY_GROUND,PLAYER_GOOD)
ENDIF

CHANGE_SLAB_OWNER

Changes the owner of a slab on the map to specified player. If it's part of a room, the entire room changes owner. Will change PATH to PRETTY_PATH.

  CHANGE_SLAB_OWNER([slab x pos],[slab y pos],[player],[fill]*)

where:

[slab x pos][slab y pos] - The x and y coordinates of the slab. Range 0-85.

[player] - The player’s name, e.g. PLAYER1, of the new owner of the slab/room

[fill]* - Optional value, which can be set to:

• NONE - The default, no matching of slabs, but will take entire room on ownership
• MATCH - Replace only slabs of same type
• FLOOR - Replace all slabs of the same type, and all adjacent attached floor slabs
• BRIDGE - Like Floor, but include bridges and floor attached by the bridges

Example:

REM If the player has stolen his allies room, just give it back.
IF_SLAB_OWNER(30,65,PLAYER0)
	NEXT_COMMAND_REUSABLE
	CHANGE_SLAB_OWNER(30,65,PLAYER1)
ENDIF

CHANGE_SLAB_TYPE

Changes a slab on the map to the specified new one. It will not change an entire room, just a single slab.

  CHANGE_SLAB_TYPE([slab x pos],[slab y pos],[slab],[fill]*)

where:

[slab x pos],[slab y pos] - The x and y coordinates of the slab. Range 0-85.

[slab] - The name of the new slab. Take if from fxdata\terrain.cfg.

[fill]* - Optional value, same as on CHANGE_SLAB_OWNER

Example:

REM Break open the unbreakable wall when the player reaches the first objective.
IF_ACTION_POINT(1,PLAYER0)
	CHANGE_SLAB_TYPE(13,44,PRETTY_PATH)
ENDIF

COMPUTE_FLAG

Modifies flag's value based on variables or other flags and values.

COMPUTE_FLAG([player],[flag],[operation],[src_player],[src_var],[alt])

where:

[player] - The player’s name, e.g. PLAYER1.

[flag] - The flag’s name to which you'll set the value.

[operation] - Can be SET, INCREASE, DECREASE, MULTIPLY. SET replaces original value, the other three modify it.

[src_player] - The arg/source player’s name, e.g. PLAYER1.

[src_var] - Source variable which will be set/added/etc to [flag]

[alt] - If set to 1, creature flags will be interpreted as in IF_CONTROLS and rooms/doors/traps as in IF_AVAILABLE. Set it to 0 and it takes the value as IF uses it.

Example:

   REM PLAYER0 gets a skeleton for every bile demon he has
   COMPUTE_FLAG(PLAYER0,FLAG1,SET,PLAYER0,BILE_DEMON,0)
   IF(PLAYER0,FLAG1 > 1)
	NEXT_COMMAND_REUSABLE
	ADD_CREATURE_TO_LEVEL(PLAYER0,SKELETON,PLAYER0,1,1,0)
	NEXT_COMMAND_REUSABLE
	ADD_TO_FLAG(PLAYER0,FLAG1,-1)
   ENDIF

COMPUTER_DIG_TO_LOCATION

Makes a computer player dig somewhere.

COMPUTER_DIG_TO_LOCATION([player],[origin],[destination])

Where:

[player] - The player’s name, e.g. PLAYER1.

[origin] - The origin location, e.g. PLAYER1 or 1 to go from an action point.

[destination] - The location to dig to, e.g. PLAYER0.

CONCEAL_MAP_RECT

Conceals part of the map with fog of war, opposite to REVEAL_MAP_RECT

CONCEAL_MAP_RECT([Player], [x], [y], [Width], [Height], [hide revealed]*)

where: [player] - The player’s name, e.g. PLAYER1.

[x,y] - Coordinates of area center point. In subtiles (range is 1..254).

[width] - The width of the area in subtiles

[height] - The height of the area in subtiles

[hide revealed]* is optional, but set to 1 or ALL also hides rocks, gems and gold. On 0 it conceals slabs that are concealed at map start.

COUNT_CREATURES_AT_ACTION_POINT

Saves the number of creatures of a specific player to a flag. Best used in a loop to keep track and trigger a condition when a certain min or max amount is reached.

COUNT_CREATURES_AT_ACTION_POINT([action_point],[player],[creature],[player],[flag])

Where:

[action_point] - Action point number.

[player] - The player’s name, e.g. PLAYER1, who owns the creature.

[creature] - The creature name, e.g. BILE_DEMON. Includes ANY_CREATURE.

[player],[flag] - The flag’s name to which you'll add the value, e.g. FLAG1, CAMPAIGN_FLAG2, BOX0_ACTIVATED

CREATE_EFFECT

Create an Effect at a location.

CREATE_EFFECT([effect],[location],[height]*)

[effect] - The effect to spawn. Can be any effect or effect element that is in game, like the hearts that appear when healing, or the red smoke when claiming a room.
Positive numbers are Effects, Negative numbers are Effect Elements. Also accepts the names as provided in effects.toml

[location] - The location] where the view should be centered if the player clicks on the "zoom to" icon on the Message Panel. It can have the same values as in DISPLAY_INFORMATION command.

[height]* - The z-position of the effect. However, when using -41 as the 'effect' parameter, this is the gold amount displayed instead.

CREATE_EFFECT_AT_POS

Create an Effect at a subtile.

CREATE_EFFECT_AT_POS([effect],[x],[y],[height]*)

[effect] - The effect to spawn. Can be any effect or effect element that is in game, like the hearts that appear when healing, or the red smoke when claiming a room.

[x,y] - Coordinates of area center point. In subtiles (range is 1..254).

[height]* - The z-position of the effect. However, when using -41 as the 'effect' parameter, this is the gold amount displayed instead.

CREATE_EFFECTS_LINE

Spawns an effect multiple times, forming a line.

CREATE_EFFECTS_LINE([origin],[destination],[curvature], [distance], [speed], [effect])

Where:

[origin] - The origin location, where the first effect spawns. E.g. PLAYER1 or 1 to go from an action point.

[destination] - The location where the line is drawn towards.

[curvature] - 0 to go in a straight line, with bigger values to get a bigger curve. At 64 if you go from the the central top slab to the central bottom slab of a square room, it will go clockwise through the outer right slab. Use negative values to go counter-clockwise.

[distance] - How far apart the effects forming the line are. Where 24 spawns effects a single slab apart

[speed] - The delay between effects. The number represents 'number of effects per 4 game turns', set it to '2' to spawn 10 effects per second. Use 0 to spawn all effects at once. Max value is 127.

[effect] - The effect to spawn. Can be any effect or effect element that is in game, like the hearts that appear when healing, or the red smoke when claiming a room. Also accepts the names as provided in effects.toml

CREATURE_AVAILABLE

Tells the game whether a creature of specific kind can come through that player's Portal. Parameters of this command are changed to original, and now look like this:

  CREATURE_AVAILABLE([player],[creature],[can be attracted],[amount forced])

where:

[can be attracted] - If set to 1, it is possible to attract the creature, either by rooms or by forced attraction. (so it works like 4th parameter in original command).

[amount forced] - Amount of creatures of that kind which can be force-attracted (attracted even if player doesn't have rooms required by that creature). Originally there was no possibility to skip attraction conditions.

CREATURE_ENTRANCE_LEVEL

Sets the level at which units come from the portal.

CREATURE_ENTRANCE_LEVEL ([player],[level])

DELETE_FROM_PARTY

Removes a unit from a defined party. Use it before the party is added to the level. When two equal units are in the party, the one that was first added will be deleted.

DELETE_FROM_PARTY([party_name], [creature], [level])

where:

[party_name] - The name as defined with the CREATE_PARTY command

[creature] - Creature model to be searched.

[level] - The experience level of the unit that is to be removed.

DISPLAY_COUNTDOWN

Displays on screen how long a specific script timer reaches the target turn.

  DISPLAY_COUNTDOWN([player], [timer], [target], [clocktime]*)

Where:

[player] - The player’s name, e.g. PLAYER1.

[timer] - The timer’s name. Each player has their own set of eight timers to choose from.

[target] - Show the difference between the current timer value, and the target timer value.

[clocktime] - Set to 1 to display the countdown in hours/minutes/seconds. Set to 0 or don't add the param to display turns.

DISPLAY_INFORMATION

Displays one of the text messages from language-specific strings banks in an Information Box. Each Information Box stacks over previous messages, and can be removed by right clicking. It disappears automatically some time after has been read.

  DISPLAY_INFORMATION([a],[location])

where:

[a] - The number of the message, assigned to it in .po or .pot translation file.

[location] - Location where the view should be centered if the player clicks on the "zoom to" icon on the Message Panel. It can now have the following values:

• PLAYERx - zoom to player's dungeon heart
• positive integer - zoom to Action Point of given number
• negative integer - zoom to Hero Gate of given number
• ALL_PLAYERS - zoom button will be inactive

DISPLAY_MESSAGE

Displays one of the text messages from language-specific strings banks as a chat message, with a specific unit or player shown as the sender. It disappears automatically after some time.

  DISPLAY_MESSAGE([a], [icon])

where:

[a] - The number of the message, assigned to it in .po or .pot translation file.

[icon] - The name of the Creature or Player that is shown as the sender of the message. Accepts 'None' for no icon.

DISPLAY_OBJECTIVE

Displays one of the text messages from language-specific strings banks in an Objective Box. Each Objective Box replaces previous one, and cannot be removed from the messages list. It removes itself only after level is won or lost.

  DISPLAY_OBJECTIVE([a],[location])

where:

[a] - The number of the message, assigned to it in .po or .pot translation file.

[location] - Location where the view should be centered if the player clicks on the "zoom to" icon on the Message Panel. It can have the same values as in DISPLAY_INFORMATION command above.

DISPLAY_TIMER

Displays a script timer on screen.

  DISPLAY_TIMER([player], [timer], [clocktime]*)

Where:

[player] - The player’s name, e.g. PLAYER1.

[timer] - The timer’s name. Each player has their own set of eight timers you can trigger

[clocktime]* - Set to 1 to display the countdown in hours/minutes/seconds. Set to 0 or don't add the param to display turns.

DISPLAY_VARIABLE

Displays a script variable on screen.

  DISPLAY_VARIABLE([player], [variable], [target]*, [target_type]*)

Where:

[player] - The player’s name, e.g. PLAYER1.

[variable] - The variable that is to be exported, e.g. SKELETONS_RAISED

[target]* - If set, it would show the difference between the current amount, and the target amount.

[target_type]* - Can be set to 0, 1 or 2. Set to 0 it displays how much more you need to reach the target, 1 displays how many you need to lose to reach the target, 2 is like 0 but shows negative values too.

DRAWFROM

Is not a command itself but may replace a parameter of most other commands. Replaces the old RANDOM() command.

   DRAWFROM(a,b,c,d,e,f,g,h)

It draws at random one value or number from up to eight parameters. Examples:

    REM Human player will have random start gold between 10000 and 15000
    START_MONEY(PLAYER0,DRAWFROM(10000,11000,12000,13000,14000,15000))
	
    REM One bug type creature will be added to pool
    ADD_CREATURE_TO_POOL(DRAWFROM(FLY,BUG,SPIDER),5)
	
    REM Add one of three predefined Hero parties to Hero gate 6 or 9
    ADD_PARTY_TO_LEVEL(PLAYER0,DRAWFROM(thugs,fiends,dudes),DRAWFROM(-6,-9),1)

It is also possible to draw a value from a range of numbers using a tilde(~). Example:

    REM Spawn a BUG at a random time at the start or near the end of the level
    IF(PLAYER0,TIMER1 >= DRAWFROM(0~12000,72000~108000))
        ADD_CREATURE_TO_LEVEL(PLAYER_GOOD,BUG,-1,1,1,500)
    ENDIF

Ranges can be combined with values. The '~' is a separate parameter. Example:

   DRAWFROM(1~4,6,8~11,13)

A range cannot be used for hero gates, action points or any non-consecutive values.

Value represented by DRAWFROM is selected at start of a map, and never changes during the gameplay.

EXPORT_VARIABLE

Exports a variable to a campaign flag to use in a future campaign level. To be used together with the IMPORT command.

EXPORT_VARIABLE([player],[variable],[flag])

where:

[player] - The player’s name, e.g. PLAYER1. Linked to both the variable and campaign flag.

[variable] - The variable that is to be exported, e.g. BATTLES_WON

[flag] - The flag’s name to which you'll export the variable. Must be a campaign flag, e.g. CAMPAIGN_FLAG1.

Example:

REM Save annoyed creatures of player1 to player1,campaign_flag1 for next level.
NEXT_COMMAND_REUSABLE
EXPORT_VARIABLE(PLAYER1,CREATURES_ANNOYED,CAMPAIGN_FLAG1)

REM Bring over how much gold player 2 has for next level
IF(PLAYER0,ALL_DUNGEONS_DESTROYED == 1)
	EXPORT_VARIABLE(PLAYER2,MONEY,CAMPAIGN_FLAG7)
	WIN_GAME
ENDIF

HEART_LOST_OBJECTIVE

Displays an Objective message when the player lost his Dungeon Heart. Works like DISPLAY_OBJECTIVE.

HEART_LOST_OBJECTIVE([a],[location])

HEART_LOST_QUICK_OBJECTIVE

Displays an Objective message when the player lost his Dungeon Heart. Works like QUICK_OBJECTIVE.

HEART_LOST_QUICK_OBJECTIVE([a],["message"],[location])

HIDE_HERO_GATE

Hides a specific hero gate, so that it can't be seen or heard by the player or by the heroes themselves.

HIDE_HERO_GATE([gate number],[hidden])

Where:
[gate number] - The number of the hero gate to be hidden. Can be positive or negative.

[hidden] - Set to 1 to hide it, and set to 0 to make it visible again.

HIDE_TIMER

Hides the timer that has been made visible with DISPLAY_TIMER

  HIDE_TIMER 

HIDE_VARIABLE

Hides the variable that has been made visible with DISPLAY_VARIABLE

  HIDE_VARIABLE

IF

This is used to test the differences between two values. This could either be a comparison between a variable and a number, or between two variables. If those two values agree with the comparison, the script will continue. If the two values do not agree with the comparison, the script will find the next ENDIF and continue from there.

  IF([player],[variable][comparison][a])
  IF([player],[variable][comparison][player],[variable])

where:

[variable] - The name of a variable, timer, flag (all types), creature, room, trap or door.

• Checking variable returns its value at the moment. Variables are:

variable	description
MONEY	The amount of money the player has
GAME_TURN	The current game turn (player independent)
HEART_HEALTH	The amount of health the dungeon heart of the player has
TOTAL_DIGGERS	The number of special diggers (Imps) that player has got
TOTAL_CREATURES	The number of creatures that player has got
EVIL_CREATURES	The number of evil creatures that player has got
GOOD_CREATURES	The number of heroes that player has got
TOTAL_RESEARCH	The amount of research points that player has got (see manipulating research section for more information)
TOTAL_DOORS	The amount of doors that player has got
TOTAL_DOORS_MANUFACTURED	The amount of doors the player created in the workshop
TOTAL_DOORS_USED	The amount of doors the player placed on the map
TOTAL_TRAPS_MANUFACTURED	The amount of traps the player created in the workshop
TOTAL_TRAPS_USED	The amount of traps the player placed on the map
TOTAL_MANUFACTURED	The amount of traps and doors the player created in the workshop
DOORS_SOLD	How many doors the player sold
TRAPS_SOLD	How many traps the player sold
MANUFACTURE_GOLD	How much gold the player gained through selling traps and doors
MANUFACTURED_SOLD	How many traps and doors the player sold
TOTAL_AREA	The amount of tiles that player owns
TOTAL_CREATURES_LEFT	The amount of creatures that have left that player's dungeon because they were annoyed
TOTAL_SALARY	The amount of salary the player has payed up to this point
CURRENT_SALARY	The current estimated amount of the players next payday
CREATURES_ANNOYED	The number of creatures annoyed in that player's dungeon
TIMES_ANNOYED_CREATURE	The number of times player did something a creature disliked
TIMES_TORTURED_CREATURE	The number of times player placed any creature in torture room
TIMES_LEVELUP_CREATURE	The number of times a creature gained a level in the training room
ACTIVE_BATTLES	The amount of battles going on for the player. Multiple creatures can be part of a single battle.
BATTLES_WON	The number of battles won by that player
BATTLES_LOST	The number of battles lost by that player
ROOMS_DESTROYED	The number of rooms belonging to the player which were sold or destroyed
SPELLS_STOLEN	The number of spells stolen from that player
TIMES_BROKEN_INTO	The number of times that players walls have been breached
DUNGEON_DESTROYED	Whether that players Dungeon Heart has been destroyed (0 if still active, 1 if destroyed)
CREATURES_SCAVENGED_LOST	Number of creatures lost by that player due to scavenging
CREATURES_SCAVENGED_GAINED	Number of creatures gained by that player through scavenging
CREATURES_SACRIFICED	Number of creatures sacrificed in the temple
CREATURES_FROM_SACRIFICE	Number of creatures gained by the player through the temple
CREATURES_CONVERTED	Number of creatures gained by the player through converting in the torture room
EVIL_CREATURES_CONVERTED	Number of creatures gained by the player through converting in the torture room, excluding heroes and imps
GOOD_CREATURES_CONVERTED	Number of heroes gained by the player through converting in the torture room
ALL_DUNGEONS_DESTROYED	Whether all the players Dungeon Hearts has been destroyed (0 if still active, 1 if destroyed) (player independent)
KEEPERS_DESTROYED	The amount of dungeon hearts destroyed by this player
DOORS_DESTROYED	The number of doors belonging to the player which were sold or destroyed
TOTAL_GOLD_MINED	Total amount of gold mined by the player
GOLD_POTS_STOLEN	Number of gold pots that were stolen from the player
BREAK_IN	Amount of break-ins
GHOSTS_RAISED	Number of Ghosts created in torture room
SKELETONS_RAISED	Number of Skeletons created in prison
VAMPIRES_RAISED	Number of Vampires created in graveyard
BONUS_TIME	The current value of the BONUS_LEVEL_TIME timer
BOX#_ACTIVATED	How many times a custom special box with number # has been activated
CREATURES_TRANSFERRED	How many creatures have been send to the next realm
REWARDED[creature]	How many times a specific creature type has been given as a reward from the temple
SACRIFICED[creature]	How many time a creature of a specific type is currently inside the sacrificial pool. Rewards reset it to 0
TOTAL_SCORE	The level score, based on quality of the dungeon and number of creatures

• Checking creature returns how many creatures of that kind a player owns. It doesn't matter if the player can controls them, or they're in custody.
• Checking room returns how many slabs of that room the player owns.
• Checking trap or door availability returns amount of deployed traps and doors owned by that player.
• Checking TIMERx, FLAGx or CAMPAIGN_FLAGx returns its current value.

[player] - The player’s name, e.g. PLAYER1. If ALL_PLAYERS is used, then the condition has to be met for all of the players in order for the commands inside to be executed.

Example:

    IF(PLAYER1,VAMPIRE > PLAYER0,VAMPIRE)
        IF(PLAYER0,VAMPIRE >= 1)
            QUICK_OBJECTIVE(1,"Blue has more vampires than you do. Attack him before scavenging starts")
        ENDIF
    ENDIF

IF_ALLIED

Checks if a player is allied to another player, or tries to be.

IF_ALLIED([player],[target_player][comparison][a])

Where:

[player] - The player’s name, e.g. PLAYER1, who may or may not have an alliance.

[target_player] - The player name that's subject to alliance.

[a] - The value to compare against. Where '0' is not allied and '1' is.

Note that if the Red player clicks the Ally-button of Blue, comparing PLAYER0 to PLAYER1 already evaluates as true, even when blue has not done the same yet. Comparing PLAYER1 to PLAYER0 would still be false. For multiplayer games, check both sides.

Example:

SET_TIMER(PLAYER0,TIMER1)
ALLY_PLAYERS(PLAYER0,PLAYER1,1)

IF_ALLIED(PLAYER0,PLAYER1 == 0)
    QUICK_OBJECTIVE(1,"Blue will not accept this betrayal, prepare for battle.",PLAYER1)
    REM no going back now, lock as enemies
    ALLY_PLAYERS(PLAYER0,PLAYER1,2)
ENDIF
IF_ALLIED(PLAYER0,PLAYER2 == 1)
    IF_ALLIED(PLAYER0,PLAYER1 == 1)
        QUICK_OBJECTIVE(2,"Blue will not accept your alliance with Green, prepare for battle.",PLAYER1)
        REM lock blue as enemy
        NEXT_COMMAND_REUSABLE
        SET_TIMER(PLAYER0,TIMER1)
        ALLY_PLAYERS(PLAYER0,PLAYER1,2)
    ENDIF
    REM lock green as ally
    ALLY_PLAYERS(PLAYER0,PLAYER2,3)
ENDIF

IF(PLAYER0,ALL_DUNGEONS_DESTROYED == 1)
    REM Set on a timer to not win while switching allies.
    IF(PLAYER0,TIMER1 > 60)
        WIN_GAME
    ENDIF
ENDIF

IF_AVAILABLE

Checks availability of an item, and compares it to a second value. That value may be a number or variable. New option values have been added to this command:

  IF_AVAILABLE([player],[variable][comparison][a])
  IF_AVAILABLE([player],[variable][comparison][player],[variable])

where:

[variable] - The name of a creature, room, spell, trap or door.

• Checking creature availability returns how many creatures of that kind can come from portal to that player. The check includes creature pool, players creature limit and whether attraction criteria are met.
• Checking room availability returns whether the room can be built by a player. Cost of the room is not considered.
• Checking spell availability returns whether the spell can be cast by a player. Cost of the spell is not considered.
• Checking trap or door availability returns amount of traps and doors a player has stored, either in workshop or in off-map storage.

Example:

    IF_AVAILABLE(PLAYER0,BOULDER > PLAYER_GOOD,TOTAL_CREATURES)
        QUICK_OBJECTIVE(1,"You have more boulders than there are heroes left. Go make pizza.")
        TRAP_AVAILABLE(PLAYER0,BOULDER,0,0)
    ENDIF

IF_CONTROLS

Checks creatures controlled by a player and compares is to a second value. That value may be a number or variable. Units in an enemy prison are excluded here.

  IF_CONTROLS([player],[variable][comparison][a])
  IF_CONTROLS([player],[variable][comparison][player],[variable])

where:

[variable] - The name of a creature. Returns how many creatures of given kind the player owns, excluding these under enemy control (in custody). Also accepts TOTAL_CREATURES, TOTAL_DIGGERS, EVIL_CREATURES and GOOD_CREATURES. Example:

    IF_CONTROLS(PLAYER0,DRAGON < PLAYER0,DRAGON)
        QUICK_OBJECTIVE(1,"Some of your Dragons are in enemy prison. Rescue them before they get converted.")
    ENDIF

IF_SLAB_OWNER

Checks if a specific slab on the map belongs to specified player.

  IF_SLAB_OWNER([slab x pos],[slab y pos],[player])

where:

[slab x pos][slab y pos] - The x and y coordinates of the slab. Range 0-85.

[player] - The player’s name, e.g. PLAYER1, to check against.

IF_SLAB_TYPE

Checks if a specific slab is of a specific type.

  IF_SLAB_TYPE([slab x pos],[slab y pos],[slab])

where:

[slab x pos][slab y pos] - The x and y coordinates of the slab. Range 0-85.

[slab] - The name of the slab to check for. Take if from fxdata\terrain.cfg.

IMPORT

Like DRAWFROM, it is not a command itself but may replace a parameter of most other commands. At the start of the level it is replaced by the value of the specified campaign flag.

IMPORT([player],[flag])

where:

[player] - The player’s name, e.g. PLAYER0.

[flag] - The flag’s name to which you'll export the variable. Must be a campaign flag, e.g. CAMPAIGN_FLAG1.

Example:

REM Give player 2 the gold he ended with on the previous level
ADD_GOLD_TO_PLAYER(PLAYER2,IMPORT(PLAYER2,CAMPAIGN_FLAG7))

REM Player0 gets no more creatures as he managed to annoy from player1 last level.
MAX_CREATURES(PLAYER0,IMPORT(PLAYER1,CAMPAIGN_FLAG1))

KILL_CREATURE

Kills given amount of creatures based on given criterion.

  KILL_CREATURE([player],[creature],[criterion],[count])

where:

[player] - The player who owns creatures to be affected.

[creature] - Creature model to be searched.

[criterion] - Creature selection criterion.

[count] - Amount of creatures affected.

LEVEL_UP_CREATURE

Levels up given creature based on given criterion.

  LEVEL_UP_CREATURE([player],[creature],[criterion],[levels])

where:

[player] - The player who owns creatures to be affected.

[creature] - Creature model to be searched.

[criterion] - Creature selection criterion.

[levels] - Number of times the unit levels up. Allows negative values.

Example:

REM The Lord that remain inside hero dungeon will level up every 3 minutes
IF(PLAYER_GOOD,TIMER1 >= 3600)
	NEXT_COMMAND_REUSABLE
	LEVEL_UP_CREATURE(PLAYER_GOOD,KNIGHT,ON_FRIENDLY_GROUND,1)
	NEXT_COMMAND_REUSABLE
	SET_TIMER(PLAYER_GOOD,TIMER1)
ENDIF

LEVEL_VERSION

Lets the game know if the level was designed specially for KeeperFX. To use new script commands, you must start the script with LEVEL_VERSION(1). Without it, the new commands will not work properly, and the game will try to emulate old behavior of commands which were modified.

MOVE_CREATURE

Moves given amount of creatures to location based on given criterion.

MOVE_CREATURE([player],[creature],[criterion],[count],[location],[effect]*)

Where:

[player] - The player’s name, e.g. PLAYER1, who owns the creature.

[creature] - The creature name, e.g. BILE_DEMON. Includes ANY_CREATURE.

[criterion] - Creature selection criterion.

[count] - Amount of creatures affected.

[location] - The location you want the creature to be teleported to. Works like other commands and accepts action points, hero gates and players.

[effect]* - The effect to spawn. Can be any effect or effect element that is in game, like the hearts that appear when healing, or the red smoke when claiming a room. When set to 0 it shows no effect, left empty it takes a standard player color specific puff. Positive numbers are Effects, Negative numbers are Effect Elements. Also accepts the names as provided in effects.toml

NEW_CREATURE_TYPE

Adds a new creature type to the creature list, and loads the related config for it. So a creature that is not yet in creatures.cfg.

NEW_CREATURE_TYPE([name])

Where:
[name] - The name of the creature to add. Will load [name].cfg from the (campaign) creatures folder.

Mapmakers can bundle their map with a config and sprite that needs to be placed in the correct folder, but without any need to modify game files.

NEW_OBJECT_TYPE

Adds a new object type to the list of possible objects. One that is not yet in objects.cfg.

NEW_OBJECT_TYPE([name])

Where:
[name] - The name you will define for the object. Used to reference it from now on.

Use the 'SET_OBJECT_CONFIGURATION' script command to then configure everything about the object, and 'ADD_OBJECT_TO_LEVEL' to place it. The script command is processed before other ones, and as such cannot be used inside IF-statements.

Example:

NEW_OBJECT_TYPE(MY_NEW_CRATE)
SET_OBJECT_CONFIGURATION(MY_NEW_CRATE,Genre,WORKSHOPBOX)
SET_OBJECT_CONFIGURATION(MY_NEW_CRATE,AnimationID,114)
SET_OBJECT_CONFIGURATION(MY_NEW_CRATE,AnimationSpeed,256)
SET_OBJECT_CONFIGURATION(MY_NEW_CRATE,MaximumSize,300)
SET_OBJECT_CONFIGURATION(MY_NEW_CRATE,DestroyOnLava,1)
SET_OBJECT_CONFIGURATION(MY_NEW_CRATE,MapIcon,531)
SET_OBJECT_CONFIGURATION(MY_NEW_CRATE,Properties,CHOWNED_ON_ROOM_CLAIM)

NEW_ROOM_TYPE

Adds a new room type to the list of possible rooms. One that is not yet in terrain.cfg.

NEW_ROOM_TYPE([name])

Where:
[name] - The name you will define for the room. Used to reference it from now on.

Use the 'SET_ROOM_CONFIGURATION' script command to then configure everything about the room. It can then be made available to the player like all other rooms. The script command is processed before other ones, and as such cannot be used inside IF-statements.

NEW_TRAP_TYPE

Adds a new trap type to the list of possible traps. One that is not yet in trapdoor.cfg.

NEW_TRAP_TYPE([name])

Where:
[name] - The name you will define for the trap. Used to reference it from now on.

Use the 'SET_TRAP_CONFIGURATION' script command to then configure everything about the trap. It can then be made available to the player like all other traps. The script command is processed before other ones, and as such cannot be used inside IF-statements.

PLAY_MESSAGE

Plays a sound message or sound effect.

PLAY_MESSAGE([player],[type],[sound])

Where:

[player] - The name of the player who gets to hear the sound.

[type] - If it is a sound effect or a speech. Accepts values SPEECH and SOUND. Speeches queue, sounds play at the same time.

[sound] - The sound file to be played. Use numbers(ID's) to play sounds from the original .dat files, or a file name(between parenthesis) to play custom sounds.

Example:

PLAY_MESSAGE(PLAYER0,SPEECH,107)

Example 2:

IF_ACTION_POINT(1,PLAYER0)
	PLAY_MESSAGE(PLAYER0,SPEECH,"you_have_discovered_ruins.mp3")
	PLAY_MESSAGE(PLAYER0,SOUND,"twinkle.wav")
	PLAY_MESSAGE(PLAYER0,SOUND,"wizzing.wav")
ENDIF

When using ID's to playSOUND or SPEECH from the game, or custom sound files, the sounds come from the sound.dat file. Speeches come from the speech_***.dat files, depending on the configured language. Transcripts of the speech-messages can be found here. To hear which sounds are available use the DKSound utility from the DKtools pack.

Bundle custom sounds with the mappack or campaign to have them played. Files need to be placed in the MEDIA_LOCATION as configured in the mappack or campaign configuration file. MP3, Ogg, VOC, FLAC and WAV formats are supported. Be sure to be case sensitive (if you use capitals in the file name, use them in the script) so linux users can also play your map.

QUICK_INFORMATION

Works like DISPLAY_INFORMATION, but instead of using a string from translations, allows to type it directly.

  QUICK_INFORMATION([a],["message"],[location])

where:

[a] - Message slot selection. There are 50 quick message slots, and each message you're making should use a different one. Using one message slot twice will lead to the first message being lost.

["message"] - The message string to be shown in a box. Message length may be up to 1024 characters.

[location] - Location where the view should be centered if the player clicks on the "zoom to" icon on the Message Panel. It can have the same values as in DISPLAY_INFORMATION command.

QUICK_MESSAGE

Works like DISPLAY_MESSAGE, but instead of using a string from translations, allows to type it directly.

QUICK_MESSAGE([a], "[message]", [icon])

where:

[a] - Message slot selection. There are 50 quick message slots, and each message you're making should use a different one. Using one message slot twice will lead to the first message being lost.

[message] - The message string to be shown in a box. Message length may be up to 1024 characters.

[icon] - The name of the Creature or Player that is shown as the sender of the message. Accepts 'None' for no icon.

QUICK_OBJECTIVE

Works like DISPLAY_OBJECTIVE, but instead of using a string from translations, allows to type it directly.

  QUICK_OBJECTIVE([a],["message"],[location])

Parameters have the same meaning as in QUICK_INFORMATION command.

QUICK_INFORMATION_WITH_POS, QUICK_OBJECTIVE_WITH_POS

Accepts additional XY coordinates of the zoom place.

RANDOM

The RANDOM() function of original DK has been replaced by DRAWFROM. This command is currently unimplemented - use DRAWFROM instead.

It is meant to be a function used in same way as DRAWFROM, but selecting value each time during gameplay instead of doing it once at start of the level.

RANDOMISE_FLAG

Gives a flag a true random value. Can be used to get truly random level scripts.

RANDOMISE_FLAG([player],[flag],[max value])

where: [player] - The player’s name, e.g. PLAYER1. See players section for more information.

[flag] - The flag’s name.

[max value] - The flag will get a value ranging from 1 to this max value.

Example:

    REM Spawn a party from a random hero gate every 5 minutes
    SET_TIMER(PLAYER_GOOD,TIMER3)
    IF(PLAYER_GOOD,TIMER3 >= 6000)
	NEXT_COMMAND_REUSABLE
	RANDOMISE_FLAG(PLAYER_GOOD,FLAG3,3)
	IF(PLAYER_GOOD,FLAG3 == 1)
		NEXT_COMMAND_REUSABLE
		ADD_PARTY_TO_LEVEL(PLAYER_GOOD,demo_party,-1,1)
		NEXT_COMMAND_REUSABLE
		SET_TIMER(PLAYER_GOOD,TIMER3)
	ENDIF
	IF(PLAYER_GOOD,FLAG3 == 2)
		NEXT_COMMAND_REUSABLE
		ADD_PARTY_TO_LEVEL(PLAYER_GOOD,demo_party,-2,1)
		NEXT_COMMAND_REUSABLE
		SET_TIMER(PLAYER_GOOD,TIMER3)
	ENDIF
	IF(PLAYER_GOOD,FLAG3 == 3)
		NEXT_COMMAND_REUSABLE
		ADD_PARTY_TO_LEVEL(PLAYER_GOOD,demo_party,-3,1)
		NEXT_COMMAND_REUSABLE
		SET_TIMER(PLAYER_GOOD,TIMER3)
	ENDIF
ENDIF

REMOVE_SACRIFICE_RECIPE

Removes a Temple recipe.

REMOVE_SACRIFICE_RECIPE([creature1],[creature2].....[creature5])

Where [creature2] to [creature5] are only needed when they are used in the recipe.

Example:

IF(PLAYER0,REWARDED[BILE_DEMON] >= 2)
  QUICK_INFORMATION(1, "You have sacrificed enough spiders. No more.", LAST_EVENT)
  REMOVE_SACRIFICE_RECIPE(SPIDER, SPIDER, SPIDER)
ENDIF

IF(PLAYER0,SACRIFICED[IMP] >= 12)
  QUICK_INFORMATION(2, "The gods don't need any more imps.",ALL_PLAYERS)
  REMOVE_SACRIFICE_RECIPE(IMP)
  SET_SACRIFICE_RECIPE(NegUniqFunc,COSTLIER_IMPS,IMP)
ENDIF

RESEARCH

Changes amount of research points needed to discover an item in library. It doesn't affect research order, only amount of points. If the item never was in research list, it's added at end. Example:

    RESEARCH(PLAYER1,MAGIC,POWER_CHICKEN,10000)

RESEARCH_ORDER

When this command is first called, the research list for specified players is cleared. Using it you may create a research list from beginning. Note that if you won't place an item on the list, it will not be possible to research it. So if you're using this command, you must add all items available on the level to the research list. Example:

   RESEARCH_ORDER(ALL_PLAYERS,ROOM,SCAVENGER,50000)
   [...] - more RESEARCH_ORDER commands should follow.

REVEAL_MAP_LOCATION

Reveals square area of subtiles around given location, or the entire open space around it.

  REVEAL_MAP_LOCATION([player],[location],[range])

Location meaning is identical to the one in DISPLAY_OBJECTIVE. Set the [range] to -1 will explore the entire open area from the location, as if your heart stood at that location start of level.

For example, to reveal Hero Gate no.1:

  REVEAL_MAP_LOCATION(PLAYER0,-1,11)

REVEAL_MAP_RECT

Reveals rectangular map area for given player.

  REVEAL_MAP_RECT([player],[x],[y],[width],[height])

where:

[player] - The player’s name, e.g. PLAYER1.

[x,y] - Coordinates of area center point. In subtiles (range is 1..254).

[width] - The width of the area in subtiles

[height] - The height of the area in subtiles

ROOM_AVAILABLE

This command tells the game that a specific room is available for the player to place down.

ROOM_AVAILABLE([player],[room],[can be available],[is available])

Where:

[player] - The player’s name, e.g. PLAYER1. See players section for more information.

[room] - The room’s name, e.g. TEMPLE. See room names section for more information.

[can be available] - This value can be set to 0, 1, 2, 3 or 4.

0. It will not become available at all.
1. The room becomes available through research.
2. The room becomes available when researched or when found on the map.
3. The room may not be researched but becomes available when claimed on the map.
4. The room becomes available for research after claimed on the map.

[is available] - This value should either be 0 or 1. If it is 1 then the room is available straight away. If it is 0 then the room can not be build until the conditions of 'can be available' are met.

RUN_AFTER_VICTORY

Lets the game know the script should continue to run after the game is won. Normally everything stops as soon as the a player wins the map, but include RUN_AFTER_VICTORY(1) in the script to have the game continue normally until the player presses the space bar. Useful if you want to give a player the chance to complete an optional objective you want to bring over to a next campaign level with a CAMPAIGN_FLAG or EXPORT_VARIABLE.

SET_BOX_TOOLTIP

Creates a custom tooltip for Custom special boxes.

SET_BOX_TOOLTIP([boxnumber],"[Custom tooltip]")

Where:

[boxnumber] - The ID of the custom box. With a new ADiKtEd or the ADD_OBJECT_TO_LEVEL command you can set a number. Multiple boxes may have the same number, and they will get the same tooltip and functionality.

[custom tooltip] - The text that will displayed when you hover your mouse over the Special box.

Example:

SET_BOX_TOOLTIP(4, "Cast Rebound on your creatures.")

REM Place a Special box with ID 4 on action point 2.
ADD_OBJECT_TO_LEVEL(SPECBOX_CUSTOM, 2, 4)

SET_BOX_TOOLTIP_ID

Sets a Tooltip on a custom special box, with a text from the language files.

SET_BOX_TOOLTIP([boxnumber],[a])

Where:

[boxnumber] - The ID of the custom box.

[a] - The number of the message, assigned to it in .po or .pot translation file.

SET_COMPUTER_EVENT

SET_COMPUTER_EVENT([player],["event name"],[value3],[param1],[param2],[param3],[param4])

Where:
[player] - The computer player’s name, e.g. PLAYER1.

["event name"] - Text name of the event which is being altered. See fxdata\keepcompp.cfg.

[value3] - Updates the third number listed at Values. (test_interval)

[param#] - Updates the four numbers listed at Params. The first 3 have different meanings for different event types, the 4th one is the gameturn the event has last been used.

Use it to tweak computer player behavior on a per map basis. Example:

REM Blue should not add new rooms when at max capacity beyond 36 tiles
SET_COMPUTER_EVENT(PLAYER1,"EVENT CHECK ROOMS FULL",400,0,0,36,0)

Note that without level_version(1) only Param1 and Param2 can be set.

SET_CREATURE_CONFIGURATION

Allows you to make changes to attribute values set in the unit configuration files. E.g. Imp.cfg.

SET_CREATURE_CONFIGURATION([creature],[attribute],[value],[second value]*)

Where:
[creature] - Creature model to be modified.

[attribute] - The name of the creature property you want to change, as found in the [attributes] or [job] blocks in the unit configs. E.g. SlapsToKill.

[value] - The new value you want to set it to. It accepts the values as used in the config files.

[second value]* - If there are two values to the attribute, use this value.

Use it to tweak creatures on a per map basis. Example:

REM On this level, Bile Demons costs lots of gold and would like to sit back.
SET_CREATURE_CONFIGURATION(BILE_DEMON,Pay,200)
SET_CREATURE_CONFIGURATION(BILE_DEMON,AttackPreference,RANGED)

Note that changing the Health or BaseSpeed will not take immediate action on creatures already on the map.

SET_CREATURE_INSTANCE

Allows you to change which instances creatures learn at which levels.

SET_CREATURE_INSTANCE([creature], [slot], [instance], [level gained])

Where:
[creature] - Creature model to be modified.

[slot] - The spell slot to configure. 1~10.

[instance] - The name of the ability, as listed in creature.cfg. Allows NULL.

[level gained] - The level where the unit acquires the ability.

SET_CREATURE_PROPERTY

SET_CREATURE_PROPERTY([creature],[property],[enable])

Where:
[creature] - The creature name, e.g. BILE_DEMON.

[property] - The name of the creature property you want to set, e.g. NEVER_CHICKENS. See imp.cfg for options.

[enable] - Set this to 1 to enable the property, or 0 to disable to property.

Example:

REM Make sure ghosts don't like farts and imps cannot be brought to the graveyard
SET_CREATURE_PROPERTY(IMP,NO_CORPSE_ROTTING,1)
SET_CREATURE_PROPERTY(GHOST,IMMUNE_TO_GAS,0)

SET_CREATURE_TENDENCIES

Allows to set tendencies: IMPRISON and FLEE, for a player's creatures. Example:

SET_CREATURE_TENDENCIES(PLAYER2,FLEE,1)

Note that a player must have prison when IMPRISON command is triggered; otherwise, it won't make any change.

SET_DOOR

Allows you to lock or unlock a door on a particular slab

SET_DOOR([lock state],[slab x pos],[slab y pos])

where:

[lock state] - Either LOCKED or UNLOCKED

[slab x pos][slab y pos] - The x and y coordinates of the slab. Range 0-85.

SET_DOOR_CONFIGURATION

Allows you to make changes to door values set in trapdoor.cfg. Look in that file for explanations on the numbers.

SET_DOOR_CONFIGURATION([doorname],[property],[value],[second value]*)

Where:
[doorname] - The name of the door as defined in trapdoor.cfg

[property] - The name of the door property you want to change, as found in trapdoor.cfg. E.g. ManufactureRequired.

[value] - The new value you want to set it to. If you want to set the 'Crate' property, you can use both the number or the name from objects.cfg. If you want to set the value of the property named 'Properties', use a number you get by adding up these values:

number	property
1	RESIST_NON_MAGIC
2	SECRET
4	THICK

[second value]* - The SymbolSprites property has 2 values to set. For other properties, do not add this parameter.

Use it to tweak doors on a per map basis. Example:

REM On this level, magic and iron doors do not give much value after several have been sold or destroyed.
IF(PLAYER0,DOORS_DESTROYED > 5)
    SET_DOOR_CONFIGURATION(MAGIC,SellingValue,150)
    SET_DOOR_CONFIGURATION(IRON,SellingValue,100)
ENDIF

SET_FLAG

Sets up a flag that is assigned a number.

SET_FLAG([player],[flag],[a])

Where:

[player] - The player’s name, e.g. PLAYER1.

[flag] - The flag’s name.

[a] - The number assigned to the flag. This can be between -2,147,483,648 and 2,147,483,647.

There's multiple Flag types:

Type	Flag names	Use
FLAG	FLAG0 to FLAG7	The classic flag. Will also be updated by custom sacrifice recipes. Accepts negative and very big numbers now.
CAMPAIGN_FLAG	CAMPAIGN_FLAG0 to CAMPAIGN_FLAG7	Value is not forgotten at the end of a level.
BOX_ACTIVATED	BOX0_ACTIVATED to BOX255_ACTIVATED	Value is updated when you claim a custom special box with the respective number.
SACRIFICED	SACRIFICED[creature]	Shows how many units of the type are currently in the temple pool. Example SACRIFICED[FLY].
REWARDED	REWARDED[creature]	Shows how many units of the type the player has received from the temple.

Example:

IF(PLAYER0,MONEY == 0)
  REM All units get angry now.
  SET_FLAG(PLAYER0,SACRIFICED[VAMPIRE],2)
ENDIF

REM When player found both boxes with number 3, set the campaign flag give a unit on the next level
IF(PLAYER0,BOX3_ACTIVATED >= 2)
  SET_FLAG(PLAYER0,CAMPAIGN_FLAG1,1)
ENDIF

SET_GAME_RULE

Allows you to make changes to door values set in rules.cfg. You can make them conditional with IF statements.

SET_GAME_RULE([rulename],[val1])

Where:
[rulename] - The name of the variable you want to change.

[val1] - The value you want to give it.

• Not all rules are configurable. Only these are:

rulename	description
BodiesForVampire	Number of bodies the graveyard needs to create a vampire
PrisonSkeletonChance	The chance that a dying humanoid in prison creates a skeleton
GhostConvertChance	The chance that a creature dying from torture creates a ghost
TortureDeathChance	The chance a victim broken from torture dies
TortureConvertChance	The chance that a victim that survives being broken, is converted
FoodGenerationSpeed	The speed at which the hatchery produces chickens
StunEvilEnemyChance	The chance to stun a hero when imprisonment is on
StunGoodEnemyChance	The chance to stun a creature when imprisonment is on
BodyRemainsFor	Time before a body disappears and cannot be used for vampires anymore
FightHateKillValue	How much an enemy will hate you for killing a unit. Negative values for love
DungeonHeartHealHealth	How much health dungeon hearts will heal (or lose) per 8 game turns
PreserveClassicBugs	Re-enable bugs long fixed in KeeperFX. Useful for old maps
ImpWorkExperience	Sets experience gain for doing worker tasks
GemEffectiveness	Sets the percentage speed of mining gems instead of gold
RoomSellGoldBackPercent	The percentage of the room price you get back when you sell it
PayDayGap	Game turns between pay days, normally this is 10000 turns, so 500 seconds
PayDaySpeed	The normal speed is 100%, set it to 200 to get twice as much time between pay days
PayDayProgress	Sets how far along you are to payday
DoorSellValuePercent	The percentage of gold the player gets for selling doors
TrapSellValuePercent	The percentage of gold the player gets for selling traps
HungerHealthLoss	How much health units lose when hungry
GameTurnsPerHungerHealthLoss	How often units lose health when hungry
FoodHealthGain	How much health is gained from eating
TortureHealthLoss	How much health is lost from torture
DiseaseHPTemplePercentage	Maximum health percentage when creatures are considered to be put to temple to cure of disease
PlaceTrapsOnSubtiles	Players can fit 9 traps per slab instead of just one
GameTurnsPerTortureHealthLoss	How often health is lost from torture
AlliesShareCta	Players can cast Call to Arms for free on their allies land
AlliesShareDrop	Players can drop creatures on land belonging to their allies
AlliesShareVision	Players gain the vision of their allies
BarrackMaxPartySize	How big a party can be that's created in the Barrack room
MaxThingsInHand	How many creatures and other things the players can hold in their hand
TrainingRoomMaxLevel	To which level the training room can train creatures

• To set PreserveClassicBugs, add up the numbers of the bugs you want to enable

number	bug	explanation
1	RESURRECT_FOREVER	Dead units can be resurrected multiple times with specials
2	OVERFLOW_8BIT	Creature stats when growing past 255 would go to 0 again
4	CLAIM_ROOM_ALL_THINGS	Claiming a room makes spells/crates on it unusable
8	RESURRECT_REMOVED	Fainted Units can be resurrected(copied) with a special
16	NO_HAND_PURGE_ON_DEFEAT	When you die you can hold on to creatures in your hand
32	MUST_OBEY_KEEPS_NOT_DO_JOBS	Creatures refuse jobs they dislike even with Must Obey enabled
64	BREAK_NEUTRAL_WALLS	In possession you can dig through neutral walls
128	ALWAYS_TUNNEL_TO_RED	Heroes will always target the red keeper
256	FULLY_HAPPY_WITH_GOLD	Any creature will be fully happy with any gold given
512	FAINTED_IMMUNE_TO_BOULDER	Fainted units cannot be killed by boulders
1024	REBIRTH_KEEPS_SPELLS	Vampires keep the spells they learned after resurrection
2048	STUN_FRIENDLY_UNITS	Infighting with imprisonment on will not kill your creatures
4096	PASSIVE_NEUTRALS	Neutral units placed in prison or torture room wander out
8192	NEUTRAL_TORTURE_CONVERTS	Neutral torture rooms convert units into neutral units

SET_GENERATE_SPEED

This command tells the game how long to wait before generating a new creature for each player.

SET_GENERATE_SPEED([a])

where:

[a] - The number of game turns between each creature.

The type of creatures that appear cannot be scripted and will depend on the rooms the player has built. It will apply to all Portals on the map. The value can be changed within IF-statements.

Example:

REM ***** Create a new creature for each   *****
REM ***** player every 500 game turns      *****

SET_GENERATE_SPEED(500)

SET_HAND_RULE

Specifies advanced rules to limit picking up units.

SET_HAND_RULE([player],[creature],[rule_slot],[rule_action],[rule]*,[param]*)

Where:

[player] - The player’s name, e.g. PLAYER1.

[creature] - The creature name, e.g. BILE_DEMON. Includes ANY_CREATURE.

[rule_slot] - Rule slot a rule will be assigned to. There are 8 available slots per player's creature type: RULE0, RULE1, ..., RULE7

[rule_action] - ALLOW or DENY. Whether creatures that match the rule should be allowed/denied from being picked up. If you just want to disable or re-enable rule already stored in a slot, use DISABLE or ENABLE and leave the last two params (rule, param) empty.

[rule]* - only specify if rule_action is ALLOW/DENY. One of the following:

• ALWAYS - all creatures match this rule until it is disabled or overridden
• AGE_LOWER/AGE_HIGHER - only creatures whose time in dungeon (age) is lower/higher than [param] match this rule
• LEVEL_LOWER/LEVEL_HIGHER - only creatures of level lower/higher than [param] match this rule
• AT_ACTION_POINT - only creatures within action point [param] radius match this rule
• AFFECTED_BY - only creatures affected by the spell in [param] match this rule
• WANDERING/WORKING/FIGHTING - only creatures with these jobs match this rule

[param]* - rule parameter. See [rule] for usage info. Leave blank if rule does not use any param.

Rule checks are evaluated from the highest rule index (RULE7) to lowest (RULE0) and lower rules are ignored once a match is found.

Example:

IF_ACTION_POINT(4,PLAYER0)
    QUICK_INFORMATION(6,"This is a battle to the death, destroy these units before you proceed",4)
    SET_HAND_RULE(PLAYER0,HORNY,RULE1,DENY,AT_ACTION_POINT,4)
    ADD_CREATURE_TO_LEVEL(PLAYER_GOOD,DWARFA,4,6,5,250)
    SET_FLAG(PLAYER_GOOD,FLAG6,1)
ENDIF
IF(PLAYER_GOOD,FLAG6 == 1)
    IF(PLAYER_GOOD,DWARFA == 0)
        QUICK_INFORMATION(7,"With the dwarves destroyed, pick up horny and prepare for the next battle",4)
        SET_HAND_RULE(PLAYER0,HORNY,RULE1,DISABLE)
    ENDIF
ENDIF

SET_HEART_HEALTH

Set the Dungeon Heart health to a specific value for a player. Must be below the max health of the player.

SET_HEART_HEALTH([player],[health])

SET_MUSIC

Chooses what music track to play

SET_MUSIC([track])

Where:
[track] - The music track to be played. Numbers 2~7 select from original tracks, or a file name(between parenthesis) to set custom music.

Example:

REM Play custom track when the heroes made it into the player dungeon
IF(PLAYER0,TIMES_BROKEN_INTO >= 1)
	SET_MUSIC("high_tension_sonata4.mp3")
	SET_TIMER(PLAYER0,TIMER1)
ENDIF
REM Set it back to track 3 after at least 15 seconds and all fights are over
IF(PLAYER0,TIMER1 > 300)
	IF(PLAYER0,ACTIVE_BATTLES == 0)
		SET_MUSIC(3)
	ENDIF
ENDIF

Bundle custom tracks with the mappack or campaign to have them played. Files need to be placed in the MEDIA_LOCATION as configured in the mappack or campaign configuration file. MP3, Ogg, VOC, FLAC and WAV formats are supported. Be sure to be case sensitive (if you use capitals in the file name, use them in the script) so linux users can also play your map.

Note that if the player does not have the -nocd command line option enabled to play music from disk instead of cd, it will not play custom music files.

SET_OBJECT_CONFIGURATION

Allows you to make changes to object values set in objects.cfg.

SET_OBJECT_CONFIGURATION([objectname],[property],[value])

Where:
[objectname] - The name of the object as defined in objects.cfg .

[property] - The name of the object property you want to change, as found in objects.cfg. E.g. DestroyOnLava.

[value] - The new value you want to set it to. If you want to set the value of the property named 'Properties', use a number you get by adding up these values:

number	property
1	EXISTS_ONLY_IN_ROOM
2	DESTROYED_ON_ROOM_CLAIM
4	CHOWNED_ON_ROOM_CLAIM
8	DESTROYED_ON_ROOM_PLACE
16	BUOYANT
32	BEATING
64	HEART

Use it to tweak objects on a per map basis. Example:

REM On this level gold pots look like gold bags and they can be found at the bottom of water
SET_OBJECT_CONFIGURATION(GOLD,AnimationID,933)
SET_OBJECT_CONFIGURATION(GOLD,DestroyOnLiquid,0)

Can be used to do advanced manipulations too. Example:

REM The red flag needs health when it becomes a dungeon hearth
SET_OBJECT_CONFIGURATION(GUARDFLAG_RED,Health,18000)

REM	Spawn a guard flag at action point 3 to be a backup heart
IF(PLAYER0,TIME_MAGE > 3)
	ADD_OBJECT_TO_LEVEL(GUARDFLAG_RED,1,0,PLAYER0)
	REM The red flag is now a dungeon heart, a beating heart with the update function and 18000 health
	SET_OBJECT_CONFIGURATION(GUARDFLAG_RED,Properties,96)
	SET_OBJECT_CONFIGURATION(GUARDFLAG_RED,UpdateFunction,UPDATE_DUNGEON_HEART)

	REM The soul container is just a regular object
	SET_OBJECT_CONFIGURATION(SOUL_CONTAINER,UpdateFunction,0)
	SET_OBJECT_CONFIGURATION(SOUL_CONTAINER,Health,0)
	SET_OBJECT_CONFIGURATION(SOUL_CONTAINER,Properties,4)
ENDIF

If you have custom sprites, you can use this command to set a custom sprite for an object. If it is rotatable, you could even set the direction. Use the custom sprite name and the wind direction for that. Example:

SET_OBJECT_CONFIGURATION(STATUE5,AnimationID,BANNER:NORTHWEST)

SET_ROOM_CONFIGURATION

Allows you to make changes to room values set in terrain.cfg. Look in that file for explanations on the numbers.

SET_ROOM_CONFIGURATION([roomname],[property],[value],[second value]*,[third value]*)

Where:
[roomname] - The name of the room as defined in terrain.cfg

[property] - The name of the room property you want to change, as found in terrain.cfg. E.g. CreatureCreation.

[value] - The new value you want to set it to. If you want to set roles, you can use numbers instead of names too.

[second value] - Some properties have 2 or more values to set. For other properties, do not add this parameter.

[third value] - Some properties have 3 values to set. For other properties, do not add this parameter.

Use it to tweak rooms on a per map basis.

• To set Roles with numbers, add up the numbers of the role you want to enable.

number	role	description
0	ROOM_ROLE_NONE	Can be used to disable others roles if set as first value.
1	ROOM_ROLE_KEEPER_STORAGE	The room is a storage for keeper soul (dungeon heart).
2	ROOM_ROLE_LAIR_STORAGE	The room is a storage for creature lair totems.
4	ROOM_ROLE_GOLD_STORAGE	The room is a storage for gold.
8	ROOM_ROLE_FOOD_STORAGE	The room is a storage for food for creatures.
16	ROOM_ROLE_CRATES_STORAGE	The room is a storage for crates (trap and door boxes).
32	ROOM_ROLE_POWERS_STORAGE	The room is a storage for keeper powers (spellbooks and specials).
64	ROOM_ROLE_PRISON	The room is a prison, forcing friends and foes to stay within.
128	ROOM_ROLE_DEAD_STORAGE	The room is a storage for dead bodies.
256	ROOM_ROLE_POOL_SPAWN	The room is a spawn point for creatures coming into dungeon from creature pool.
512	ROOM_ROLE_CONDITIONAL_SPAWN	The room is a spawn point for creatures with special spawn conditions programmed.
1024	ROOM_ROLE_SACRIFICE	The room can be used to sacrifice creatures and gain rewards.
2048	ROOM_ROLE_PURIFY_SPELLS	The room can be used to cancel negative spells affecting creatures.
4096	ROOM_ROLE_FOOD_SPAWN	The room is a spawn place for food.
8192	ROOM_ROLE_CRATES_MANUFACTURE	The room is a manufacture place for trap crates.
16384	ROOM_ROLE_RESEARCH	The room is a research place for spellbooks and rooms.
32768	ROOM_ROLE_TORTURE	The room is a torture chamber, allowing torture of friends and foes.
65536	ROOM_ROLE_HAPPY_PRAY	The room makes its workers increase their happiness by praying.
131072	ROOM_ROLE_HEAL_SLEEP	The room makes its workers to heal by sleeping.
262144	ROOM_ROLE_SCAVENGE	The room makes its workers scavenge enemy creatures.
524288	ROOM_ROLE_TRAIN_EXP	The room makes its workers increase their experience by training.
1048576	ROOM_ROLE_MAKE_GROUP	The room makes its workers form a group of creatures.
2097152	ROOM_ROLE_GUARD	The room makes its workers guard the room area for enemies.
4194304	ROOM_ROLE_POOL_LEAVE	The room is a gate which allows a creature to leave the players dungeon back to pool.
8388608	ROOM_ROLE_PASS_WATER	The room is a bridge for use over water.
16777216	ROOM_ROLE_PASS_LAVA	The room is a bridge for use over lava.

SET_SACRIFICE_RECIPE

Creates or modifies a Temple recipe.

SET_SACRIFICE_RECIPE([command],[reward],[creature1],[creature2].....[creature5])

Where:

[command] - The possible commands as listed in the sacrifices section in rules.cfg. Additionally, CUSTOMREWARD and CUSTOMPUNISH may be used. These play the respective sounds, and may increase the flag as configured for the reward parameter.

[reward] - The Creature, Spell or Unique function that is triggered when the Sacrifice completes, as seen in rules.cfg. Use FLAG0-FLAG7 to indicate which flag is raised when a player completes the sacrifice.

[creature1] to [creature5] are creature names, like HORNY. Only the first one is mandatory.

Example:

SET_SACRIFICE_RECIPE(CUSTOMREWARD, FLAG3, WIZARD, MONK)
IF(PLAYER0,FLAG3 >= 1)
  QUICK_INFORMATION(2, "If you give the dark gods wizards and monks, we'll give you gold", ALL_PLAYERS)
  NEXT_COMMAND_REUSABLE
  ADD_GOLD_TO_PLAYER(PLAYER0,666)
  NEXT_COMMAND_REUSABLE
  SET_FLAG(PLAYER0,FLAG3,0)
ENDIF

REM Sacrifice 5 heroes for the avatar to attack from the temple
SET_SACRIFICE_RECIPE(MkGoodHero,AVATAR,KNIGHT,SAMURAI,WIZARD,GIANT,MONK)

SET_TEXTURE

Changes the slabs belonging to a specific player to a custom texture

SET_TEXTURE([player],[texture])

Where:
[player] - The name of the player who's slabs are changed.

[texture] - The name or number of the texture to use for the player, like 'STONE_FACE'. Accepts 'None' or '-1'.

USE_SPELL_ON_PLAYERS_CREATURES

Casts a unit spell on all of a players creatures of a type.

USE_SPELL_ON_PLAYERS_CREATURES([player],[creature],[spell],[spell_level]*)

Where:
[player] - The name of the player who owns the creature, e.g. PLAYER1.

[creature] - Creature model to be searched. Accepts 'ANY_CREATURE'.

[spell] - The spell to cast, use the spell name from fxdata\magic.cfg. You can only use Freeze, Armour, Rebound, Heal, Invisibility, Teleport, Speed, Slow, Fly, Sight, Light, Disease and Chicken.

[spell_level]* - Higher level units cast some spells with more spell power. It's the spells keepers can cast too. For these spells, give the level of the creature, otherwise use 0 or leave it off.

SET_TRAP_CONFIGURATION

Allows you to make changes to trap values set in trapdoor.cfg. Look in that file for explanations on the numbers.

SET_TRAP_CONFIGURATION([trapname],[property],[value],[second value]*,[third value]*)

Where:
[trapname] - The name of the trap as defined in trapdoor.cfg

[property] - The name of the trap property you want to change, as found in trapdoor.cfg. E.g. ManufactureLevel.

[value] - The new value you want to set it to. If you want to set the 'Crate' property, you can use both the number or the name from objects.cfg

[second value] - Some properties have 2 or more values to set. For other properties, do not add this parameter.

[third value] - The ShotVector property has 3 values to set. For other properties, do not add this parameter.

Use it to tweak traps on a per map basis. Example:

REM On this level, alarm traps are replaced by exploding barrels
SET_TRAP_CONFIGURATION(ALARM,Shots,1)
SET_TRAP_CONFIGURATION(ALARM,Model,931)
SET_TRAP_CONFIGURATION(ALARM,TriggerType,2)
SET_TRAP_CONFIGURATION(ALARM,ActivationType,5)
SET_TRAP_CONFIGURATION(ALARM,EffectType,2)
SET_TRAP_CONFIGURATION(ALARM,Hidden,0)

REM And gas traps will hurt you from a distance.
SET_TRAP_CONFIGURATION(POISON_GAS,Shots,5)
SET_TRAP_CONFIGURATION(POISON_GAS,TimeBetweenShots,200)
SET_TRAP_CONFIGURATION(POISON_GAS,TriggerType,3)
SET_TRAP_CONFIGURATION(POISON_GAS,ActivationType,5)
SET_TRAP_CONFIGURATION(POISON_GAS,EffectType,5)

SWAP_CREATURE

Replaces a creature with custom creature. Allows you to replaces for example 'FLY', all preplaced ones and all that will spawn on the level, with a 'SWAMP_RAT', provided 'SWAMP_RAT' was added to 'SwapCreatures' in creature.cfg and a file called 'swamp_rat.cfg' is placed in the creatures folder.

It cannot be used inside IF statements and will do the swap before the level is loaded.

SWAP_CREATURE([new_creature],[creature])

Multiple different new creature types can be added to the creature.cfg file, and any number of existing units can be swapped out, this guarantees there are never more than 32 different kinds on a map, but allows for many more over the course of a campaign. At this point, only sprites (how the creature looks) that are already in the game can be used when making a swap creature config.

Example:

REM Since there are no beetles on the map, swap in a super knight to be used as a landlord
SWAP_CREATURE(LORD,BUG)
SET_CREATURE_PROPERTY(KNIGHT,LORD,0)

REM Spawn the powered up knight as the lord of the land
IF_ACTION_POINT(1,PLAYER0)
	ADD_CREATURE_TO_LEVEL(PLAYER_GOOD,BUG,-1,1,10,0)
ENDIF

TRANSFER_CREATURE

Transfers specific creatures to the next realm.

TRANSFER_CREATURE([player],[creature],[criterion],[count]*)

Where:
[player] - The name of the player who owns the creature, e.g. PLAYER1.

[creature] - Creature model to be searched. Accepts 'ANY_CREATURE'.

[criterion] - Creature selection criterion.

[count] - Amount of creatures transferred.

Can transfer creatures for any player, including heroes. The player must be present on the next level, for units to spawn at the player heart. Heroes may also spawn at a hero gate if there is no hearth, it would use the hero gate with the lowest number.

USE_POWER

Casts an untargeted keeper power through the level script.

USE_POWER([caster_player],[power_name],[free])

Where:
[caster_player] - The player who counts as the casting player. Most spells cannot be cast by PLAYER_GOOD.

[power_name] - The name of the power to cast. E.g. POWER_HOLD_AUDIENCE. Get the names from fxdata\magic.cfg

[free] - When at 0, the price of the power is deducted from the player's gold reserves. At 1 the power is free.

Example:

REM Blue will end the level when at 25 units
IF(PLAYER1,TOTAL_CREATURES >= 25)
  USE_POWER(PLAYER1,POWER_ARMAGEDDON,1)
ENDIF

USE_POWER_AT_LOCATION

Casts a keeper power at specific map location through the level script.

USE_POWER_AT_LOCATION([caster_player],[location],[power_name],[power_level],[free])

Where:
[caster_player] - The player who counts as the casting player.

[location] - The location you want to cast on. Works like other commands and accepts action points, hero gates and players.

[power_name] - The name of the power to cast. E.g. POWER_CAVE_IN. Get the names from fxdata\magic.cfg

[power_level] - The charge level of the power. Range 1-9. Is ignored for powers that cannot be charged.

[free] - When at 0, the price of the power is deducted from the player's gold reserves. At 1 the power is free.

USE_POWER_AT_POS

Casts a keeper power somewhere at the map through the level script.

USE_POWER_AT_POS([caster_player],[subtile_x],[subtile_y],[power_name],[power_level],[free])

Where:
[caster_player] - The player who counts as the casting player.

[subtile_x][subtile_y] - The subtile where the power is cast. Range 1-254.

[power_name] - The name of the power to cast. E.g. POWER_CAVE_IN. Get the names from fxdata\magic.cfg

[power_level] - The charge level of the power. Range 1-9. Is ignored for powers that cannot be charged.

[free] - When at 0, the price of the power is deducted from the player's gold reserves. At 1 the power is free.

Example:

REM If Red has a fortified wall at the breach point, blue will break it with a lvl3 cast of destroy walls
IF_SLAB_TYPE(14,11,DRAPE_WALL)
  USE_POWER_AT_SUBTILE(PLAYER1,44,35,POWER_DESTROY_WALLS,3,1)
ENDIF

USE_POWER_ON_CREATURE

Casts a keeper power on a specific creature. It also accepts non-targeted powers like POWER_SIGHT, which will simply use the location of the unit.

USE_POWER_ON_CREATURE([player],[creature],[criterion],[caster_player],[power_name],[power_level],[free])

Where:
[player] - The name of the player who owns the creature, e.g. PLAYER1.

[creature] - Creature model to be searched.

[criterion] - Creature selection criterion.

[caster_player] - The player which counts as the casting player.

[power_name] - The name of the power to cast. E.g. POWER_HEAL. Get the names from fxdata\magic.cfg.

[power_level] - The charge level of the power. Range 1-9. Is ignored for powers that cannot be charged.

[free] - When at 0, the price of the power is deducted from the players gold reserves. At 1 the power is free.

Example:

REM Stop Red from claiming Blue tiles
IF(PLAYER1,FLAG1 == 1)
  NEXT_COMMAND_REUSABLE
  USE_POWER_ON_CREATURE(PLAYER0,IMP,ON_ENEMY_GROUND,PLAYER1,POWER_CAVE_IN,1,1)
ENDIF

USE_SPECIAL_INCREASE_LEVEL

Actives the effect of an 'Increase Level' dungeon special.

USE_SPECIAL_INCREASE_LEVEL([player],[count])

Where:
[player] - The name of the player who owns the creature, e.g. PLAYER1.

[count] - How many times the special is activated.

USE_SPECIAL_LOCATE_HIDDEN_WORLD

Actives the effect of an 'Locate Hidden World' dungeon special.

USE_SPECIAL_LOCATE_HIDDEN_WORLD

USE_SPECIAL_MULTIPLY_CREATURES

Actives the effect of an 'Multiply Creatures' dungeon special.

USE_SPECIAL_MULTIPLY_CREATURES([player],[count])

USE_SPECIAL_MAKE_SAFE

Actives the effect of an 'Make Safe' dungeon special.

USE_SPECIAL_MAKE_SAFE([player])

USE_SPECIAL_TRANSFER_CREATURE

Opens the transfer creature special menu for the player, allowing the transfer of a creature.

USE_SPECIAL_TRANSFER_CREATURE([player])

Note that the player could - on purpose or by accident - close the menu without transferring a creature. An updated objective will close the menu. Use the CREATURES_TRANSFERRED variable to be sure a creature is transferred.

USE_SPELL_ON_CREATURE

Casts a unit spell on a specific creature. Only abilities with actual spell effects can be used. So Freeze yes, Fireball, no.

USE_SPELL_ON_CREATURE([player],[creature],[criterion],[spell],[spell_level]*)

Where:
[player] - The name of the player who owns the creature, e.g. PLAYER1.

[creature] - Creature model to be searched. Accepts 'ANY_CREATURE'.

[criterion] - Creature selection criterion.

[spell] - The spell to cast, use the spell name from fxdata\magic.cfg. You can only use Freeze, Armour, Rebound, Heal, Invisibility, Teleport, Speed, Slow, Fly, Sight, Light, Disease and Chicken.

[spell_level]* - Higher level units cast some spells with more spell power. It's the spells keepers can cast too. For these spells, give the level of the creature, otherwise use 0 or leave it off.

Example:

REM Freeze the blue dragon.
IF(PLAYER1,FLAG1 == 1)
  USE_SPELL_ON_CREATURE(PLAYER1,DRAGON,ANYWHERE,SPELL_FREEZE,0)
ENDIF

Unreleased

ADD_EFFECT_GENERATOR_TO_LEVEL

Place any Effect Generator at a specific place on the map.

ADD_EFFECT_GENERATOR_TO_LEVEL([effect generator],[location],[range])

Where:

[effect generator] - The effect generator name from effects.toml.

[location] - The location you want the generator to spawn.

[range] - The range within which the generator will spawn effects.

SET_HAND_GRAPHIC

Changes the sprite of the power hand to a different one.

SET_HAND_GRAPHIC([player],[hand])

Where:
[player] - The name of the player who gets the different graphic, e.g. PLAYER1.

[hand] - The name of the hand, as defined in powerhands.toml.

SET_POWER_CONFIGURATION

Makes changes to keeper powers, as originally set in magic.cfg.

SET_POWER_CONFIGURATION([power],[property],[value 1],[value 2/slot/toggle]*)

Where:
[power] - Power model to be modified.

[property] - The name of the power property you want to change, as found in magic.cfg. E.g. 'Castability'.

[value] - The new value you want to set it to. It accepts the values as used in the config files. For 'Properties' and 'Castability' put the value between "quotation marks" if you want to set multiple values at once.

[value 2/slot/toggle]*

• If there are two values to the property, use this value.
• For Power and Cost, there are 9 slots to edit. Enter a value between 1~9 here.
• For Properties and Castability, leave this empty to set [value] as the only value, set to 0 to remove the value from the list of values, set to 1 to add it to the list of values.

Example:

REM Sight no longer shows the progress of the active power
SET_POWER_CONFIGURATION(POWER_SIGHT,Properties,HAS_PROGRESS,0)

REM IF the player has over 50 creatures he can blow them up with time bomb, no longer just imps.
IF(PLAYER0,TOTAL_CREATURES > 50
  SET_POWER_CONFIGURATION(POWER_TIME_BOMB,Castability,"ALL_GROUND OWNED_CRTRS BOUND_CRTRS NEEDS_DELAY")
ENDIF

REM It makes no sense fully charged disease is so expensive, make cheaper
SET_POWER_CONFIGURATION(POWER_DISEASE,Cost,8600,9)