KeeperFX API

KeeperFX has a TCP API server that can be used for inter-process communication (IPC). This means that you can make tools to interact with the game using a simple and straightforward interface.

This page is for software developers who want to write an application that can interact with the game.

Intro

The TCP server can be configured using the API_ENABLED and API_PORT variables in keeperfx.cfg. By default the API is disabled, and the port is set to 5599. Set API_ENABLED to ON to enable the API.

The API is a simple plaintext TCP server that uses JSON for communication. One message is read and handled on every game tick. This might be a bit slow, but it does make sure nothing blocks and the game runs as smooth as possible.

When developing a program or tool that communicates with the KeeperFX API, you can use telnet to try out your commands.

Features

The KeeperFX API exposes quite a few different features that you can make use of:

  • Execute a map command (Ex: ADD_CREATURE_TO_LEVEL, Although there is no support for scope bound commands yet like WIN_GAME)
  • Execute a console command (Ex: !frametime)
  • Read a variable
  • Set a variable
  • Get all player flags
  • Subscribe to a variable (+ unsubscribe)
  • Subscribe to an event (WIN_GAME, LOSE_GAME, GAME_LOADED, GAME_SAVED + unsubscribe)
  • Get information about the current map (+ campaign)
  • Get information about KeeperFX (currently only the version)

Subscriptions

The KeeperFX API implements a subscription based system for events and the change of variables. This way you can monitor when a variable in the game changes and act however you want when it gets changed. For example, you can have your 3rd party tool display the amount of imps you have, by subscribing to the IMP variable and waiting for a var_update event . You can also monitor specific events like a game is won or lost.

How to interact with the API

You simply need to code something to connect with the TCP server and send JSON string data and read the response. Almost all messages that are sent to the server will be given a return message with "success": true.

Data involving subscribed events and variables will be sent whenever they are changed. These subscription messages should not conflict with the order of return data for other actions you sent. The first response you get after you send a message will always be the corresponding response.

Remember that only a single incoming message is handled per game turn. This is meant to protect the game from freezing. Subscriptions will be grouped and sent as multiple messages in a single game tick, after a possible response message. This way you do not need to care about the correct order of messages, and you can handle every message that isn't a response separately.

Acknowledgement IDs (ack id)

The API allows you to add an extra ack variable to requests. This variable will be returned in the response exactly as it was given. This is useful if you have a client that reads response packets asynchronously. By generating a unique ID or string and sending it with your request you can always link a response packet back to the original request.

If you use a blocking TCP client you can simply read the first response after sending a request. You will not need this extra variable in this case.

Responses

Action

Every action will return with a success value, being either true or false:

key type value
success bool true
Data

Every action that returns data will put the data in the JSON as such:

key type value
success bool true
data object {}

If you are requesting the value of a variable or some specific string it will make data either an int or string.

Actions

get_kfx_info

Gets information about the KeeperFX instance that is active. This will return data about the game of the player. Currently only the version is returned. This will most likely change in the future.

key type value
action string "get_kfx_info"

Return data struct:

key type example return value
kfx_version string 1.0.0
get_level_info / get_map_info

Gets information about the map that is being played. These 2 actions are synonyms.

key type value
action string "get_level_info" or "get_map_info"

Return data struct:

key type example return value
level_name string Name of the level
level_number int The map number of this map. Ex: 123 for map00123
players int How many players are on this map
mapsize_x int Width of the map (in slabs)
mapsize_y int Height of the map (in slabs)
is_multiplayer bool Whether or not this is a multiplayer level or not
campaign campaign struct Data about the current campaign

Campaign struct:

key type example return value
campaign_name string The name of the campaign. Ex: 'Dungeon Keeper - Original Campaign'
campaign_display_name string The display name of the campaign. Ex: 'Dungeon Keeper original campaign'
campaign_fname string The filename of the campaign. Ex: 'keeporig'
is_map_pack bool Whether or not this campaign is actually a mappack instead.
subscribe_var

Subscribe to a variable and receive messages whenever the variable changes.

key type value
action string "subscribe_var"
var string The variable name
player (optional) string/int The player this variable belongs to. (Default: PLAYER0)

Returns "success": true if we are now subscribed to the variable. This action will also return true if we are already subscribed to it.

