KeeperFX

https://keeperfx.net/wiki
Admin
KeeperFX is an open-source remake and extensive modification for Dungeon Keeper, providing modern...
Tokens:175,694
Snippets:1,192
Trust Score:8.4
Update:1 week ago
Show doc for...
Tokens:
Raw
### Game Setup Example

Source: https://keeperfx.net/wiki/lua-level-script

Sets game generation speed, starting money, and creature availability.

```lua
SetGenerateSpeed(300)			  
StartMoney(PLAYER0, 7500)															 
CreatureAvailable(PLAYER1, "TROLL", true, 2)
```

--------------------------------

### COMPUTER_PLAYER setup example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Sets up standard computer player to ensure no processes are skipped when AI takes action.

```plaintext
REM Set up standard computer player to be sure no processes will be skipped when AI takes action.
COMPUTER_PLAYER(PLAYER1,0)

```

--------------------------------

### START_MONEY example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example of START_MONEY that gives all players 40000 gold at the start of the level.

```plaintext
REM Give all players 40000 in gold at the start of the level
START_MONEY(ALL_PLAYERS,40000)

```

--------------------------------

### MAGIC_AVAILABLE examples

Source: https://keeperfx.net/wiki/Level-Script-Commands

Examples showing how to make a power available from the start or require research. The first example sets POWER_SPEED available immediately; the second requires research for POWER_CONCEAL.

```plaintext
REM This Speed Creature power has been set so that it is available from the start of the level.
MAGIC_AVAILABLE(ALL_PLAYERS,POWER_SPEED,1,1)

REM This Conceal Creature power has been set do that it needs to be researched before it becomes available.
MAGIC_AVAILABLE(ALL_PLAYERS,POWER_CONCEAL,1,0)

```

--------------------------------

### DOOR_AVAILABLE example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example making the Wooden Door available to PLAYER1 with zero doors given at start.

```plaintext
REM The Wooden Door is now available to the player to manufacture and none have been given to him at the start
DOOR_AVAILABLE(PLAYER1,WOOD,1,0)

```

--------------------------------

### ROOM_AVAILABLE examples

Source: https://keeperfx.net/wiki/Level-Script-Commands

Examples showing how to make a room available from the start or require research. The first example sets TREASURE room available immediately; the second requires research for TORTURE room.

```plaintext
REM This Treasure Room has been set so that it is available from the start of the level.
ROOM_AVAILABLE(ALL_PLAYERS,TREASURE,1,1)

REM This Torture Chamber has been set do that it needs to be researched before it becomes available.
ROOM_AVAILABLE(ALL_PLAYERS,TORTURE,1,0)

```

--------------------------------

### CREATE_PARTY example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example of creating a party named FIRST_STRIKE.

```plaintext
CREATE_PARTY(FIRST_STRIKE)

```

--------------------------------

### COMPUTER_PLAYER example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example that sets up an aggressive computer using Player 2's dungeon.

```plaintext
REM Set up and aggressive computer that uses Player 2's dungeon
COMPUTER_PLAYER(PLAYER2,1)
```

--------------------------------

### IMPORT example with ADD_GOLD_TO_PLAYER and MAX_CREATURES

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example showing how to use IMPORT to bring values from previous level into commands.

```plaintext
REM Give player 2 the gold he ended with on the previous level
ADD_GOLD_TO_PLAYER(PLAYER2,IMPORT(PLAYER2,CAMPAIGN_FLAG7))

REM Player0 gets no more creatures as he managed to annoy from player1 last level.
MAX_CREATURES(PLAYER0,IMPORT(PLAYER1,CAMPAIGN_FLAG1))

```

--------------------------------

### SET_TIMER example with IF and WIN_GAME

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example showing how to set a timer and trigger a win when it reaches a threshold.

```plaintext
REM Setup Player 0's TIMER0
SET_TIMER(PLAYER0,TIMER0)

REM When TIMER0 reaches 1000, win the game
IF(PLAYER0,TIMER0 >= 1000)
  WIN_GAME
ENDIF

```

--------------------------------

