Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

Flowgraph Module System

Table of Contents

...

Overview

A Module is an exported Flowgraph Flow Graph that can be loaded and called from another Flowgraph Flow Graph at any point during the game session.

Any Flowgraph Flow Graph can be converted to a Module simply by exporting the Flowgraph to its Xml format using the "Save" option in the Flowgraph Editor.creating a new module in the Flow Graph Editor, and copying the Flow Graph contents to this new module.

Table of Contents
maxLevel3
minLevel2
excludeOverview

The advantages of using Modules:

  • Same Flowgraph Flow Graph can be used in multiple levels, but only exist in one location.
  • Modules can receive unique input values from their caller, allowing them to be very robust.
  • Modules can return unique output values to their callers, allowing them to be used in many different situations.

...

  • Modules can be instanced (default behavior), meaning that multiple copies of the same module can be active simultaneously, but running with different inputs

Module Types

There are currently two supported module types.

  • Global: Modules which are used in multiple levels should be created as Global modules.
  • Level: Modules only used in a specific level should be created as Level modules.

Modules are saved in either of these two locations:

  • Global: ../GameSDK/Libs/FlowgraphModules
  • Level../GameSDK/Levels/<levelfolder>/FlowgraphModules

Converting a Flow Graph to a Module

A Module is just a special flavor of a FlowgraphFlow Graph. This means ANY Flowgraph any Flow Graph can become a Module module with a few simple modifications made to it. So pick your favorite Flowgraph that you want to turn into a Module, or create a simple one to work with. The first thing you will need to do is place a Module:Start Node. This acts as the starting point for your Module when it is called. It also carries over any input sent from the Caller Node (more on this later).

Image Removed

Outputs:

...

First create a module by selecting File -> New FG Module -> Global/Level... in the Flow Graph Editor:

Image Added

or right-click on the FG Modules item in the Flow Graph overview and choose New Global FG Module / New Level FG Module from the context menu:

Image Added

Your new module will appear in the Flow Graph overview:

Image Added

The new module will already contain two nodes: Module:Start_<YourModuleName> and Module:End_<YourModuleName>. These are specifically created for this module, and cannot be removed.

Start Node Outputs:

...

  • Start: Called when the module was created by the caller node. Treat this like you would the MiscGame:Start Node node.
  • Entity - EntityId assigned to the Module as its Graph Entity. This is your your own reference; any Node that is either set to use the Graph Entity or not assigned an Entity will automatically use this.
  • Param1 - Additional parameter data passed from the Caller Node.
  • Param2 - Additional parameter data passed from the Caller Node.
  • Param3 - Additional parameter data passed from the Caller Node.
  • Param4 - Additional parameter data passed from the Caller Node.
  • Param5 - Additional parameter data passed from the Caller Node.
  • Param6 - Additional parameter data passed from the Caller Node.

After you have placed the Starting point, you may want to place an Ending point by using the Module:Return Node. Note that this set is not required. When a Module returns, it is unloaded and stops executing. If you want your Module to always remain executing while the level is being played, then don't return from it! Returning from a Module does allow you to pass optional data back to the Caller.

Image Removed

Inputs:

  • End - Call to return from the Module with a Success status.
  • Cancel - Call to return from the Module with a Fail status.
  • Param1 - Additional parameter data passed back to the Caller Node.
  • Param2 - Additional parameter data passed back to the Caller Node.
  • Param3 - Additional parameter data passed back to the Caller Node.
  • Param4 - Additional parameter data passed back to the Caller Node.
  • Param5 - Additional parameter data passed back to the Caller Node.
  • Param6 - Additional parameter data passed back to the Caller Node.

Creating an empty Module

If you want to create a new Module from scratch you can simply choose File->New FG Module... from the Flowgraph Editor menu. This will create a new Flowgraph with the Module:Start and Module:Return flownodes already added to it.

Image Removed

  • Update: Called when the caller node wants to pass new parameters or indicate that the internal state of the module should update/reset.
  • Cancel: Called when the caller node wants to cancel the module execution.

End Node Inputs:

  • Success: Call this to end the module and pass a 'success' status back to the caller node.
  • Cancel: Call this to end the module and pass a 'canceled' status back to the caller node.

Deleting a Module

If you want to delete or rename a specific Module module you can right click on the Module module name in the FG Modules list.

Image RemovedImage Added

Note
titleNote

If you delete a Module module it will also delete the saved XML file .

Saving a Module

To save your Flowgraph so that it can be used as a Module, all you need to do is bring up your Flowgraph in the Flowgraph Editor, and select Save from the File Menu. There are multiple locations where you should save the Flowgraph, depending on how you want to use it:

  • Game/Libs/FlowgraphModules/
    This is your Global Modules folder. Save your Module here if you want to use it in multiple levels.
  • Game/Level/MyLevel/FlowgraphModules/
    This is your Level Modules folder. Every Level can have their own Modules folder. Save your Module here if you want to use it only in one particular level.

