Dungeon Keeper Script Commands Reference v1.3

Modified by fans

Contents

Contents

1.0 Introduction to level scripts

1.1 Finding the level script

1.2 Script Layout

1.3 Example Maps

2.0 Script Parameters and Variables

2.1 Game Turns

2.2 Players

2.3 Variables

2.4 Comparisons

2.5 Action Points

2.6 Creature Names

2.7 Room Names

2.8 Door and Trap Names

2.9 Spell Names

3.0 Miscellaneous Commands

3.1 REM

3.2 WIN_GAME

3.3 LOSE_GAME

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

3.5 SET_TIMER([player],[timer])

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

3.7 IF_ACTION_POINT([action point],[player])

3.8 IF_AVAILABLE([player],[name][comparison][a])

3.9 ENDIF

3.10 RESET_ACTION_POINT([action point])

3.11 NEXT_COMMAND_REUSABLE

4.0 Setup Commands

4.1 SET_GENERATE_SPEED([a])

4.2 COMPUTER_PLAYER([player],[a])

4.3 START_MONEY([player],[gold])

4.4 MAX_CREATURES([player],[a])

4.5 ALLY_PLAYERS([player],[player])

5.0 Creatures, Spells, Traps and Doors

5.1 ADD_CREATURE_TO_POOL([creature],[a])

5.2 CREATURE_AVAILABLE([player],[creature],[can be available],[is available])

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

5.4 DOOR_AVAILABLE([player],[door],[can be available],[number available])

5.5 TRAP_AVAILABLE([player],[trap],[can be available],[number available])

5.6 MAGIC_AVAILABLE([player],[spell],[can be available],[is available])

5.7 DEAD_CREATURES_RETURN_TO_POOL([a])

6.0 Manipulating Creatures

6.1 SET_CREATURE_MAX_LEVEL([player],[creature],[max experience])

6.2 SET_CREATURE_STRENGTH([creature],[a])

6.3 SET_CREATURE_HEALTH([creature],[a])

6.4 SET_CREATURE_ARMOUR([creature],[a])

6.5 SET_CREATURE_FEAR([creature],[a])

7.0 Manipulating Research

7.1 Default Research Values

7.2 RESEARCH([player],[research type],[room or spell],[a])

8.0 Adding New Creatures and Parties to the Level

8.1 ADD_CREATURE_TO_LEVEL([player],[creature],[action point],[a],[experience],[gold])

8.2 ADD_TUNNELLER_TO_LEVEL([player],[action point],[head for],[action point/target player],[experience],[gold])

8.3 CREATE_PARTY([party name])

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

8.5 ADD_TUNNELLER_PARTY_TO_LEVEL([player],[party name],[action point],[head for],[action point/target player],[experience],[gold])

8.6 ADD_PARTY_TO_LEVEL([player],[name],[action point],[a])

9.0 Displaying information and affecting interface

9.1 DISPLAY_OBJECTIVE([a],[player])

9.2 DISPLAY_OBJECTIVE_WITH_POS([a],[x],[y])

9.3 DISPLAY_INFORMATION([a])

9.4 DISPLAY_INFORMATION_WITH_POS([a],[x],[y])

9.5 QUICK_OBJECTIVE([a],["objective"],[where])

9.6 QUICK_INFORMATION([a],["information"])

9.7 TUTORIAL_FLASH_BUTTON([button],[player])

9.8 BONUS_LEVEL_TIME([a])

9.9 SET_MUSIC([a])

10.0 Tweaking computer players

10.1 Computer Player Control Parameters

10.2 SET_COMPUTER_PROCESS([player],["process name"],[priority],[data1],[data2],[data3],[data4])

10.3 SET_COMPUTER_CHECKS([player],["checks name"],[check every],[data1],[data2],[data3],[data4])

10.4 SET_COMPUTER_EVENT([player],["event name"],[data1],[data2])

10.5 SET_COMPUTER_GLOBALS([player],[a],[a],[a],[a],[a],[a])

11.0 Script commands index

12.0 Credits

13.0 Changes log

14.0 References

1.0 Introduction to level scripts

To get your map to work in Dungeon Keeper, you will need to script it first. If you do not, the map will not load properly and you will not be able to play it. The script will tell Dungeon Keeper what spells are available on the level, what creatures appear and other settings that are unique to the level.

1.1 Finding the level script

When you first save your level, a number of files are created in the Levels directory. For example, for level 200 (the example map), the following files are created:

Map00200.apt
Map00200.clm
Map00200.dat
Map00200.inf
Map00200.lgt
Map00200.lif
Map00200.own
Map00200.slb
Map00200.tng
Map00200.txt
Map00200.wib
Map00200.wlb

You will notice that there is a .txt file included in the list. This is the script file which you will edit.

If you open it, you will see that it contains many commands which the game uses to create the level. When you have looked at the example script, open the script file of your own level.

1.2 Script Layout

You can enter commands into the script in any order. The script does not run like a proper program or an HTML script. Instead, Dungeon Keeper stores it all in memory. This means that IF commands will be triggered immediately when their conditions are met. Bear this in mind when you are writing your scripts.

The example scripts are laid out in the following way:

This is done to keep the script readable and easy to look at when searching for errors. Although not necessary, it is good practice to keep to this format so others can look at your script without finding it incomprehensible.

Each subsection of this manual has a different theme and you should try and go through each subsection and place the commands into your script in the same order. This is to keep the scripts similar so that other people can reference them easily.

Note: All action commands in the script (such as ADD_PARTY_TO_LEVEL) will only be triggered once. IF commands will keep triggering every time their conditions are met but the commands inside them will only trigger the one time. You will need to use the NEXT_COMMAND_REUSABLE command if you want them to keep triggering.

