Dungeon Keeper script language

The 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 .
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:
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".
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:'Final' in this context means the one in the released retail game; it doesn't count KeeperFX changes.
*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.
=== 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.
==== 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):
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.
*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:
:*Notepad++ (make sure code page 850 is set)
:*MS-DOS Editor
:*Visual Studio Code (make sure code page 850 is set)
: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:
== References ==
== External links ==
*Dungeon Keeper Script Commands Reference on Lubiki.
*Level Script commands on GitHub.
*Script file documentation by Jon Skeet.
== Notes ==