FlowGraph

From Blue Mars Developer Guidebook

Jump to: navigation, search
There are security restrictions on this article

Contents

Overview

Opening the FlowGraph

In the City Editor or Block Editor, the FlowGraph Editor can be opened via menu, icon, or an entity's RollupBar options:

  • View > Open View Pane > Flow Graph, pictured on the left
  • the FG icon, pictured in the center
  • since a FlowGraph is always created on a particular entity in a level, the FlowGraph can be opened by selecting that entity and clicking Create or Open in the FlowGraph section of the RollupBar, pictured on the right

Image:fg_open.png


Working with the FlowGraph

These short documents provide a good FlowGraph overview. The following links point to external official CryEngine2 documentation and are generally relevant for Blue Mars. Note that not all of the standard CryEngine2 nodes are available/applicable to Blue Mars.

  • FlowGraph Reference - brief overview and terminology
  • Window Elements - parts of the FlowGraph Editor
  • Node Composition - node ports, value types, link connections
  • Adding and Editing nodes - how to add, move, copy & delete Entity and Component nodes
    • Entity nodes: with entity selected in the level, right-click in the FlowGraph and choose Add Selected Entity
      • similarly, to assign a new entity to an existing Entity node, with the new entity selected, right-click on the node and choose Add Selected Entity
    • Component nodes: drag into the graph from the Component menu on the left
      • not available: Add Node option from right-click menu
  • Creating and Editing links - details about connection links
    • create links to connect ports by clicking and dragging from a node's output port to another node's input port
    • remove links by dragging from the connected input to the gray area ("unplugging" the link)
    • to temporarily disable a connection, mouse-over the center point of the link until the cursor changes, right-click and select Disable
    • use the Logic:Any Component node to assign multiple inputs to a port
  • Creating and Managing FlowGraphs - details about creating, deleting & disabling FlowGraphs
    • create a FlowGraph by selecting an entity, clicking Create in the FlowGraph section of the RollupBar, and clicking OK (it's not necessary to enter a Group name)
    • a FlowGraph belongs to an entity, so deleting the entity will also result in deleting the attached FlowGraph
    • similarly, copying/cloning an entity will also copy the entity's FlowGraph
  • Importing/Exporting FlowGraphs - how to import/export FlowGraph nodes and links for use in other levels (this does not export assigned entities, just the nodes and links)
  • Entity Component Nodes Reference - descriptions of some Entity Component nodes
    • describes the EntityId, EntityInfo, EntityPos, GetPos nodes; note that not all of these Entity Component nodes are available

Note that a FlowGraph belongs to an entity in a level -- it doesn't really matter which entity it belongs to, except for your own organizational purposes. If you delete the entity, the created FlowGraph is also deleted, so it's a good idea to have a method to help prevent that from happening. For example, create a FlowGraph on a primary (meaningful) entity in the graph which you aren't likely to delete, like an avatar trigger or item, etc. Labeling the Graph Entity is how the engine helps you easily distinguish that entity. And another benefit to creating the FlowGraph on a primary entity is that when you copy that entity in the level, that FlowGraph gets copied too, referencing the new entity as the Graph Entity.

Display of Component Nodes

If you can't find a Flow Node, it may be hidden. Make sure all the Component categories are enabled via the View > Components menu, pictured below. Image:fg_editor.png

Debug Category

Please note that nodes in the Debug Category are not expected to work in the user client.

The Input:Key Debug node is for development/debugging purposes only. To use key/mouse actions, create an action map and use the OnAction callback in a script - there's an example in the Script Center's Basic ActionMap Example.


AR Component Nodes

The following nodes are found in the Component window in the AR folder.

Start

The output event is triggered when:

  • in Blue Mars, the player avatar is loaded for the first time in the level, or
  • in a Blue Mars level which does not auto-spawn a player avatar, the level is loaded (e.g., the Golf minigame level does not auto spawn an avatar - it has no ARDefaultCamera), or
  • in City Editor, the Preview Mode is started

When the Start node is triggered in the example below, the Current TimeOfDay Time is printed:

Image:fg_ar_start.png


OpenWebBrowser

Upon triggering the input event, the specified URL string (starting with "http://") will be opened in a web browser (performs the same action as Game/ShowPageInBrowser Lua API).

This example opens the Blue Mars website upon entering or leaving the avatar trigger. On the Enter event, the URL has been set in the node's Input Window, and on the Leave event, the String:SetString node usage is demonstrated.

Image:fg_ar_openWebBrowser.png


ARBuyBluWindow (Coming Soon!)

Shows "Buy BLU" screen.

File:SS-2010.09.15-12.11.15.png

Note that once the Show input is activated, all HUD UI elements are disabled unless a user closes the "Buy BLU" screen.

File:SS-2010.09.15-12.17.57.png

Examples

Here are some examples. It's important to keep in mind that events triggered in the Flow Graph happen locally (they are not automatically synchronized on all clients).

  • See Script Center Door for example usage of Movement:RotateEntityTo and Vec3:SubVec3 nodes


Adding FlowGraph ports to a Lua script

An entity script can receive or send information via FlowGraph Input/Output ports, as shown in the Basic Script Example. To create ports we define the Flow Events in our script, then re-launch the City Editor to refresh. See the FlowGraph Events page for the available port value types and an example which defines both Input and Output ports.

Here's the code from the Basic Script Example; a more detailed explanation can be found on that page.

function BasicScriptExample:Event_Start()
  self:StartScript();
end

BasicScriptExample.FlowEvents = {
  Inputs = {
    Start = {BasicScriptExample.Event_Start, "bool"},
  },
} 

Adding a "Start" input event to an entity script


Handling Input function values

As mentioned on the FlowGraph Events page, an input function's second argument is used to accept a value such as the string and entity values shown below. Note that we get the entity by using the System.GetEntity function and the entity's id as the argument.

function Example:Event_AcceptString(arg1, arg2_string)
  System.Log("received string: ".. arg2_string);
end

function Example:Event_AcceptEntity(arg1, arg2_entity)
  self.ent = System.GetEntity(arg2_entity.id);
  System.Log("received entity named: ".. self.ent:GetName());
end

Example.FlowEvents = {
  Inputs = {
    AcceptEntity = {Example.Event_AcceptEntity, "entity"}, --port color is red
    AcceptString = {Example.Event_AcceptString, "string"}, --port color is turquoise
  },
} 

Accepting input event "entity" and "string" values


Sharing a FlowGraph

Saving

To save a FlowGraph you wish to share with other developers or use in your other levels:

  1. Save the .xml file
    1. use File>Save or File>Save As
    2. or, use File>Export Selection to save only the highlighted nodes
  2. Share the .xml file
    1. pass this file to another developer
    2. or, for your own use in another level, place this .xml file in your Common directory


Using a shared FlowGraph

There are a few ways to share a FlowGraph setup among developers. As mentioned in the overview, a FlowGraph is always created on a particular entity in a level, so the first step is to create a FlowGraph on an entity (or open an existing FlowGraph which has been created on an entity) in your level. Simply opening an arbitrary FlowGraph which does not belong to an entity in your level is not sufficient -- it will not be saved.

Once you have a valid FlowGraph open (created on one of your entities), you can either File>Import or File>Open, copy & paste to transfer the new nodes into your entity's FlowGraph. Note that the shared FlowGraph .XML file must be placed in your city directory or your Common directory in order to load. Here are the detailed steps:

  1. Create a FlowGraph on a particular entity, or open an existing entity's FlowGraph in your level. This is done by selecting the entity and using the Create/Open button in the RollupBar, or selecting an existing graph in the View>Graphs list.
  2. Option #1: copy nodes
    1. Open the FlowGraph you wish to copy with the File>Open command
    2. Click and drag to select nodes
    3. Right-click>Copy (or Ctrl-C) to copy nodes
    4. Go back into your entity's Flowgraph and right-click>Paste with links. The new nodes are automatically selected and can be repositioned by clicking on one node and dragging.
  3. Option #2: import nodes
    1. With your entity's FlowGraph open, use File>Import to open the FlowGraph you wish to copy
    2. If the imported nodes are positioned over other nodes hold down Ctrl, click to select the imported nodes, and drag to reposition.
  4. Make any necessary assignments to nodes
    1. Nodes labeled "Choose Entity" in red need an entity assignment. Select the desired entity, right-click>Assign selected entity, or right-click>Assign graph entity. The graph entity refers to the entity to which the FlowGraph belongs.


Example

A simple example is the measureDistance.xml FlowGraph, pictured below, which is a convenient way to measure the distance on the XY plane between objects during development. I leave this .xml file in the Game/Levels/AR/Common directory so I can open it from any AR level and quickly assign two entities to the Entity:EntityPos nodes, hit the AI/Physics button in the Editor, and see the calculated distance in the debug message. To bring the nodes into an existing FlowGraph, follow the steps above.

Here's the file if you would like to try it out: File:FG MeasureDistance.zip.

Image:fg_share_measureDist.png

Problems with this wiki page? Contact us either by: Support Email or Support Ticket System

Blue Mars Guidebook Privacy Policy
Blue Mars Guidebook Community Guidelines

Personal tools