Skip to content

Script (.txt) Files

Jump to bottom
Julien edited this page Jul 4, 2019 · 4 revisions
  • 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).

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
    <=
    >=
    <
    >
    !=
    ==

Clone this wiki locally