This article documents a Zandronum-specific ACS feature which may not be supported by ZDoom and its other child ports.

Zandronum has database support, allowing you to persist data across server restarts.

Note: You need to have port 10666 forwarded to test this online.

Database Functions

Data retrieval and saving

Function Parameters Return Description
GetDBEntry string namespace, string key int value Retrieve a numeric value out of the database.
SetDBEntry string namespace, string key, int value void Set a database row to a specific numeric value.
GetDBEntryString string namespace, string key string value Retrieve a string value out of the database.
SetDBEntryString string namespace, string key, string value void Set a database row to a specific string value.
IncrementDBEntry string namespace, string key, int value void Increment a database row by a specific number.

Reading and writing data to a database is done through an easy-to-use namespace/key/value system. If you put data into the database with a specific namespace and key, you can retrieve that same data by supplying the same namespace and key later.

Namespaces are intended to be roughly analogous to "tables" in other databases, used to split up different sets of data by concern. Namespaces can also be iterated through and sorted.

Iteration and Sorting

Function Parameters Return Description
GetDBEntryRank string namespace, string key, bool order int position Sort a namespace by value and return the position of the given key in that namespace.
GetDBEntries string namespace resource results Return a resource that contains a pointer to all rows in a namespace.
SortDBEntries string namespace, int limit, int offset, bool order resource results Return a resource that contains a pointer to rows in the namespace sorted by value.
CountDBResults resource results int count Count the number of rows a resource contains.
GetDBResultKeyString resource results, int row string key Returns the key at the specific row of a resource.
GetDBResultValueString resource results, int row string value Returns the value at the specific row of a resource as a string.
GetDBResultValue resource results, int row int value Returns the value at the specific row of a resource as an integer.
FreeDBResults resource results void Free a resource from memory.

Most of these functions deal with a resource. A resource is simply a number that points to results of a database query. The queries that Zandronum allows you to make is either retrieving all rows in a namespace at once, or retrieving a limited subset of them in a sorted fashion. Once you have a query result as a resource, you then use functions to figure out what exactly that result contains.

Transactions

Function Parameters Return Description
BeginDBTransaction void void Begin a database transaction.
EndDBTransaction void void Commit the database transaction.

A transaction prevents functions that normally write to the database from writing immediately. Instead, they are kept in memory until you end the transaction, at which point it writes everything at once. If you need to write lots of rows to the database, writing them all at once in a transaction is much faster than writing them one by one. Transactions are also guaranteed to be atomic, which means that if Zandronum crashes during the transaction, either everything in a transaction is written to the database or nothing gets written - the database will never be left in a state where only half the rows were written.

A word of warning

Using any ACS database function stops the entire gamesim while it runs the database query. This is normally not much of an issue, but if you start to see performance issues with your modification, looking at how many database queries you're running is a good place to start. If your database queries are causing performance issues, try batching your queries up and running them all at once with a transaction.

Remote Database support

Zandronum does not support connecting to a remote database server over a network. Due to limitations of ACS, database functions lock up the entire game simulation until a result is found - such a scheme would be unworkable over a something as fickle and with as much latency as the Internet.

However, if you know a little bit of non-ACS programming or scripting, you can connect to the on-disk database with any language that supports SQLite3 and do whatever you want with it, including sending it someplace else over a network. If this sounds like fun, but you have no programming experience aside from ACS, this author recommends Python since it works on Windows, Linux and OSX and comes with sqlite3 support out of the box.

Examples

This article lists no examples, please add one.