Dungeon Keeper Wiki
Advertisement

The Dungeon Keeper script language is used to script levels in Dungeon Keeper: it is used to specify which rooms, Keeper spells, traps, doors, and creatures (both via the Creature Pool and to each player) are available, who starts with how much gold, how quickly Portals attract creatures, timers, parties and when and where they spawn, winning conditions, amongst other things.

The language was simpler in the early days of Dungeon Keeper's development, with certain commands having fewer parameters and others had yet to be merged into one. Development of the language continues in KeeperFX, with the introduction of new commands and updates to existing ones ongoing as of 2024.

Script files are stored as MAPn.TXT (where n is the five-digit zero-led level number), in the same directory as the other level files.

Features[]

The language relies heavily on if statements (though it doesn't support 'else' clauses), despite only supporting up to 48 (in KeeperFX, this limit is increased to 512) of them in any one script. Any event in a level (whether that be an Action Point being triggered, a timer reaching a certain value, or something else) requires an if statement for its evaluation for anything to happen because of it. Each condition specified by an if statement is checked once per game turn. Certain commands that are often triggered by such conditions can only be executed once, unless preceded by a command that allows re-execution.

There are a number of hard-coded variables (for things such as how much money a player has and how many doors or creatures they have) that can be checked by an if statement, as well as eight 8-bit unsigned (meaning they can store a value between 0 and 255) integer flags (numbered from 0 to 7) for each player (these can also be checked by an if statement). Level designers cannot specify their own variables.

Outside of if statements, the only commands available pertain to setting up the level, such as specifying what's available to whom, what computer players there are and their AI type, and initialising flags and timers (which can also be done in if statements).

From KeeperFX 1.1.0, players are numbered from 0 to 6 (originally, there were only three players and the heroes), and are referred to as PLAYERn (where n is the player number), with the heroes being referred to as PLAYER_GOOD. Player numbers are really colour codes:

Player colours
Player Colour
PLAYER0 Red
PLAYER1 Blue (some say purple)
PLAYER2 Green
PLAYER3 Yellow
PLAYER_GOOD White (not truly white)
PLAYER4 Purple (some say pink)
PLAYER5 Black (not truly black)
PLAYER6 Orange

Although colours cannot be changed for each player, there is no requirement to have all prior players if you want to have a player. For example, you do not also need PLAYER1 or PLAYER2 if you want a yellow player; you can simply have PLAYER3. In fact, The Deeper Dungeons level Kari-Mar does exactly this. However, all levels must have at least one human player, with PLAYER0 typically fulfilling this rôle.

Data types are specific to the game; it expects player, room, trap, door, spell, and creature names to be specific values and not in quotes. Number and text parameters are treated similarly to integers and strings respectively in normal programming languages.

KeeperFX features commands that allow for far greater manipulation of the map than the original game; it supports commands to give players gold, alter terrain, change a creature's owner, amongst others.

History[]

Level designer Barrie Parker was "responsible for the content of the script language".[1]

The earliest known surviving scripts used "Vince's Generic Script Base", which is evidently dated 30 July 1996. This early version of the script language has some significant differences to the final:[Note 2]

  • There were some queerly named commands, such as NEUTRAL_ENTRANCE_LEVEL and CREATURE_INBY. The former supposedly set creatures' maximum experience level, and the latter appears to have added creatures to the Creature Pool like the ADD_CREATURE_TO_POOL command does in the final version, or perhaps it set a creature's availability in the pool to a specific value.
  • COMPUTER_PLAYER only took one parameter; it lacks the AI type. The AI was set with the COMPUTER_SPEED and COMPUTER_DESIRE commands, which are absent in the final version: they likely morphed into the undocumented SET_COMPUTER_PROCESS, SET_COMPUTER_CHECKS, SET_COMPUTER_EVENT, and SET_COMPUTER_GLOBALS commands, which are used in some campaign levels. COMPUTER_SPEED took three parameters: the player, the general speed, and the dig speed. COMPUTER_DESIRE took five parameters: player, gold, creatures, "blood", and building.
  • ADD_TO_PARTY lacked the objective and countdown parameters.
  • There was a CREATE_TEXT command that was used to specify a string into a slot. This was then used by the DISPLAY_OBJECTIVE command, which took only the string number as its parameter.
  • There was a MESSAGE command, likely used for debugging purposes.
  • Counting and numbering appeared to start from 0 rather than 1.

By spring 1997, the language had evolved to the form used by the final version. The 28 May 1997 build had a PRINT command that was used in Moonbrush Wood, Sleepiburgh, and Skybird Trill to print out (via a printer) taunts from the Avatar, but this Easter Egg and command were cut due to testers mistaking the taunts for genuine death threats.[2]

Post-release added features[]

The Deeper Dungeons[]

The Deeper Dungeons added the QUICK_OBJECTIVE and QUICK_INFORMATION commands, which include the string-defining behaviour of the earlier CREATE_TEXT command. Strings created by these commands are put into their own buffer, and are discrete from the ones in the data files. However, these strings are fixed; unlike the strings in the data files, there is no set language, and quick strings are read as-is and interpreted in the code page of the language the game is running in, meaning that in some languages, some characters in quick strings can appear as gibberish or something otherwise unexpected due to a mismatch. Only unaccented Latin alphabet text can be displayed without issues across all languages, which means that English is the only language that is unlikely to be problematic when used for quick text.

Quick text corruption example
Original text Corrupted text (Japanese)
Quick text Dungeon Keeper Quick text corrupted Dungeon Keeper

KeeperFX[]

The language and its features continue to be developed, as part of the KeeperFX expansion of the game. New features include (but are not limited to):

Wetlands colourful fire Dungeon Keeper FX

Creation of effects such as this gay fire fuelled by spells emanating from the Hero Gates is one of many things that are possible.

  • Advanced timer manipulation
  • Object creation
  • Custom Dungeon Specials
  • Effect creation
  • Terrain manipulation
  • Force-attract creatures
  • Dungeon Heart health manipulation
  • In-game chat messages
  • Levelling up creatures
  • Swapping creatures and object graphics

Trivia[]

  • Notepad++ has a plugin for the Dungeon Keeper script language, and it recognises KeeperFX commands.[3]
    Notepad++ Dungeon Keeper level script codepage

    Setting the code page for accented characters in Western European languages in Notepad++

  • Using Windows Notepad to edit script files is not recommended. The layman's explanation as to why is described above. The technical explanation is as follows: it only supports UTF-8, UTF-16, and ANSI, for which it uses the Windows-1252 code page. UTF-16 breaks maps, and while UTF-8 and ANSI are okay for English, they cause problems for maps whose quick text is in another language. The codes for some characters, such as accented characters, are not what the game expects; for example, the game expects the character â to be 0x83, but in ANSI, it's 0xE2, which is what Notepad'll save it as when using ANSI. The game interprets 0xE2 as Ô, so that's what'll appear in-game in this circumstance. In UTF-8, it's 0xC3A2, which would mean ├ó is what appears, but the ├ character is not supported; U appears instead, so Uó is what will appear. To solve this issue for Western European languages, use a text editor that supports code page 850. Compatible text editors include:
Unfortunately, some languages, such as Central European languages, use non-standard codes. The only way to get them to work properly is to hex-edit scripts that use these characters. The code pages for each language are as follows:
Code pages
Language Code page
English 850
French 850
Spanish 850
Italian 850
German 850
Dutch 850
Polish 852 (with non-standard codes)
Czech 852 (with non-standard codes)
Swedish 865
Japanese 932 (Windows-31J)
Chinese 936
Korean 949 (with non-standard codes)
Russian Non-standard

References[]

  1. 1.0 1.1 Prima's Official Guide To Dungeon Keeper Gold Edition. p. 333. Prima Publishing. (1998). ISBN 978-0-7615-1581-4.
  2. Interview with Simon Carter discussing DK development, death threats, DK3 & more!. Keeper Klan (2013). Retrieved on 26 February 2021.
  3. YourMaster (2 September 2014). DK Level script plugin for Notepad++. Keeper Klan. Retrieved on 6 April 2021.

External links[]

Notes[]

  1. The earliest known surviving script from the game's development is dated 17 September 1996, for Level 106.
  2. 'Final' in this context means the one in the released retail game; it doesn't count KeeperFX changes.
Advertisement