Flowgraph Editor lets you create gameplay logic using a node-based editor while ingame. This document will give you some basic information on how to use this new programming tool.
To get a demo of what the editor is capable of, open the new World Editor by pressing
F10. Open the Flowgraph Editor by clicking Tools in the menu bar, then on Flowgraph Editor. The first time you open the Flowgraph Editor, you will see the the welcome window. Click on the “Start Gridmap Demo” button on the right. The editor will close and the game will load GridMap with 8 demo projects which you can explore ingame.
You can open the Editor at any time and check out the execution of the projects. Simply press
F10 again, then select any of the projects in the Task Manager window in the bottom right corner. As long as the projects are running, you won’t be able to edit anything though. To do that, you can stop the execution of a project by clicking the Stop button either at the top of the screen or next to the name of the project in the Task Manager window.
Make sure not to stop the “Demo All-In-One” project, as stopping this will close all the other projects. This is because projects “clean up” when they are stopped, and that project opened and started all the other demo projects.
As a simple modification, we will change some values of the Gravity Demo: if you haven’t tried it, this demo creates 4 triggers, each of which will set the gravtiy to certain value when the player drives through this trigger. Select the project in the Task Manager window and stop the execution by pressing the Stop button.
We will now change the “Earth” trigger to a “Venus” trigger. Find the topmost Debug Text node, and click it. You will see it’s properties in the Properties window in the top right. Find the text field with “Earth” inside, and change the string to “Venus”, and confirm with
Enter. If you start the project again, you will see what we expect: The marker with “Earth” now shows “Venus”. But the gravity needs to be changed as well.
To do that, find the Set Gravity node with the value “-9.81”, and change the value in the same way we did for the Debug Text node, but change the value to “-8.87”, which is the gravity of Venus. Also change the text of the Message node next to it, so the user knows what happened.
Congrats on your first mod!
Here are some concepts an definitions of things you should know when using or talking about the Flowgraph Editor:
- Node: A node is the most basic element in the Flowgraph Editor. There are lots of nodes that do different things. Nodes can have either inputs and outputs, usually both. If a node receives flow, it will do its work. Nodes which do not have flow inputs but flow outputs are called root nodes. Those are usually the start of your graph and will trigger the execution by an outside hook, for example
- Pin: Pins are the interface of a node, and can be either input or output in nature. Pins can have various types:
number, string, bool, vec3, quat, colorare the base types. There can also be multi-type or any-type, as well as flow, which is a special type.
- Link: These are used to connect pins, and thus nodes. Links always connect exactly two pins: the source and the target. Links can be hidden to reduce clutter through the context menu.
- Flow: This is how the flowgraph gets executed. If flow reaches a node, that node will do its work, and then usually give an out flow which can reach later nodes. By chaining together multiple nodes, they will work one after another. If a node does not receive flow, it will not do anything, and all nodes that are nected to its output will also not work.
- Graph: A graph is a set of nodes and links. In most cases, you only need one graph, but you can group a selection of your graph and create a subgraph.
- Project: A Project is a set of graphs. Projects can be running or stopped. When running, the nodes will do their work. You can only edit when the project is stopped.
There are also further concepts, which are advanced in nature:
- Subgraphs: Graphs can be contained in other graphs. A graph can have multiple children, but only one parent.
- Integrated Node: This special node represents a child graph. Its pins directly connect to the child graphs I/O nodes.
- I/O Nodes: These nodes connect to their corresponding Integrated node.
- Macros: If you want to reuse a subgraph often, you can convert it into a macro. The subgraph will be then replaced by an instance of the macro you created. Macros can be local in their project, or be saved into a file to be used globally.
- Instances: These can never be edited directly, but automatically update once you change the corresponding macro.
- Variables: Varibales can be read and written using nodes. Each graph has their own set of variables, which can only be accessed from within this graph. Each project also has their set of variables, which can be acces from every graph in this project.
This section will briefly inform you what each of the windows of the editor is about. You can open windows by clicking on Windows in the menu bar.
This window is always open, and it is the area in which you will be creating your graphs. At the top of this window, you see the current projects name and some buttons to start and stop your project.
By default positioned in the top right, this window lets you modify various properties of nodes and graphs. When you have exactly one node selected, you can see that nodes properties, input and output pins. Many nodes have a custom view here, but the pin section will always be there (assuming the node has pins). You can click on the icon of an in-pin to lock its value - this saves you creating additional nodes just for values and reduces clutter.
If you have no node selected, you will see the properties of the current graph you have open. Here, you can change the name and description of this graph, delete it and copy it. You can also convert subgraphs into macros and vice versa.
This window gives you a list of all the nodes that can be used in the editor, grouped by category. You can enter a search term in the search field above to filter results. You can drag or click entries to create new nodes.
In this window you can see all the currently open projects and their execution status. You can click on a projects name to select it, or on one of the buttons to the right the start, stop or close the project. one of the topmost buttons to start or stop all projects.
If you use variable setter nodes in your project, keep in mind that the variables values are always updated at the end of the frame, using the selected merge strategy.
This is the welcome window, which lets you create or open projects and start or load the demos.
In here you can change the projects name and description. You can also Save and Save As… your project.
Here you can see all the graphs of your project in a hierarchical view. In the settings, you can also select an option to show nodes here as well.
This is a developer window which will show you which projects include a particular node. Since it need to check out a lot of files, this can be very slow.
This is the projects action history. You can see any changes you made to the project here, and revert to previous versions by clicking the entry in the list. You can also use
Ctrl + Z and
Ctrl + Y here to undo and redo.
This window is for the Curve node. You can use it to create custom splines.
In here you get an overview of all the timeline related nodes on your project. You can drag and thus scale elements on the timeline.
In the main menu of the editor, you have other settings:
- Dev Mode: This will activate the developer mode. It unlocks additional features, menu entries and settings. If you are just using the editor and not developing for it, you should keep this deactivated.
- Display Ids: This will show the ID of every object in the editor. Useful for debugging.
- Display Fixed pin value: This will show or hide the values of fixed pins.
- Display nodes in overview: This will show or hide node entries in the overview window.
- View Mode: These are special viewing modes for developers. You should keep the ‘default’ viewmode, if you are not developing for the editor.
- Print Nodelib: This will print the node library entries into a file in your userfolder. It is a tab-separated table, which contains various informations about nodes.
- Reload Lua: This will reload Lua.
Ctrl + L
- Toggle Editor Debug: This will toggle the debug view of the main window, giving you detailed information about positions and so on.