### NEW_OBJECT_TYPE example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example that creates a new object type and configures it with SET_OBJECT_CONFIGURATION commands.

```plaintext
NEW_OBJECT_TYPE(MY_NEW_CRATE)
SET_OBJECT_CONFIGURATION(MY_NEW_CRATE,Genre,WORKSHOPBOX)
SET_OBJECT_CONFIGURATION(MY_NEW_CRATE,AnimationID,114)
SET_OBJECT_CONFIGURATION(MY_NEW_CRATE,AnimationSpeed,256)
SET_OBJECT_CONFIGURATION(MY_NEW_CRATE,MaximumSize,300)
SET_OBJECT_CONFIGURATION(MY_NEW_CRATE,DestroyOnLava,1)
SET_OBJECT_CONFIGURATION(MY_NEW_CRATE,MapIcon,531)
SET_OBJECT_CONFIGURATION(MY_NEW_CRATE,Properties,CHOWNED_ON_ROOM_CLAIM)

```

--------------------------------

### BONUS_LEVEL_TIME example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example showing how to set the bonus timer to 12000 turns.

```plaintext
BONUS_LEVEL_TIME(12000)

```

--------------------------------

### RESET_ACTION_POINT example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example showing how to reset Action Point 3 so it can be triggered again.

```plaintext
REM After the following line, the action point 3 can be triggered again
RESET_ACTION_POINT(3)

```

--------------------------------

### WIN_GAME example with IF

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example showing how to win the level when Player 1's dungeon is destroyed, using IF and WIN_GAME commands.

```plaintext
REM Win the level if Player 1's dungeon is destroyed
IF(PLAYER1,DUNGEON_DESTROYED==1)
  WIN_GAME
ENDIF

```

--------------------------------

### SET_DOOR_CONFIGURATION example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example that adjusts door selling values and properties after many doors have been destroyed. Uses IF condition on DOORS_DESTROYED.

```plaintext
REM On this level, magic and iron doors do not give much value after several have been sold or destroyed.
IF(PLAYER0,DOORS_DESTROYED > 5)
    SET_DOOR_CONFIGURATION(MAGIC,SellingValue,150)
    SET_DOOR_CONFIGURATION(IRON,SellingValue,100)
    SET_DOOR_CONFIGURATION(WOOD,Properties,"RESIST_NON_MAGIC MIDAS")
ENDIF

```

--------------------------------

### USE_POWER example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example usage of USE_POWER. Blue will end the level when at 25 units by casting POWER_ARMAGEDDON for free.

```plaintext
REM Blue will end the level when at 25 units
IF(PLAYER1,TOTAL_CREATURES >= 25)
  USE_POWER(PLAYER1,POWER_ARMAGEDDON,1)
ENDIF

```

--------------------------------

### SET_GENERATE_SPEED example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example that creates a new creature for each player every 500 game turns. The comment is included as shown.

```plaintext
REM Create a new creature for each player every 500 game turns
SET_GENERATE_SPEED(500)
```

--------------------------------

### SET_BOX_TOOLTIP example with ADD_OBJECT_TO_LEVEL

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example showing how to set a tooltip on a custom special box and place it on an action point using ADD_OBJECT_TO_LEVEL.

```plaintext
SET_BOX_TOOLTIP(4, "Cast Rebound on your creatures.")

REM Place a Special box with ID 4 on action point 2.
ADD_OBJECT_TO_LEVEL(SPECBOX_CUSTOM, 2, 4)

```

--------------------------------

### TRAP_AVAILABLE example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example making the Word of Power Trap available to PLAYER1 with zero traps given at start.

```plaintext
REM *** The Word of Power Trap is now available to the player to manufacture
REM *** and none have been given to him at the start
TRAP_AVAILABLE(PLAYER1,WORD_OF_POWER,1,0)

```

--------------------------------

### TUTORIAL_FLASH_BUTTON example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Makes a workshop available, shows a quick information message, and flashes button 13 for 200 turns.

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

