Script (.txt) Files

Size: Varies.
Required?: Yes.
Compressed?: Never.
Description: Level script which determines victory conditions, enemy keepers actions, training mode, etc.
Format: Text file.
Notes: Description of language, based on Michael Keane's excellent web page, is given below (unfinished as yet).
Adikted support: None. No point in me writing another text editor :)

Dungeon Keeper Scripting Language

General notes

This is a pretty simple scripting language, or at least so it appears. I don't believe there are any loops or jumps, and condition testing seems to be simple. The are only three statement forms - conditions, commands, and condition terminators. Conditions are naturally nested, but that's about as complicated as it gets.

Each line contains a single instruction. Whitespace in the form of spaces and tabs is ignored. Comments begin with REM. I believe all unconditional commands (ie ones outside any condition statements) are executed at the beginning of the game, then ignored. All conditions are checked at regular intervals, I imagine.

A program to provide some basic editing for script files is available in the utilities package.

Conditions

IF (player, variable operator integer)
The code between the IF and the matching ENDIF is executed if the variable condition is met for the given player. Note that doors and traps should be tested with IF_AVAILABLE.
IF_AVAILABLE (player, variable operator integer)
Effectively the same as a normal IF condition, this is used for testing the number of traps or doors (of the given kind) a player has.
IF_ACTION_POINT (integer, player)
The code until the matching ENDIF is executed if the given player reaches the action point specified by the first parameter. Action points are set in the .apt file.
ENDIF
On a line on its own, this terminates a block of code started with one of the above conditions.

Commands

Party commands

CREATE_PARTY (name)
This creates an empty party with the given name.
ADD_TO_PARTY (name, creature, level, gold, objective, integer)
Adds a creature to the named party. The purpose of the final value is unknown at this time.
ADD_PARTY_TO_LEVEL (player, name, integer, integer)
Adds the named party to the game, under the control of the given player. The purposes of the final two values are unknown at this time. The final one is 1 in all the level scripts which came with DK, while the other ranges between -5 and 11.
ADD_TUNNELLER_PARTY_TO_LEVEL (player, name, integer, DUNGEON, integer, integer, integer)
Seems to be the same as ADD_PARTY_TO_LEVEL, only this one includes a tunneller along with them. I don't know for sure what any of the integers do. The first seems to be a dungeon location, the second might be how many, the third is the action point at which the tunnelers arrive, and the fourth is how much gold each has. The fourth parameter always seems to be just DUNGEON.
ADD_TUNNELLER_TO_LEVEL(player, integer, DUNGEON, integer, integer, integer)
As above, except adding just tunneller(s) rather than a whole party.
ADD_CREATURE_TO_LEVEL (player, creature, integer, integer, integer, integer)
Adds an individual creature to the level, under the given player's control. The first integer is the location (action point number or player... if a player, does it add it at the dungeon heart?), the second is unknown, the third is the creature's level, and the fourth is how much gold it is carrying.

Availability commands

MAGIC_AVAILABLE (player, spell, boolean, boolean)
ROOM_AVAILABLE (player, room, boolean, boolean)
The above two commands determine the availability of spells and rooms. The first boolean determines if the player may use the spell/room, the second determines if he has it to begin with (1), or whether he has to research it (0).
CREATURE_AVAILABLE (player, creature, boolean, boolean)
DOOR_AVAILABLE (player, door, boolean, boolean)
TRAP_AVAILABLE (player, trap, boolean, boolean)
These would appear to be similar to the earlier commands, except as you never start with any doors or traps, and you can't research creatures, I'd guess the boolean values may mean subtly different things.

Timers

SET_TIMER (player, timer)
Starts the given timer for the given player.
BONUS_LEVEL_TIME (integer)
Sets the time a player has to complete the level. A timer appears in the top right corner of the screen. Only useful for original version, not Deeper Dungeons.

Creature attribute commands

SET_CREATURE_FEAR (creature, integer)
SET_CREATURE_ARMOUR (creature, integer)
SET_CREATURE_HEALTH (creature, integer)
SET_CREATURE_STRENGTH (creature, integer)
Change the base values of all creatures of the specified type.
SET_CREATURE_MAX_LEVEL (player, creature, integer)
Change the maximum level that a creature can reach. Setting the max level to be 10 means that, for instance, a demon spawn can't turn into a dragon.

Information commands

TUTORIAL_FLASH_BUTTON (integer, integer/player)
Flashes a button on the toolar until the player selects it. The first integer must be in the valid range of button ids (unknown as yet). The second value is always -1, 0, or PLAYER0 in the original scripts.
DISPLAY_INFORMATION (integer, player)
DISPLAY_OBJECTIVE (integer, player)
These add an "i" or a "?" to the information panel of the given player, with the text as determined by the integer - this is an index into the text.dat file.
CREATE_TEXT (integer, string)
Does nothing, basically.
PRINT (string)
This could be the command to print the fabled messages when playing in Win95 with a printer attached. I haven't heard of anyone actually receiving anything though.
QUICK_OBJECTIVE (0, string, player number)
Deeper Dungeons only, sets brief objective description. (?)
QUICK_INFORMATION (0, string, player number)
Deeper Dungeons only, sets brief information description. (?)

