Skip to content

2. API

Jump to bottom
OvenProofMars edited this page Feb 19, 2024 · 15 revisions

Introduction

Power DI has an API for adding new data sources, lookup tables, datasets, or reports templates to the mod. Below you'll find a description of how to interact with these endpoints. Due to the high number of computations needed, and the fact that lua is only single threaded, most of Power DI's components use a combination of promises and coroutines to avoid impacting the framerate. Data sources, datasets, and reports are session specific, which mean every session will have their own sets of data.

To get access to the API simply call:

local PDI = get_mod("Power_DI")

Endpoint overview

  • PDI.Utilities
    • PDI.utilities.get_gameplay_time
  • PDI.datasources
    • PDI.datasources.get_available_datasources
    • PDI.datasources.register_datasource
  • PDI.datasets
    • PDI.datasets.get_available_datasets
    • PDI.datasets.register_dataset
  • PDI.lookup_tables
    • PDI.lookup_tables.get_available_lookup_tables
    • PDI.lookup_tables.register_lookup_table
  • PDI.reports
    • PDI.reports.get_available_reports
    • PDI.reports.register_report = function

Utilities

get_gameplay_time

PDI.utilities.get_gameplay_time()
Argument type: n.a.
Return type: number
Info: Will return the elapsed mission time (in seconds) or 0

Data sources

In basis the data sources are tables filled with events by gathering information via hooking Darktide functions. When registering a new data source you supply a hook function that will be managed by Power DI. Try to keep the data you record in data sources to a minimum, only collect data that can only be gathered at that specific moment in time. Any lookups that can be done later are better done while making a dataset.

get_available_datasources

PDI.datasources.get_available_datasources()
Argument type: n.a.
Return type: table
Info: Will return an array of names (string) of the registered data sources.

register_datasource

PDI.datasources.register_datasource(datasource_template)
Argument type: table
Return type: function
Info: Register a new data source to Power DI. Requires a data source template as argument (see datasource_template below) and will return a function that is used to retrieve to correct data source table of the currently active session to write data to.

datasource_template (table)

key value type value info
name string Name of the data source, must be unique.
hook_templates table array of hook templates associated with this data source.

hook_template (table)

key value type value info
hook_class table Table of the class you want to hook into
hook_functions table Table with your custom hook functions. Key: hook function name (string), value: hook function (function)

Example

local PDI = get_mod("Power_DI")
local data_locations = {}

local add_attack_result = function(self, ...)
   local data_output = data_locations.AttackReportManager()
   --Add event to data_output (data source table)
end

local datasource_template = {
   name = "AttackReportManager",
   hook_templates = {
      {
         hook_class = CLASS.AttackReportManager,
         hook_functions = {
            add_attack_result = add_attack_result,
         },
      }
   },
}

data_locations.AttackReportManager = PDI.datasources.register_datasource(datasource_template)

Datasets

Datasets take the data gathered in data sources and transforms them into a formatted table by doing both calculations and lookups. The dataset creation function you will supply to Power DI will have to make use of promises. Your dataset function will be supplied with proxies to the requested data sources, proxies to all the lookup tables, and special functions, which all can be used to create your dataset.

get_available_datasets

PDI.datasets.get_available_datasets()
Argument type: n.a.
Return type: table
Info: Will return an array of names (string) of the registered datasets.

register_dataset

PDI.datasets.register_dataset(dataset_template)
Argument type: table
Return type: boolean
Info: Register a new dataset for Power DI. Requires a dataset template as argument (see dataset_template below).

dataset_template (table)

key value type value info
name string name of the dataset, must be unique
required_datasources table Array of data source names your dataset needs access to.
legend table Table with field names and field types that will be available in your dataset. Key: field name (string), value: field type (string)
dataset_function function Function that will create the dataset. (See dataset function below)

dataset function

Your dataset function will be called by Power DI to create the dataset, and will be supplied with a table as an argument which holds the requested data source proxies, lookup table proxies, special dataset functions, and the dataset output table.

key value type value info
name string name of the dataset, there for administrative purposes.
dataset table output table for your dataset
datasource_proxies table table containing proxies to the requested data sources. Please note that these proxies cannot be iterated over normally, a special function is provided for this purpose.
lookup_proxies table table containing proxies to the lookup tables.
append_dataset function Asynchronous function that will append your dataset with the data from a data source (see functions below).
iterate_datasource function Asynchronous function that allows you to iterate over a data source.
iterate_dataset function Asynchronous function that allows you to iterate over your dataset.
sort_dataset function Asynchronous function that allows you to sort your dataset.
complete_dataset function Asynchronous function that finalizes your dataset.
Asynchronous functions

The functions mentioned above are run asynchronous, and will thus return a promise. Your dataset creation function must therefor be written as a promise chain.

data.append_dataset(self, datasource_name)
Argument types: table, string
Return type: table (promise)
Info: Append your dataset table with the data from a data source.