```

--------------------------------

### DRAWFROM usage examples

Source: https://keeperfx.net/wiki/Level-Script-Commands

Examples of DRAWFROM used in script commands: random start money, random creature type, and random hero gate.

```plaintext
REM Human player will have random start gold between 10000 and 15000
START_MONEY(PLAYER0,DRAWFROM(10000,11000,12000,13000,14000,15000))

REM One bug type creature will be added to pool
ADD_CREATURE_TO_POOL(DRAWFROM(FLY,BUG,SPIDER),5)

REM Add one of three predefined Hero parties to Hero gate 6 or 9
ADD_PARTY_TO_LEVEL(PLAYER0,DRAWFROM(thugs,fiends,dudes),DRAWFROM(-6,-9),1)

```

--------------------------------

### TUTORIAL_FLASH_BUTTON syntax and example

Source: https://keeperfx.net/wiki/level-script-commands

Flashes a toolbar button until selected. [button] accepts a number or name of room/trap/door/power. [duration] in game turns; positive sets duration, 0 flashes until clicked. Example shows flashing button 13 for 200 turns after making a workshop available.

```plaintext
TUTORIAL_FLASH_BUTTON([button],[duration])

```

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

```

--------------------------------

### IF/ENDIF example with FLAG1 and MONEY

Source: https://keeperfx.net/wiki/Level-Script-Commands

Shows a nested IF block that adds gold to a player. The player will never get the gold because FLAG1 is reset before the next script level is evaluated.

```keeperfx
IF(PLAYER0,FLAG1 >= 1)
  IF(PLAYER0,MONEY < 10000)
    NEXT_COMMAND_REUSABLE
    ADD_GOLD_TO_PLAYER(PLAYER0,1000)
  ENDIF
  SET_FLAG(PLAYER0,FLAG1,0)
ENDIF

```

--------------------------------

### Example: Configuring gold digging processes

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example configuration for PLAYER1. Sets DIG TO CLOSE GOLD with money minimum 1250, turn scale 600, 5 gold tiles, max distance 20. Sets DIG TO GREEDY GOLD and DIG TO GREEDY GOLD2 with turn scale 76666 to delay digging for gold for two hours after first greedy dig.

```plaintext
REM *** Dig safely for gold if more than 1250 is in treasury; search for vein in 20 squares,
REM *** wait 30 secs 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 after first time digging greedly 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)

```

--------------------------------

### SET_CREATURE_FEAR example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example usage of SET_CREATURE_FEAR, setting spider fear to 190.

```plaintext
REM Set the spider fear to 190
SET_CREATURE_FEAR(SPIDER,190)

```

--------------------------------

### SET_MUSIC example with custom track and timer

Source: https://keeperfx.net/wiki/level-script-commands

Example that plays a custom track when the player dungeon is broken into, then switches back to track 3 after 15 seconds and when all battles are over.

```plaintext
REM Play custom track when the heroes made it into the player dungeon
IF(PLAYER0,TIMES_BROKEN_INTO >= 1)
	SET_MUSIC("high_tension_sonata4.mp3")
	SET_TIMER(PLAYER0,TIMER1)
ENDIF
REM Set it back to track 3 after at least 15 seconds and all fights are over
IF(PLAYER0,TIMER1 > 300)
	IF(PLAYER0,ACTIVE_BATTLES == 0)
		SET_MUSIC(3)
	ENDIF
ENDIF
```

--------------------------------

### SET_CREATURE_HEALTH example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example usage of SET_CREATURE_HEALTH, setting orc health to 1000.

```plaintext
REM Set the orc health to 1000
SET_CREATURE_HEALTH(ORC,1000)

```

--------------------------------

### SET_CREATURE_CONFIGURATION example: adjust entrance room and slab requirements

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example that sets HELL_HOUND's EntranceRoom to LAIR, GUARD_POST, GARDEN and RoomSlabsRequired to 9, 4, 1.

```plaintext
REM On this level, Hounds are attracted by 9 slabs of Lair, 4 slabs of Guard Post and 1 slab of Hatchery
REM instead of 9 slabs of Scavenger Room.
SET_CREATURE_CONFIGURATION(HELL_HOUND,EntranceRoom,LAIR,GUARD_POST,GARDEN)
SET_CREATURE_CONFIGURATION(HELL_HOUND,RoomSlabsRequired,9,4,1)

```