1.3 Example Maps

Included with the Dungeon Keeper Editor are two example maps that you can use to study and cut and paste from. The single player example map is level 200 and the multiplayer example map is level 201. They are playable levels with as many features included as possible. The script files have been heavily commented using the REM command to explain the script at every step.

2.0 Script Parameters and Variables

This section will describe parameters to script commands available to use in Dungeon Keeper.

Below are a few common references explained:

2.1 Game Turns

A game turn is a counter that counts how many times Dungeon Keeper has run through it’s main loop. The main loop is a series of commands which tells the game to update and then draw everything on the screen. Each time it runs through these instructions, the game turn counter increases by one and the loop is run again.

On slower PCs, the game turns will increase slowly, while on fast machines the game turns will increase faster. To stop the game becoming too fast, there is a limit of 20 game turns a second. Bear these things in mind when you write your script so that timers are balanced on all machines.

If a script command requires number of game turns as a parameter (for example delay before some action), then it must be in range from 0 to 2147483647. The maximum value is equivalent to delay of approx. 3 years, so it should be enough for all cases. To make one minute delay, you should use 1200 game turns.

Note: The limit is 20 turns, not 12 turns how other sources claim.

2.2 Players

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

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.

Note: The player numbers start at 0 and not 1. The main (red) player is player 0 and the one you will always use for single player games.

2.3 Variables

Variables are names that have a number associated with them, e.g. the MONEY variable contains the amount of gold that player has. Most variables in Dungeon Keeper are individual to each player and are constantly updated with the correct information. Some, such as the FLAGS (see SET_FLAG command for more information) need to be created and updated by the script.

The following variables are used by Dungeon Keeper:

Note: Room names, door names, trap names and creature names can also be used as variables for IF statement. Those will return:

2.4 Comparisons

The Comparisons are symbols which you can use to compare two values. These will be mainly used by the IF commands.

Note: If possible, use ‘Less than or equal to’ or ‘Greater than or equal to’ instead of the ‘Equal to’ command because the IF command isn’t checked every game turn. This may cause the game to miss things and therefore cause errors.
For example, instead of asking whether the player has 30 creatures, ask if the player has 30 creatures or more.

2.5 Action Points

Action points are areas of the map that are triggered if a creature steps into it. The Action Point can only be triggered once (unless you use the RESET_ACTION_POINT command) and is player independent so you can only detect which player triggered it.

Each Action Point has a number which you will have to remember. You will use this number in the script.

Hero Gates are special Action Points that act as Portals for Heroes. They do not have trigger areas so you cannot use them as traps, only as entry points for parties or new creatures. Like the Action Points, each Hero Gate has a number and you will need to use this number in the script.

2.6 Creature Names

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.

How you design your level is up to you but when Dungeon Keeper was being developed, it was decided that some creatures should not come through the Portals (although they can be placed on the map for the player to find). The reasons for this are: Ghosts are created when a creature dies on a torture table and Skeletons are created when a creature dies in a Prison. Horned Reapers are only available through a sacrifice in the Temple and Vampires only rise from the Graveyard. Tentacles like water and are only bonuses on those levels with water. Bear this in mind when you are scripting your level.

Note: The three last creacures are not real game creatures, but only helpers. They should not be used. Floating Spirits are mainly used when your dungeon heart is destroyed (when you click on the Possess icon), or at the very beginning of any levels (when you "enter" into the Dungeon Heart).

Fanfact: Floating Spirits can be added into creature pool, but when they come out the portal they are completely useless - have no attack, and seem to crash the game if you slap them or a Boulder Trap hits them.

2.7 Room Names

Like the creatures, the rooms in Dungeon Keeper have special script names.

2.8 Door and Trap Names

Doors and Traps have script names which must be used when referring to them.

2.9 Spell Names

Spells have script names which must be used when referring to them.

Note: The three last powers are given to you at start of the level, and you don't need library to store them. Other spells need to be enabled in you want to allow the player to research them or have them at start.

3.0 Miscellaneous Commands

These commands can be placed anywhere in your script and do not directly affect the level.

3.1 REM

This can be placed at the start of a line to tell the game to ignore any text after it.

Example:

REM ***** Setup Level Section              *****

3.2 WIN_GAME

Tells the game that you have won the level.

This command must be included in single player games to tell the player he has won. In multiplayer levels, it is not necessary. You should always use them with IF commands to make sure something happens to cause the game to end.

Example:

REM ***** Win the level if Player 1's      *****
REM ***** dungeon is destroyed             *****

IF(PLAYER1,DUNGEON_DESTROYED==1)

       WIN_GAME

ENDIF

3.3 LOSE_GAME

Tells the game you have lost the level.

This command does not always need to be included as you will automatically lose the level if you Dungeon Heart is destroyed. You should include it if there is a strict goal the player needs to attain.

Example:

REM ***** Lose the level if Player 0's     *****
REM ***** total battles lost is 30         *****

IF(PLAYER0,BATTLES_LOST >= 30)

       LOSE_GAME

ENDIF

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

Sets up a flag that is assigned a number.

[a] - The number assigned to the flag. This can be between 0 and 255.

Example:

REM ***** Setup FLAG0                      *****

SET_FLAG(PLAYER0,FLAG0,0)

..

REM ***** If Player 0's total creatures    *****
REM ***** is larger than 40 then set the   *****
REM ***** flag to 1                        *****

IF(PLAYER0,TOTAL_CREATURES > 40)

       SET_FLAG(PLAYER0,FLAG0,1)

ENDIF

..

