HPG Documentation

# Working with Data

Within your mission you will need to access and store data.

The lowest form of storage is the param. Params are a collection of key/value pairs which are associated with your execution context. When you first start a mission, you are running on the main objective thread and params will be empty. If you get some data and need to refer to it, you can set that data to a param like my_param. The key my_param is used to reference some data which can then be accessed or written to at any time. When you call a macro using call_macro, the params will be passed explicitly, which means by default you will not get a copy of any existing params unless you pass each one by name. The point of params is that you have local exclusive space to manage your data.

The second lowest form is locals. Locals are available across your mission, but work otherwise exactly like params. locals are shared data which is also available in the briefing and dispatch where params are not available. You will use locals very often and they are also useful for debugging so you may example an otherwise "inaccessible" param value. locals are still within the mission platform and do not incur any extra costs or time when reading/writing.

If you need to store large amounts of data between missions, use the table API. Tables are key/value pairs loaded and saved to disk, and you may store as much data as you need within a table.

If you have static information that you define up front with your mission, the static command will retrieve any path from the data section of your mission. This is a great place to define high level configuration options so that somebody can adjust your mission.

Avoid using global data, a table may be used instead for any persisted data you need.

You can read and store data in L:Vars which you then also view with the MSFS Behaviors window, however L:Vars incur a small performance penalty over params and locals.

# String interpretation

local and static data as well as params (no prefix) can be referenced using strings and braces.

In the cases below my_id exists in params, locals or static data respectively.

Examples:

"object{my_id}"
"object{local:my_id}"
"object{static:my_id}"

# Data storage options

  • param - isolated to each macro+child threads and the objective thread+child threads.
  • local - shared for the mission and between missions when using reload_mission and load_mission.
  • global - read a global variable which is persisted. Avoid storing data here when you can use a table instead!
  • table - read table data which is persisted (a group of keys may be stored under a table name)
  • static - read static data from the mission data table, such as configuration settings
  • location read locations from the mission locations table
  • var - L:Vars: global to MSFS, visible in the behaviors window and A:Vars: MSFS Aircraft SDK variables.

# Data Tables

Data tables are used to store and retrieve information. Data tables are optionally stored to disk so you may have persisted information.

Data tables are identified by their name, which will then be used as a filename on disk. Each table is a JSON object with keys.

You can access your tables on disk at %LocalAppData%\Packages\Microsoft.FlightSimulator_8wekyb3d8bbwe\LocalState\packages\hpg-airbus-h145-ap\work

# Table API

  • open_table
  • save_table
  • clear_table
  • set table
  • table (QUERY)

# Table Usage

To begin, open_table with the table name that you will use. This step will either load a table from disk, or create a new empty one for you. If you want to remove everything from a table, you can clear_table anytime after it is opened.

After that, you can use set commands to set a specific key in the table. Each key in the table is unique, and you can store any data within that key. Writing to the same key twice will remove the previous data, and it wll be lost if it wasn't previously copied.

You can read data from table by using table with the specified key

Let's see this in action, we'll open a table named test1 and set item1 to 99 and then save it. After that, print item1 to the screen using set_message.

{"open_table": "test1"}
{"set": {"table":"test1", "key": "item1"}, "value": 99},
{"save_table": "test1"},
{"set_message":{"text":"The contents of the item1 key are: {0}", "params": [
  {"table": "test1", "key": "item1"}
]}}

We will see The contents of the item1 key are: 99 as expected.

Now, remove the lines which save and modify the table:

{"open_table": "test1"}
{"set_message":{"text":"The contents of the item1 key are: {0}", "params": [
  {"table": "test1", "key": "item1"}
]}}

And you'll see the result is unchanged as the table was loaded from disk.

We can use this persistance to save settings, logs of the mission or whatever else we want to. Try to avoid calling save_table too rapidly as it is hitting the disk.

# Sample Test Program

← Interacting with the user →