--------------------------------

### USE_SPELL_ON_CREATURE example with IF

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example showing how to use USE_SPELL_ON_CREATURE to freeze a blue dragon.

```plaintext
REM Freeze the blue dragon.
IF(PLAYER1,FLAG1 == 1)
  USE_SPELL_ON_CREATURE(PLAYER1,DRAGON,ANYWHERE,SPELL_FREEZE,0)
ENDIF

```

--------------------------------

### SET_COMPUTER_PROCESS example: building rooms

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example script that builds a 4x3 treasure room, a 2x3 hatchery, and a 3x3 scavenger room after the prison is built. Priorities are set to 0 for important rooms and -10 for the scavenger room.

```plaintext
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
SET_COMPUTER_PROCESS(PLAYER1,"BUILD A HATCHERY",      0,2,3,13,0)

REM Build 3x3 scavenger room, only  after the Prison has been built
SET_COMPUTER_PROCESS(PLAYER1,"BUILD A SCAVENGER ROOM",-10,3,3,9,8)

```

--------------------------------

### REM example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example of a REM comment line used to label a section.

```plaintext
REM ***** Setup Level Section *****

```

--------------------------------

### StartMoney

Source: https://keeperfx.net/wiki/lua-level-script

Sets the starting money for a player.

```APIDOC
## StartMoney

### Description
Sets the starting money for a player.

### Method
StartMoney

### Parameters
- **player** (player) - Required - The player to set money for.
- **amount** (number) - Required - The amount of money to start with.

### Example
```lua
StartMoney(PLAYER0, 7500)
```
```

--------------------------------

### ADD_CREATURE_TO_POOL example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example of ADD_CREATURE_TO_POOL that adds 20 BILE_DEMONs to the creature pool.

```plaintext
ADD_CREATURE_TO_POOL(BILE_DEMON,20)

```

--------------------------------

### USE_POWER command syntax and example

Source: https://keeperfx.net/wiki/level-script-commands

Syntax and example for the USE_POWER command. Casts an untargeted keeper power. The example shows using POWER_ARMAGEDDON for free when player 1 has at least 25 creatures.

```plaintext
USE_POWER([caster_player],[power_name],[free])

```

```plaintext
REM Blue will end the level when at 25 units
IF(PLAYER1,TOTAL_CREATURES >= 25)
  USE_POWER(PLAYER1,POWER_ARMAGEDDON,1)
ENDIF

```

--------------------------------

### SET_CREATURE_ARMOUR example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example usage of SET_CREATURE_ARMOUR, setting demon spawn armour to 60.

```plaintext
REM Set the demon spawn armour to 60
SET_CREATURE_ARMOUR(DEMON_SPAWN,60)

```

--------------------------------

### SET_SACRIFICE_RECIPE example with custom reward and flag

Source: https://keeperfx.net/wiki/level-script-commands

Example showing how to create a sacrifice recipe with CUSTOMREWARD and FLAG3, then check the flag and grant gold. Also includes a comment and a second recipe for sacrificing five heroes to summon an avatar.

```plaintext
SET_SACRIFICE_RECIPE(CUSTOMREWARD, FLAG3, WIZARD, MONK)
IF(PLAYER0,FLAG3 >= 1)
  QUICK_INFORMATION(2, "If you give the dark gods wizards and monks, we'll give you gold", ALL_PLAYERS)
  NEXT_COMMAND_REUSABLE
  ADD_GOLD_TO_PLAYER(PLAYER0,666)
  NEXT_COMMAND_REUSABLE
  SET_FLAG(PLAYER0,FLAG3,0)
ENDIF

REM Sacrifice 5 heroes for the avatar to attack from the temple
SET_SACRIFICE_RECIPE(MkGoodHero,AVATAR,KNIGHT,SAMURAI,WIZARD,GIANT,MONK)
```