REM ***** If FLAG0 is equal to 1 then win  *****
REM ***** the game                         *****

IF(PLAYER0,FLAG0==1)

       WIN_GAME

ENDIF

3.5 SET_TIMER([player],[timer])

Sets up a timer that increases by 1 every game turn from when it was triggered.

Example:

REM ***** Setup Player 0's TIMER0          *****

SET_TIMER(PLAYER0,TIMER0)

..

REM ***** When TIMER0 reaches 1000, win    *****
REM ***** the game                         *****

IF(PLAYER0,TIMER0 >= 1000)

       WIN_GAME

ENDIF

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

This is used to test the differences between two values ([variable] and [a]). 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.

Note: You can only have a maximum of 48 IF conditions (all types) in your script.

Example

REM ***** Detect whether Player 0's total  *****
REM ***** number of creatures is larger    *****
REM ***** than 40. If so, win the game, if *****
REM ***** not, continue                    *****

IF(PLAYER0,TOTAL_CREATURES >= 40)

      WIN_GAME

ENDIF

..

REM ***** If Player 0's Dungeon Heart is   *****
REM ***** destroyed then lose the game     *****

IF(PLAYER0,DUNGEON_DESTROYED==1)

       LOSE_GAME

ENDIF

3.7 IF_ACTION_POINT([action point],[player])

Detects whether an Action Point has been trigger by one of that players creatures. The Action point is only triggered once (unless you use the RESET_ACTION_POINT command) and you can only detect which player triggered it.

Note: You can only have a maximum of 48 IF conditions (all types) in your script.

Example:

REM ***** If Action Point 2 has been       *****
REM ***** triggered by one of Player 1's   *****
REM ***** creatures then perform the       *****
REM ***** following tasks                  *****

IF_ACTION_POINT(2,PLAYER1)

       ..

ENDIF

3.8 IF_AVAILABLE([player],[name][comparison][a])

Allows you to ask whether something is available to that player. If it is not, then the answer will be 0. If it is then the answer will be 1.

Note:You can only have a maximum of 48 IF conditions (all types) in your script.

Example:

REM ***** If Player 2 has a Temple then    *****
REM ***** perform the following tasks      *****

IF_AVAILABLE(PLAYER2,ROOM_TEMPLE >= 1)

       ..

ENDIF

3.9 ENDIF

This command must be placed at the end of all IF statements. This tells the IF command where to jump to when the comparisons in the statement are not met.

See IF commands for examples.

3.10 RESET_ACTION_POINT([action point])

Once an Action Point has been triggered, it cannot be triggered again unless it has been reset by this command.

Example:

RESET_ACTION_POINT(3)

3.11 NEXT_COMMAND_REUSABLE

Once any action command, such as ADD_CREATURE_TO_LEVEL or SET_TIMER, has been triggered once, it cannot be triggered again. This means that you cannot create loops or generators that add heroes to the level each time one of your creatures steps foot in a room. To get around this, the Dungeon Keeper script has a special command called NEXT_COMMAND_REUSABLE. You will need to place this in front of every command in the loop to make it work (it does not need to be placed in front of IF commands)

Example:

REM ***** This loop adds a new hero to the *****
REM ***** level at Action Point 5 while a  *****
REM ***** creature belonging to Player 0   *****
REM ***** is within the boundaries of      *****
REM ***** Action Point 5. It will only     *****
REM ***** stop when the Hero Dungeon Heart *****
REM ***** has been destroyed               *****

IF_ACTION_POINT(5,PLAYER0)

       IF(PLAYER_GOOD,DUNGEON_DESTROYED==0)

              NEXT_COMMAND_REUSABLE
              ADD_CREATURE_TO_LEVEL(PLAYER_GOOD,ARCHER,5,1,3,300)

       ENDIF

ENDIF

..

REM ***** This loop adds a new hero to the *****
REM ***** level at Hero Gate 3 every 1000  *****
REM ***** game turns. This is done by      *****
REM ***** starting a timer, adding the     *****
REM ***** hero when it reaches 1000 and    *****
REM ***** then resetting it again          *****

SET_TIMER(PLAYER0,TIMER0)

IF(PLAYER0,TIMER0 >= 1000)

       NEXT_COMMAND_REUSABLE
       ADD_CREATURE_TO_LEVEL(PLAYER_GOOD,WITCH,-3,1,6,600)

       NEXT_COMMAND_REUSABLE
       SET_TIMER(PLAYER0,TIMER0)

ENDIF

4.0 Setup Commands

These commands set up your level and initialise your computer players (if you have any).

4.1 SET_GENERATE_SPEED([a])

This command tells the game how long to wait before generating a new creature for each player. The type of creatures that appear cannot be scripted and will depend on the rooms the player has built. This is a global setting and will apply to all Portals.

Example:

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

SET_GENERATE_SPEED(500)

4.2 COMPUTER_PLAYER([player],[a])

If you have placed down an enemy dungeon heart (not a hero dungeon heart), this command tells Dungeon Keeper that a computer player needs to be assigned.

Note: The official manual claims that numbers for computer players other than 0, 1, 3, 4, 5, or 10 will not make the game work properly.

Example:

REM ***** Set up and aggressive computer   *****
REM ***** that uses Player 2's dungeon     *****

COMPUTER_PLAYER(PLAYER2,1)

4.3 START_MONEY([player],[gold])

How much gold each player has at the start of the level.

Example:

REM ***** Give all players 40000 in gold   *****
REM ***** at the start of the level        *****

START_MONEY(ALL_PLAYERS,40000)

4.4 MAX_CREATURES([player],[a])

