Dynamic Action

Version 9, last updated by Pilus at 28 Jan 09:45 UTC

This is a documentation for development of new dynamic actions. This includes syntax for the dynamic action data table. It does not cover general description of how dynamic actions are used. It is the intension that this page should be the background for a final documentation for GHI users who seek to make their own dynamic actions, once a gui is made for that.

Dynamic Action structure

The dynamic actions are parted into different catagories (see #{89}). Each category have a file in the folder "GHI/DynamicActions". This file contains data for all dynamic actions in that category.

Inside the file the scripts are defined as tables, which are inserted in the global table GHI_ProvidedDynamicActions.

Data syntax

Dynamic Action Data syntax

The following is the syntax for the data that can be provided for the dynamic actions. The data set is provided as a table and can use the following indexes:

Index	Type	Description
name	string	The name of the dynamic action
guid	string	A unique identifier for the dynamic action
authorName	string	The name of the author. This is set to "The Gryphonheart Team"
authorGuid	string	The guid of the author. This is set to "0x01"
version	number	Version of the dynamic action. This is set to 1, as it not relevant to change this before the first test version is released
category	string	The category of the action. This can be defined as a variable in the file so all of the actions in the file are given the same category. The category can contains all characters, including whitespaces.
description	string	Description of the purpose and functionality of the action.
icon	string	Icon for the action
gotOnSetupPort	boolean	If true it includes an "OnSetup" out port as well as the defined out ports. Otherwise it only show the defined out ports. There is no need to declare an OnSetup port in the table with ports.
setupOnlyOnce	boolean	If true it will only run the script once.
allPortsTriggerScript	boolean	If true, then all ports will run the script when run. This overwrites 'setupOnlyOnce'.
script	string	The code to run when the 'Setup' port is triggered.
ports	table	A table containing ports, following the Port Data syntax. Each port is saved in the table with the ports guid as index.
inputs	table	A table containing inputs, following the Input syntax. Each input is saved in the table with the inputs guid as index.
outputs	table	Same as input, but with the output syntax.

Port Data syntax

Index	Type	Description
name	string	The name of the port.
order	number	The order priority of which to show the port. Ports with lower order are shown first.
direction	string	The string 'in' or 'out'
description	string	Description of the port

Input syntax

Index	Type	Description
name	string	The name of the input.
description	string	Description of the input.
type	string	The name of the type of input. The type must be one of the types defined in 'Input and output types'.
defaultValue	string	Default value of the input
typeData (optional)	table	Data for the input type, such as selection options in the 'tableOfStrings' input type.

Output syntax

Index	Type	Description
name	string	The name of the output.
description	string	Description of the output.
type	string	The name of the type of output. The type must be one of the types defined in 'Input and output types'.

Input and Output types

The types available to the dynamic actions. Their translation to into menu objects are defined in GHM_Inputs.lua. More types can be added while we develop, feel free to suggest.

Type Name	Input Only	Type Description	Type GHM Object
string		A normal string	Editbox
number		A number (both decimal and int)	Editbox (with numbers only)
boolean		true or false	Checkbox
tableOfStrings	x	Several given strings.	CustomDD
code	x	The data itself is a string, but it gets edited in a code editor	CodeField
longString	x	The data itself is a string, but it gets edited in a text field	TextField
color	x	A string being the index of one of the colors defined in GHI_MiscAPI.GHI_GetColors	CustomDD with the colors inserted
time	x	A number representing a time in seconds	TimeSlider
icon	x	A string, being an icon path	IconPicker
tableOfTextures	x	A table of strings, which is texture paths.	Texture frame
item		A string being an item guid.	Item Picker
sound		A string with a sound path	Sound Selection

Script Information

The script that will be run on trigger setup in normal code executed in the scripting environment belonging to the author of the item the dynamic action is attached to. The whole normal API of the execution environment is available, with the addition of a dynamic action API. This dynamic action API is all packed in a table under the name 'dyn'. This results in the following functions being available:

dyn.GetInput(inputGuid) - Returns the value of the input variable with the given guid.

dyn.SetOutput(outputGuid, value) - Sets the value of the output variable with the given guid to the given variable.

dyn.TriggerOutPort(portGuid) - Triggers the output port with the name portGuid. Actions connected to this port will be run before this function returns.

dyn.SetPortInFunction(portGuid, func) - Sets a function, which will be called when the port with the given guid is triggered.

If the dynamic action got an 'OnSetup' out port (if gotOnSetupPort is set to true), it is automatically triggered right after the script is executed.

Example

This example is from the dynamic action 'Zone' in the 'Location' category. It does not have an OnSetup port. The purpose of the script is to trigger the port 'inside' if the player is inside the zone defined in the input named 'zone'. Otherwise it should trigger the port with the guid 'outside'.

local targetZone = dyn.GetInput("zone");

local currentZone = GetRealZoneText();

dyn.SetOutput("currentZone",currentZone);

if currentZone:lower() == targetZone:lower() then

dyn.TriggerOutPort("inside");

else

dyn.TriggerOutPort("outside");

end