--------------------------------

### SET_CREATURE_STRENGTH example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example usage of SET_CREATURE_STRENGTH, setting demon spawn strength to 190.

```plaintext
REM Set the demon spawn strength to 190
SET_CREATURE_STRENGTH(DEMON_SPAWN,190)

```

--------------------------------

### COMPUTER_PLAYER example 2

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example showing heroes that build rooms and can be defeated by killing their heart, plus black roaming creatures that attack everybody.

```plaintext
REM On this map the heroes build rooms and can be defeated by killing their heart.
COMPUTER_PLAYER(PLAYER_GOOD,9)
REM And also, there are black roaming creatures on the map that belong to no dungeon and attack everybody.
COMPUTER_PLAYER(PLAYER5,ROAMING)
```

--------------------------------

### Command line example: -level and -campaign

Source: https://keeperfx.net/wiki/command-line-options

Use this command to load a specific level from a campaign or map pack. The example loads level 80 from the 'deepdngn' campaign, which is Morkardar.

```text
keeperfx.exe -level 80 -campaign deepdngn
```

--------------------------------

### DEAD_CREATURES_RETURN_TO_POOL example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example of DEAD_CREATURES_RETURN_TO_POOL that prevents dead creatures from returning to the pool on this map.

```plaintext
REM Dead creatures will not return to pool on this map.
DEAD_CREATURES_RETURN_TO_POOL(0)

```

--------------------------------

### TUTORIAL_FLASH_BUTTON

Source: https://keeperfx.net/wiki/level-script-commands

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

```APIDOC
## TUTORIAL_FLASH_BUTTON

### Description
Flashes a button on the toolbar until the player selects it.

### Syntax
```
TUTORIAL_FLASH_BUTTON([button],[duration])
```

### Parameters
- **button** (integer or string) - Required - The unique number of the button. It also accepts the name of the room, trap, door or power.
- **duration** (integer) - Required - In game turns. Setting it to positive number controls how long the button is flashing. Setting it to 0 will flash the button until clicked, with no time limit.

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

--------------------------------

### ADD_TUNNELLER_TO_LEVEL examples

Source: https://keeperfx.net/wiki/Level-Script-Commands

Three examples showing how to add Tunnellers with different targets: an Action Point, a player's Dungeon Heart, and the dungeon of the player with the highest score. Each example includes a REM comment explaining the behavior.

```plaintext
REM Add a level 6 Hero Tunneller at Action Point 7. He will tunnel towards Action Point 5
ADD_TUNNELLER_TO_LEVEL(PLAYER_GOOD,7,ACTION_POINT,5,6,400)

REM Add a level 4 Hero Tunneller at Action Point 3. He will tunnel 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 Action Point 5. He will tunnel towards
REM *** the dungeon of the player with the highest score
ADD_TUNNELLER_TO_LEVEL(PLAYER_GOOD,5,APPROPRIATE_DUNGEON,0,9,400)

```

--------------------------------

### TUTORIAL_FLASH_BUTTON command syntax

Source: https://keeperfx.net/wiki/Level-Script-Commands

Flashes a button on the toolbar until selected. Parameters: [button] button number or name, [duration] in game turns; 0 flashes until clicked.

```plaintext
TUTORIAL_FLASH_BUTTON([button],[duration])

```

--------------------------------

### NEXT_COMMAND_REUSABLE example with timer loop

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example showing how to use NEXT_COMMAND_REUSABLE to create a loop that adds a hero every 1000 game turns. Place it before every command in the loop, but not before IF commands.

```plaintext
REM *** This loop adds a new hero to the level at Hero Gate 3 every 1000 game turns. This is done by
REM *** starting a timer, adding the hero when it reaches 1000 and 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

```

--------------------------------

### RESEARCH command example

Source: https://keeperfx.net/wiki/Level-Script-Commands

Example usage of RESEARCH: sets research points for POWER_CHICKEN to 10000 for PLAYER1.

```plaintext
RESEARCH(PLAYER1,MAGIC,POWER_CHICKEN,10000)

```
Tokens:
Raw