The maximum number of creatures a player can have. The player can still gain creatures through Scavenging and Torturing but no more will come through the portal until the number of creatures drops below the maximum again.

Example:

REM ***** Player 1 will not gain any more  *****
REM ***** creatures through his Portal     *****
REM ***** once he has 40 creatures in his  *****
REM ***** dungeon                          *****

MAX_CREATURES(PLAYER1,40)

4.5 ALLY_PLAYERS([player],[player])

This command sets two players as allies at the start of the game.

Example:

ALLY_PLAYERS(PLAYER1,PLAYER2)

5.0 Creatures, Spells, Traps and Doors

These commands set what creatures, spells, traps and doors appear on the level and whether they need to be researched or not. You do not need to use these commands for Heroes and their traps and doors.

5.1 ADD_CREATURE_TO_POOL([creature],[a])

The creature pool is a set number of creatures that can be attracted by all the players. Imagine a large group of creatures waiting outside the Dungeon Area (all Portals share this group). A player puts down a room, e.g. a Torture Chamber, and a creature (Dark Mistress) is attracted. The Mistress is taken from this group. If there are no more Mistresses in the group then the player will not be able to gain any more unless he uses other means, e.g. scavenging. This is a first come, first serve system so players will need to hurry if they want to gain the rarest creatures. If a creature becomes angry, it will exit via an Portal and return to the pool. Dead creatures do not return to the pool so be careful the players do not run out.

This command sets the number of creatures that are placed in this pool. If you leave any creatures off the list then they will not appear in the pool.

Example:

ADD_CREATURE_TO_POOL(BILE_DEMON,20)

5.2 CREATURE_AVAILABLE([player],[creature],[can be available],[is available])

This command tells the game that a specific creature can come through that player’s Portal.

Since the default value for [can be available] is 0, you can just include in the script file only those creatures you want the player to be able to attract. This will cut down your script file considerably.

Remember, you can use the ALL_PLAYERS option for [player] to cover all the players with one command.

Example:

REM ***** A Warlock can now appear at the  *****
REM ***** Portal if owned by player 2      *****

CREATURE_AVAILABLE(PLAYER2,SORCEROR,1,1)

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

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

Since the default value for [can be available] is 0, you can just include in the script file only those rooms you want the player to be able to research. This will cut down your script file considerably.

Remember, you can use the ALL_PLAYERS option for [player] to cover all the players with one command.

Note: The Treasure Room, Lair, Hatchery, Training Room and Research Room should all be available at the start of each level.

Example:

REM ***** This Treasure Room has been set  *****
REM ***** so that it is available from     *****
REM ***** the start of the level.          *****

ROOM_AVAILABLE(ALL_PLAYERS,TREASURE,1,1)

REM ***** This Torture Chamber has been    *****
REM ***** set do that it needs to be       *****
REM ***** researched before it becomes     *****
REM ***** available.                       *****

ROOM_AVAILABLE(ALL_PLAYERS,TORTURE,1,0)

5.4 DOOR_AVAILABLE([player],[door],[can be available],[number available])

This command tells the game that a specific door is available for the player to construct.

Since the default value for [can be available] is 0, you can just include in the script file only those doors you want the player to construct. This will cut down your script file considerably.

Remember, you can use the ALL_PLAYERS option for [player] to cover all the players with one command.

Example:

REM ***** The Wooden Door is now available *****
REM ***** to the player to manufacture     *****
REM ***** and none have been given to him  *****
REM ***** at the start                     *****

DOOR_AVAILABLE(PLAYER1,WOOD,1,0)

5.5 TRAP_AVAILABLE([player],[trap],[can be available],[number available])

This command tells the game that a specific trap is available for the player to construct.

Since the default value for [can be available] is 0, you can just include in the script file only those traps you want the player to construct. This will cut down your script file considerably.

Remember, you can use the ALL_PLAYERS option for [player] to cover all the players with one command.

The computer player may sometimes build too much traps, expanding the workshop or placing traps in wrong places. In original DK campaign, computer type 0 puts all its traps on a single tile. This is corrected in DD, but the computer player there places traps all over, which may also lead to problems. To make sure the computer won't build too much traps, it is wise to set a limit, e.g. disable trap after three have been built, and disable the workshop building after it has 16 or 25 files.

Example:

REM ***** The Word of Power Trap is now    *****
REM ***** available to the player to       *****
REM ***** manufacture and none have been   *****
REM ***** given to him at the start        *****

TRAP_AVAILABLE(PLAYER1,WORD_OF_POWER,1,0)

5.6 MAGIC_AVAILABLE([player],[spell],[can be available],[is available])

This command tells the game that a specific spell is available for the player to cast.

Since the default value for [can be available] is 0, you can just include in the script file only those spells you want the player to research. This will cut down your script file considerably.

Remember, you can use the ALL_PLAYERS option for [player] to cover all the players with one command.

Example:

REM ***** This Speed Creature spell has    *****
REM ***** been set so that it is available *****
REM ***** from the start of the level.     *****

MAGIC_AVAILABLE(ALL_PLAYERS,POWER_SPEED,1,1)

REM ***** This Conceal Creature spell has  *****
REM ***** been set do that it needs to be  *****
REM ***** researched before it becomes     *****
REM ***** available.                       *****

MAGIC_AVAILABLE(ALL_PLAYERS,POWER_CONCEAL,1,0)

5.7 DEAD_CREATURES_RETURN_TO_POOL([a])

Normally, when a creature dies, and its body vanishes, it is added to the creature pool again. This command allows you to ensure that all dead creatures are dead forever.

Note: This function should be used only in special maps, where there are sources of new creatures other than portals.

Example:

