Free and versatile Node Editor Framework for Unity 3D
20 | 21 |
24 | 
25 |
26 | (Texture Composer, an example avaiable on the forums)
27 |
32 | Documentation by Seneral
33 |
34 | Version 1.02 (30.01.16)
35 |
40 | Repository 41 | - 42 | Forums 43 |
44 |
55 | Preface
56 | Features
57 | Examples
58 |
59 |
60 | Getting Started
61 | Custom Nodes
62 | Custom ConnectionTypes
63 |
64 |
65 | Customization
66 | Interface
67 | Framework Overview
68 |
69 |
70 | Events
71 |
72 |
73 | Conclusion
74 |
86 | This Documentation intends to give you an overview of the Node Editor. It was initially posted by me, Seneral,
87 | as a personal project on the Unity forums.
88 | After receiving a great amount of positive feedback I continued improving and supporting it, now featuring alot of major things a Node Editor needs to have!
89 | The GitHub repository was set up by Baste during the early developement,
90 | and now it's the main platform to share and contribute to Node Editor.
91 |
The Node Editor is special in that it's open source, but still is packed full of features, some of which are very unique to this project and which we're proud of featuring:
96 |The framework also shines with clean and easy to modify code. It's clearly seperated in multiple parts, some of which can even be taken and used somewhere else, such as the unique, generic scaling approach!
106 |
110 | You can start off by checking out the Editor Window at 'Window/Node Editor' and loading one of the example canvases, such as the CalculationCanvas.
111 | Do that by either loading it with the button at the top right or by locating it in the project folder and double-clicking it.
112 | With right-click you can add additional nodes, using drag'n'drop you can connect node Outputs and Inputs with each other.
113 |
124 | Here you'll find some help on how to get you started creating custom Nodes and ConnectionTypes in the simplest form, without touching the Framework code. 125 | These two methods already can help you make little extensions requiring the Node Editor Framework to be installed seperately. 126 |
127 |
131 | The implementation of additional, custom nodes is fairly easy. You have to create a script anywhere in the project extending the Node class of the NodeEditorFramework namespace.
132 | It will provide the Framework all needed information about the node itself, the optional Node Attribute contains information about the presentation in the editor.
133 | The Framework will search all script assemblies for additional nodes, so extra setup is not required.
134 | In the following are the necessary Node members outlined, based upon the ExampleNode found at 'Plugins/Node_Editor/Nodes'.
135 | First to mention is that even though the Framework is programmed in C#, you can add nodes in UnityScript with the limitation that they have to be compiled in phase 2,3 or 4,
136 | as described here. Therefore the following members are described language independently.
137 |
NodeEditorFramework dependencyNodeNode [Params: [Bool] hide; [String] contextPath]ID [constant string]; expose: property GetID [override]AllowRecursion [override, default: false]ContinueCalculation [override, default: true]AcceptsTransitions [override, default: false]Create [override; Params: [Vector2] position; Return: [Node] Created Node]
155 | CreateInstance. Assign it's property rect using the position parameter and give it a name.CreateInput/CreateOutput or NodeInput.Create / NodeOutput.Create [Params: Name; TypeName; NodeSide; position]NodeGUI [override]
164 | DisplayLayout or SetPosition to position (and draw) themCalculate [override; Returns: [Bool] Calculation success]
172 | allInputsReady, hasUnassignedInputs and descendantsCalculated may help to check if the node is ready, based on the needs and purposes of it.GetValue to get the value stored in the connection of the same type. Similarily, set the output values with SetValue.
186 | Implementing custom ConnectionTypes is similar to Node implementation, as it uses the same fetching system:
187 | Declare a class inheriting from the ITypeDeclaration interface and specify it's properties.
188 |
191 | 
192 |
193 | ConnectionTypes.cs: Top Block: ITypeDeclaration; Bottom Block: Built-in Float type
194 |
215 | Even though you can already built small extensions with methods described above pretty well, to natively integrate Node Editor into your 216 | own editor extension you may want to cutomize it, from building your own editor interface to modifying and extending the framework itself. 217 |
218 |222 | The provided Editor Window basically serves as the default Node Canvas explorer for all dependant extensions and single canvases, 223 | but also as a starting point to develop a custom Editor Window from. That means, you can savely delete it if you don't want it in your extension. 224 | In the following I'll outline all things you need to consider to build a basic Node Editor Interface in both Runtime and the Editor. 225 |
226 |
230 | The Editor needs to store the currently opened Canvas (NodeCanvas) and it's Editor State (NodeEditorState).
231 | For an explanation of these, please look up the Framework Overview. You can save both using NodeEditor.SaveNodeCanvas
232 | and load them with NodeEditor.LoadNodeCanvas and NodeEditor.LoadEditorStates.
233 | Take reference from the default NodeEditorWindow to see how exactly these functions are integrated.
234 | The function AutoOpenCanvas also shows how to automatically open a canvas by double-clicking it's asset in the Editor.
235 |
240 | First, you need to make sure that the NodeEditor is initiated using NodeEditor.checkInit, and that there is always a canvas loaded, else creating a new one.
241 | Before drawing you'll want to define the rect in which the canvas is drawn. No boundaries are set anymore on where the canvas is set, in how many subgroups, etc.
242 | Only the case of modifying the GUI.matrix scale before is not yet supported. You currently must assign the rect to the canvasRect property of the EditorState.
243 | In order to best account for errors, the following drawing statement is embedded in a try-catch block catching only UnityExceptions, unloading the old and creating a new canvas when an error occurs.
244 | Draw the canvas by passing both the NodeCanvas and the EditorState into NodeEditor.DrawCanvas, which will behave like an ordinary GUI control in most cases.
249 | The GUISkin of the Node Editor can currently only be changed by modifying the NodeEditorGUI.cs source file or by simply replacing the textures. 250 | For the future a more extensive and seperated control over the GUISkin is planned. 251 |
252 | 253 |255 | This section aims to bring you a decent overview on how the framework is structured, so you can get to modify it quickly. 256 | This does not necessarily include implementation details – code sections that need extra detailing are commented. 257 | Also, this section is not only for those planning to get into the code, but for everyone to get an overview what he's working with:) 258 |
259 |263 | Those two components essentially make up something you can load up into the Editor. Basically, the canvas is the important part with all the nodes and any additional information directly related to the Canvas. 264 | In contrary, the EditorState holds all information on the state, or in other words, on how the Canvas is presented. This includes zoom and pan values, selected Nodes, the canvasRect, etc. 265 | Not all of these values are actually saved with the asset, though. That structure allows for multiple 'views' on the same Canvas and editing it simultaneously.
266 |
270 | This function acts very similar to any other GUI control, with a few exceptions, and is responsible for drawing the Canvas.
271 | On the first glance it's just a wrapper for DrawSubCanvas, with the exception that it holds the OverlayGUI and NodeGUISkin code.
272 | DrawSubCanvas is used in the future for Nested Canvases, as the name proposes.
273 | In the first major block, the background texture is sliced and placd across the screen where needed, accounting for pan and zoom, relative to the rect center.
274 | In the function InputEvents all inputs are catched. It's well commented, so no further explanation is necessary here. It accounts for Rects that should be ignored for input.
275 | Then, the scale area gets initiated with a call to my custom solution GUIScaleUtility.BeginScale. Any GUI code afterwards is getting scaled appropriately.
276 | In the following, everything that needs to be scaled gets drawn, including temporal connections, node transitions, connections, bodies and knobs.
277 | Thereafter, the scale area gets closed again with another call to GUIScaleUtility.EndScale. The LateEvents function checks all inputs with secondary priority (after the nodes)
278 | just like InputEvents does, in this case it only makes sure the node can only be dragged when not clicking on a control (GUI.hotControl is 0).
279 |
290 | (WIP)
291 | The Framework supports a multitude of Events which might be important during the editing process. Those Events can either be received
292 | by subscribing to the appropriate delegate in the NodeEditorCallbacks class or by extending from NodeEditorCallbackReceiver (which is a MonoBehaviour)
293 | and overriding the appropriate method. Both classes can be found in NodeEditorCallbackReceiver.cs.
294 | Current Events include:
295 |
OnEditorStartup (): The Node Editor gets initiated (can also happen when switching scene or playmode)OnLoadCanvas (NodeCanvas): The passed canvas has been loaded (copy)OnLoadEditorState (NodeEditorState): The passed editorState has been loaded (copy)OnSaveCanvas (NodeCanvas): The passed canvas has been saved (copy)OnSaveEditorState (NodeEditorState): The passed editorState has been saved (copy)OnAddNode (Node): The passed node has been created or duplicatedOnDeleteNode (Node): The passed node will get deletedOnMoveNode (Node): The passed node has been moved by the userOnAddConnection (NodeInput): A new connection has been added to the passed input. If it had a connection before, OnRemoveConnection has been called, tooOnRemoveConnection (NodeInput): The connection will get removed from this inputOnAddTransition (Transition): The passed transition has been createdOnRemoveTransition (Transition): The passed transition will be removed
320 | (WIP)
321 | I'm happy that the Node Editor has received so much positive comments and helpful critism since I posted it back in May 2015.
322 | Since then a few people took the time and motivation to contribute to the project which I appreciate very much!
323 | You can check all contributions out on the contributions page.
324 | But also those who use, test and report bugs are very important for this project.
325 | If you wish to contribute, you may take a look at the roadmap as a rough guideline what is planned and how you can help. Of course, own ideas are just as fine.
326 | Make sure to post or tell me if you are making an extension using Node Editor, may it be big or small, and notify me about any problems you may encounter:)
327 | This is vital to the project! Just make sure to account for the MIT License included with Node Editor.
328 | Also, you can always contact Seneral with a PM on the Forums or per Email at lev.gaeher@gmail.com:)
329 | I hope this Documentation has helped you understanding the NodeEditor, else feel free to suggest imrovements and ask me!
330 |