Fusion3 Blog - Resilient Architecture (Patreon)
Content
Today’s blog post is about an architectural change we made during Fusion 3’s development.
It is a bit more technical and "under-the-hood" than usual, but we thought the topic might be interesting for our readers.
In essence, it is about certain assumptions we had during development that turned out to be detrimental to the stability and future development of Fusion 3 and how we are solving it.
Fusion 3 is a big project and has to keep track of the entire logical representation of the users' game/application in order to be able to edit it.
Originally, the editor loaded projects and relied on them being completely valid, with validation being performed at load time, and the load failing at the first error. This is a pretty typical approach to loading data, and it seemed to work well enough early in development. However, as development went on, we started running into more and more problems with this approach.
One problem was that the entire project had to be loaded and linked up before you could even get into the editor, meaning large projects could take a long time to load. If there was any problem in our code or some outdated stuff in an old test project we were using for development, we’d have to manually fix it by hand before we could get to the stuff we were actually trying to fix, change, or test, and then load the project again just to find the next problem, since only the first error was reported each time. For a while we assumed this would only be an ongoing problem during development, but then we realized it could happen in the wild too.
That brings us to the next problem. Fusion 3’s project format is a folder with many files and subdirectories, which is a good thing since that makes it more compatible with source version control systems like Git. The bad part is this also means that projects can end up in invalid states at no fault of your own, just by merging changes from a collaborator. Consider a game with a tank object that has a custom action for setting what direction its turret is facing. Collaborator A adds some events to the frame that use this action to orient the turret, while Collaborator B decides the tank’s own events should handle this and deletes the custom action. Both forks are fully valid, but after merging changes, the project now has events that refer to a nonexistent action. What should happen now?
With our original architecture, the result would be a terrible user experience: the project would fail to open with a single confusing error message pointing to a single line in a JSON file. Even if you knew how to manually edit the JSON file to fix it, you’d have to keep trying to open the project over and over until every error was fixed. Better collaboration support is a major goal of F3, so we decided this was unacceptable. But how do you address a problem like this?
One option is to just throw away everything that would generate an error. This would allow you to open corrupt projects, but you’d lose everything that was even slightly crooked from F3’s perspective, and upon saving it’d be gone for good. This is workable, but still a bad user experience.
Another option is to take advantage of what F3 really is: an editor. Does your document editor fail to open documents with misspelled words? Does your spreadsheet editor delete cells with invalid dates? Absolutely not. Instead you get red squiggly underlines, and everything is preserved, so you can make fixes as needed. You can even still print the document, the red squigglies just won’t show up in the printed copy. Sounds like a similar approach could be taken for F3, right?
With that in mind, we started prototyping a new architecture for the F3 editor to explicitly allow invalid and broken states. To load a project, we can just read all the JSON files from disk and convert them into tree structures that exactly mirror the original JSONs, while including additional information like line numbers, unique identifiers, and timestamps (elaborated on later). Internally we call these Abstract JSON Trees, or AJTs for short. Once all the JSONs are parsed, the project is considered loaded. Done! Sort of. Next you’ll obviously want to open a frame editor or event editor, and from there things get interesting.
When navigating around the Fusion 3 editor, we can just only query the specific parts of interest. This is made possible using an innovative system for making strongly typed views over the weakly typed AJTs (elaborated on later). Any time something doesn’t make sense, we can just create error representations on screen - visual indicators of a problem you can fix or ignore, like the broken events shown below. When you go to edit them, the parts that are still valid will remain valid, allowing you to copy out expressions that are still fully or mostly valid, for example.
(Error messages and presentations are a work in progress, and will continue to be improved over time.)
You can even start adding an action, decide you don’t want to fill in all the parameters, and just save with it in an incomplete state, like the second action above, whose expression editor is shown below. It won’t have any effect until it’s fully valid, but now you can come back to it later. If later never comes, that’s alright, anything invalid is excluded from the final build.
(Yes, the expression editor lets you view and edit all the parameters simultaneously in F3!)
As we worked more on this new architecture for the editor, we started to realize it wasn’t just solving the initial problems described above, it was also solving other problems we had but had just falsely assumed were unavoidable:
When you make changes to the project, they are written directly into the AJTs, which can be saved back to JSON format immediately. Anything that doesn’t need to be changed is left unchanged, so anything that is broken won’t be corrupted further. This means it is generally safe to open a project to edit one thing and then save it again.
Because these tree structures act as a single source of truth for the entire project, it becomes extremely easy to use them to track all changes for undo/redo support. This has an added bonus of letting us roll back partial changes if an exceptional error occurs while making modifications - we just run the undo operations for the partial changes, getting back to a clean state.
The undo/redo system then lets us know exactly which files need to be saved to disk when saving the project, and we can reliably notify various views in the editor to refresh their content when it has been modified, either externally or by other parts of the editor.
Meanwhile, the automatic background build that we mentioned in a previous post does have to examine everything in order to produce a runnable executable, so as it goes along, it notes down any issues it finds and replaces or ignores anything that’s broken. At the end, a working executable is generated (for some definition of “working”) and the editor is handed a full list of all issues for you to look at and decide if and how to fix. This keeps the editor snappy since it only has to worry about a small subset of the project at a time, while all the final validation is handled on a background thread.
These are all things that the old architecture either couldn’t support or required us to track and implement manually on a case by case basis, which was very tedious and prone to mistakes. The only downside is that renames are more complex and expensive in the new architecture, but that’s far outweighed by all the other benefits.
The real saving grace that made all this possible is the aforementioned strongly typed views, something we were only able to properly create thanks to new features in C++23. They aren’t something you’ll notice as a user of F3, but they help protect us from accidentally mishandling the AJTs while we work on F3’s internals. JSON documents are inherently weakly typed, with the only concrete data types being key-value pair arrays, indexed arrays, strings, numbers, and booleans - hence the term “Abstract” JSON Tree. Fusion 3 has stronger “concrete” types built on those foundations, such as object classes, events, properties, actions, conditions, expressions, and more. It would be a disaster if we got confused about what kind of F3 type was supposed to be at a particular node in the tree and overwrote it, corrupting it and potentially deleting work in the process.
In the old architecture, the concrete F3 types were typical concrete C++ classes that contained copies of all the data loaded from the JSONs. They would be linked together and have lots of interconnecting pointers, making them somewhat dangerous to work with and brittle. In the new architecture, the concrete F3 types are exposed via strongly typed views which are just proxies to the underlying AJTs, and the only data they hold themselves is information on where exactly they are in the AJT. Thanks to new C++23 features, we can write the code for a strongly typed view one time and get multiple different “versions” of it for different situations, e.g. a read-only version or a version that only tracks the AJT node identifier instead of holding a pointer to the node. In both the old and new design, the concrete F3 types provide simple class member functions for reading and mutating. This meant that converting the editor code from the old system to the new system was mostly straightforward and intuitive.
The aforementioned additional information - the line numbers, unique identifiers, and timestamps - come into play when we detect changes on disk, allowing us to merge them appropriately. This means you don’t necessarily have to save and close the editor when pulling changes from your collaborators. The JSONs can be reloaded, compared with what’s already in memory, and merged, and then any screens open in the editor can be notified to refresh content related to what was changed. The unique identifiers help the editor know what still exists as well as tracking moves. Currently, support for reloading changes from disk is very rudimentary, but we will improve it over time.
So, after solving a lot of internal problems along the way, we also solved the original problem too, as well as variations of it: if someone needs you to send the project now so they can work on frame A, but you’re part way through major changes in frame B, you can just save and send it. It doesn’t matter how broken things are in frame B, your collaborator will be able to load the project and get their work done in Frame A, and you’ll be able to merge it all when you’re both finished. You might even call it… a Fusion!