REM ***** Dead creatures will not return   *****
REM ***** to pool on this map.             *****

DEAD_CREATURES_RETURN_TO_POOL(0)

6.0 Manipulating Creatures

With the following commands, you can manipulate the creature statistic directly and alter them specifically for your level. This will not affect the statistics in the creature.txt file and can be set for a specific player.

6.1 SET_CREATURE_MAX_LEVEL([player],[creature],[max experience])

This command sets the maximum experience level the creature can train to. You can use this to stop certain creatures from becoming too powerful.

Example:

REM ***** Do not allow human player Hell   *****
REM ***** Hounds to go higher than level 5 *****

SET_CREATURE_MAX_LEVEL(PLAYER0,HELL_HOUND,5)

6.2 SET_CREATURE_STRENGTH([creature],[a])

This command sets the strength of all the creatures of that type on the level. Each creature has a default strength which can be found in the creature.txt file, e.g. the BILE_DEMON has a strength level of 80.

Example:

SET_CREATURE_STRENGTH(DEMON_SPAWN,190)

6.3 SET_CREATURE_HEALTH([creature],[a])

This command sets the health of all the creatures of that type on the level. Each creature has a default full health level which can be found in the creature.txt file, e.g. the DRAGON has a full health level of 900.

Example:

SET_CREATURE_HEALTH(ORC,1000)

6.4 SET_CREATURE_ARMOUR([creature],[a])

This command sets the armour of all the creatures of that type on the level. Each creature has a default armour level which can be found in the creature.txt file, e.g. the Dark Mistress has a armour level of 50.

Example:

SET_CREATURE_ARMOUR(DEMON_SPAWN,60)

6.5 SET_CREATURE_FEAR([creature],[a])

This command sets the fear of all the creatures of that type on the level. Each creature has a default fear which can be found in the creature.txt file, e.g. the FLY has a fear level of 30.

Example:

SET_CREATURE_FEAR(SPIDER,190)

7.0 Manipulating Research

When you put creatures into the Library and they start to research, a research counter will start to increase. The rate at which it increases depends on the number of creatures in the Library and their individual abilities and experience levels. Each spell and room has a research number assigned to it. When this number is reached by the research counter, the room or spell is deemed to be researched. All the rooms and spells have default research values (see below) but you can adjust these for individual levels if you want to.

7.1 Default Research Values

These are the default research values for the rooms.

These are the default research values for spells.

7.2 RESEARCH([player],[research type],[room or spell],[a])

This command allows you to adjust the research value for individual rooms or spells and even for a specific player.

Example:

REM ***** Change the research value of the *****
REM ***** Scavenger Room from 27500 to     *****
REM ***** 50000                            *****

RESEARCH(PLAYER1,ROOM,SCAVENGER,50000)

Fanfact: The game engine also recognizes CREATURE as a value of [research type] parameter. It is unknown if a command with this value has any influence on the game.

8.0 Adding New Creatures and Parties to the Level

As well as set the attributes for your level, the Dungeon Keeper script allows you to add new creatures to the level at specified points and times. In conjunction with Action Points, you can trigger parties of Heroes to appear when a players’ creatures enter a certain part of the level.

8.1 ADD_CREATURE_TO_LEVEL([player],[creature],[action point],[a],[experience],[gold])

This command will add a number of new creatures to the level at the co-ordinates of a specifies Action Point. You cannot set where the creatures head for so you may need to use a party instead.

Note: You can only have a maximum of 48 ADD_CREATURE_TO_LEVEL commands.

Example:

REM ***** Add 7 level 4 Hero Wizards who   *****
REM ***** are carrying 400 gold at Action  *****
REM ***** Point 3                          *****

ADD_CREATURE_TO_LEVEL(PLAYER_GOOD,WIZARD,3,7,4,400)

8.2 ADD_TUNNELLER_TO_LEVEL([player],[action point],[head for],[action point/target player],[experience],[gold])

This commands adds a number of Tunneller Dwarves to the level. They will immediately start digging towards their target. Tunneller Dwarves are the only creatures that can tunnel towards a target.

Note: You can only have a maximum of 16 ADD_TUNNELLER_TO_LEVEL commands.

Example:

REM ***** Add a level 6 Hero Tunneller at  *****
REM ***** Action Point 7. He will tunnel   *****
REM ***** towards Action Point 5           *****

ADD_TUNNELLER_TO_LEVEL(PLAYER_GOOD,7,ACTION_POINT,5,6,400)

..

REM ***** Add a level 4 Hero Tunneller at  *****
REM ***** Action Point 3. He will tunnel   *****
REM ***** towards Player 2's Dungeon Heart *****

ADD_TUNNELLER_TO_LEVEL(PLAYER_GOOD,3,DUNGEON_HEART,2,4,400)

..

REM ***** Add a level 9 Hero Tunneller at  *****
REM ***** Action Point 5. He will tunnel   *****
REM ***** towards the dungeon of the       *****
REM ***** player with the highest score    *****

ADD_TUNNELLER_TO_LEVEL(PLAYER_GOOD,5,APPROPIATE_DUNGEON,0,9,400)

8.3 CREATE_PARTY([party name])

This command tells the game to expect a party with a specific name.

Note: You can only have a maximum of 16 parties.

Example:

CREATE_PARTY(FIRST_STRIKE)

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

This command adds a number of creatures to a party (maximum seven).

Note: You can only have a maximum of 7 in a party. The leader is selected based on the creature types and their experience level (best and most experienced). Because only the leader will react on [objective] and [countdown] parameters, and you may be not certain which member will become a leader, it is wise to set these parameter to same values for all members of the party.