...

(Undo is not supported).

Calling a Module from

...

Flow Graph

To call the Module, all we you need to do is use the Call node specific to your module. It will be named Module:Call Node.Image Removed_<YourModuleName>:

Image Added

Inputs:

  • Call - : Call to load the Module module and begin its execution.
  • Module - Name of the Module to call. This should match the name of the Xml file you saved in the previous step. You do not have to include the ".xml" part.
  • Entity - EntityId that should be this Module's Graph Entity.
  • Param1 - Additional parameter data to pass to the Module's Start nodes.
  • Param2 - Additional parameter data to pass to the Module's Start nodes.
  • Param3 - Additional parameter data to pass to the Module's Start nodes.
  • Param4 - Additional parameter data to pass to the Module's Start nodes.
  • Param5 - Additional parameter data to pass to the Module's Start nodes.
  • Param6 - Additional parameter data to pass to the Module's Start nodes.

Outputs:

  • Called - Called when the Module is fully loaded and has started executing. Returns True if successful, False if failed to load.
  • Done - Called when the Module returns with a Success status.
  • Canceled - Called when the Module returns with a Fail status.
  • Param1 - Additional parameter data passed back from the Module when it returned.
  • Param2 - Additional parameter data passed back from the Module when it returned.
  • Param3 - Additional parameter data passed back from the Module when it returned.
  • Param4 - Additional parameter data passed back from the Module when it returned.
  • Param5 - Additional parameter data passed back from the Module when it returned.
  • Param6 - Additional parameter data passed back from the Module when it returnedIf the module is already started it will trigger the update port of the Start node with updated parameters (only if not instanced).
  • Instanced: If set to 1 (default behavior) it will create a new independent instance of the module whenever you trigger the Call input port.
  • Cancel: Call to cancel this module (needs correct InstanceID if instanced).
  • InstanceID: InstanceID to identify a module instance. Can be -1 (default behavior) to create a new instance, otherwise it will update the given instance (only if instanced).

Outputs:

  • OnCalled: Called when module was started (returns -1 if the module is not instanced).
  • Done: Called when the module returns with a success status.
  • Canceled: Called when the module returns with a fail status.

Custom Module Ports

You can also customize the inputs and outputs for each module, to pass extra data back and forth. To do so, select your module and use the Tools -> Edit Module menu option in the Flow Graph editor:

Image Added

This brings up a dialog which allows adding inputs and outputs:

Image Added

Supported data types are:

  • Bool
  • EntityId
  • Int
  • Float
  • String
  • Vec3

Image Added

Clicking OK on this dialog will regenerate the module nodes (Start, End and Call) with the new inputs and outputs:

Image Added

Image Added

All inputs passed to the Call node will activate the corresponding outputs on the Start node, and similarly inputs to the End node will be passed back to the Call node when Success or Cancel are activated.

C++ Interface

To access the Flow Graph Module System from outside you can use the IFlowgraphModuleManager interface.

Code Block
titleCode/CryEngine/CryCommon/IFlowgraphModuleManager.h
borderStylesolid
#include "IFlowgraphModuleManager.h"
//...
IFlowgraphModuleManager* pModuleManager = gEnv->pFlowSystem->GetIModuleManager();

Calling a Module from C++

In some cases it might be needed to start module instances directly from code and pass results back to C++. In this case you can do the following:

Code Block
languagecpp
titleCalling a module from code
void CMyClass::MyModuleCallback(bool bSuccess, const TModuleParams& outputParams) 
{
   // do something with the output parameters 
}

void CMyClass::CallMyModule()
{
   IFlowGraphModuleManager* pModuleManager = gEnv->pFlowSystem->GetIModuleManager();
   if (const IFlowGraphModule* pModule = pModuleManager->GetModule(“MyModule”))
   {
      TModuleParams inputParams;
      //… add input parameters (has to match the inputs in the module)
      pModuleManager->CreateModuleInstance(pModule->GetId(), inputParams, functor(*this, &CMyClass::MyModuleCallback));
   }
}

 

Debugging a Module

In order to get an overview of all currently available Flow Graph modules and/or see currently active module instances it is possible to use the following console variables:

  • fg_debugmodules 0/1/2 - 0: Disabled / 1: Shows a list of all currently available modules / 2: Shows a list of all currently available modules and active module instances
  • fg_debugmodules_filter "filterstring" - "filterstring" can be used to only show specific modules

Image Added

  • Module: The name of the module.
  • ID: Internal module ID.
  • Num Instances: Number of currently active instances of the module.
  • Instance ID: Instance specific ID.
  • Caller Graph - Node: Flow Graph and Node ID of the Flow Graph who called the module. 
  • Type: Global or Level module.

 

Note

Grayed out modules are modules with no active instances.