Artificial intelligence

COMPUTER_PLAYER (player, integer)
Set the AI for the given player to be a set system, depending on the integer. 0 and 1 are the common values; 2 is the one Jonty Barnes wrote for level 19.
SET_COMPUTER_PROCESS (player, string, integer, integer, integer, integer, integer)
SET_COMPUTER_CHECKS (player, string, integer, integer, integer, integer, integer)
SET_COMPUTER_GLOBALS (player, integer, integer, integer, integer, integer, integer)
Very little idea what any of these mean. Will update if/when I find out more.

Miscellaneous

ALLY_PLAYERS (player, player)
Automatically allies the two given players, usually computers. Unknown effect on human players.
START_MONEY (player, integer)
Does exactly what you'd expect.
SET_GENERATE_SPEED
Speed for generation of creatures in the portal - how many game turns occur between new creatures being added. (So higher is slower.)
NEXT_COMMAND_REUSABLE
Presumably means that the following command can be processed more than once, if the conditions before it are met. I'd guess that if this isn't present, commands are removed from the version of the script in memory when they are processed.
WIN_GAME
LOSE_GAME
Take a wild guess...

Unknown commands

These commands are in the binary but don't appear in any of the original scripts.

SET_HATE
SET_MUSIC
DEAD_CREATURES_RETURN_TO_POOL
DISPLAY_OBJECTIVE_WITH_POS
DISPLAY_INFORMATION_WITH_POS
SET_COMPUTER_EVENT

Values

Boolean
0 or 1 - 1 usually means true, 0 means false
Integer
Well, like, it's a number, innit? :)
Players
PLAYER0
PLAYER1
PLAYER2
PLAYER3
PLAYER_GOOD
ALL_PLAYERS
Global values
ALL_DUNGEONS_DESTROYED
CREATURES_SCAVENGED_GAINED
CREATURES_SCAVENGED_LOST
DOORS_DESTROYED
TOTAL_GOLD_MINED
DUNGEON_DESTROYED
GOLD_POTS_STOLEN
TIMES_BROKEN_INTO
SPELLS_STOLEN
ROOMS_DESTROYED
BATTLES_WON
BATTLES_LOST
CREATURES_ANNOYED
TOTAL_CREATURES_LEFT
TOTAL_AREA
TOTAL_DOORS
TOTAL_RESEARCH
TOTAL_CREATURES
TOTAL_IMPS
BREAK_IN
GAME_TURN
MONEY
Rooms
GUARD_POST
BRIDGE
LAIR
GARDEN
BARRACKS
GRAVEYARD
TEMPLE
SCAVENGER
WORKSHOP
TRAINING
TORTURE
PRISON
RESEARCH
TREASURE
ENTRANCE
Flags
FLAG0
FLAG1
FLAG2
FLAG3
FLAG4
FLAG5
FLAG6
FLAG7
Creature objectives
DEFEND_PARTY
ATTACK_ROOMS
ATTACK_DUNGEON_HEART
ATTACK_ENEMIES
STEAL_SPELLS
STEAL_GOLD
Door types
STEEL
BRACED
WOOD
MAGIC
Trap types
LAVA
WORD_OF_POWER
LIGHTNING
POISON_GAS
ALARM
BOULDER
Spell types
POWER_ARMAGEDDON
POWER_POSSESS
POWER_DESTROY_WALLS
POWER_CHICKEN
POWER_DISEASE
POWER_CONCEAL
POWER_PROTECT
POWER_SPEED
POWER_LIGHTNING
POWER_HOLD_AUDIENCE
POWER_HEAL_CREATURE
POWER_CAVE_IN
POWER_CALL_TO_ARMS
POWER_SIGHT
POWER_SLAP
POWER_OBEY
POWER_IMP
POWER_HAND
Creature types
FLOATING_SPIRIT
ORC
TENTACLE
GHOST
HELL_HOUND
SPIDER
VAMPIRE
BUG
IMP
BILE_DEMON
SORCEROR
DARK_MISTRESS
FLY
DEMONSPAWN
DRAGON
TROLL
SKELETON
HORNY
SAMURAI
THIEF
FAIRY
GIANT
WITCH
TUNNELLER
AVATAR
KNIGHT
DWARF
MONK
ARCHER
BARBARIAN
WIZARD
Timers
TIMER0
TIMER1
TIMER2
TIMER3
TIMER4
TIMER5
TIMER6
TIMER7
Operators
<=
>=
<
>
!=
==

Please send any comments to skeet@pobox.com
Back to the Dungeon Keeper Extras page.