Example:

REM ***** Create a party called MY_PARTY.  *****

CREATE_PARTY(MY_PARTY)

..

REM ***** Add to MY_PARTY a level 5 Fairy  *****
REM ***** with 600 in gold who will attack *****
REM ***** the rooms of the target player   *****

ADD_TO_PARTY(MY_PARTY,FAIRY,5,600,ATTACK_ROOMS,0)

8.5 ADD_TUNNELLER_PARTY_TO_LEVEL([player],[party name],[action point],[head for],[action point/target player],[experience],[gold])

This adds a specified party of creatures to the level with a Tunneller Dwarf as it’s leader. The Tunneller will immediately dig to it’s target and the other creatures will follow.

Note: The ADD_TUNNELLER_PARTY_TO_LEVEL command counts as one ADD_TUNNELLER_TO_LEVEL command. Therefore, there can only be a total of 16 of these commands in your script.

Example:

REM ***** Add MY_PARTY to the level at     *****
REM ***** Action Point 4 with a level 5    *****
REM ***** Tunneller as it's leader. The    *****
REM ***** party will head for Action       *****
REM ***** Point 1                          *****

ADD_TUNNELLER_PARTY_TO_LEVEL(PLAYER_GOOD,MY_PARTY,4,ACTION_POINT,1,5,600)

REM ***** Add MY_PARTY to the level at     *****
REM ***** Action Point 10 with a level 4   *****
REM ***** Tunneller as it's leader. The    *****
REM ***** party will head for the dungeon  *****
REM ***** of Player 1                      *****

ADD_TUNNELLER_PARTY_TO_LEVEL(PLAYER_GOOD,MY_PARTY,10,DUNGEON,1,4,600)

8.6 ADD_PARTY_TO_LEVEL([player],[name],[action point],[a])

Very similar to the ADD_TUNNELLER_PARTY_TO_LEVEL command, this adds a party to the level but does not include a Tunneller Dwarf. This means the party will not be able to tunnel to their target.

Note: The ADD_PARTY_TO_LEVEL command counts as one ADD_CREATURE_TO_LEVEL command. Therefore, there can only be a total of 48 of these commands in your script. The [a] (number of copies) variable in the ADD_PARTY_TO_LEVEL command does not affect this number and you will only use up one command however many copies you make.

Example:

REM ***** Add 2 copies of MY_PARTY to the  *****
REM ***** level at Action Point 5. They    *****
REM ***** belong to Player 3               *****

ADD_PARTY_TO_LEVEL(PLAYER3,MY_PARTY,5,2)

9.0 Displaying information and affecting interface

You can include the following commands in your script to display objectives for the player to follow, or information about level background story or some of the level mechanisms. There are also some commands to influence other elements of the game interface.

Please note that there is no CREATE_TEXT nor PRINT command. Commands with these names can be often found in scripts of the original maps. There were such commands in early version of the game, but were removed later. CREATE_TEXT has been replaced by DISPLAY_OBJECTIVE command to allow easier translation to languages other than english, PRINT was removed to prevent the game from using printer connected to PC.

9.1 DISPLAY_OBJECTIVE([a],[player])

Displays one of the text messages stored in TEXT.DAT file (if used in Dungeon Keeper) or DD1TEXT.DAT (if used in Deeper Dungeons) in an Objective Box. This file comes in various language version, so messages from it are always in the language selected during installation of Dungeon Keeper.

Example:

REM ***** Display objective box which says:*****
REM ***** "Your plan proceeds smoothly,    *****
REM ***** keeper. Allow your Imps time to  *****
REM ***** fortify the walls of your        *****
REM ***** dungeon. This increases the      *****
REM ***** efficiency of rooms and repels   *****
REM ***** would-be invaders."              *****

DISPLAY_OBJECTIVE(26,PLAYER0)

9.2 DISPLAY_OBJECTIVE_WITH_POS([a],[x],[y])

Displays one of the text messages stored in TEXT.DAT file (if used in Dungeon Keeper) or DD1TEXT.DAT (if used in Deeper Dungeons) in an Objective Box. Allows to enter map coordinates of an area which is shown when the eye icon is clicked on the message.

Example:

REM ***** Display objective box which says:*****
REM ***** "Enemy reinforcements have       *****
REM ***** arrived. So what? Let's hear it  *****
REM ***** for more killing."               *****
REM ***** Allows to view map coords (19,21)*****

DISPLAY_OBJECTIVE_WITH_POS(130,19,21)

9.3 DISPLAY_INFORMATION([a])

Creates a text box with Information Pop-up Icon. Works identical (except of the icon) as DISPLAY_OBJECTIVE.

Example:

REM ***** Display information which says:  *****
REM ***** "How time flies... hurry!"       *****

DISPLAY_INFORMATION(166)

9.4 DISPLAY_INFORMATION_WITH_POS([a],[x],[y])

Creates a text box with Information Pop-up Icon. Works identical (except of the icon) as DISPLAY_OBJECTIVE_WITH_POS.

Note: The unpatched version of the game do not recognizes this command correctly. Therefore, this command is very unsafe and shouldn't be used - it will work properly only with unofficial patch installed.

REM ***** Display information which says:  *****
REM ***** "If thou art bold and pure of    *****
REM ***** heart, Come down here, be torn   *****
REM ***** apart."                          *****
REM ***** Allows to view map coords (66,77)*****

DISPLAY_INFORMATION_WITH_POS(804,66,77)

Fanfact: This command has wrong internal command number in the game engine, and therefore is interpreted as DISPLAY_INFORMATION by the unpatched game. This is clearly a typing mistake of the programmer.

