VR-Forces 5.2 Lua Function Documentation

displayGraphUtil

(For high level concepts about how to use Lua to write scripted tasks, please see VR-Forces User's Guide.)

Introduction

The functions in this library assist with generating graph commands in the dot language (see https://graphviz.org/doc/info/lang.html) and displaying the graph. Graphs are intended to illustrate and debug script logic. Generally, dot commands are assembled into a single string and passed to displayGraph() (below) or vrf:processGraphCommands(). The graph can then be seen on the tasks tab of the entity information panel in the VR-Forces GUI.
This module calls vrf:setGraphCapable(), so a script requiring this module does not need to make that call (necessary for displaying the graph in the GUI).
To create graph output, the script should first include the command
require "displayGraphUtil".
Note that tasks that use the behaviorEngine, fsm or fsm2 packages do not need to do anything to generate graphs; these packages include a call to setGraphCapable, the definition of updateDisplayGraph, etc. The examples here are for scripts that do not use these packages.

Using Display Graph Functions

The functions in this package are used to create a single string that describes a graph. This string is passed to displayGraph() to show the graph.
The example here assumes that there are three states in the script, "deploy", "process", "wrap up". A global variable currentState indicates what state the script is in.
 require "displayGraphUtil"
 ...
 function makeGraphString()
 	   local graphString = dotPreambleString("My Script")
 	   -- Show the task parameters table:
 	   graphString = graphString..dotTableString("param", taskParameters, "Task Parameters")
 	   -- Display the current sim time:
 	   graphString = graphString..dotTimeString()
 	   graphString = graphString..dotEdgeString("deploy", "process", "In position")
 	   graphString = graphString..dotEdgeString("process", "wrap up", "Action complete")
 	   graphString = graphString..dotEdgeString("process", "deploy", "New task")
 	   -- Highlight the current state in yellow:
 	   graphString = graphString..dotNodeString(currentState, {color = "#ffffa0"})
 	   graphString = graphString..dotClosingString()
 	   return graphString
 end
 
 local graph = makeGraphString()
 displayGraph(graph)

Integrating Graph Functions into the Script

The example above will cause the graph to be displayed once if the GUI has the task tab of the entity information panel open. However, to make sure that the graph is displayed immediately when the task tab is selected, displayGraph() must be called inside of the updateGraphDisplay() script entry point function. In addition, the graph should be displayed every time the script state changes. This can be accomplished as follows:
 -- This function is called by the script interface when the task tab 
 -- is opened on the entity information panel.
 function updateDisplayGraph()
 	 local graph = makeGraphString()
 	 displayGraph(graph)
 end
 
 function tick()
 	 local oldState = currentState
 	 ...
 	 if oldState ~= currentState then
 	 	 updateDisplayGraph()
 	 end 
 end

Function List

displayGraph (dotCommands) Use the given dot commands to display the graph.
dotClosingString () Provides a string to close the dot commands.
dotEdgeString (startNode, endNode, transition, attributes) Provides a string containing the dot command for a transition arrow between two nodes.
dotNodeString (nodeId, attributes) Provides a string containing the dot command for a node.
dotPreambleString (scriptName) Provides a string that should be put at the beginning of the dot commands.
dotTableString (nodeId, t, title, color) Provides a string containing the dot command for a ractangular node that shows the contents of a table.
dotTimeString (nodeName, time) Provides a string containing the dot command for a rectangular node with the time in it.
replaceNonAlpha (inString) Removes non-alphanumeric characters from string and replaces them with '_'.


Functions

displayGraph (dotCommands)
Use the given dot commands to display the graph. This function wraps vrf:processGraphCommands(); however, it checks to see if the script is running in the VR-Forces Lua environment first. If it is not, and instead is running in an external environment (for example, in a Lua engine that is part of the editor), the commands are instead written to a file and the dot program is run to generate html. An Edge browser is then started to display the graph. This display in Edge only works in Windows.

Parameters:

  • dotCommands: (string) The description of the graph in the dot language.
dotClosingString ()
Provides a string to close the dot commands. Add this to the end of the dot command string after all node, transition and table command strings.

Usage:

     local str = dotPreambleString(vrf:getScriptId()) 
     str = str..dotNodeString(... 
     str = str..dotClosingString()

Return value:

    String to put at end of dot commands.
dotEdgeString (startNode, endNode, transition, attributes)
Provides a string containing the dot command for a transition arrow between two nodes. The edge can have a label on it. If the nodes have been declared in a dotNodeString, then the nodeID used in that function must match the nodeID used in this function. Note that if the nodes have not been separately declared with a dotNodeString, this command will cause them to be drawn anyway.

Parameters:

  • startNode: (string) The name of the start node. This name will have non-alphanumeric characters replaced by '_'.
  • endNode: (string) The name of the end node. This name will have non-alphanumeric characters replaced by '_'.
  • transition: (string) The label of the transition. Optional.
  • attributes: (table) Optional table of attributes and values to set the style of the edge. See https://graphviz.org/docs/edges/ for the possible edge attributes. The attribute table should not include "label", since that is what the transition parameter specifies.

Return value:

    (string) The string containing the edge command.
dotNodeString (nodeId, attributes)
Provides a string containing the dot command for a node.

Parameters:

  • nodeId: The name of the node (string). Non-alphanumeric characters will be replaced by "_" in the ID.
  • attributes: A table containing one or more attributes for the node. Attributes can be:
    • shape (string) One of the standard graphviz node shapes: box, ellipse, circle, diamond, parallelogram, house, hexagon, etc. See the list at https://graphviz.org/doc/info/shapes.html. The default shape is an ellipse.
    • color (string) A color name or # followed by 3 pairs of hex characters indicating the R, G, and B values of the color. For example, #0000ff for blue. See https://graphviz.org/docs/attr-types/color/
    • label (string) A label that will be written on the node. The default label is the node ID.

Usage:

     str = some_dot_commands
     str = str .. dotNodeString("node223", {label = "phase 2", shape = "ellipse"})

Return value:

    A string with the dot commands in it.
dotPreambleString (scriptName)
Provides a string that should be put at the beginning of the dot commands. Call this and put it in the dot command string before any node, table or transition strings.

Parameters:

  • scriptName: (string) The name of the script, for a title. May contain spaces.

Usage:

     local str = dotPreambleString(vrf:getScriptId()) 
     str = str..dotNodeString(...

Return value:

    String to put in the beginning of all dot commands.
dotTableString (nodeId, t, title, color)
Provides a string containing the dot command for a ractangular node that shows the contents of a table.

Parameters:

  • nodeId: The name (string) of the node. Non-alphanumeric characters will be replaced by "_" in the ID.
  • t: The table to be displayed.
  • title: (string) The name to be displayed above the table.
  • color: (string) Optional. A color name or color define with # and RGB values in hex (see https://graphviz.org/docs/attr-types/color/)

Return value:

    A string with the dot command for the table.
dotTimeString (nodeName, time)
Provides a string containing the dot command for a rectangular node with the time in it. The time parameter is optional; if not provided, the simulationTime is used. The time is displayed in hh:mm:ss format.

Parameters:

  • nodeName: (string) Optional. The name of the node. This is used for the label of the node. Defaults to "Time".
  • time: (number) Optional. A time in seconds. Defaults to sim time. If a time is specified, a nodeName must be specified too (arguments are positional).

Return value:

    A string with dot commands in it.
replaceNonAlpha (inString)
Removes non-alphanumeric characters from string and replaces them with '_'. This operation is performed on all node IDs that are passed to the dotNodeString and dotEdgeString functions in order to make sure the string is printable and does not have characters that dot cannot use as node names. Scripts that create dot commands without the helper functions may use these to generate legal node names, and make sure that names used in node and edge commands are the same.

Parameters:

  • inString: (string) The input name.

Usage:

     graphString = graphString..dotEdgeString("First node", "Second node")
     graphString = graphString..replaceNonAlpha("First node")..' [label=<Bold Label>] ' 
     graphString = graphString..replaceNonAlpha("Second node")..' -> '..replaceNonAlpha("Third node")

Return value:

    (string) The modified name.

Copyright© 2025 MAK Technologies, Inc. All rights reserved.