The Manual

1.Getting started

Welcome to the documentation for the SDK and editor.

1.1.Installation

Download the sdk & editor from here: https://benmorris.itch.io/plugin-based-scene-editor

macOS:

  • Double click the fireflyeditor.dmg
  • Drag the fireflyeditor.app into the Applications folder (linked to in the installer)
  • Launch the fireflyeditor.app from your Applications folder

2.Walkthrough: Creating a game project

(Available in version 0.40.4+)

Prerequisites:

The editor contains a code wizard that generates a standalone executable.

Instructions:

  • Open the editor
  • Go to the Development menu and select “New Executable…”
  • Enter your game’s name
  • Hit the Generate button and then follow the instructions i.e.
  • Open CMakeGui (assumes you’ve installed CMake)
  • Set the CMakeGui field “Where is the source code” to the generated source code path (as indicated by the wizard)
  • Set the CMakeGui field “Where to build the binaries” to a sub directory of the above path i.e. a “build” sub-directory beneath the above path
  • Hit Configure – Fix the error i.e. set the firefly_DIR field to the install location of the editor’s cmake folder i.e.
    • macOS: /Applications/fireflyeditor.app/Contents/Resources/cmake
    • Windows: C:/Program Files(x86)/FireflyTech/FireflySceneComposer/lib/cmake
  • Hit “Configure” again
  • Hit “Generate”
  • Hit “Open Project” to launch the generated game project in Xcode
  • Build / Run

3.Walkthrough: Extending the engine

(Available in Editor/SDK version 0.39.0+)

The engine is Entity Component System (ECS) based. ECS is an architecture that allows you to add behaviours (components) at runtime to entities (an entity being a game object or “SceneItem” in this SDK’s parlance). All components of a specific type are processed by an associated system in a cache friendly manner for performance. For more details on ECS see here: ECS (wikipedia)

In this walkthrough we will extend the engine adding a new Component and System using an editor supplied code wizard.

Prerequisites

macOS:

Steps

A video of the workflow (described below):

Open the editor

Click the Menu -> Tools -> Development -> New SceneItem / System / Component plugin menu item

Set the:

  • Plugin name to MyPlugin
  • Initial Scene Item name to MySceneItem
  • Specify the path you want to generate code in (should be a writable location)

Click the Generate button

In the wizard’s output pane you should see some output like:

Successfully generated plugin MyPlugin6. Your initial scene item’s uuid is {92e6af43-6776-45a0-9e63-159463e3005e}.

Next, open CMakeGUI and set your source path to:

/Users/benmorris/Dev/Test/MyPlugin6

Launch the CMake GUI (see below) and set the path to your Plugin’s source code as indicated by the wizard output and a directory to build your plugin in.

Hit the Configure button

Fix the error (i.e. CMake can’t locate the SDK) by setting the firefly_DIR variable to the install location of the fireflyeditor.app app pointing to the path of the SDK’s CMake package config file (under the fireflyeditor.app’s bundle in the Contents/Resources/CMake directory – see the above image for a typical path)

Hit the Configure button

Hit the Generate button

Hit the Open Project button to launch your project in Xcode (assuming it’s installed)

Hit the build button in Xcode

NB. The generated Xcode project contains a post-build step that will copy your plugin to the editor’s ‘Frameworks’ folder and so is immediately available in the engine / editor.

Relaunch the editor

Go to the System tab and confirm you have a system called MySystem also confirm that your component is available for adding to game objects by clicking the Component drop down in the editor right hand pane (beneath the properties pane, the component name should be MyComponent)

Congratulations, you’ve created a plugin and it is now accessible within the editor / engine, can be attached to scene items and will be updated each frame by your MySystem system.

NB. To debug your plugin in Xcode set the launching executable for your plugin to the fireflyeditor.app in your /Applications folder (or your install location) and then add your breakpoints then build / run as usual.

Next, we will add a property to our component and modify the system to do something with that property.

 

4.The Editor

4.1.The toolbar

The toolbar is loaded by the editor on startup by scanning the editor directory for plugins that expose specific entry points that provide access to tool icons and behaviours and so is fully customisable through plugins. By default the editor ships with an interaction plugin that provides pick, move, rotate and add tools.

From left to right (beneath the File / Edit / etc menu):

    • View: Displays a drop down of viewpoints (i.e. cameras) currently added to the scene. You can change the currently active camera here. The active viewpoint can also be modified in script and through an action connection described later on in this page.
    • Run! Runs the scene in a standalone executable for testing the scene as it might appear as a (published) standalone simulation. This also enables you to have both the editor and the running scene open simultaneously on a multi monitor display. The standalone executable’s scene can be reloaded by pressing the F5 key.
  • Pick tool – Activates picking. Holding down CTRL whilst picking allows you to pick multiple objects
  • Move tool – Activate to move picked objects
  • Rotate tool – Activate to rotate picked objects
  • Add tool – Activate to add objects to the scene
  • Tool options – This button with an elipsis to the right of the Add tool can be clicked to open an application modal dialog that displays the options associated with the active tool. The options are provided by the tool’s plugin for a given tool.