9.5 QUICK_OBJECTIVE([a],["objective"],[where])

This command brings up the Objective Box at the bottom of the game screen and displays the specified text. The command will be triggered as soon as the game reaches it in the script so you will probably need to trigger it with an IF command.

Note: This command will work only if you're using the Deeper Dungeons expansion pack, or Dungeon Keeper Gold installed on your PC. Remember, if you give this level to another person, they must also have the Deeper Dungeons expansion pack (or DK Gold) installed on their machine. Only DEEPER.EXE, DEEPER95.EXE and KEEPERFX.EXE can support this command.

Even if used in Deeper Dungeons, the command may not work properly if user will use the load/save game functions. Workaround for this is to start the level and load savegame from inside the level.

Example:

QUICK_OBJECTIVE(1,"Your dungeon is doomed, Keeper",PLAYER1)

9.6 QUICK_INFORMATION([a],["information"])

This command is similar to the QUICK_OBJECTIVE command except that instead of an Objective Window, the text is written on an Information Pop-up Icon. Again, this command will be triggered as soon as the game reaches it in the script so you will probably need to trigger it with an IF command.

Note: This command will work only if you have the Deeper Dungeons expansion pack, or Dungeon Keeper Gold installed on your PC. Remember, if you give this level to another person, they must also have the Deeper Dungeons expansion pack (or DK Gold) installed on their machine.

Note: There is no player defined on this command as there is for the objective. The information will not be displayed at all if you have stated the player name.

Example:

QUICK_INFORMATION(1,"Well done. You have researched the Temple.")

9.7 TUTORIAL_FLASH_BUTTON([button],[duration])

Flashes a button on the toolar until the player selects it.

Example:

ROOM_AVAILABLE(PLAYER0,WORKSHOP,1,1)
QUICK_INFORMATION(1,"Build a 3x3 workshop which is now available to you.")
TUTORIAL_FLASH_BUTTON(13,PLAYER0)

9.8 BONUS_LEVEL_TIME([a])

Sets the time a player has to complete an objective. A timer appears in the top right corner of the screen. Only works on levels 100 to 105, marked as the bonus levels. The value shown on timer is amount of game turns left divided by 2.

Note: This command does not create the counter, it only sets the bonus level time shown on it. You can't have the timer in custom maps or other original campaign maps. If you don't specify a BONUS_LEVEL_TIME in a bonus level, the counter will still be there, but will be set to 00000.

Example:

REM ***** Set the level time to 10 minutes *****

SET_TIMER(PLAYER0,TIMER1)
BONUS_LEVEL_TIME(12000)

IF(PLAYER0,TIMER1 >= 12000)
	LOSE_GAME
ENDIF

9.9 SET_MUSIC([a])

This command was designed to choose the music track to play.

It is unknown if this command works, and how it works.

Example:

SET_MUSIC(1)

10.0 Tweaking computer players

Computer player commands allows you to change the common behaviour of the computer player, or force it to conduct a specific action. None of these commands was originally documented - this section is completely work of fans.

10.1 Computer Player Control Parameters

These are the values of variables used in computer player (so-called AI) control commands. Note that these can only be used on a already initialized computer player (after a COMPUTER_PLAYER() command). Also, only some of available processes/events/tasks are used for a specific computer player model.

10.2 SET_COMPUTER_PROCESS([player],["process name"],[priority],[data1],[data2],[data3],[data4])

Changes conditions and parameters for one of the computer processes. A process is started if the computer player realizes that any action is needed. Some of the processes have more than one version, and specific one is selected by checking variables inside the processes.

Note that some processes are only used for some of the computer player types. To make sure your commands won't be inactive, you should set up the computer player type 0 (see COMPUTER_PLAYER command), e.g.

REM ***** Set up standard computer player  *****
REM ***** to be sure no processes will be  *****
REM ***** skipped when AI takes action.    *****

COMPUTER_PLAYER(PLAYER1,0)

10.2.1 Digging to gold processes

In this case, the function definition is:

SET_COMPUTER_PROCESS([player],["process name"],[priority],[money minimum],[turn scale],[gold dug at once],[max distance])

Note: If you will use all the gold process commands with very small range, the computer player will still dig for far gold when he'll run completely out of it. This is due to a "fail safe" process which exist after these four. To disable digging for gold, you will have to place a first vein just next to the player, and use very large value of [turn scale], e.g. 144000 will make the computer not to dig for gold in 2 hours after digging the first vein.

Example:

REM ***** Dig safely for gold if more than *****
REM ***** 1250 is in treasury; search for  *****
REM ***** vein in 20 squares, wait 30 secs *****
REM ***** before the next digging          *****

SET_COMPUTER_PROCESS(PLAYER1,"DIG TO CLOSE GOLD",0,1250,600,5,20)

REM ***** Don't dig for gold in two hours  *****
REM ***** after first time digging greedly *****
REM ***** for gold.                        *****

SET_COMPUTER_PROCESS(PLAYER1,"DIG TO GREEDY GOLD", 0,  100,76666,5,50)
SET_COMPUTER_PROCESS(PLAYER1,"DIG TO GREEDY GOLD2",0,    0,76666,5,60)

10.2.2 Build a specific room processes

In this case, the function definition is:

SET_COMPUTER_PROCESS([player],["process name"],[priority],[room width],[room height],[room index],[required index])

Maximum size of a room is restricted only by amount of tiles which a player can mark for digging. Rooms of size up to 23x23 are usually created properly.

Note: You can't build rooms where width and height differ by more than one. If e.g. you will set width to 4, you can only use height values of 3, 4 or 5.

