{"name":"Arma 3: Scripted Database","title":"Arma 3: Scripted Database","type":"topic","url":"https://community.bistudio.com/wiki/Arma_3:_Scripted_Database","revid":376300,"updated":"2025-10-03T15:35:17Z","aliases":[],"markdown":"> [!CAUTION]\n> This information is **obsolete** as of Arma 3 v2.02. Reason: For better peformance (faster access and write speeds) you can use HashMaps instead.\n\nA Scripted Database is a simple way to manage information with ingame functions from Bohemia Interactive and has been introduced in Take On Helicopters.\nInstead 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.\nThe 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.\n\n### Functions\n\nA list of all functions which are used to operate the database can be found here: Database functions.\nThe functions in which you should be interested in are:\n\n- BIS_fnc_dbValueSet\n- BIS_fnc_dbValueReturn\n\nAnd to a certain extent:\n\n- BIS_fnc_dbClassList\n- BIS_fnc_dbClassRemove\n- BIS_fnc_dbClassReturn\n- BIS_fnc_dbClassSet\n- BIS_fnc_dbImportXML\n- BIS_fnc_dbValueList\n\n### Database Creation\n\nThere are theoretically three options:\n\n#### Empty Array Declaration\n\nThe most straightforward option. Simply add `TAG_database = [];` to any script where you want to declare the database, eg initServer.sqf.\n\n#### XML Import\n\nBIS_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.\n\n#### Config Import\n\nA 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.\n\n### Database Operation\n\n#### Classes And Values\n\nThe 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:\n\n```sqf\n[\"#PLAYERS\", [\"#1234\", [\"&NAME\", \"Bob\", \"&KILLS\", 20, \"&RANK\", \"Sergent\"], [\"#5678\", [\"&NAME\", \"Davis\", \"&KILLS\", 0, \"&RANK\", \"Private\"]]]\n```\n\nLet's format that a bit differently:\n\n```sqf\n[\n    \"#PLAYERS\", // The uppermost class containing information about the players\n    [\n        \"#1234\", // An imaginary user id to identify a player without doubt\n        [\n            // Following here are some stats that the player has\n            \"&NAME\", \"Bob\",\n            \"&KILLS\", 20,\n            \"&RANK\", \"Sergeant\"\n        ],\n        \"#5678\",\n        [\n            \"&NAME\", \"Davis\",\n            \"&KILLS\", 0,\n            \"&RANK\", \"Private\"\n        ],\n    ]\n]\n```\n\n#### Values Access\n\nTo 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.\nThe 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.\nThe 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\":\n\n```sqf\nprivate _puid = getPlayerUID player;\nprivate _rank = [TAG_database, [\"players\", _puid, \"rank\"], \"PRIVATE\"] call BIS_fnc_dbValueReturn;\nhint _rank;\n```\n\nIf 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:\n\n```sqf\ngetText (missionConfigFile >> \"Players\" >> getPlayerUID player >> \"rank\");\n```\n\nSo while the config is not editable the database is, which leads us to...\n\n#### Values Editing\n\nValues 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`):\n\n```sqf\nprivate _newRank = rank player;\nprivate _puid = getPlayerUID player;\n[TAG_database, [\"players\", _puid, \"rank\"], _newRank] call BIS_fnc_dbValueSet;\n```\n\nThe previous database array will be overwritten by the function, see the set command.","sections":[{"heading":null,"level":1,"markdown":"> [!CAUTION]\n> This information is **obsolete** as of Arma 3 v2.02. Reason: For better peformance (faster access and write speeds) you can use HashMaps instead.\n\nA Scripted Database is a simple way to manage information with ingame functions from Bohemia Interactive and has been introduced in Take On Helicopters.\nInstead 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.\nThe 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."},{"heading":"Functions","level":3,"markdown":"A list of all functions which are used to operate the database can be found here: Database functions.\nThe functions in which you should be interested in are:\n\n- BIS_fnc_dbValueSet\n- BIS_fnc_dbValueReturn\n\nAnd to a certain extent:\n\n- BIS_fnc_dbClassList\n- BIS_fnc_dbClassRemove\n- BIS_fnc_dbClassReturn\n- BIS_fnc_dbClassSet\n- BIS_fnc_dbImportXML\n- BIS_fnc_dbValueList"},{"heading":"Database Creation","level":3,"markdown":"There are theoretically three options:"},{"heading":"Empty Array Declaration","level":4,"markdown":"The most straightforward option. Simply add `TAG_database = [];` to any script where you want to declare the database, eg initServer.sqf."},{"heading":"XML Import","level":4,"markdown":"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."},{"heading":"Config Import","level":4,"markdown":"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."},{"heading":"Database Operation","level":3,"markdown":""},{"heading":"Classes And Values","level":4,"markdown":"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:\n\n```sqf\n[\"#PLAYERS\", [\"#1234\", [\"&NAME\", \"Bob\", \"&KILLS\", 20, \"&RANK\", \"Sergent\"], [\"#5678\", [\"&NAME\", \"Davis\", \"&KILLS\", 0, \"&RANK\", \"Private\"]]]\n```\n\nLet's format that a bit differently:\n\n```sqf\n[\n    \"#PLAYERS\", // The uppermost class containing information about the players\n    [\n        \"#1234\", // An imaginary user id to identify a player without doubt\n        [\n            // Following here are some stats that the player has\n            \"&NAME\", \"Bob\",\n            \"&KILLS\", 20,\n            \"&RANK\", \"Sergeant\"\n        ],\n        \"#5678\",\n        [\n            \"&NAME\", \"Davis\",\n            \"&KILLS\", 0,\n            \"&RANK\", \"Private\"\n        ],\n    ]\n]\n```"},{"heading":"Values Access","level":4,"markdown":"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.\nThe 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.\nThe 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\":\n\n```sqf\nprivate _puid = getPlayerUID player;\nprivate _rank = [TAG_database, [\"players\", _puid, \"rank\"], \"PRIVATE\"] call BIS_fnc_dbValueReturn;\nhint _rank;\n```\n\nIf 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:\n\n```sqf\ngetText (missionConfigFile >> \"Players\" >> getPlayerUID player >> \"rank\");\n```\n\nSo while the config is not editable the database is, which leads us to..."},{"heading":"Values Editing","level":4,"markdown":"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`):\n\n```sqf\nprivate _newRank = rank player;\nprivate _puid = getPlayerUID player;\n[TAG_database, [\"players\", _puid, \"rank\"], _newRank] call BIS_fnc_dbValueSet;\n```\n\nThe previous database array will be overwritten by the function, see the set command."}],"categories":["Arma Scripting Tutorials"],"groups":["Scripting"]}