Scripted Database – Arma 3
m (category) |
Lou Montana (talk | contribs) m (Some wiki formatting) |
||
| (3 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
{{TOC|side}} | {{TOC|side}} | ||
A [[Arma 3: Scripted Database|Scripted Database]] is a simple way to manage information with ingame functions from Bohemia Interactive and has been introduced in [[{{tkoh}}]]. Instead of using file operations it is a semi persistent sqf database. This means that the database is only | {{Feature|informative|{{GVI|arma3|2.02}} For better peformance (faster access and write speeds) you can use [[HashMap]]s instead.}} | ||
A [[Arma 3: Scripted Database|Scripted Database]] is a simple way to manage information with ingame functions from Bohemia Interactive and has been introduced in [[{{tkoh}}]]. Instead of using file operations it is a semi persistent sqf database. This means that the database is only available during the mission and can be modified with ingame commands. The downside is that it will be wiped when the mission ends or the game/server crashes. To make the database persistent you can save it periodically to the [[profileNamespace]]. | |||
| Line 25: | Line 26: | ||
=== Declaring An Empty Array === | === Declaring An Empty Array === | ||
The most straightforward option. Simply add | The most straightforward option. Simply add <sqf inline>TAG_database = [];</sqf> to any script where you want to declare the database, eg [[Event Scripts#initServer.sqf|initServer.sqf]]. | ||
=== Importing From An .xml File === | === Importing From An .xml File === | ||
| Line 41: | Line 42: | ||
The Scripted Database consists of classes and values. Classes can be identified by the class symbol "#" while the symbol for values is "&". The sole purpose of [[BIS_fnc_dbSymbolClass]] and [[BIS_fnc_dbSymbolValue]] is to return this sign. While the class is followed by an array which contains values, the value is only followed by its content which can be any data type. After the values content might follow another value or the array for that class can end. Here is an example of what the database looks like: | The Scripted Database consists of classes and values. Classes can be identified by the class symbol "#" while the symbol for values is "&". The sole purpose of [[BIS_fnc_dbSymbolClass]] and [[BIS_fnc_dbSymbolValue]] is to return this sign. While the class is followed by an array which contains values, the value is only followed by its content which can be any data type. After the values content might follow another value or the array for that class can end. Here is an example of what the database looks like: | ||
<sqf>["#PLAYERS",["#1234",["&NAME","Bob","&KILLS",20,"&RANK","Sergent"],["#5678",["&NAME","Davis","&KILLS",0,"&RANK","Private"]]]</sqf> | |||
Let's format that a bit differently: | Let's format that a bit differently: | ||
< | <sqf> | ||
"#PLAYERS", | [ | ||
"#PLAYERS", // The uppermost class containing information about the players | |||
[ | [ | ||
"#1234", | "#1234", // An imaginary user id to identify a player without doubt | ||
[ | [ | ||
// Following here are some stats that the player has | |||
"&NAME", "Bob", | "&NAME", "Bob", | ||
"&KILLS", 20, | "&KILLS", 20, | ||
| Line 61: | Line 63: | ||
] | ] | ||
] | ] | ||
</ | </sqf> | ||
=== Accessing Values === | === Accessing Values === | ||
To get the content of a value you can use the [[BIS_fnc_dbValueReturn]] function. The first parameter is the database from which the value should be returned. The second one is the path where the value is located. If the function can not find the specified value you can set a default return value with the third parameter similar to [[getVariable]]. The following code displays the rank the player currently has in the database and if no value exists it will mark the player's rank as "PRIVATE": | To get the content of a value you can use the [[BIS_fnc_dbValueReturn]] function. The first parameter is the database from which the value should be returned. The second one is the path where the value is located. If the function can not find the specified value you can set a default return value with the third parameter similar to [[getVariable]]. The following code displays the rank the player currently has in the database and if no value exists it will mark the player's rank as "PRIVATE": | ||
<sqf> | |||
private _puid = getPlayerUID player; | |||
private _rank = [TAG_database, ["players", _puid, "rank"], "PRIVATE"] call BIS_fnc_dbValueReturn; | |||
hint _rank; | |||
</sqf> | |||
If you ever worked with configs then you might notice the similarity between the array and the config paths. This is how you access a config value: | If you ever worked with configs then you might notice the similarity between the array and the config paths. This is how you access a config value: | ||
<sqf>getText (missionConfigFile >> "Players" >> getPlayerUID player >> "rank");</sqf> | |||
So while the config is not editable the database is, which leads us to... | So while the config is not editable the database is, which leads us to... | ||
| Line 76: | Line 80: | ||
Values can be edited with the function [[BIS_fnc_dbValueSet]]. Continuing with the example from above the player was just promoted and a new rank has to be set in the database (array TAG_database): | Values can be edited with the function [[BIS_fnc_dbValueSet]]. Continuing with the example from above the player was just promoted and a new rank has to be set in the database (array TAG_database): | ||
<sqf> | |||
private _newRank = rank player; | |||
private _puid = getPlayerUID player; | |||
The previous database array will be overwritten by the function, see the | [TAG_database, ["players", _puid, "rank"], _newRank] call BIS_fnc_dbValueSet; | ||
</sqf> | |||
The previous database array will be overwritten by the function, see the [[set]] command. | |||
[[Category:Arma Scripting Tutorials]] | [[Category:Arma Scripting Tutorials]] | ||
Latest revision as of 16:53, 15 July 2022
A Scripted Database is a simple way to manage information with ingame functions from Bohemia Interactive and has been introduced in Take On Helicopters. Instead of using file operations it is a semi persistent sqf database. This means that the database is only available during the mission and can be modified with ingame commands. The downside is that it will be wiped when the mission ends or the game/server crashes. To make the database persistent you can save it periodically to the profileNamespace.
Functions
A list of all functions which are used to operate the database can be found here: Database functions. The functions in which you should be interested in are:
And to a certain extent:
- BIS_fnc_dbClassList
- BIS_fnc_dbClassRemove
- BIS_fnc_dbClassReturn
- BIS_fnc_dbClassSet
- BIS_fnc_dbImportXML
- BIS_fnc_dbValueList
Creating A Database
There are theoretically three options:
Declaring An Empty Array
The most straightforward option. Simply add TAG_database = []; to any script where you want to declare the database, eg initServer.sqf.
Importing From An .xml File
BIS_fnc_dbImportXML can convert the content of an xml file into an array which has the format of a Scripted Database. An xml file can be way easier to read than a nested array. Just keep in mind that you can't modify the xml file from within the game, meaning that once the mission restarts the default database from that file will be loaded and not the database which existed at the end of a mission.
Importing From A Config
A config can either be Description.ext (mission config), the Campaign Description.ext (campaign config) or an addon's config.bin/.cpp (global config). The BIS_fnc_dbImportConfig function can import the config classes from the config but not the values. This makes this function a bit useless as the same can be achieved with the other options but even better. Writing to the config is also only possible from outside the game and not with commands.
Operating A Database
Classes And Values
The Scripted Database consists of classes and values. Classes can be identified by the class symbol "#" while the symbol for values is "&". The sole purpose of BIS_fnc_dbSymbolClass and BIS_fnc_dbSymbolValue is to return this sign. While the class is followed by an array which contains values, the value is only followed by its content which can be any data type. After the values content might follow another value or the array for that class can end. Here is an example of what the database looks like:
Let's format that a bit differently:
Accessing Values
To get the content of a value you can use the BIS_fnc_dbValueReturn function. The first parameter is the database from which the value should be returned. The second one is the path where the value is located. If the function can not find the specified value you can set a default return value with the third parameter similar to getVariable. The following code displays the rank the player currently has in the database and if no value exists it will mark the player's rank as "PRIVATE":
If you ever worked with configs then you might notice the similarity between the array and the config paths. This is how you access a config value:
So while the config is not editable the database is, which leads us to...
Editing Values
Values can be edited with the function BIS_fnc_dbValueSet. Continuing with the example from above the player was just promoted and a new rank has to be set in the database (array TAG_database):
The previous database array will be overwritten by the function, see the set command.