======Data Files======
----

Although it requires a bit of manual setup, it's possible to access custom data stored in JSON files from [[script|scripts]]. To do so, you must first create a subfolder named "data" within your game's project folder and place the desired JSON file into that folder. When [[exporting your game]], the editor will automatically include any files in the data folder having the .json extension.

As a simple example, let's say you wanted to maintain a list of [[item|items]] that the [[player character]] should begin the game with without needing to update your game's [[startup script]] every time the list changes. In this scenario, you could create a JSON file within the data folder named "start_items.json" that looks something like this, with an array of [[item]] IDs corresponding to the desired [[item|items]].

<code javascript>
[
   "ITEM_0001",
   "ITEM_0002",
   "ITEM_0003"
]
</code>

You can then use the "data" syntax to reference the filename and access its data from a [[script]]. In our example, you could use this syntax along with a [[script_syntax|For loop]] to give each [[item]] to the player from your game's [[startup script]].

<code bauxite>
for $item_id in data["start_items.json"] do
   give_item($item_id);
end;
</code>

Alternatively, each [[item]] in the list could be accessed using the array index syntax, or you could even randomly select one [[item]] from the list to give to the player.

<code bauxite>
for $i in range(3) do
   give_item(data["start_items.json"][$i]);
end;
</code>

<code bauxite>
give_item(data["start_items.json"][random(0, 2)]);
</code>

This could be expanded further by also providing a count for each of the [[item|items]]. Instead of just a list of string values, the JSON file would have a list of objects, each having a key/value pair for the [[item]] ID and count.

<code javascript>
[
   {
      "id": "ITEM_0001",
      "count": 2
   },
   {
      "id": "ITEM_0002",
      "count": 5
   }
]
</code>

Using the expanded JSON file containing counts for each [[item]], the [[script]] below would give the player two of ITEM_0001 and five of ITEM_0002.

<code bauxite>
for $item in data["start_items.json"] do
  give_item($item["id"], $item["count"]);
end;
</code>

As another example, assume that we want to maintain a list of [[entity]] properties that will be assigned to a [[character]] at some point during the game. A file named "npc_props.json" could be created in the data folder with the following contents (specifically an object with a set of key/value pairs as the root element).

<code javascript>
{
   "visited": false,
   "visit_count": 0,
   "mood": "happy"
}
</code>

You could then loop through the key/value pairs and assign each value to a property on the [[entity]].

<code bauxite>
for $prop in data["npc_props.json"] do
   set_entity_property(entity["npc01"], $prop, data["npc_props.json"][$prop]);
end;
</code>

~~NOTOC~~