NB. These tools are provided through the Interaction plugin. You can add your own icons to this toolbar as described in a walk through on this page.

The Scene Tree View

The scene tree (below) represents the scene hierarchy. This is purely a data representation, in reality, scene items are rendered in batches by the engine to reduce state switches so isn’t necessarily executed in the order seen in the tree.

4.2.Adding objects

  1. Select the Add object tool
  2. Choose Box in the tool options dialog (you can open this dialog by clicking the tool options button on the main toolbar as described above)
  3. Click on the scene (or an object within the scene) to add boxes under the clicked position. If no mesh is found under the mouse click then the newly added object will be created at the scene origin
  4. Verify the boxes have been placed in the positions as expected
  5. Perform undo (CTRL + Z) to remove all added boxes
  6. Perform redo (CTRL + Y) to re-add all boxes
  7. Save scene (File -> Save menu)
  8. New scene (File -> New menu)
  9. Load the scene saved in step 7 (File -> Open menu)
  10. With the scene now loaded hit the “Run!” toolbar button and verify your scene loads in a separate window

4.2.1.Importing models

NB. The editor performs scene import again using plugins allowing for the pluggable addition of other model formats (i.e. proprietary to your engine). The default scene importer comes bundled with an importer plugin that uses the Asset Import Library (Assimp) and so provides support for many standard 3D model formats. 

  1. Create a new scene (File -> New)
  2. Import a model (File -> Import). The editor supports many file model formats, .obj, .3ds etc
  3. Verify the imported model looks correct

4.2.3.Selecting objects

  1. Active the picking tool in the toolbar
  2. Left mouse click on an object to select
  3. To select multiple objects hold down either the Command key (Apple) or CTRL key (Windows) to select multiple objects

4.2.4.Duplicating objects

  1. Load a previously generated scene
  2. Select a scene object using the picking tool
  3. Activate the Move tool
  4. Hit CTRL + D to duplicate the scene object
  5. Move the duplicated scene object with the move widget

4.2.5.Moving, rotating and scaling objects

  1. Load a previously generated scene
  2. Select a single object in the scene
  3. Activate the Move tool
  4. Move the picked object
  5. Undo the object move (CTRL + Z)
  6. Redo the object move (CTRL + Y)
  7. Activate the pick tool
  8. Select multiple scene objects
  9. Activate the Move tool
  10. Move the picked objects
  11. Perform undo and redo and verify the movement is un-done / re-done as expected

4.2.6.Previewing a scene

  1. Load a scene created previously
  2. Expand the scene tree (left hand tree view) until you can see the “MyScene” node
  3. Click the “MyScene” node
  4. Right click and select “Add child -> Diagnostics-> Frame Counter”
  5. Save the scene
  6. Hit the “Run!” toolbar button to preview your scene
  7. Verify your scene opens in a separate window and the frame rate is visible
  8. (With the preview window still open) In the editor window activate the add object tool
  9. Place another object in the scene by clicking in the editor’s scene view
  10. Save the scene File -> Save menu
  11. Activate the preview window by mouse clicking in the preview window
  12. Hit F5 to re-load the preview window’s scene
  13. Verify the scene reloaded in the preview window and its appearance reflects the scene in the editor

4.2.7.Switching viewpoints

  1. Create a new scene (File -> New)
  2. Beneath the menu bar (i.e. beneath the panel that hosts the main menus File, Edit, Tools etc) there’s a viewpoint drop-down list. Modify the selected camera.
  3. Verify the viewpoint changes
  4. Expand the scene tree until the Editor Camera node is visible
  5. Select the Editor camera and right click choosing the “Make this a child of -> Cameras -> Editor Camera”
  6. Verify the newly added camera appears in the viewpoint drop-down list in step 2.

NB. To allow a user to toggle between different views in your scene you can add an Input capture device (i.e. Keyboard) to the scene and create an Action (as described in “Scripting – Activating a script”) to wire a Keyboard key press event to a Camera’s “Activate” slot. You can assign an action (i.e. key press) to each Camera of interest.

5.Scripting

The engine is fully scriptable using LUA. All classes described in the API documentation (Help -> API documentation menu) are scriptable with the API documentation being a reference to the (scriptable) API.

There are 2 scripting approaches:

  • Adding a Script component to a scene item
  • Creating a global script

 