Possible errors:

error description
MISSING_VAR No variable supplied
UNKNOWN_VAR Unable to map given variable to game variable
SUB_FAILED Failed to sub to variable
unsubscribe_var

Unsubscribe a variable we previously subscribed to.

key type value
action string "unsubscribe_var"
var string The variable name
player (optional) string/int The player this variable belongs to. (Default: PLAYER0)

Returns "success": true if we are now unsubscribed. This action will also return true if we are not subscribed to it.

Possible errors:

error description
MISSING_VAR No variable supplied
UNKNOWN_VAR Unable to map given variable to game variable
UNSUB_FAILED Failed to unsubscribe the variable
subscribe_event

Subscribe to a game event. After subscribing to this game event the API will notify us of whenever this event happens.

key type value
action string "subscribe_event"
event string The event name (in capital letters)

Returns "success": true if we are now subscribed to the event. This action will also return true if we are already subscribed to it.

Possible events:

event name description
LOSE_GAME When the player loses the game
WIN_GAME When the player wins the game
GAME_SAVED When the player saves the game
GAME_LOADED When the player loads the game
GAME_STARTED When the player starts the map

Possible errors:

error description
MISSING_EVENT No event supplied
STRING_TOO_LONG The given event string is too long
SUB_FAILED Failed to sub to event
unsubscribe_event

Unsubscribe from a game event.

key type value
action string "unsubscribe_event"
event string The event name (in capital letters)

This returns "success": true if the command was successful.

This follows the same events as subscribe_event.

Possible errors:

error description
MISSING_EVENT No event supplied
STRING_TOO_LONG The given event string is too long
SUB_FAILED Failed to sub to event
unsubscribe_all

Unsubscribe from a all events and variable updates.

key type value
action string "unsubscribe_event"

This always returns "success": true.

map_command

Runs a map command in the given map.

key type value
action string "map_command"
command string The map command

This returns "success": true if the command was successful.

Scopes and multi-line commands do NOT work (yet) ! There are some commands that do not work as a single line either, like WIN_GAME or LOSE_GAME. This will most likely be changed in a future version.

Running commands when the game is paused does not work either, and you will get a "success": false back with the corresponding error.

Possible errors:

error description
GAME_IS_PAUSED The game is paused
MISSING_COMMAND You did not supply a command
FAILED_TO_EXECUTE_MAP_COMMAND The map command failed to execute. It's possible that this map command does not exist
console_command

Execute a console command for the specified player.

key type value
action string "console_command"
command string The console command
player (optional) string/int The player we want to have execute this console command

This returns "success": true if the command was successful.

Possible errors:

error description
GAME_IS_PAUSED The game is paused
MISSING_COMMAND You did not supply a command
FAILED_TO_EXECUTE_CONSOLE_COMMAND The console command failed to execute. It's possible that this map command does not exist or something else went wrong.
get_all_player_flags

Get a list of all player flags.

key type value
action string "get_all_player_flags"

Return data struct:

key type example return value
PLAYER0 flag struct {}
... flag struct {}
PLAYER6 flag struct {}
PLAYER_GOOD flag struct {}
PLAYER_NEUTRAL flag struct {}

Flag struct:

key type value
FLAG0 int <value>
... int <value>
FLAG7 int <value>
read_var

Get a the value of a game variable.

key type value
action string "read_var"
var string The variable name
player (optional) string/int The player this variable belongs to. (Default: PLAYER0)

Return data:

key type value
success bool true
data int <variable value>

Possible errors:

error description
MISSING_VAR No variable supplied
UNKNOWN_VAR Unable to map given variable to game variable
set_var

Set the value of a game variable.

key type value
action string "set_var"
var string The variable name
player (optional) string/int The player this variable belongs to. (Default: PLAYER0)
value int The value this variable should be set to

Possible variable types to update: FLAG, CAMPAIGN_FLAG, BOX_ACTIVATED, SACRIFICED, REWARDED

Return data:

key type value
success bool true

Possible errors:

error description
MISSING_VAR No variable supplied
UNKNOWN_VAR Unable to map given variable to game variable
UNABLE_TO_SET_VAR Unable to set this kind of variable (look above)
VALUE_MUST_BE_INT The given value must be an integer