# How To Use NarrativeFlow's Compiled Files In Your Game Engine When you're ready to export your narrative for testing within your game engine (or packaging for release!), you'll need to compile your project. Don't worry, compiling is really simple and nearly instant. First, check for any unresolved [errors or warnings](Problems%20and%20Errors%20-%20Reference%20And%20Resolutions.md) in the project by switching to the Problems tab in the Left Panel. If there are any, resolving them before compiling for testing is probably a good idea, and doing so before publishing is essential. Any unresolved problems will almost certainly result in errors, bugs, crashes, etc. at runtime. With this said, if you need to, you can compile and test your project even if there are unresolved problems. After all problems have been resolved, or if you need to test your narrative regardless of any problems, simply hit the Compile button in the Menu Bar across the top of the interface. A Save File system dialog will show, asking you where you'd like to save your compiled NarrativeFlow project file. After you've saved your file, you're ready to load that file into your game's engine and interact with that file with the NarrativeFlow Interpreter Script! > [!info]- Using Unreal Engine or Unity Engine? > **Using Unreal Engine or Unity Engine?** > > NarrativeFlow and any narrative you create with it is **100% compatible** with Unreal Engine and Unity Engine. In fact, those engines are some of the easiest to use NarrativeFlow files with. > > Please note that, as far as I can tell, unfortunately, the terms and conditions of both Unreal Engine and Unity Engine don't allow me to provide tutorials or example/template projects without me literally signing over a piece of my livelihood to them for the rest of my life (seriously). > > So as much as I wish I could, tutorials aren't provided for those game engines, unfortunately... > > This is completely outside of anything I can do, and I look forward to more open/clear terms and conditions provided for those engines/by their respective companies in the future. > > Once again though, **you can 100% use NarrativeFlow projects with those game engines**. I simply cannot provide direct tutorials/examples for those game engines without potentially having large companies demanding my livelihood from me. # The NarrativeFlow Interpreter Script Alright, you've compiled your NarrativeFlow project and saved that file to a location accessible by your game engine. Now, we need to load the file in your game engine and interact with it. The way we do this is through the NarrativeFlow Interpreter Script. > [!SUCCESS] How To Download Your Interpreter Script > NarrativeFlow's Interpreter Script is already available in the following programming languages: > - C# > - C++ > - Lua > - JavaScript > - Python > - GDScript (Godot Engine) > - GML (GameMaker Studio) > > You can download any Interpreter Script version from [the official GitHub repo here](https://github.com/NarrativeFlow-Mitch/NarrativeFlow-Interpreter-Scripts). > > If there's a programming language you'd like the Interpreter Script translated into (Java, Rust, C, etc.), please [reach out to me](https://narrativeflow.dev/lets-talk) and tell me about it. > [!important] > Lua and C++ don't have native JSON parsing capabilities. > > For your convenience, I've already included relevant code within those Interpreter Script versions for using a common JSON parsing library: > > - [dkjson](https://dkolf.de/dkjson-lua/) (for the Lua version) > - [nlohmann/json](https://github.com/nlohmann/json) (for the C++ version) > > You'll need to download the relevant code library/script for the JSON parsing to work. > > If the respective JSON parsing library works for your needs, great! If not, then feel free to use whichever JSON parsing library you want, no hard feelings. > > The only thing you'd need to do is change the relevant code within the Interpreter Script to use your JSON parsing library of choice. ## Code License For NarrativeFlow's Interpreter Scripts In an effort to protect my livelihood (thank you for supporting my family!), I use a slightly modified MIT license. Don't worry, the only reason I'm using a custom license is to prevent the standalone selling of the Interpreter Script itself. Other than that, I *want* you to use the Interpreter Script in your commercial products and modify it according to your needs, so have fun! If you have any questions about the license or Interpreter Script, please [reach out to me here](https://narrativeflow.dev/lets-talk). > [!info]- NarrativeFlow Interpreter Script Code License > NarrativeFlow Interpreter Script Code License – Modified MIT License > > Copyright (c) 2025 NarrativeFlow LLC > > Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to use, copy, modify, merge, publish, and distribute the Software, subject to the following conditions: > > 1. The Software may be used in personal and commercial projects, including but not limited to, games, applications, educational content, and interactive experiences. > > 2. The Software may be included in commercial products, provided that it is not the primary value of the product (e.g., inclusion in a game or educational course is allowed and encouraged, but selling the code itself as a standalone template or package is not). > > 3. You may not sell, sublicense, or redistribute the Software on its own, or as part of a product where the main offering is access to the source code or derivative works of the Software, whether free or paid. > > 4. This copyright notice and permission notice must be included in all copies or substantial portions of the Software. > > THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ## Interfacing With The Interpreter Script Insert the script into your game engine, and you're ready to interface with it. Using the Interpreter Script is pretty easy. Here's a quick overview: - Load the contents of a compiled NarrativeFlow project file in your game engine and create the Project object. - Create an object for any Experience you wish to interact with by calling the "Create Experience" function. - Start a narrative chain in your Experience by calling "Get Start Node". - Simply call "Get Next Node" whenever you want to retrieve the next content Node in your narrative. All non-content Nodes will, by default, be processed automatically. - If you need to retrieve or change a variable's value, use the provided functions for variables. - If you need to retrieve the content associated with a Data Table item, use the provided function for Data Table items. Let's look at each step in detail. Please note that the rest of this tutorial will be using the C# language and that version of the Interpreter Script. ### Load The Contents Of A Compiled Project File And Create The Project Object To create our NarrativeFlow `Project` object, we need the contents of our compiled project file (i.e. load the file's data as a string). In C#, reading the contents of a compiled NarrativeFlow project file looks something like this: ```cs string fileContents = File.ReadAllText("C:\YourCompiledProject.narrative"); ``` With that said, some game engines have built-in methods to read files, so perhaps check the recommended method for your engine. Once we have the contents of our compiled project file loaded, we can simply create a NarrativeFlow `Project` object from that content, like this: ```cs NarrativeFlow.Project Project = new NarrativeFlow.Project(fileContents); ``` Depending on your game, this object probably needs to be a "global" variable/object. That way, your `Project` object is persistent and doesn't get removed when transitioning to a different scene, removing entities, etc. ### Create An Experience Object And Start A Narrative Chain Now that we have our `Project` object created, we need to create an `Experience` object so we can start a narrative chain that it contains. ```cs NarrativeFlow.Experience Experience = new NarrativeFlow.Experience(Project, "Experience Name"); ``` In this example, `Project` is the project variable you just created above, and `"Experience Name"` is simply a string matching the exact name of the Experience you want to load. Now that we've created an `Experience` object and loaded our desired Experience into it, we can start a narrative chain like this: ```cs NarrativeFlow.Node CurrentNode = Experience.GetStartNode("Start Node Name"); ``` Doing this loads the content of the Start Node with the name you provide into our `CurrentNode` variable. `GetStartNode()` searches for and returns the Start Node that has the provided name within that Experience. If no Start Node with the given name is found, `null` will be returned. Now that we have our Start Node content loaded into a variable, we can interact with it. To learn what member variables/properties Nodes have, check out the Node Member Variables section below. When we're ready to get our next content Node in the narrative chain, all we need to do is call `GetNextNode()`, like this: ```cs CurrentNode = Experience.GetNextNode(); ``` If our last Node was a Choice Node, we need to pass the choice the player selected as an argument/parameter, like this: ```cs CurrentNode = Experience.GetNextNode(int SelectedChoice); ``` Then, after we determine what type of Node was returned, you can use the member variables of `CurrentNode` however you want in your game engine. ```cs switch (CurrentNode.type) { case "dialog": ShowDialogueBox(CurrentNode.dialogSource, CurrentNode.dialogString, CurrentNode.properties); break; case "choice": ShowChoiceUI(CurrentNode.choices, CurrentNode.properties); break; case "function": ParseAndDoStatement(CurrentNode.statement); break; case "start": InitializeConversationScene(CurrentNode.properties); break; case "end": EndConversationScene(CurrentNode.properties); break; default: // A default case is always recommended to catch any errors. // While hopefully not needed, it's a very wise practice. break; } ``` ### Node Member Variables Your NarrativeFlow data, both when you save and compile your projects, is saved in the JSON data format as plain-text. JSON is an open, non-encrypted, human-readable format. This means your data stays *yours*. Typically, JSON data is parsed into an object with member variables/properties. Below is a list of member variables/properties that the different Node types returned by `GetStartNode()`/`GetNextNode()` will have. > [!info] > By default, the Interpreter Script handles Variable, Conditional, Probability, and Teleport Nodes for you, and Connector and Comment Nodes are trimmed out when compiling, so you don't need to handle any of those Node types yourself. > > In addition, Dialog, Choice, Start, and Function Nodes each have a `linksTo` property. This is used internally by the Interpreter Script and can safely be ignored (or used however you wish). #### Dialog Node - dialogSource (string) - dialogString (string) - linksTo (int) - properties (array) - name (string) - value (string) #### Choice Node - choices (array) - choiceString (string) - linksTo (int) - properties (array) - name (string) - value (string) #### Start Node - name (string) - linksTo (int) - properties (array) - name (string) - value (string) #### End Node - properties (array) - name (string) - value (string) #### Function Node - statement (string) - linksTo (int) ### Variable and Data Table Item Values `GetVariableValue("Variable Name")` will return a string containing the value of the given variable at that time. So if the value of that variable has changed either through your narrative or game engine, the current value at that time will be returned. If the value of that variable hasn't been modified yet, then that variable's default value will be returned. `GetDataTableItem("Item Name")` simply returns a string containing the content of the item you request, exactly as you defined it in the Data Table modal. ## Modifying The Interpreter Script The Interpreter Script is meant to be modified according to your needs. If you want something to function differently, feel free to modify it however you want. In fact, with a few changes, you could do some pretty advanced things. For example, you could modify the Interpreter Script so that you can put function calls in the assignment and comparison value fields which will be passed to your game engine, parsed, and run, returning a relevant result to be used for the assignment/comparison. I.e. Instead of assigning a static value or a variable's value, you could have a function call or a code statement, which would be evaluated by your game engine first, returning the result to be assigned/compared against. Or maybe you want to modify the Interpreter Script so that each variable is processed as a specific data type, or how variables are automatically parsed. Or perhaps you want to change how Node data is retrieved, which Node types are returned, how an Experience gets the next Node, how End or Teleport Nodes are handled, etc. This is why the Interpreter Script just uses a slightly modified MIT license. As long as you don't claim it as your own, sell it as-is in a standalone format, or remove the copyright, you can modify it however you want. I created the Interpreter Script *for you*, so feel free to modify it according to your needs. # Final Thoughts While the Interpreter Script was designed to be as simple as possible to drop into your project and start using, anyone can encounter some difficulty. If this is the case for you, and you can't seem to get it working in your project the way you expect, please [reach out to me here](https://narrativeflow.dev/lets-talk). If the problem is related to the Interpreter Script, I'll do my best to help you resolve the issue so you can get back to crafting your incredible narrative!