5.1.Script Component

(Available from version 0.40.2+)

  1. Select an object in the scene
  2. In the Property Pane (right hand side of editor) select the “Script” component in the component drop down
  3. Set the script’s source

A script component has access to the following variables:

  • object – this is a reference to the object to which this component is attached
  • time – the current frame time

5.2.Global Scripts

Creating a global script

  1. Create a new scene (File -> New)
  2. Expand the scene tree (left hand tree view) until you can see the “MyScene” node
  3. Click the “MyScene” node
  4. Right click and select “Add child -> Scripting -> Script”
  5. Select the added Script node and verify the scripts source code is visible in the right hand property pane
  6. Right click and select “Actions -> Execute”
  7. Verify the script has executed

Activating a global script

  1. Continuing on from the Global scripting steps above, select the root “Group” node in the scene tree view (left hand pane)
  2. Right click and select “Add child -> Input -> Keyboard” to add a Keyboard input capture node to the scene
  3. In the Actions pane (see image below), recreate the details in the image below as follows:
    1. Click “Add” to add an action
    2. Click the Sender field and choose “Keyboard”
    3. Click the Signal field and choose “F – key down”
    4. Click the Receiver field and choose “Script”
    5. Click the Slot field and choose “Execute”
  4. Set focus on the scene view by clicking into the scene view
  5. Hit the “F” key to trigger your action (executes script)

6.Shaders

The engine supports shader discovery by loading shaders from a special directory:

  • (macOS) [your_install_location]/fireflyeditor.app/Contents/Frameworks/Shaders
  • (Windows) [your_install_location]/bin/Shaders

Shaders are automatically loaded from these locations on startup and are then create-able within the editor / engine.

To instantiate these shaders in-editor

  • Click on the Assets tab
  • Click on the Shaders tab
  • Click Add
  • Choose the shader
  • Set its properties
  • Choose the Assets/Materials tab
  • Create a new Material
  • Set the Material’s shader (to the one you created above)
  • Assign the shader to a scene object by selecting the object in the scene and then set its Material property (to the one you created above)

NB. To instantiate shaders in code see the example_Shaders demo source code (accessible from the demo launcher on editor startup).

6.1.Adding custom shaders

To add new shaders:

  • Place your vertex shader in the special Shaders directory i.e. myshadername.vert
  • Place your fragment shader in the special Shaders directory i.e. myshadername.frag
  • Restart the editor

NB. Ensure there are no source code comments in your shaders as currently the shaders are opened and the lines are compressed into a single string so comments break this.

6.2.Built-in shader variables

The following engine variables are currently available to shaders at runtime as uniform variables and so can be referenced by your shader code:

  • iResolution
  • iGlobalTime
  • iElapsedTime

7.Post processing shaders

(NB. Available from version 0.40.1+)

A post processing shader effect is a special type of shader that renders anything beneath it in the scene graph (usually your scene) to a texture. The texture is then displayed on a full screen rectangle so that the rectangle’s fragments cover the entire display and, in so doing, allow a pixel shader to be applied to every pixel on the display to create a full screen (post processing) effect.

This short video demonstrates how a post processing shader can be applied to a scene within the editor.

NB. For details on how to apply a post processing shader to a scene programatically see the example_PostProcessing source code and demo in the demo browser displayed on editor startup.

8.Texturing

(Available from v0.40.6)

The editor / engine supports texturing. Typical workflow is:

  • Drag texture images into the editor (Assets -> Textures)
  • Assign the texture(s) to a shader that supports texturing (i.e. has texture inputs)
  • Assign the shader to a material
  • Apply the material to a model

The short video below demonstrates the workflow:

8.1.Multitexturing

Follows a similar workflow to texturing (see video below).

9.Rendering overview

The engine is a hybrid scene graph / ECS architecture.

The rendering algorithm:

  1. Scene graph traversal: A pre-order traversal of the scene graph. For each item in the scene graph:
    1. The scene item’s Prepare() method is called
    2. Typically the Prepare() method enqueues an item onto a render queue (or if the item is a scene manager, an Octree for instance, any further traversal of the Octree’s scene-graph is short-circuited allowing the scene manager to perform frustum / occlusion culling enqueueing only the visible items that exist in the Octree’s sub scene-graph)
  2. System Update: Once the scene graph has been traversed the systems are updated (a system is effectively an array of components of a specific type). A system component can optionally query the visibility of the scene item (to which it is attached) to determine if it should be updated or not.
  3. Rendering: The render queue renders the scene by performing state-based sorting of the render items it contains followed by calling each item’s Render() method

Improvements: The scene graph might be replaced with a rendering system and component at some point in the future simplifying the above to a two step process i.e. system update followed by rendering.