data.iterate_datasource(self, data_source_name, iteration_function)
Argument types: table, string, function
Return type: table (promise)
Info: Allows you to iterate over a data source. The iteration function will get key and value as arguments.

data:iterate_dataset(self, iteration_function)
Argument types: table, function
Return type: table (promise)
Info: Allows you to iterate over your dataset. The iteration function will get key and value as arguments.

data.sort_dataset(self, sort_function)
Argument type: table, function
Return type: table (promise)
Info: Allows you to sort your dataset. The sort function will get key_1 and key_2 as arguments.

data.complete_dataset(self)
Argument type: table
Return type: n.a.
Info: Finalizes the dataset. Required to be called.

Example

local PDI = get_mod("Power_DI")

local player_abilities = function(data)
   local UnitSpawnerManager = data.datasource_proxies.UnitSpawnerManager
   data:append_dataset("PlayerAbilities")
   :next(
      function()
         return data:iterate_dataset(
            function(k,v)
               local player_unit_uuid = v.player_unit_uuid
               local player_unit_lookup = UnitSpawnerManager[player_unit_uuid]
               v.player_name = player_unit_lookup.unit_name
               local event_type
               if v.charge_delta > 0 then
                  event_type = "Charge gained"
               elseif v.charge_delta < 0 then
                  event_type = "Charge used"
               end
               v.event_type = event_type

               v.player_unit_uuid = nil
               v.player_unit_position = nil
            end
         )
      end
   )
   :next(
      function()
         data:complete_dataset()
      end
   )
end

local dataset_template = {
   name = "player_abilities",
   required_datasources = {
            "PlayerAbilities",
            "UnitSpawnerManager",
   },
   legend = {
      player_name = "string",
      ability_type = "string",
      event_type = "string",
   },
   dataset_function = player_abilities
}

PDI.datasets.register_dataset(dataset_template)

Lookup tables

Lookup tables contain static data that can be used to populate datasets with additional categories etc.

get_available_lookup_tables

PDI.lookup_tables.get_available_lookup_tables()
Argument type: n.a.
Return type: table
Info: Will return an array of names (string) of the available lookup tables.

register_lookup_table

PDI.lookup_tables.register_lookup_table(lookup_table_template)
Argument type: table
Return type: boolean
Info: Add a new lookup table to Power DI, making it available for your and other mods to use. Requires a lookup table template as argument (see lookup_table_template below).

lookup_table_template

key value type value info
name string name of the lookup table, must be unique
lookup_table table Table with key value pairs for you lookups.

Reports

Though fundamentally not very different from the functionality available in the UI, adding report templates via the API makes them available as a reusable report template instead of a user report template.

get_available_reports

PDI.reports.get_available_reports()
Argument type: n.a.
Return type: table
Info: Will return an array of names (string) of the registered report templates.

register_report

PDI.reports.register_report(report_template)
Argument type: table
Return type: boolean
Info: Register a new report template for Power DI. Requires a report template as an argument (see report_template below).

report_template

key value type value info
name string name of the report, must be unique
dataset_name string name of the dataset that will be used for generating the report.
report_type string report type. Currently only "pivot_table" is available.
columns table array of field names from the dataset to be used as columns. Currently only one entry is fully supported.
rows table array of field names from the dataset to be used as rows.
values table array of value templates used to create the report (see value_template below).
filters table array of function strings to be used for filtering the dataset (see function strings below). Currently only the first entry will be used.

value_template

key value type value info
type string choice between "sum", "count", and "calculated_value". Determines the type of calculation that will be done during the creation of the report.
field_name string name of the dataset field that will be used. Required when type is "sum" or "count".
function_string string string that will be used as the basic for the calculated value function (see function strings below). Required when type is "calculated_value".
label string label of the value that will be visible in the UI.
format string Choice between "none", "number", "percentage". Determines the format when displaying the value in the UI.
visible boolean Boolean to set the visibility of the value. Useful in conjunction with calculated field, as you may want to hide the source data of the calculated value.

function strings

Power DI allows for custom functions to be typed by the user, used for filtering the dataset or calculated values. The function strings are simplified lua code, that will be converted to a lua function and run within a separate environment. For the calculated fields you have to compare to the labels of the values you entered. For the data filter you have to compare to the field names of the dataset.

Available symbols:

Symbol Function
= equal
~ not equal
> greater than
< less than
or or
and and
( bracket open
) bracket close
"" string
+ addition
- subtraction
* multiplication
/ division

Example: attacker_type = "Player" and damage > 0

Example

local PDI = get_mod("Power_DI")
local report_template = {
   name = "Status report",
   dataset_name = "mloc_dataset_player_status", 
   report_type = "pivot_table",
   columns = {"player"},
   rows = {"state_category", "state_name",},
   values = {
      {
         field_name = "state_name",
         type = "count",
         label = "States",
         visible = true,
         format = "number"
      },
   },
   filters = { "player ~ nil" },
}
PDI.reports.register_report(report_template)

Clone this wiki locally