The importand rooms: Treasure Room, Lair, Hatchery, Library and Training Room, should have priority around 0. Other rooms should have priority around -10. This will make sure AI will conduct other processes when neccessery.

Example:

REM ***** Build 4x3 treasure room at start *****
SET_COMPUTER_PROCESS(PLAYER1,"BUILD A TREASURE ROOM",     0,4,3, 2,0)

REM ***** Build only 2x3 hatchery          *****

REM SET_COMPUTER_PROCESS(PLAYER1,"BUILD A HATCHERY",      0,2,3,13,0)

REM ***** Build 3x3 scavenger room, only   *****
REM ***** after the Prison has been built  *****

SET_COMPUTER_PROCESS(PLAYER1,"BUILD A SCAVENGER ROOM",-10,3,3,9,8)

10.3 SET_COMPUTER_CHECKS([player],["checks name"],[check every],[data1],[data2],[data3],[data4])

If no importand event is occuring, the computer player searches for things that need to be done using checks. Checks are similar to IF commands which allows computer player to undertake a process under some circumstances determined by values of variables.

10.3.1 Check for attack

In this case, the function definition is:

SET_COMPUTER_CHECKS([player],["checks name"],[check every],[attack percent],[CTA duration],[min for attack],[last check])

This command is not fully documented yet. Sorry.

10.4 SET_COMPUTER_EVENT([player],["event name"],[data1],[data2])

Event is a sudden situation that needs a process to be undertaken. Unlike checks, events are triggered by often complicated logic conditions. Both checks and events are used to test if a process should be started.

This command is not fully documented yet. Sorry.

10.5 SET_COMPUTER_GLOBALS([player],[a],[a],[a],[a],[a],[a])

This command is not fully documented yet. Sorry.

11.0 Script commands index

ADD_CREATURE_TO_POOL([creature],[a])

ADD_CREATURE_TO_LEVEL([player],[creature],[action point],[a],[experience],[gold])

ADD_PARTY_TO_LEVEL([player],[name],[action point],[a])

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

ADD_TUNNELLER_PARTY_TO_LEVEL([player],[party name],[action point],[head for],[action point/target player],[experience],[gold])

ADD_TUNNELLER_TO_LEVEL([player],[action point],[head for],[action point/target player],[experience],[gold])

ALLY_PLAYERS([player],[player])

BONUS_LEVEL_TIME([a])

COMPUTER_PLAYER([player],[a])

CREATE_PARTY([party name])

CREATURE_AVAILABLE([player],[creature],[can be available],[is available])

DEAD_CREATURES_RETURN_TO_POOL([a])

DISPLAY_INFORMATION([a])

DISPLAY_INFORMATION_WITH_POS([a],[x],[y])

DISPLAY_OBJECTIVE([a],[player])

DISPLAY_OBJECTIVE_WITH_POS([a],[x],[y])

DOOR_AVAILABLE([player],[door],[can be available],[number available])

ENDIF

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

IF_ACTION_POINT([action point],[player])

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

LOSE_GAME

MAGIC_AVAILABLE([player],[spell],[can be available],[is available])

MAX_CREATURES([player],[a])

NEXT_COMMAND_REUSABLE

QUICK_INFORMATION([a],["information"])

QUICK_OBJECTIVE([a],["objective"],[where])

REM

RESEARCH([player],[research type],[room or spell],[a])

RESET_ACTION_POINT([action point])

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

SET_COMPUTER_CHECKS([player],["checks name"],[check every],[data1],[data2],[data3],[data4])

SET_COMPUTER_EVENT([player],["event name"],[data1],[data2])

SET_COMPUTER_GLOBALS([player],[a],[a],[a],[a],[a],[a])

SET_COMPUTER_PROCESS([player],["process name"],[priority],[data1],[data2],[data3],[data4])

SET_CREATURE_ARMOUR([creature],[a])

SET_CREATURE_FEAR([creature],[a])

SET_CREATURE_HEALTH([creature],[a])

SET_CREATURE_MAX_LEVEL([player],[creature],[max experience])

SET_CREATURE_STRENGTH([creature],[a])

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

SET_GENERATE_SPEED([a])

SET_MUSIC([a])

SET_TIMER([player],[timer])

START_MONEY([player],[gold])

TRAP_AVAILABLE([player],[trap],[can be available],[number available])

TUTORIAL_FLASH_BUTTON([button],[player])

WIN_GAME

11.1 Undocumented script commands

SET_HATE([a],[a],[a]) NNN

SWAP_CREATURE([?],[?]) AA

12.0 Credits

Producer: Sean Cooper

Project Leader: Alex Peters

Lead Programmer: Mark Stacey

Additional Artwork: Peter Amachree

Manual and Documentation: Jon Rennie

Manual Verification: Shintaro Kanaoya, Nathan Smethurst, Barrie Parker

Testing Manager: Andy Robson

Testing: Nathan Smethurst, Steve Lawrie, Tristan Paramor, Jeff Brutus

Documentation Modifications: Tomasz Lis

Used information provided by: DzjeeAr, DragonsLover, Danrhan

13.0 Changes log

Version 1.3

• Many modifications, suggested by DragonsLover
• Better creature parties explanation

Version 1.2

• Fixations to small mistakes
• Extended game turns explanation
• Added information and interface commands
• Added computer player commands

Version 1.1

• File format changed to HTML
• Divided into two parts: Official Editor Manual and Script Reference
• Fixations of text formattiong

Version 1.0

• Original version of the reference, released by Bullfrog with the Official Map Editor for Dungeon Keeper

14.0 References

1. Dungeon Keeper Mapmaker's Documentation
2. Dungeon Keeper Official Editor Manual