randomPoison

Continuous Delivery for the Discerning Game Developer

2021-01-06T00:00:00+00:00

Continuous Delivery is a set of software development practices for automating the process of taking a change submitted to source control and making it ready for production. This means fully automating the process of building the product, testing it, and preparing the build for release. At a high level I’d summarize the goal of CD as “Any commit to trunk can go into production”. Effectively what we want to end up with is this:

If you’re not used to working on a project that has a CD pipeline setup this can sound somewhat absurd, especially if you’re used to the process of preparing a build for production taking days or weeks to complete. There’s also a common perception in software development that software quality and stability come at a direct cost to development velocity, so the idea that investing heavily in things like test automation, which are generally perceived as efforts to increase quality and stability, can actually speed up development is unintuitive to many people. However, there’s a large body of empirical evidence demonstrating that practices like CD improve both software stability and development velocity, as well as having beneficial knock-on effects like reducing employee burnout.

I’m not going to be going further into the business case for CD here, but for anyone who’s interested in seeing more of the details then I highly recommend checking out the Accelerate State of DevOps reports. The State of DevOps Report is an ongoing research study into how different software development practices (with an emphasis on DevOps) impact software delivery and operational performance. The latest one is the 2019 report, and demonstrates a clear, causal link between practices like CD and SDO performance.

Broadly speaking, a CD pipeline will have the following steps:

I’m going to go through each of these stages and talk about what they require to be fully implemented, and what development practices can be used achieve success in those areas. I’m also going to touch on some additional topics that aren’t strictly a part of CD, but are part of the broader software development process and can be part of a positive feedback loop when combined with a robust CD pipeline.

Integrating Changes

Everything starts with a commit: Some change to the underlying source code or data that drives the product. In the CD pipeline, the first step after making the commit is to integrate that change into the mainline codebase for the project. This is a practice called “trunk based development”, where all work is done directly to your project’s trunk branch (or on a short-lived feature branch that’s merged into trunk regularly). This keeps the effort of merging changes into trunk minimal, and avoids cases where large merge conflicts cause delays.

For the most part this practice is standard these days; Even projects that don’t intentionally follow “trunk based development” as a practice use a workflow that is fairly similar. There’s also generally no automation that needs to be setup in order to enable it, since modern version control tools handle the workflow for you. But there’s a key piece of nuance here that I do want to highlight: Even large changes need to be implemented in a trunk-based manner, and (this is the important part) incomplete work should be regularly merged back into your trunk.

When working on relatively small or scope-constrained pieces of work there’s generally no issue following this practice. But things can be more complicated when working on something that’s larger in scope, such as adding a major feature or doing some kind of large-scale refactoring. Even for teams that generally follow trunk-based development, it can be tempting to do large chunks of work on a branch before merging the work into trunk. In order for a CD pipeline to work effectively, it’s important to avoid this and instead follow practices that allow even major changes to be broken down and merged into the mainline piecemeal.

In short: Merging unfinished work is good, actually! We as developers often have an aversion to merging in partially-completed work, especially if what we’re merging in is non-functional. However, the only real issue with merging incomplete work is if:

It disrupts development in some way, e.g. by causing build or test failures, or by exposing unfinished work to internal testers.
It disrupts the end user in some way, by being surfaced to users before the work was finished.

But with the right development practices, even very large pieces of work can be broken into small pieces and implemented in an iterative way without disrupting development or causing problems for users. Following this approach ensures that build and testing functionality provided by the CD pipeline can provide feedback early and often, and means we can avoid making large, disruptive changes.

There are a lot of approaches that can be taken when it comes to breaking up large changes, and the right one depends heavily on context, but I’ll go over a few now as examples:

Avoid exposing new functionality at all until it’s ready to be integrated in the game. For example, if a new feature is intended to be accessible through a button in a menu, don’t add that button until the feature has been fully implemented. Instead you can add a debug-only way of accessing the feature (e.g. an option in a debug menu or a debug-only keyboard shortcut). This allows the functionality to still be merged into the codebase before it’s done without risking exposing unfinished functionality to players.
Hide changes behind feature flags. If you can’t fully hide the new functionality, such as in cases where you’re making tweaks to an existing feature, build the system to make the new functionality toggle-able and use feature flags or configuration options to determine when to enable the feature.
Branch by Abstraction. For large refactoring work you’ll often be completely replacing an existing system with a completely new implementation. In this case, you need a way to continue to use the old implementation while the new one is in development. To do this, build out a layer of abstraction between the functionality that’s being refactored and the code that uses it that will allow you to swap out the underlying implementation. This will allow you to still test out the new implementation while leaving the old implementation in production until you’re ready to remove it. Once the new implementation is done, the old version and the abstraction layer can be removed.

Build and Deployment

The next step depends on what type of application you’re working with and what technologies its built with, but will generally some be kind of build or deployment step, possibly a combination of the two. For many projects, some build step is necessary in order to take the raw source code for the project and convert it into a format that can be run (though this may not be necessary if your application is written in an interpreted language like Python or JavaScript). Once the application has been built, there’s usually some kind of deployment step that’s needed in order to make the new build accessible. For server applications this will mean deploying the new build into a development environment. For client applications (i.e. ones that are run by the end user directly) there is likely some steps needed to distribute the build to the people who need it, whether that’s making it available internally to the development team or uploading it to your distribution platform of choice.

As with the integration step it’s pretty common these days for this step to already be automated, at least at a basic level. So what I want to focus on here are the nuances that are important for ensuring that your CD pipeline is working effectively:

The entire process needs to be automated (short of actually releasing the build)!
Run the entire process on every commit!

One of the driving philosophies of CD is “if something is painful, do it more often”. While it’s common to have a basic build process run on every commit, it’s also common to only run the full release build pipeline when preparing to actually do a release. As a result, issues in the release build process don’t get caught until the worst possible time: When you’re trying to get a release out. Similarly, it’s common to leave steps like uploading builds to release platforms as manual steps since they are performed infrequently, and the effort of automating them is seen as being more costly than continuing to do it by hand.

But if you fully automate the process and run the full process on every commit, all of the benefits of CD get applied to your release build process as well as your daily dev build process. If an issue comes up with your release builds, you find out as soon as the problem is introduced and can fix it well before it has the potential to cause a delay. This approach also allows you to do away with things like manual release branches, since every commit to trunk will produce a viable release candidate.

I expect that the biggest objection to this approach is that for many products the release pipeline is far too slow to run on every commit: Upwards of an hour, possibly taking several hours for large projects. This is a valid issue, but not an insurmountable one. In the most extreme cases running the entire release build pipeline can take so long that it would take the entire day, which would nullify the benefit of running on every commit. In these cases I recommend running release builds nightly, since that’s still much better than waiting until you’re actually doing a release to run the release build. For less extreme cases, say build times of an hour or so, an alternate approach is to run your builds in multiple stages. I talk about this approach more when talking about test automation.

Testing

Testing is probably the most critical part of the entire CD pipeline. Having a robust, automated test suite is the key that allows you to be confident that the product works as intended after any given change, allowing you to work quickly with confidence. However, it’s also often the hardest piece to implement effectively. Building out an effective test suite takes a substantial amount of engineering and QA effort over a long period of time, and when starting from scratch it can be hard to know where to start or to see the value that will come from that effort. I’m going to try to dig into some key pieces of the “how” and “why” of automated testing in order to make the prospect less intimidating.

Continuous Testing

The first piece that I want to emphasize is Continuous Testing. Traditional, manual testing approaches involve having a human perform tests periodically at various points in time: Engineers will perform ad hoc tests as they implement functionality, and QA testers will perform both ad hoc tests and more rigorous tests based on pre-made test plans. However, there’s a fundamental limit on how frequently and how thoroughly manual tests can be performed. As the scope of a product grows and more functionality is added, the amount of work needed to fully test every piece of functionality grows exponentially. For even relatively small applications it’s simply impossible for the full test suite to be run manually with any degree of frequency. As a result, manual tests tend to be limited to regular smoke tests, with more thorough regression tests being performed only when necessary.

Automated testing makes truly continuous testing possible, since it’s often possible to run the entire test suite after every change. This makes for a huge improvement over manual testing for a number of reasons:

Quicker feedback, since tests are run immediately after a commit without needing to wait for a QA tester to be available. It’s often easy to identify exactly which change introduced a test failure with automated testing.
Finer-grain testing can be run. Manual testing can only really test the game from the perspective of a player, which means they can only catch when things break in fairly obvious ways. Automated tests can target individual pieces of code directly in a way that simply can’t be done by manual testing.
More consistent results. Manual testing is always subject to human error, which means test results can be inconsistent.
Easier to check edge cases. One of the big advantages of automated tests is that they can cover the less common cases that are often missed by the more general smoke testing that manual testers do regularly. Uncommon cases are the most likely to break as a result of day-to-day changes, since they’re often not covered by the ad hoc testing done by engineers and designers. Automated tests can consistently verify such cases after every change.
Improved working conditions for manual QA testers! I’ll go into this in more detail in a little bit, but one of the biggest advantages of automated testing is how it frees up manual testers. Rather than constantly having to smoke test the game in order to catch regressions, or constantly having to deal with instability and breakage, testers can focus on things like exploratory testing and user experience testing, things that only a human tester can do effectively.

In order to setup continuous testing, there’s only really two conditions that need to be met:

You must run your suite of automated tests as part of your CD pipeline after every commit.
You must fail the pipeline and reject the build if any tests fail.

Even with a fairly small test suite, there’s immense value in running those tests in this way. Whatever pieces are covered by automated tests, no matter how small, will be tested thoroughly and consistently after every change.

Test-Driven Development

Of course, the larger and more thorough your test suite the more reliably it will catch bugs as they’re introduced. However, getting to that point can be difficult, especially if you’re looking to add test coverage to an existing project. To help build up test coverage, I recommend following an approach called “Test-Driven Development”. The basic idea is that for any given change you want to make to the project, you write a test for the new expected behavior before actually making the change. The test will fail when you first write it, but will pass once you’ve correctly implemented the change in question. There are a number of benefits to this approach:

It gradually builds up test coverage. The effort of building up a test suite is spread over the entire development process, rather than trying to sit down and build an entire test suite all at once.
It tests the tests. When writing a test to cover an existing piece of functionality, it can be hard to tell if the test is actually testing the right thing, and if the test doesn’t fail when the underlying functionality is broken the test isn’t providing any value. With test driven development, you write tests at a point where you know the underlying functionality isn’t working, so if the test doesn’t fail at that point then you know there’s something wrong with the test.
It encourages developers to account for edge cases from the beginning. The act of writing tests encourages you to think about what edge cases need to be covered and how the code should handle those cases. Putting in the time to write tests for those edge cases first means that it’s easier for developers to ensure that they’ve fully handled all those cases when they move on to implementation.

I especially like this approach for dealing with bug fixes. When working on a new feature, writing tests ahead of time can be difficult. For a large feature, the sheer number of potential tests to write can be overwhelming and it can be hard to figure out what tests would be the most valuable to write at the start. Plus, if the feature is still being prototyped you might not even know for sure what the expected functionality is, and trying to write tests at that phase of development can be both frustrating and disruptive to the prototyping process. But with bug fixes, you can be 100% confident that every test you write adds immediate value since it’s always covering a bug that we know has come up in practice. It also adds a lot of confidence to the fix, since we have a test that should pass to confirm that the fix worked.

Architecting Code for Testability

One critical thing to keep in mind is that code needs to be written in such a way that it is amenable to testing. In order to be testable, code needs to have the following properties:

Deterministic - The functionality needs to behave the same way given the same inputs and context every time.
Controllable - Any inputs taken by the code must be fully controllable by the test environment, such that the exact same conditions can be used to run the test every time. If the code depends on external systems in an uncontrollable way, then it introduces ways for the tests to fail inconsistently.
Independent - The code needs to be able to be run independently from other systems that it would otherwise interact with when running normally. Tests can be written to cover interactions between multiple systems (called “integration tests”), but even then you need to be able to limit the test to only the subsystems in question without needing to pull in other, unrelated systems.

These properties aren’t hard to achieve, but it’s also also easy to write code that doesn’t adhere to them if you’re not actively focused on making your code testable.

It’s also worth noting that some kinds of functionality will be easier to setup in this way than others. When it comes to games, code related to the game’s visuals and world state tend to be relatively hard to test, since the game world is an inherent piece of shared state, and is often both an input and an output for a given piece of code. Where possible, it’s helpful to separate “business logic” from “view logic”, such that you can test the underlying functionality separately from the logic for controlling the game’s visuals. Even for more complex game logic, the underlying functionality will have all of the above properties once it’s separated and can be tested on its own.

Testing Art and Data

At Synapse we build games that are highly data-driven, and changes to the game’s data can be a source of bugs as much as changes to the game’s code. As such, testing the game’s data and ensuring that everything is configured correctly is key to having thorough test coverage. Fortunately, testing data is relatively easy! Data can be loaded in isolation of most of the game systems, and it’s generally relatively simple to write tests for specific properties that the data needs to have. In the best case, you can reuse the game’s code to write tests that directly verify that the input data works as expected when used by the game. But even if your setup doesn’t allow for that, writing separate tests for the data is still fairly easy to do.

Games also have a much heavier emphasis on art assets than many other applications. Fortunately, art assets can be treated fairly similarly to data in terms of automated testing: While we can’t do much to test that the assets look right, there’s often specific requirements for how art assets are configured and added to the project, and those parts can be tested automatically. With engineers, artists, and designers all potentially making tweaks to the project at the same time, it can be especially beneficial to have tests covering art assets and game data, since more people touching a project introduces more places for bugs to be introduced.

Verify Changes Before Merging

One key point I haven’t talked about yet is when to run your automated test suite.

The ideal setup is to perform all tests before changes are merged into your project’s trunk. As I mentioned at the beginning, the goal of CD is that any commit to trunk can go into production. That invariant can’t be maintained if tests are only run after committing to trunk. Instead, the better approach is to make changes to a branch first. Tests are performed on the branch and the change is only merged once tests have passed. For programmers this often involves making a “pull request” or “merge request”, and is tied directly into the code review process such that changes require both manual approval and automated verification before being merged.

Things get trickier once you add artists and designers into the mix, since the standard pull request process used by engineers is cumbersome for changes that don’t need to go through the full code review process. An alternate approach that can be used here is to have artists and designers commit to a separate branch off of trunk. The test suite can be run after each commit, and changes can be merged to trunk automatically if the tests pass.

However, it’s not always going to be possible to run all tests when merging to trunk. Some tests may simply take too long to run to do so after every commit. Similarly, if your project takes a long time to build (as is often the case for games), any tests that need to be run after the build finishes will be slow to run as well. When faced with these cases, the first thing you should always do it try to speed up the tests. If the tests can be simplified in some way that allows them to still catch failures while running quickly, then doing that is your best bet. The more frequently tests are run, the more value they have, so maximizing the set of tests that can be run after every commit is your best bet for having an effective test suite.

But even still, there will always be some tests that simply take to long (or are too flaky) to run after every commit without being disruptive. For these there are two main options:

Run tests in multiple stages. After a commit, first run the quick tests and allow the change to be accepted if those pass. Once the initial tests pass, kick off a second stage for the slower tests. The second stage won’t necessarily run for every commit, rather it runs as fast as it can, starting again with the latest commit after the previous batch finishes. This may mean that multiple commits are bundled into a single test run, but this will still ensure that the tests are being run as quickly as they can be. This works well for tests that take several minutes to run, but are otherwise still reliable.
Run the tests nightly, or otherwise on an automatic schedule. This approach should generally be your last resort, since tests that are run on a schedule, rather than in response to a change to the project, need to be checked manually and can’t be used to automatically gate changes. However, running tests nightly can be useful in some cases:
- Tests that take a really long time, on the order of hours.
- Tests that can be flaky and may fail even when nothing is wrong. You should be cautious about including tests like this at all, since test failures can be easy to dismiss as random failures even if they’re catching actual bugs. But if you have such tests cases that are genuinely useful, then running them nightly is probably the best approach to avoid random test failures from causing disruption to normal development.
- Exploratory tests that are looking for new bugs. Some testing approaches, generally called “fuzz testing” or “gremlin testing”, attempt to interact with the product in semi-random ways in order to discover crashes and other bugs. These tests generally need a long time to run (hours or days) and can fail unpredictably, so it’s only practical to run them overnight and review any issues that they uncovered later.

This brings us to the question of how we respond to failures in the CD pipeline. If we’re setup to follow the ideal case of “tests are run before merging to trunk”, then generally the way to handle failure is pretty obvious: Whoever was making the change sees that their change was rejected, they fix whatever caused the tests to fail, then once tests pass again they’re good to merge. For these cases the impact of the test failure is minimal since it hasn’t been merged into trunk and so won’t disrupt development, and it’s clear who exactly needs to address the breakage.

However, for tests that are run as a second stage or after merging, we have the possibility of failure for changes that have already been merged to trunk. In these cases, it’s important make fixing trunk the top priority for the team. This doesn’t mean that every person on the team has to stop what they’re doing until the issue is fixed, but someone needs to immediately focus on fixing it, and anyone else who’s help is needed should prioritize helping. This is part of the reason why running tests before merging is so important: Failures that are caught before merging are far less disruptive than those caught after merging, so catching as many issues as possible as early as possible is key to keeping the development process smooth.

A Note on Manual QA

Earlier I talked about the advantages of automated testing and the advantages it has over manual testing for certain kinds of testing. But I really want to be clear that automated testing is NOT a substitute for manual testing. Rather, automated testing allows your manual testers to work far more effectively than they could otherwise.

On a project without automated testing, manual QA efforts are a constant uphill battle against breakage and regressions, and most of our testers’ time is spent just making sure the game still works. This is a problem for a few reasons:

It’s a huge time sink, since smoke testing and regression testing needs to be done nearly constantly as changes are made to the project.
Delays and disruptions are common, since bugs are constantly being introduced. This means that QA testers rarely have time to focus on other work like writing test plans.
Finalizing a release is difficult and stressful since bugs are often found last minute and there’s a lot of pressure on the QA team to approve a build on time, something which is often entirely out of their control.

Automated testing resolves these issues by handling the most rote, tedious forms of testing and establishing a baseline of stability. This removes a lot of the stress that comes from working on an unstable project, and frees testers up for the kinds of work that only manual testers can do:

User experience testing. QA testers can give feedback not just on whether or not something works, but how it’s experienced from a player’s perspective. This means they can identify if things are confusing from a player’s perspective, or things that otherwise don’t line up with how we want player’s to experience the game.
Exploratory testing. Automated testing can ensure that old bugs never come back, but it’s not really able to find new bugs. Manual testers know how to poke and prod at features in order to find ways to break them, and any bugs they uncover can get added to the automated regression testing suite in order to ensure that those bugs never come back.
Designing test cases. Manual QA can be included early in the design and implementation phases in order to ensure that edge cases and potential bugs are caught before they ever make it into the game. These efforts then translate directly into building out automated testing for any edge cases that QA identifies.

The end result of all this is a more stable game, a better final product, and a much, much happier QA team.

Conclusion

There’s far more information about Continuous Delivery than I can cover in this article, but I hope I’ve provided a reasonable high-level introduction to what a CD pipeline looks like and what work goes into building one. Continuous Delivery as a practice can provide an immense amount of value for a software development team, but it’s sadly under-utilized within the game development world due to some of the unique challenges that game development projects need to contend with. I hope that more game devs begin to utilize this practice to ship higher quality games more quickly than they could otherwise.

The State of the Unity Package Ecosystem

2020-07-14T00:00:00+00:00

I’m a Unity developer: Professionally I make mobile games with the Unity game engine. I’ve been working with Unity since 2014, and have seen the engine and the ecosystem around it change a lot over the years. I’m also an avid open source developer, and a big believer in the value of having a community-driven ecosystem around any core technology. Many times in my years working with Unity I’ve tried unsuccessfully to setup reusable, open source libraries for Unity in the way that I would for other ecosystems like JavaScript (via NPM) or Rust, failing inevitably due to some limitation in the tooling available for Unity. In the last year or so things have been changing a lot within the Unity ecosystem, and I’m finding that I’m finally able to do all of the things that I’m used to being able to do when setting up open source libraries.

What follows is my attempt to recount the history of package management in Unity, along with the ways that Unity and its ecosystem have been changing recently to make authoring packages easier.

The Bad Old Days

I started using Unity right at the tail end of the Unity 4 cycle, just before Unity 5 came out. At that time, Unity’s only tool for sharing assets between Unity projects was asset packages. Asset packages are glorified zip archives containing a set of game assets (including code files!) in a pre-defined directory tree. When you import an asset package Unity merges the package’s directory tree into your project’s root Assets folder, giving you an option to preview which files were going to be imported ahead of time.

This system works well enough as a way to do one-off asset imports, but as you might imagine it’s not a terribly good system for managing more complex dependencies, especially code dependencies. If a new version of the package is released and files or folders were moved in the new version the import process doesn’t handle removing the old versions of the assets, leaving you with duplicates. Ideally a package will keep all of its assets under a single top-level directory so that you only need to delete a single folder before importing the new version. In practice many packages fail to follow this convention. Some packages even store project-specific configuration files within the package’s folder, so if you try to delete the root package folder before upgrading you’ll loose configuration settings that you probably meant to keep. There’s also nothing preventing you from making modifications to code/assets pulled in from these packages, and in practice such modifications are common in Unity projects. This makes upgrading packages doubly difficult because you now have to manage merging your changes with incoming changes.

There were also limited means of distributing such packages. The main place for hosting them was the Unity Asset Store, which mainly existed for selling pre-made assets. You could distribute packages there for free, but the interface for accessing and downloading packages as a user was pretty rough. It was also not uncommon to find open source projects on GitHub that provided pre-built asset packages for import. However it was also just as common to find projects on GitHub that didn’t provide a pre-built package, where the recommended way of grabbing the code was to manually copy the contents into your project. For a long time the Unify Community Wiki was also a popular option for smaller code snippets, though you had to manually copy-paste the code into your project which… blech. I get the impression that it sees a lot less usage these days than it once did, though.

So while there was undoubtedly useful utilities out there, and loads of developers trying to do their best with the tools available, I wouldn’t say that Unity really had an ecosystem per se. The tooling available simply made it impossible to share common code dependencies in a way that would allow for large, reusable libraries to be built. Instead, everyone working on a Unity project had their own local copy of the same handful of common dependencies (usually with a couple of bespoke modifications).

Take, for example, JSON parsing. For a long time Unity didn’t have built-in support for JSON serialization, and even now the support it has is very limited and not usable for many games. So instead most projects using JSON in some form end up having to pull in a separate JSON serialization library. The most common solution for a long time was SimpleJSON, which was posted on the Unify wiki. Nowadays I see miniJSON used a lot (Unity even uses within their UDP package). The far more robust Json.NET was also made into a Unity package for the low, low price of $20 (the actual distribution of Json.NET has always been free). Of course, if you’re making a Unity package that itself needs JSON parsing support, you can’t assume that everyone using your package will already have a JSON library in their project (or which one they’ll be using even if they do already have one), so you need to provide your own copy of the JSON parsing library you’re using. I’ve worked on a project that had no fewer than 6 JSON parsing implementations in various places, several of them copies of SimpleJSON! The project I work on currently has 3 copies of miniJSON (pulled in via external packages) in addition to the 2 different JSON libraries we’re using for the game itself!

A New Hope

In the 2017.2 release Unity started adding a new package manager, which became available to users in the 2018.1 release. In its initial form there wasn’t official support for making custom packages (it was only being used to distribute Unity’s own packages). However at least one clever person was able to reverse engineer the package format, making it possible to start experimenting with the package manager early.

With the 2018.3 release, Unity added official support for custom packages, as well as experimental support for distributing packages via Git and custom NPM servers. At this point the functionality was still largely undocumented, but was working well enough to start using in actual projects. Synapse has at least one project on Unity 2018.4 that relies on this functionality and has found that it works well in practice.

Starting in 2019.1 Unity provided official documentation for setting up custom packages, and they’ve continued to flesh out the docs and improve on UPM’s functionality throughout the 2019 release cycle. The big thing that this has enabled is the ability to start breaking out reusable bits of functionality into local packages. For studios like Synapse that have made many games over the years, it’s useful to have common utilities that are reused between games. Historically we’ve been able to share these utilities between games using version control mechanism like SVN externals or Git submodules.

At this point, UPM provides enough functionality that building out an ecosystem of Unity packages is actually a viable prospect. Well, at least in theory. In practice there’s still one major hiccup that needs to be addressed:

Hosting Packages

At the time of writing Unity still doesn’t have an official way to host custom UPM packages. The officially-supported ways for pulling in package dependencies are:

The local file system, either by dropping the package directly into your project’s Packages folder or by manually specifying the path to the package on your local filesystem.
Via Git, by specifying the URL of Git repository. This makes posting a package up on GitHub a pretty common way of sharing Unity packages.
Via NPM (of all things). Unity’s docs specifically suggest hosting your own NPM package registry.

The last option is, in theory, the best option since it doesn’t force a dependency on Git (since not all projects are already using Git) and doesn’t require users to vendor local copies of the package. However, hosting your own package registry is a hurdle for most developers who just want to share some useful utility code. Some intrepid folks have actually started hosting their packages on NPM proper, which… is something, I guess.

Fortunately, it was only a matter of time before someone stepped in to provide a common package registry for Unity developers. Enter OpenUPM: An open source package registry with a built-in build pipeline for automatically deploying packages to the registry. Any UPM package hosted on GitHub can be added to the registry, and OpenUPM will build the package and host it for redistribution. It also provides a nifty command line tool for adding and updating packages, since the “scoped registry” system for adding external packages can be tedious to update by hand.

OpenUPM is… a bit of a weird project. As far as package registries go, it’s pretty odd to be able to publish other people’s packages. The built-in build pipeline is also somewhat unusual, since you usually publish packages to the registry directly rather than having the registry go out and find the package elsewhere. The need for a separate command line tool also goes against the grain for UPM, where the expected flow for adding/updating packages is to go through the package manager window in the editor.

However I can forgive OpenUPM’s quirks since it’s providing a very important service (and most of those quirks are working around problems that Unity caused in the first place). Being able to easily host Unity packages means that for the first time in Unity’s history it’s actually possible to start building out a more complete package ecosystem! Packages can be published and versioned properly, and packages can reliably depend on other packages without having to manually copy their contents.

Testing Open Source Projects

However, if you’re maintaining an open source project of any kind, having build and test automation is pretty critical in order to be able to ensure that the code you’re publishing actually works as intended. Historically this has been a major pain point for Unity projects.

For one thing, running the Unity editor from the command line has always been a struggle. For a long time the command line options were very poorly documented, and the editor would often fail to correctly report errors, leaving you with no feedback as to what failed or why. It was also especially difficult to run Unity in a headless environment, meaning things like Docker were often non-starters.

Worst of all is Unity’s license activation policy. In order to run Unity you need to activate a license. Anyone can activate a free license for personal use, but doing so is a manual process process, there’s no automated way of doing so. What’s worse is that license activations are pinned to the machine that you activated the license on, which means that VM-based build systems are basically unusable since each run requires a fresh license activation. If you have a professional Unity license you can activate that more easily from the command line. However professional licenses can only be activated on two machines at a time, which means even if you’re paying the big bucks for a license you can still have at most two concurrent builds! Even once running Unity from the command line became more viable, the need to activate a license has effectively killed every attempt I’ve ever made to setup automated testing for my open source projects (and I’ve tried many times over the last few years).

However, in the last couple of years two projects have popped up that have managed to solve this issue (for the most part). First, a user on GitLab has started providing pre-built Docker images with Unity installed. The project also includes instructions for how to activate a Unity personal license from within the Docker container. This effectively works around the need to activate a license per machine, because a given Docker image looks like the same machine to Unity no matter how many times you run it!

Using those Docker images, another person has been able to build out pre-made actions Unity for GitHub Actions (GitHub’s new CI service). The project provides actions for running tests and building for different platforms, and provides built-in support for activating personal licenses! This cuts the amount of manual work needed to setup test automation down to a minimum, and makes it actually viable to setup automation for open source project. For example, the kongregate-web package that I maintain is setup to test against two different versions of Unity, and verifies that the code works both in editor and when built for WebGL!

Generating Documentation

Another longstanding issue I’ve had in trying to maintain open source Unity packages is difficulty in generating API documentation. C# has built-in support for doc comments, however I previously hadn’t been able to find a tool that can generate a hostable website for browsing the doc. This makes it hard for users to see what functionality your package provides without digging through source code, which is less than ideal.

But recently I came across DocFX, which seems to now be the semi-official documentation generator for .NET, and I was able to get it working for a Unity package without much issue! DocFX knows how to parse C# source code, and it doesn’t seem to mind that the code isn’t setup with a proper .csproj file. Just write regular XML comments in your source code, point DocFX at it, and you’re good to go. It’s even pretty easy to automatically publish the generated docs to a GitHub Pages site using GitHub Actions! Unity seems to be using it to generate the documentation for all of their packages, too, which gives me some confidence that the tool has proven to work reasonably well with Unity projects.

The Not-So-Bright Side

As per usual, not everything is sunshine and roses in the Unity world. UPM is a massive step forward compared to what we had before, but there are still some unfortunate pain points to deal with:

The lack of an official package registry is really a massive oversight. Centralized package hosting is usually like half the point of having a package manger in the first place, and treating GitHub as the semi-official solution isn’t ideal for projects that aren’t already using Git. OpenUPM is a stopgap solution, but the way the scoped registry system is setup poses problems for packages that depend on other packages on OpenUPM. Specifically…
A package can’t itself declare scoped registries, so a project pulling in the package needs to also add the scoped registry declarations for the package’s entire dependency tree. This is gradually becoming more of an issue as people continue to publish more packages on OpenUPM that in turn depend on other packages. This is one of the things that make the custom OpenUPM command line tool necessary, since you have to potentially add scoped registry entries for the package’s entire dependency tree.
The package manager UI in the editor doesn’t seem to work well with general purpose registries like OpenUPM. The UI will show packages that are a part of the declared scope for the registry (i.e. where the package name starts with the specified prefix), but for OpenUPM there’s no common scope that all packages are a part of, so the UI doesn’t let you brown or add OpenUPM packages. I can imagine some valid reasons why UPM is setup to work this way, but it highlights the difficulties that come with not having an official package registry.
Dealing with conflicts between package versions in dependencies isn’t great. Your project can only pull in a single canonical version of a package, so if multiple packages depend on different versions of the same package UPM needs to pick a single version to use. Unity can sometimes resolve this automatically by grabbing the highest required version, but also sometimes it can’t and you get to deal with it yourself. Honestly I’m not too upset about this one, though; This restriction comes down to how .NET works than anything Unity-specific, and this is a problem that you run into with various package managers so it’s not like this is an entirely solved problem. Still, it’s a pain point that’s only going to increase as inter-dependencies between packages becomes more common.
While I highlighted earlier the ways in which running tests for a Unity project has gotten easier, there’s still more setup when testing a package than is really necessary: For each Unity version that you want to test against you need to have a separate test project setup to test against, including a separate manual license activation for each of those Unity versions. In most cases the package will be self-contained with everything it needs to run its test suite, so these are generally empty projects that exist just so that you can run Unity from the command line. It would be far easier to setup CI for new packages if you could just point Unity at a package and have it run the tests without needing a full project setup, and if you didn’t need to have a license activation when running package tests.

At least a couple of these can potentially be addressed by the community by building better tooling. However, some of these can only really be addressed by the improvements to Unity itself.

Closing Thoughts

Things are currently looking much brighter for the Unity ecosystem than they have in the past: With an actual package manager for Unity and an easy way to host those packages it’s much easier to create reusable code than it was previously, the recent improvements to CI setups make it much more viable to maintain an open source Unity package, and the ability to generate readable documentation for packages makes it easier to to use community-provided packages. While I don’t think all of the difficulties around building open source Unity packages are completely behind us, I have hope that it will continue to get easier as more tooling is built by the community.

Handling Variant Data: A Journey in Three-And-A-Half Parts

2020-03-27T00:00:00+00:00

This post is an overly-long (and unnecessarily self-indulgent) exploration of handling variant data in a number of different programming languages. While I’m not good at writing introductions that help ease readers into the topic at had, I’ll at least start with some extra context to help others figure out if this article is relevant to their interests:

This article specifically discusses C# and JavaScript, though I’ll try to extract conclusions that are applicable to a broader set of languages.
For discussing how to represent data in an interchange format, I’ll be focusing primarily on JSON.
:crab: Rust :crab: is also discussed for comparison purposes. I promise I’ll try to keep it brief.
Architecturally I’ll be focusing on working within a client/server application, however most of the points discussed should apply to non-networked applications.
I’ll be discussing the topic within the context of game development, but the concept is generally applicable for most application domains.

Admittedly the specifics in this article are tailored to be relevant to my current work at Synapse Games, but I’ll do my best to keep the discussion general.

Prologue

The point of this article is not to discuss what variant data is, rather to discuss how to handle variant data in software development. However, it’s going to be difficult to have that discussion without having a shared understand of what variant data is, so I suppose some introduction is in order.

At a high level, you have variant data whenever a given value can have multiple possible “types” or “shapes” and you need to be able to interpret the value differently based on the “type”. Generally this comes up when dealing with lists (or other collections) of heterogeneous data, where you can’t statically determine the type of each element in the collection.

As a practical example of this, we’ll look at awarding a player items for completing a quest in a hypothetical mobile game. In our example game, the player can earn a number of different types of rewards from completing a quest:

⭐ Stars (i.e. soft currency)
💎 Gems (i.e. hard currency)
🧙 New heroes
🛡️ Equipment items

Each of these different items is defined slightly differently:

⭐ Stars and 💎 Gems both only specify a quantity.
🧙 Heroes specify a unique ID for the hero that has been unlocked. No quantity is specified, since you can only unlock a given hero once!
🛡️ Equipment specifies a unique ID for the item, plus positive integer value for the item’s durability.

This setup isn’t a completely realistic example of how you’d want to setup this kind of game, however it presents the following challenges that make it a useful example:

There are three different “shapes” for reward items: Just a quantity (⭐ and 💎), just an ID (🧙), or an ID plus an integer (🛡️).
Two of the possible rewards look the same (⭐ and 💎), so we need to make sure we can differentiate between the two at runtime!
Two of the possible reward types share a common field (🧙 and 🛡️ both have an ID field), but do not otherwise have the same shape. In practice, that means that this field may need to be interpreted differently depending on the actual type of the reward (i.e. a hero ID is used to look up the stats for the hero, and the equipment ID is used to look up the stats for the equipment, and the two can’t be interchanged).

When a player completes a quest, the server for our hypothetical game needs to be able to do the following:

Load the list of rewards from a configuration file somewhere.
Build a runtime representation of the list of rewards such that it can update the players account with the awarded items.
Encode that list in JSON so that it can be sent to the client. This could be as simple as forwarding the same configuration data it originally loaded, or could involve re-serializing its own in-memory representation.

In turn, the client must be able to:

Decode the rewards JSON into an appropriate runtime representation that it can use.
Display the list of rewards to the player.

This leaves us with two main questions:

How do we best represent our rewards in our data format of choice so that we can save it to a configuration file and communicate between our client and server code?
How do we best represent our list of rewards at runtime in our language(s) of choice?

For the first question, we’ll look at how we can robustly represent this kind of data in JSON since it’s a very common data format and the principles we discuss will be broadly applicable for many other formats. For the latter, the answer depends heavily on what language you’re using and what features it provides to help with this kind of data. As such we’ll discuss two different options: We’ll look at JavaScript to see how variant data can be handled in a highly dynamic language, and C# to see how we can use a stronger type system to enforce correctness when working with variant data.

Part I: JSON

Before we dig into the nuances of how to represent this data in different programming languages, let’s look at how we can represent a list of rewards in a language-independent way by encoding it in JSON. Both our client and server code ultimately needs to understand this JSON format, so it should be informative to the subsequent discussions.

The dead simplest approach would be to make a list of objects, with each object containing the fields needed for each item:

[
  { "quantity": 100 },
  { "quantity": 5 },
  { "id": 123 },
  {
    "id": 111,
    "durability": 1000
  }
]

While this setup contains all of the necessary data for our rewards, we can quickly identify a couple of problems with this approach:

⭐ Stars and 💎 Gems are exactly the same in the JSON! That means our code is going to have a hard time distinguishing between the two, risking that we award 💎 when the player should have gotten ⭐ (or vice versa). You could get around this by using a different field names for the two (e.g. “quantity” for ⭐ Stars and “amount” for 💎 Gems), but that often leads to making the data (and the code relating to it) harder to understand.
In order to distinguish between a 🧙 Hero and an 🛡️ Equipment we need to check for the presence of the durability field. While this is simple to do now, it will quickly become tedious and error-prone if we end up adding more item types in the future.

The best way to disambiguate the rewards is to tag each reward with its type. For example:

[
  { "type": "stars", "quantity": 100 },
  { "type": "gems", "quantity": 5 }
]

Doing this means we only have to check a single field in order to reliably determine the type of each reward. For JSON specifically, there are at least three different ways we can tag our data:

Internal tagging, where the tag is done as a field within the object:
```
{
  "type": "stars",
  "quantity": 100
}
```
This format is the cleanest in terms of readability (as long as you can guarantee that the tag field will always be listed first), but has the drawback that the data itself cannot contain a field with the same name used for the tag field. It’s also worth noting that this approach won’t work if your data wasn’t already represented as an object, e.g. if the data is a string then there’s nowhere to add the tag field.
Adjacent tagging, where the tag and data are adjacent fields within a containing object:
```
{
  "tag": "stars",
  "data": {
    "quantity": 100
  }
}
```
This approach avoids the issue of conflicting field names and allows more flexibility in how you represent the data for each reward as compared to the internal tagging approach. For example, a ⭐ Stars reward could also be represented as:
```
{
  "tag": "stars",
  "data": 100,
}
```
Where data is a numeric value, rather than an object containing a numeric value. This depends somewhat on the capabilities of your programming language, though.
External tagging, where the tag is the key a container object:
```
{
  "stars": {
    "quantity": 100
  }
}
```
The main advantage of this approach is that it can enable more efficient deserialization logic as the deserialization code can always determine the expected “type” of the data before reading any of the data itself, however it is arguably the most awkward syntax from a human-readability perspective. It also has the same flexibility in representation for the reward data that the adjacent tagging approach does.

All of these approaches are valid and will solve the issue of ambiguity in your data. In practice which approach you choose will come down to two factors:

How important human-readability is for your purposes. It may be worth going with internal tagging if you expect to often be reading (or writing!) the JSON for your data.
What format is best supported by the serialization system used for your language. Different serialization libraries will have different conventions for how they manage this kind of data, and it’s often easiest to stick with the default conventions of the library you’re using.

Interlude: Goals and Criteria

Before we start looking at how to handle this data in our target programming languages, I want to lay out some criteria for what a “good” system for handling variant data looks like. As we’ll see, there’s many different ways of representing such data at runtime, so we’ll need some way of comparing them against each other.

Robustness - Is the deserialization logic able to reliably handle or reject unexpected data? While this depends on the specifics of your application, it’s generally best to catch invalid input data as early as possible.
Correctness - When working with variant data in code, does the system catch invalid usage of variant data (e.g. trying to get the durability field of a ⭐ Stars reward)? Does it ensure that you handle all the possible variants when? Does it make it easy to refactor existing code when you add/remove/change a variant?
Performance - How much overhead is needed to represent variant data? Variant data almost always has some additional costs as compared to non-variant data, but different approaches will have different performance characteristics.

My personal goal is to find a solution that best enforces correctness/robustness while minimizing performance overhead, and the examples I bring up throughout this post will generally trend in the direction of finding more tools to enforce correctness. Where possible I try to bring up opportunities to make different trade offs, or at least point out where further pursuing correctness would have diminishing returns.

It’s also worth noting up front that often times it’s possible to side step needing to handle variant data at all. Looking at our rewards example, we could in theory not put all of our rewards in a single list. Instead, we could make each reward type its own field or list, such that each item in the list is always of a known type:

{
  "stars": 100,
  "heroes": [
      { "id": 123 },
      { "id": 234 }
  ],
  "equipment": [
      { "id": 111, "durability": 70 },
      { "id": 707, "durability": 100 }
  ]
}

This completely sidesteps the need to differentiate between different types of reward, since each field only ever contains a reward of a single type!

This is absolutely a reasonable approach, and it may well be a better solution for your use case than dealing with variant data. An alternate solution we’ve used at Synapse is to use a generic system for defining items, such that all items are effectively the same “type”. However, sometimes this simply isn’t an option for what you’re trying to do, sometimes you specifically need to have different types of data/object in a single collection. As such, it’s still helpful to explore the available options for dealing with variant data, even if a non-variant solution is sometimes the better option.

Part II: JavaScript (and dynamic languages in general)

The nice thing about implementing this in JavaScript is that we can represent the data in memory identically to how we represent it in JSON. The bad thing about implementing this in JavaScript is that that’s the only nice thing.

Okay, let me try that again with less snark: For highly dynamic languages, we have both the gift and the curse of having no type system to worry about when dealing with variant data. This means that it’s very easy for us to jam heterogenous data into a collection and start working with it immediately, but unfortunately means that you often don’t have much support at the language-level for handling that data in a robust way. I’m going to be looking at JavaScript specifically because it’s widely used (and it’s the only dynamic language that I know fairly well), but a lot of these solutions will apply to other dynamic languages.

Since JSON is (deliberately) so similar to JS types, it’s very easy to translate one of the tagging solutions described above directly. By switching on the type field, we can iterate over a list of rewards and handle each reward based on its type. For example, using the internal tagging example from before:

let rewards = [
    { "type": "stars", "quantity": 100 },
    { "type": "gems", "quantity": 5 },
];

for (const reward of rewards) {
    switch (reward.type)
    {
        case "stars":
            console.log("Got some stars: ", reward.quantity);
            break;

        case "gems":
            console.log("Got some gems: ", reward.quantity);
            break;
    }
}

This solution is fairly straightforward and will work basically the same way for any of the tagging styles shown in the previous section. However, when we look at the criteria I laid out above it leaves a lot to be desired:

There’s nothing in the language to help you correctly handle all possible variants when switching on the variant tag. You have to remember to list them all, or your code will silently ignore some of your elements.
There’s nothing preventing you from accessing invalid fields on the variant (or fields from the wrong variant) even after you’ve checked the tag.
If you’re using JSON.parse(), there’s nothing to prevent your code from loading invalid or malformed data. This is generally true with JSON.parse() (you’ll need to use a separate JSON schema validator like ajv to validate the data), but working with variant data exacerbates the issues that come with silently consuming invalid data: Unless you have a default case in every switch block where you check the variant tag, your code will always silently ignore invalid or unknown variants. This can lead to especially subtle bugs that can be difficult to diagnose.

That being said, those limitations are pretty general limitations of JavaScript and aren’t specific to working with variant data: There’s nothing stopping you from accessing invalid fields on non-variant data, either, for example. This means that our nice-and-simple approach is also probably about as good as it gets. There are plenty of ways that you could build more infrastructure around this in order to enforce correctness, but doing so adds a lot of overhead in the form of runtime checking. Doing so also goes against most idiomatic usage patterns for JavaScript, since JavaScript APIs often lean into the flexibility the language provides in order to be as permissive as possible, rather than trying to proactively reject invalid data.

Ultimately, there’s not much you need to do when dealing with variant types in a dynamic language. Make sure you structure your data with an explicit tag and you’ll have everything you need to disambiguate objects of different types.

Part III: C#

In C#, the obvious way to represent variant data like this is with an enum:

public enum RewardType
{
	Stars,
	Gems,
	HeroUnlock,
	Equipment,
}

However, this leaves us with the question of how to handle the data for each variant. A simple solution is to create a single class that contains the data for all the variants, plus a field for the tag so that you can determine which fields are valid:

public class Reward
{
	public RewardType Type;

	public long Quantity;
	public HeroId Hero;
	public EquipmentId Equipment;
	public int Durability;
}

This approach wins out in simplicity, but has a number of drawbacks that make it less than ideal for actual use:

There’s nothing that requires you to check the Type field before accessing any of the fields of the reward.
There’s nothing preventing you from accessing the wrong fields for the current reward type.
There’s nothing obvious indicating which fields are valid for any given reward type. You’ll either need to have comments in the code (and then make sure you check those comments when working with Reward data) or document those details somewhere else (and then hope you can remember where those docs are).
Every reward uses as much memory as all reward types combined. This is a fairly minor point compared to the other two, but minimizing garbage allocation is often important for consistent performance in games, so it would be good to reduce the memory needed for Reward objects if possible.

The fact that this approach makes it easy to accidentally access invalid fields is problematic, as any field that’s not valid for the current reward type is effectively uninitialized, making it a potential source of bugs.

The better way to represent variant data, in my opinion, is to use an interface (or base class) and downcasting:

public interface IReward { }

public struct Stars : IReward
{
	public readonly long Quantity;
}

public struct Equipment : IReward
{
	public readonly EquipmentId Id;
    public readonly int Durability;
}

// And so on, with a different struct
// or class for each reward type.

When working with an IReward object, you can take advantage of the pattern matching feature added in C# 7.0 to handle the reward based on its concrete type:

switch (reward)
{
    case Stars stars:
        Console.WriteLine($"Awarded {stars.Quantity} stars");
        break;

    case Equipment equipment:
        Console.WriteLine(
            $"Awarded equipment with ID {equipment.Id} " +
            $"and durability {equipment.Durability}");
        break;

    // And so on...
}

This approach has a number of advantages over using a single, combined class for all of the reward types:

You can’t access any of the fields for any of the rewards variants without first checking the reward type (by downcasting to a concrete type). On the other hand, if there’s data that’s guaranteed to be shared by all reward types (e.g. if there’s always a quantity field so that more than one of a given item can be given at once), that can be added to the IReward interface so that it’s accessible without downcasting.
If you accidentally downcast an IReward object to the wrong type, you’ll either get null or an exception (depending on what type of casting you did) but you’ll never get an invalid object.
Any given reward type only needs to have the fields that are relevant to it, making the reward data much easier to work with when writing code.
Performance-wise there’s a bit of extra overhead that comes with downcasting, but it also saves a bit of heap space by reducing the size of each allocated reward object.

While I like this solution a lot, there are a few things about it that I’m not quite satisfied with:

The compiler won’t remind you to handle all possible variants. If you don’t have a case for all variants, your switch statement will silently do nothing. The switch expression added in C# 8.0 is a bit better in that it at least throws an exception if none of your cases are executed, but it has other restrictions that mean it can’t always be used (i.e. that it must return a value). And unfortunately, C# doesn’t emit warnings when you fail to handle possible cases even when working with regular enums.
This approach also doesn’t play well with deserialization conventions. Most serialization libraries for C# use reflection to handle loading data into instances of your classes, Json.NET being perhaps the most widely used example. When you’re deserializing into a List<IReward>, the serialization system can’t necessarily tell what concrete type should be instantiated for each element in the list. In general this means you’ll need to write some extra glue to tell it what the valid variants are and how to determine the type of each element. This article discusses how to handle this kind of data in Json.NET, for example.

That said, this approach is a pretty solid solution as far as C# goes. It should also apply nicely to most other languages that support classical inheritance. Even if your language of choice doesn’t have pattern matching, most languages have some kind of speculative downcasting that will allow you to do something similar.

Epilogue: Rust

If you’re curious about how we could further pursue correctness in handling variant data, we can take a look at how this would be handled in the Rust programming language. If you’re not familiar, Rust is a relatively new programming language that combines a very strong, expressive type system with the ability to write abstractions with very little performance overhead. This includes first-class support for the kind of variant types that we’ve been looking at!

First, a brief introduction to Rust’s enums. Like many languages, Rust supports creating user-defined enumeration types that can be one of several user-defined values. So for the following enum definition:

pub enum MyEnum {
    Foo,
    Bar,
}

You can create a value of MyEnum::Foo or MyEnum::Bar, any other value for a variable of type MyEnum is a compiler error:

// Correct way to use `MyEnum`.
let my_enum = MyEnum::Foo;

// ERROR: Not a valid variant.
let my_enum = MyEnum::NotReal;

// ERROR: Arbitrary integers aren't
// valid values.
let my_enum = 5;

// ERROR: Integers can't be cast to
// the enum type.
let my_enum = 5 as MyEnum;

Rust then has match blocks which behave similarly to switch blocks in other languages:

match my_enum {
    MyEnum::Foo => println!("my_enum was Foo"),
    MyEnum::Bar => println!("my_enum was Bar"),
}

However, unlike most languages, Rust’s enums can also contain data!

pub enum Reward {
    Stars { quantity: u32 },
    Gems { quantity: u32 },
    Hero { id: HeroId },
    Equipment {
        id: EquipmentId,
        durability: u32
    },
}

When working with a value of an enum, you can’t directly access any of the fields declared in the variants:

let reward = Reward::Stars { quantity: 20 };

// ERROR: No field `quantity` on type `Reward`.
let quantity = reward.quantity;

Instead, you need to match on the value and handle all of the possible variants. Only within the relevant match arm can you access the fields of any given variant:

match reward {
    Reward::Stars { quantity } =>
        println!("Awarding {} stars", quantity),

    Reward::Gems { quantity } =>
        println!("Awarding {} gems", quantity),

    Reward::Hero { id } =>
        println!("Unlocking hero {}", id),

    Reward::Equipment { id, durability } => {
        println!(
            "Awarding equipment {} with durability {}",
            id,
            durability,
        );
    }
}

This setup, in my opinion, is the ideal way of handling variant data at runtime. It makes it very easy to always correctly handle reward data:

You’re statically prevented from accessing the data in the reward until you’ve checked which type of reward it is, and you can only ever access the fields of the correct variant.
If you forget to handle any of the possible cases, you get a compiler error! This also means that if you later add a new reward type, the compiler will makes sure you go back and update all the places in the code base where you’re already checking the type of a reward.
It’s also very efficient: There’s no allocation involved in creating an instance of Reward, and the size of Reward is equal to the size of its largest variant plus the size of the discriminant (which will rarely need to be larger than a single byte).
Rust’s de facto serialization library Serde automatically validates incoming data and rejects any data that can’t be correctly represented at runtime. And because validation happens as part of deserialization, there’s little-to-no performance overhead in doing so!

While not many people are using Rust in production, most functional programming languages support something similar (referred to as “sum types”, “algebraic data types”, or “tagged unions”). If you’re using such a language, you’ll likely get similar results to what you’d get from using an enum in Rust!

Conclusion

Whew! That’s a lot of words on a pretty minor data pattern. While I covered a lot of details across a number of different languages, I think the main takeaways to keep in mind are:

Tag your variant data! Don’t do ad hoc variant detection by checking for the presence of different fields, as that can still fail if you have ambiguous variants.
Take advantage of language features to make your variant data safer to work with. If you have a type system, don’t just jam all of your variants into a single type that has a bunch of uninitialized fields. If you’re working with a more dynamic language, make sure to still use a tag at runtime!

Once you start getting into the specifics of a single application, there’s a lot more nuance you can get into in terms of how to best represent your data and when it’s best to use variant data vs a different approach. But all of that discussion is out of the scope of this article, so I’ll leave it at that!

Sharing C# Code with Unity

2019-11-20T00:00:00+00:00

I’ve been doing some investigation into building client/server game architectures with Unity on the front end and a C# server on the back end, specifically pairing an ASP.NET server in a traditional .NET environment with a Unity front-end. For games with no realtime gameplay and a desire for high scalability, as is often the case with online mobile games (my industry, for better or worse), it makes sense to build your server with something other than Unity. Traditional .NET development is attractive in this case because it allows you to use the same programming language, C#, to build both your client and server.

In particular, one of the major advantages of using the same programming language for both client and server would be the ability to share common game logic between the two. Doing so has major advantages over having the two codebases be completely isolated:

Shared definitions for data objects and serialization logic greatly simplifies communication between client and server, reducing errors while making it easier to evolve your API contract.
Sharing common game logic means that you can do client-side prediction and keep your game experience smooth in the face of a slow network connection. This is useful even for non-realtime games!
Generally reduced development time, since logic written for the server can be reused in the client (and vice versa).

You can have a look at the DotNetGamePrototype repository to see the example project I’ve been building as part of this investigation.

I have broken this post up into two parts: A direct description of the technical issues that come with sharing code, along with potential ways to deal with these issues, and then a more subjective evaluation of how this impacts any projects that want to take this approach. If you care primarily about my final conclusions, skip to the second part below.

Part One: Technical Issues

At the most basic level, most C# code will be source-compatible between a Unity project and a standalone .NET C# project. That is, if you copy-and-paste the source code from one to the other, it will almost certainly compile and run as expected. There are a few caveats to this, though:

Any code outside of the .NET Standard must be present in both environments, i.e. if you reference class Foo, Foo must be defined in both projects.
Not all of the .NET Standard is available to Unity. At the time of writing, Unity supports .NET Standard 2.0 but not 2.1, with no ETA on when support will arrive.
For certain platforms, Unity uses a special C# scripting backend called IL2CPP. This backend has additional restrictions on what you can do, and only supports a subset of the .NET Standard. If building for platforms that require IL2CPP (such as iOS and most consoles), any shared code must limit itself to the supported subset of functionality.

Meeting these requirements only enables a bare minimum of source compatibility, though. Once you have some C# code that you want to share between projects, you’ll need some method of making that code available in both contexts. There are two main ways to share code between the projects:

Define the shared code as both a UPM package and a standalone C# project (i.e. add a package.json and a .csproj file to the directory) and then add the shared code as a direct dependency for both projects.
Only define the shared code as a standalone C# project. Add it as a direct dependency to the server project, and add the built DLLs to Unity.

The easiest way to share code is to set it up with the necessary configuration for both a standalone .NET project (i.e. a .csproj file) and a Unity package (i.e. a package.json file and an Assembly Definition file). If you keep your client and server in the same repository, you can reference the shared project from both via relative paths. This was how I did it in the example Unity client and example server project, and it took minimal effort to setup.

It’s worth noting that setting up your code as a UPM package isn’t strictly necessary. For example, you could directly embed your shared code directly in your Unity project and then reference it from your server code. The key part of this approach is that it shares the source files directly, rather than pre-building a DLL to import into Unity.

The advantage of this approach over most others is simplicity: It requires no extra tooling, no build steps to copy build results or publish packages. You can modify the shared code from both your server project and your Unity project and the changes will immediately show up in both. If keeping your client and server in the same repository is a viable solution for you, then this is probably the easiest approach.

The drawback of this approach is that you end up polluting your shared code project with Unity-specific details. In addition to the package.json and assembly definition file, Unity requires that there be a .meta for every file in the package. Unity generates these meta files for you, but that will require you to open Unity every time you add a new file in order to ensure the meta file is generated correctly. These meta files also clutter the files list in your editor (though, with some extra configuration, you can usually configure it to ignore them).

This drawback is relatively minor, and more one of project cleanliness more than a technical issue. Still, it highlights the fact that this solution is a hack, rather than a well-supported use case for Unity.

Exporting a DLL

If you want to avoid polluting your shared codebase with Unity-specific configuration and files, you can instead build your shared library as a DLL and import that DLL into your Unity project. So long as you are meeting the constraints listed above, the DLL generated from your project can be loaded into a Unity project without issue, including ones that target IL2CPP platforms.

Exporting your project as a DLL to Unity is fairly simple:

dotnet publish -c Release -o ../UnityProject/Assets/Plugins

You’ll have to remember to do this any time you update the shared project, or else setup some kind of automation to do so automatically. Such a solution is theoretically possible (at least, I see no technical blockers), but none exists already as far as I can see.

While this approach involves more built-time work, it has the advantage of enabling you to easily pull NuGet dependencies into your Unity project. You can add a <CopyLocalLockFileAssemblies> element in your .csproj, making the DLLs for all dependencies immediately available alongside the DLL for your project:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="SomePackage" Version="1.2.3" />
  </ItemGroup>
</Project>

When you run dotnet publish, it will also copy any NuGet packages that you’re using in your shared project into the Unity project. Unfortunately, using NuGet packages within Unity has its own problems which we’ll discuss below.

Incompatible Dependency Management

The above approaches work well when your shared code only depends on the .NET Standard, but things quickly begin to break down when you introduce additional dependencies. This could mean adding a Nuget package as a dependency, adding a dependency on a UPM package, or even just adding another internal shared package that is also referenced by the first shared package.

The key issue is that Unity uses a different dependency management system than the rest of the C# ecosystem. While the .NET ecosystem at large uses NuGet, Unity has historically had no proper package management system, opting to manually copy source code (or sometimes pre-built DLLs) directly into each project. Starting with the 2018.3 release Unity has introduced their own Unity Package Manager as a more robust solution for dependency management.

While UPM is a massive improvement over the previous (non-)solution, it doesn’t support loading NuGet packages, making interop between the two ecosystems difficult. Unless you’re willing to forego using any code outside of the .NET Standard, you’ll want to be able to add dependencies to your shared package via NuGet. Once you do, though, you’ll have a hard time getting your code to still work in Unity.

If you’re taking the shared package approach described above, Unity won’t pull down your NuGet dependencies and your code won’t compile. There are a couple of community-made tools for pulling down NuGet packages (such as UnityNuGet and NuGetForUnity), but it is unclear if any solution is robust enough to be a reliable solution for projects looking to pull in NuGet packages.

On the other hand, the approach described above for automatically copying NuGet dependencies into the Unity project seems to work well if you have a single locally-maintained C# package, but it doesn’t scale up to a more complex project setup. For example, if you were two have two different projects both depending on SomePackage, each one would pull a copy of SomePackage.dll into your Unity project and your project will fail to build due to the duplicate DLLs. There are ways to work around this if there are only a few conflicts, but it’s not clear if any such solution would scale well with a large tree of dependencies.

Incompatible Software Ecosystems

Even if you find some solution for sharing NuGet packages with Unity, there are deeper incompatibilities to contend with. As noted previously, Unity only supports a subset of valid C#/.NET code on all platforms. At the most basic, you’ll only be able to use NuGet packages that support .NET Standard 2.0, which not all packages do. Fortunately, it should be possible to avoid including such packages in the first place by specifying netstandard2.0 as the target framework in your shared package’s .csproj.

Things get more tricky when dealing with the restrictions imposed by IL2CPP and the other platform-specific restrictions that Unity projects need to deal with. According to Unity’s documentation, there are a number of things things that are perfectly valid in regular .NET development that will fail in Unity projects built with IL2CPP:

The contents of System.Reflection.Emit are explicitly not supported on platforms that do not support just-in-time compilation. iOS is the prime example of this, though as I understand it some consoles also have this restriction.
The compiler will aggressively remove any code that is never referenced (i.e. a class that is never instantiated). This interacts badly with reflection-based serialization, where a given class may only ever be instantiated via reflection. In this case you can manually tell the compiler to not strip a class, but that can be difficult to do if the missing class is hidden in the internals of a pre-compiled DLL.
Generic virtual methods also interact badly with ahead-of-time compilation. There are hacky workarounds for dealing with this when you know all of the concrete instantiations, but this can again be difficult when the specifics are hidden in a pre-compiled DLL that you’re pulling in from a dependency.

Additionally, there are platform-specific restrictions unique to the set of platforms supported by Unity that don’t get taken into account by most (or any) packages published to NuGet. Especially, when publishing to the web you’ll run into various restrictions that no other .NET environment has to deal with:

Not all platforms support threads, so any code that relies on threads will fail at runtime.
System resources don’t behave the same on all platforms. On the web, browser sandboxing means that very few system resources are accessible at all. In some cases Unity can fake these for you (as is the case with how Unity fakes the existence of a file system), in other cases those APIs will simply fail at runtime. On mobile and console platforms, you have only limited access to the file system, so a library that attempts to create files in the background (e.g. as a data cache) may fail unexpectedly.

In my limited experimentation, I have already run into a couple of cases where these limitations come up: The Json.NET library and WebSocket handling.

Json.NET is by far the most widely used NuGet package, and is the de facto standard for JSON serialization in C# and the .NET ecosystem. It also doesn’t work with Unity. There are multiple ports out there in various states of abandonment or disrepair, but none of them are available via NuGet so they can’t be shared with a non-Unity C# library. In order to use Json.NET in your shared code, you have to setup a system where it is pulled in via NuGet when used in your server code, and then pulled in by a different method in your Unity project. This is doable, but if you use the setup described above to pull NuGet dependencies into your Unity project automatically you’re going to run into conflicts fast. This could be possibly be fixed if the upstream library were setup to better support Unity, but there’s been no indication that the maintainer is interested in taking on that work. This solution also only works because Json.NET is popular enough to have community-maintained forks that work with Unity, you likely won’t have the same luck with smaller libraries.

In the case of WebSockets, it’s actually impossible to provide a NuGet package that supports Unity on all platforms. When running in a browser, you can’t open a socket directly. Instead, you have to use the browser’s WebSocket API, creating C# bindings to the JavaScript API. And, of course, this setup only works in the browser so you’ll need to abstract over both the browser API and a native implementation for other platforms. You’ll find plenty of WebSocket implementations on NuGet, but none that can be shared meaningfully between Unity and a .NET project. It’s also worth highlighting that this issue isn’t specific to WebSockets; Many system resources have similar caveats that will make NuGet packages incompatible with Unity. Generally you’ll deal with this in the Unity project by abstracting over two or more platform-specific implementations, but this in turn presents complications for dependency management, in that you may only need a given dependency on certain platforms.

Part Two: Assessment

Overall, my assessment of the situation is that code sharing between Unity and .NET works just well enough to be tempting to use, while being broken enough to present major obstacles to large scale development.

The fundamental issue is that, while the two are similar on the surface, Unity is not a true .NET environment. On some platforms Unity uses Mono to run your code, which at least means that your code will behave like regular C# at runtime, but IL2CPP is introduces huge problems for compatibility. Combine that with the fact that Unity has a completely bespoke solution for dealing with dependency management and has to handle certain platform-specific issues that other .NET runtimes don’t (most notably ahead-of-time compilation and running in web browsers), and the picture we end up with is one where Unity is not just another .NET runtime, but its own separate thing that happens to be largely (but not completely!) source-compatible with .NET.

Source compatibility is the notable thing here: Being able to copy a piece of code between a Unity project and a .NET project sure feels like compatibility, so it’s awfully tempting to say that code sharing is possible. And, as noted above, it is possible (easy, even!) at a small scale. What worries me is that nothing about this setup seems scalable.

It’s easy enough to start writing some shared code and use one of the basic methods described above to integrate it into both projects. You can even get pretty far while using some small, simple packages off of NuGet. But eventually you’ll get to a point where you want to use Json.NET or WebSockets or some other thing that needs a fundamentally different solution between .NET and Unity and you’ll hit a wall. You’ll have some piece of core functionality that should be shared between your client and server yet can’t be. And at that point you’ll be close to your ship date and too heavily invested in your current architecture to make major changes, so you’ll hack around the problem and do what you can to get things working.

In some ways, this is a worse situation than being outright incompatible, because it provides the opportunity to start doing something now that is all-but-guaranteed to fail somewhere down the line. It feels like something that should just work; I’m writing the same code in my client and server projects, it seems silly to not be able to share code between the two. But on digging deeper into the situation, it becomes clear that the two have very different code environments: Different compilation processes, different runtime environment, different idiomatic solutions to common problems. The shared language gives the veneer of commonality, where in reality there is an ocean of difference.

It’s worth noting, though, that this assessment is more a gut feeling than a complete analysis. In practice there are no hard blockers to sharing code, just a hundred little things that make it difficult. My experience as a software developer tells me that won’t work out, that you’ll spend more hacking around the problems than is worth it for the convenience of sharing code, that you’ll not be able to use helpful libraries in your server code because they’re not compatible with Unity. But, the only way to really know how bad things are would be to build out a real, large-scale, production-ready project and see what problems you run into.

That all being said, there are potentially ways in which better automation and tooling could improve the situation, maybe even enough to make the effort worthwhile:

Build out better support for resolving NuGet dependencies in a Unity project. It’s already possible to export a packages dependencies as a JSON file and include it in Unity, so a plugin that can fully resolve dependency trees, detect conflict, and import the dependencies into Unity would make interop much smoother. Ideally this would be built directly into UPM, but if it’s not something Unity is willing to do, then it may be possible to make this work as a custom package.
Automatically detect incompatibilities with Unity. You can use reflection and disassembly to inspect the contents of a .NET DLL. In theory, you could automate the process of detecting if the library uses any language features that don’t work with IL2CPP. I have no idea if this is actually possible to do in a robust way, but it would make a huge difference to be able to detect these issues ahead of time.

I’m certainly not the only person interested in making this work, so hopefully someone with more time (and more expertise with the wider .NET world) can make some progress here. Until then, I’ll be investigating other avenues for client/server code sharing and see if I can’t come up with a more satisfying solution.

Using async/await in Unity

2019-10-07T00:00:00+00:00

I’ve been investigating the usage of C#’s async/await functionality in Unity projects, and in doing so I’ve done a number of experiments to determine the nuances of how it works in specific cases¹. This post attempts to list out and demonstrate these details so that others can better determine if using async/await makes sense for their Unity project.

All of these tests were done with Unity 2019.2.4f1. I can’t guarantee that everything will behave the same on other versions of Unity, and the async/await support was known to be buggy in the 2017/2018 release cycles. You can view the various test scripts I wrote on GitHub.

A major caveat here: Some of the details highlighted are general details about task-based async code in C#, but some details are specific to how UniTask implements task support for Unity. If you choose to use a different implementation of tasks (or not use a custom task implementation at all), some of these details may be wrong.

No Minimum Delay

One nice advantage of await is that it doesn’t impose a 1 frame minimum delay the way that yield return does. This is something that I’ve run into when caching assets in-memory. For example:

public IEnumerator LoadPrefab(Action<GameObject> callback)
{
    if (!assetIsLoaded)
    {
        yield return LoadPrefabIntoCache();
    }
    
    var prefab = GetPrefabFromCache();
    callback(prefab);
}

// Some code that wants to use the coroutine;
GameObject prefab = null;
yield return LoadPrefab(result => { prefab = result; });

The first time coroutine runs you’ll have to wait for the prefab to be loaded, however on subsequent calls it would be ideal if the code calling LoadPrefab() would resume on the same frame. Unfortunately, if you yield return on a coroutine, the calling code cannot resume until the next frame at the earliest, even if the invoked coroutine completes synchronously. If you need to avoid the 1 frame delay, you have to manually check if the work would complete synchronously:

GameObject prefab = null;
if (IsPrefabCached)
{
    prefab = GetPrefabFromCache();
}
else
{
    yield return LoadPrefab(result => { prefab = result; });
}

Fortunately, await doesn’t have this restriction; If you await a task that completes synchronously, the calling task will also resume synchronously. It’s worth noting, though, that if you await a task that doesn’t complete synchronously, your task won’t resume until the next frame even if the child task completes within the same frame².

Execution Order Stays The Same

When starting a coroutine, the body of the coroutine will synchronously execute up to the first yield statement:

public IEnumerator MyCoroutine()
{
    Debug.Log("Beginning of MyCoroutine()");
    yield return null;
    Debug.Log("End of MyCoroutine()");
}

// The following test:
Debug.Log("Before coroutine");
StartCoroutine(MyCoroutine());
Debug.Log("After coroutine");

// Will print the following:
//
// Before coroutine
// Beginning of MyCoroutine()
// After coroutine
// End of MyCoroutine()

Tasks work the same way, synchronously executing up to the first await before returning to the calling code:

private async void VoidTask()
{
    Debug.Log("Doing a void task!");
    await UniTask.Delay(1000);
    Debug.Log("Void task resumed!");
}

// The following test:
Debug.Log("About to call VoidTask()");
VoidTask();
Debug.Log("Returned from VoidTask()");

// Will print the following:
//
// About to call VoidTask()
// Doing a void task!
// Returned from VoidTask()
// Void task resumed!

Starting and Stopping Tasks

There are two major differences between coroutines and tasks that you’ll need to be aware of:

Tasks start automatically as soon as you call an async function, there’s no StartCoroutine() equivalent for tasks.
Tasks are not tied to a GameObject the way that coroutines are, and will continue to run even if the the object that spawned them is destroyed.

For starting tasks, this change is convenient and removes some of the confusion that made coroutines difficult to work with (e.g. I’ve seen many people not call StartCoroutine() and then be confused why their coroutine wasn’t running).

By default, a task will end automatically once it runs to completion. However, if you want to be able to cancel a task before it completes you’ll need to use a CancellationToken:

cancellation = new CancellationTokenSource();
try
{
    await UniTask.Delay(500, cancellationToken: cancellation.Token);
}
finally
{
    cancellation.Dispose();
    cancellation = null;
}

// Somewhere else, in reaction to an event that
// should cancel the pending task:
cancellation.Cancel();

This approach requires a bit more setup than is needed with coroutines (mainly to handle disposing of the CancellationTokenSource when done), but makes the default behavior more intuitive and gives you better control over when your tasks run.

Cancel Task When Game Object is Destroyed

For example, imagine a scenario where you want to load a sprite from an asset bundle and assign it to a sprite renderer on a game object. If the game object is destroyed while waiting for the asset to load, the subsequent attempt to update the sprite renderer will throw an exception:

var sprite = await assetBundle.LoadAssetAsync<Sprite>();

// This will throw an exception of the game object was
// destroyed while waiting for the sprite to load.
spriteRenderer.sprite = sprite;

To cancel the task in the case that the game object is destroyed, you can use a CancellationTokenSource and the RegisterRaiseCancelOnDestroy() extension method:

var cancellation = new CancellationTokenSource();
cancellation.RegisterRaiseCancelOnDestroy(this);

// This await will never resume if the game object
// is destroyed.
var sprite = await assetBundle
    .LoadAssetAsync<Sprite>()
    .ConfigureAwait(cancellationToken: cancellation.Token);
spriteRenderer.sprite = sprite;

Perform Cleanup When Task is Cancelled

One of the problems with coroutines is that there’s no way to detect if a coroutine has been cancelled, making it effectively impossible to perform cleanup or consistently maintain invariants in the face of arbitrary coroutine cancellation. Fortunately, with async/await you can use try blocks to perform any final cleanup logic the same way you would anywhere else:

try
{
    await SomeAsyncOperation();
}
finally
{
    // This logic will be run, even if the task
    // is cancelled.
}

This works with task cancellation as well, since cancellation is done by throwing an OperationCancelledException. This also means that it’s possible to run logic only in the case that the task was cancelled while letting exceptions propagate as normal:

try
{
    await SomeAsyncOperation();
}
catch (OperationCancelledException)
{
    // This logic only runs if the task was
    // cancelled. Be sure to re-throw the
    // exception so that any parent tasks are
    // cancelled as well.
    throw;
}

Exceptions and Callstacks

With coroutines, each one behaves as its own top-level “stack”, meaning that callstacks from within a coroutine don’t show where the coroutine was spawned from. This also applies to exceptions, which don’t unwind through a hierarchy of coroutines, making exceptions thrown in coroutines non-intuitive. This makes debugging errors in coroutines often very difficult, as you lose all context for logging and exceptions from within a coroutine. Tasks, on the other hand, are a first-class part of the language and so handle these cases much better.

Exceptions behave the same as with synchronous code, unwinding the stack through tasks and providing a trace of the path it followed. For example:

private async Task ThrowRecursive(int depth)
{
    if (depth == 0)
    {
        throw new Exception("Exception thrown from deep in the call stack");
    }
    else
    {
        await ThrowRecursive(depth - 1);
    }
}

Calling this as await ThrowRecursive(3) shows the following in the console:

You can see the full stack of calls, from the top-level function that called ThrowRecursive() down through the multiple await statements. This also applies to any call stacks generated, including the ones included in debug logging. This makes debugging with async/await far easier than with coroutines.

Compatibility with Coroutines

UniTask provides functionality for awaiting a coroutine within tasks and for yielding on tasks within coroutines. Using await with an IEnumerator an AsyncOperation or a YieldInstruction will work without issue. If you want to include a cancellation token or otherwise configure how the task will wait for the coroutine, you can use the ConfigureAwait() helper method:

await Resources.Load("MyAsset").ConfigureAwait(cancellationToken: token);

To yield return a Task or UniTask you must use the ToCoroutine() extension method:

yield return MyTask().ToCoroutine();

Debugging

When debugging with Visual Studio, you can step over await statements in the debugger and it will step to the next line!³ This is because tasks are a first-class part of the language, so the debugger is able to track them directly and better determine when to break in the debugger. Coroutines, on the other hand, aren’t really a part of the language and are a hacky misuse of C# iterators, and so the debugger can’t “see through” them the way it can with tasks.

Years of experience with coroutines and their nuances have made me very wary of all the ways that Unity can surprise you when it comes to async code. ↩
In theory, it would be possible to resume a task within the same frame by having it resume at a later part of the update loop, e.g. await during the main update and then resume during LateUpdate. However, this is probably not currently supported by UniTask and would probably not be something that is generally useful. ↩
There’s currently a bug with the Unity editor and UniTask that is causing the editor to crash when stepping over await in an async UniTask function. This shouldn’t be an issue if you’re using async Task, though. ↩

The Brilliance of SpatialOS’s Modular Inspector

2019-03-29T00:00:00+00:00

Improbable, the developers of SpatialOS, recently released an alpha preview of their new Modular Inspector, and boy is this thing :fire: HOT :fire:. When I first saw the demo videos, I was blown away by the sheer ingenuity of the design. In particular, I’m impressed by how well the new inspector is designed to give the user the power to wrangle complex worlds and see exactly what information they care about.

Since I’m part of the ongoing process to put together an editor for Amethyst, I want to go into some deeper detail about why this new inspector is so brilliant. ECS is starting to become a more widely-recognized paradigm in the gamedev community, but I think there’s a lot of confusion around how you make ECS as comprehensible and easy to use as the existing Object Oriented paradigms. I think the SpatialOS Modular Inspector is the first graphical tool to really demonstrate how this is possible.

Queries, Not Hierarchies

The biggest thing that the Modular Inspector does is replace the traditional hierarchy view that’s common in game editors with a tool for building dynamic queries over the contents of your world.

In most editors that come with game engines, the default scene view is a nested hierarchy based on parent/child relationships between objects. For example, this is the Hierarchy view in the PlayCanvas editor:

This is also the provided scene view in Unity (in the Hierarchy view) and Unreal (in the World Outliner). While this view is often comfortable and familiar for game developers, it maps poorly to ECS, where the vast majority of your game logic is oriented around flat lists of entities, grouped by which components they have. As such, the Query Editor in the SpatialOS inspector is a brilliant paradigm shift because it means that the graphical inspector for you game operates on the same logic that your systems (or workers, in the case of SpatialOS) do: It queries the world with a set of constraints (usually the presence or absence of certain component types) and gets back a flat list of all entities matching the specified criteria.

Modular, Composable Tools

The Query Editor itself doesn’t actually show the results of the query, though. Instead, the query’s output is piped into one or more other modules that are used to visualize the entity data. This highlights the next big thing that the SpatialOS inspector does well: It builds upon a modular set of tools that can be composed by piping the output of one module into another.

This is brilliant for two reasons:

It’s a truly modular approach to constructing your UI. Each module takes specific inputs to configure it, but doesn’t specify where those configuration values need to come from. As such, you can manually set values yourself, use the output from another module, use values set on components/workers, or any other source of data that the inspector supports. While the SpatialOS inspector isn’t itself extensible, one can easily imagine this same model working well with custom extensions and plugins, where user-defined plugins can easily communicate through data inputs and outputs.
It puts the emphasis on data and how it flows through the components of your UI. Data flow is a big part of the ECS paradigm, and modeling our UI tools around data flows means that they fit more naturally with our intuition of how our games work.

The SpatialOS team clearly took inspiration from visual scripting tools here, where this model of nodes connected by data inputs and outputs is common. However, this is the first time I’ve seen the paradigm applied to constructing custom UI configurations, and I’m impressed at how well the paradigm works in the context of making a customizable UI.

Different Visualizations for Different Situations

The Modular Inspector also provides different customizable ways of visualizing component data on the entities in your query. The Viewport provides a 2D visualization of the positions and movement of entities in a specified area, and the Entity Table provides a direct look at specific fields of the components attached to those entities. Both of these modules can be customized: You can tweak the colors and icons used for different entity types in the Viewport, and you can select which components and fields are displayed in the Entity Table. Combined with the fact that you can have multiples of each, all driven by different queries, these tools provide you tons of control over how you visualize the data in your world.

It Looks Really Good

I mean damn, just look at it :eyes:

Applying This to Other Engines/Editors

It’s worth noting that the tools that Improbable has put together are clearly focused on one thing: Debugging ECS worlds. These tools have little use when it comes to authoring content for your game, but are incredibly useful when it comes time to verify that your world simulation is doing what you expect. As such, I think there’s a lot we can learn from these tools in order to build better debugging tools for Amethyst and other ECS-based game engines.

Chaining Functions Without Returning Self

2019-03-21T00:00:00+00:00

It’s a common pattern in the Rust ecosystem to have a function return self at the end in order to enable method chaining. For example:

// Create, modify, and consume a `Foo` in a single expression.
// So concise! Much ergonomic! Wow!
consume(
    Foo::default()
        .chain()
        .chain()
        .chain()
        .chain()
);

// Method definitions that make this possible:
// -------------------------------------------

#[derive(Default)]
struct Foo {
    // Some internal state.
}

impl Foo {
    fn chain(self) -> Self {
        // Make some changes to `self`, then return `self`.
        self
    }
}

fn consume(foo: Foo) {
    // Do something with the final `Foo` after it's
    // been fully initialized and configured.
}

This approach is often used in combination with the builder pattern, though it can also be applied to a wide variety of other situations. The above example demonstrates the most straightforward of these cases (i.e. initializing and modifying an object in a single statement), but, as I’m going to demonstrate, this approach quickly breaks down when applied to a wider variety of use cases.

In this post, I intend to cover the following points:

Returning self is not an effective way of achieving method chaining in Rust.
Method and function chaining should be orthogonal to the return type of a function.
You should only return self from a function if it’s semantically meaningful to do so.
Method cascades provide a promising alternative to returning self when you want method chaining.

Chaining by Returning `self`

Since returning self is currently the de facto way of enabling method chaining in the Rust ecosystem, I’m going to start by demonstrating that doing so doesn’t work as well as we would like. To show this, we’re going to work with the following definitions:

// Define a struct `Foo` with some internal state that its methods
// will modify. We'll use `Foo::default()` throughout the examples
// to create the initial instance of the data.
#[derive(Debug, Default)]
struct Foo {
    value: usize,
}

impl Foo {
    // Define a method that can be chained by taking and returning
    // ownership of the data.
    fn chain_move(mut self) -> Self {
        self.value += 1;
        self
    }

    // Define a method that can be chained on a borrow of the data.
    fn chain_ref(&mut self) -> &mut Self {
        self.value += 1;
        self
    }
}

// Define a function that will consume the final data by taking
// ownership of it.
fn consume_move(foo: Foo) {
    println!("{:?}", foo);
}

// Define a function that will consume the final data by borrowing it.
fn consume_ref(foo: &Foo) {
    println!("{:?}", foo);
}

In the examples I will also sometimes use an imaginary method chain to demonstrate an idealized way of performing method chaining. This will be used to show the “ideal” use case (i.e. the most ergonomic way of applying method chaining in a given situation) so as to compare how chain_ref and chain_move work in practice.

Let’s now take a look at each of the use cases we would like to support, and see how they work with each of the method chaining approaches.

Single Method Chain

The most basic case is having a single long method chain, from construction into the consumption of your type:

consume(Foo::default().chain().chain());

This works reasonably well with both chain_move and chain_ref so long as you match the chaining style with the consumer:

consume_move(Foo::default().chain_move().chain_move());
consume_ref(Foo::default().chain_ref().chain_ref());

Note, though, that while the chain_move version works with both consume_move and consume_ref version, chain_ref can only be used with consume_ref. If we try to pass the result of chain_ref into consume_move, we get this error:

error[E0308]: mismatched types
 --> src/main.rs:9:18
  |
9 |     consume_move(Foo::default().chain_ref().chain_ref()); // Doesn't compile.
  |                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected struct `Foo`, found &mut Foo
  |
  = note: expected type `Foo`
             found type `&mut Foo`

Since chain_ref() returns a &mut Foo, we can’t use it anywhere a Foo is expected (though there are ways of working around this, which will be covered below).

Use Before Consuming

Let’s say you needed to log the value before consuming it. The most intuitive way of doing this would be to directly bind the result of the chain to a variable, log the variable, then pass the variable to the consume method:

let foo = Foo::default().chain().chain().chain();
println!("foo: {:?}", foo);
consume_ref(&foo);
consome_move(foo);

This can be done directly with chain_move:

let foo = Foo::default().chain_move().chain_move();
println!("foo: {:?}", foo);
consume_ref(&foo);
consume_move(foo);

But doing the same thing with chain_ref won’t compile:

let foo = Foo::default().chain_ref().chain_ref();
println!("foo: {:?}", foo);
consume_ref(foo);

error[E0716]: temporary value dropped while borrowed
 --> src/main.rs:2:15
  |
2 |     let foo = Foo::default().chain_ref().chain_ref();
  |               ^^^^^^^^^^^^^^                        - temporary value is freed at the end of this statement
  |               |
  |               creates a temporary which is freed while still in use
3 |     println!("foo: {:?}", foo);
  |                           --- borrow later used here
  |
  = note: consider using a `let` binding to create a longer lived value

As the compiler helpfully notes, the temporary value created by Foo::default() is dropped at the end of the chain sequence, so we can’t bind it to a variable. Instead, we must first create the initial Foo and bind it to a mutable variable. Once that’s done, we are able to use chain_ref to apply modifications to it before logging and consuming the final value:

let mut foo = Foo::default();
foo.chain_ref().chain_ref();
println!("foo: {:?}", foo);
consume_ref(&foo);
consume_move(foo);

Note that you must also use this approach to use chain_ref in combination with consume_move; By binding the initial Foo to a variable, you avoid the issue of it being a temporary value and being dropped too early.

While this is functional, it has a few drawbacks as compared to the chain_move version:

You can no longer create and modify the value in a single expression.
You have to bind foo as a mutable variable, which loosens some of the guarantees you get in the chain_move version when binding the variable immutably.
When converting from the single chain version to this version, it’s easy to initially apply the naïve transformation shown above and get tripped up when it doesn’t work. The chain_move version, on the other hand, works fine with the naïve transformation.

For this case, both chain_ref and chain_move work equally well with consume_ref and consume_move since, once the object is bound to a variable, it is easy to either lend that value to another function or to transfer ownership entirely.

Modifying an Owned Value

Now let’s say that you want want perform an initial method chain, then conditionally apply another chain of operations to the same object. This means that we already have a bound, mutable variable that we would like to modify in the same method-chaining style that we use to create the object. The ideal version of this would be as follows:

let mut foo = Foo::default().chain().chain().chain();
if some_condition {
    foo.chain().chain().chain();
}
consume_ref(&foo);
consume_move(foo);

In this case, the chain_ref version performs reasonably well (though you again need to first bind the variable before performing the initial chain of modifications):

let mut foo = Foo::default();
foo.chain_ref().chain_ref().chain_ref();
if some_condition {
    foo.chain_ref().chain_ref().chain_ref();
}
consume_ref(&foo);
consume_move(foo);

Doing the same with chain_move can also be made to work, though it requires the value to be rebound after the conditional chain:

let foo = Foo::default();
let foo = if some_condition {
    foo.chain_move().chain_move().chain_move();
} else {
    foo
};
consume_ref(&foo);
consume_move(foo);

Again, this is functional but somewhat awkward to construct (having the extra else branch only to satisfy the borrow checker) and not necessarily an obvious construction for someone who’s not already familiar with the details of Rust’s ownership rules.

In this case, both chain_ref and chain_move work, but both have ergonomic drawbacks as compared to the ideal version.

Chaining Within a Function

Let’s say you want to break some of your logic into a separate function. This is possible with both functions, thought the signature of your helper function will have to change depending on which chaining approach you are using:

fn do_modifications_ref(foo: &mut Foo) {
    foo.chain_ref().chain_ref().chain_ref();
}

fn do_modifications_move(foo: Foo) -> Foo {
    foo.chain_move().chain_move().chain_move()
}

It’s worth noting that you can still use chain_ref within do_modifications_move, but you can’t use chain_move within do_modifications_ref (since you can’t take ownership of foo).

No Chaining At All

Let’s say you’re a boring person and don’t want to use method chaining at all, plain-old method calls are enough for you. If that’s the case, the chain_ref version can also be used to modify the value without chaining, e.g.:

let mut foo = Foo::default();
foo.chain_ref();
foo.chain_ref();
foo.chain_ref();

The chain_move version can technically be used without chaining, but requires the variable to be re-bound in each statement, again making the code both harder to read and harder to write:

let foo = Foo::default();
let foo = foo.chain_move();
let foo = foo.chain_move();
let foo = foo.chain_move();

A Real-World Example

In the abstract, this may seem like a number of minor issues and trivial complaints. To provide a real-world example of the implications these drawbacks have, let’s look at an example that I ran into (one that motivated my writing this article).

Say you’re writing a tool that uses std::process::Command to spawn a child process. Command is designed to be used via method chaining by having all its methods take and then return &mut self. Your initial version looks something like this:

let result = Command::new("foo")
    .arg("--bar")
    .arg("--baz")
    .arg("quux")
    .status()
    .unwrap();

At some point later, you realize that you want to only pass the --baz flag conditionally, so you make the obvious changes to your code:

let command = Command::new("foo")
    .arg("--bar");

if set_baz {
    command.arg("--baz");
}

let result = command
    .arg("quux")
    .status()
    .unwrap();

But it doesn’t compile, because you can’t bind the result of the initial method chain when the chaining methods return &mut Self (as Command::arg does). To get it to work, you have to bind the result of Command::new to a variable, then perform all configuration on it:

let mut command = Command::new("foo");
command.arg("--bar");

if set_baz {
    command.arg("--baz");
}

let result = command
    .arg("quux")
    .status()
    .unwrap();

This is a minor bit of friction for someone already familiar with Rust, but it can be a frustrating (and unnecessary) roadblock for someone new to the language.

Method Chaining is Orthogonal to Return Value

At this point, I feel comfortable in having demonstrated that returning self is, at best, an awkward way of implementing method chaining for a Rust type. Beyond that, though, it’s worth asking a more fundamental question: Should it work better? Should we consider this a failing of Rust, that the language doesn’t play well with method chaining? Or is there something fundamentally wrong with this form of method chaining?

To answer these questions, let’s take a look at the function signature for chain_ref:

fn chain_ref(&mut self) -> &mut Self { ... }

Rust’s type system allows us learn a lot about what a function can do solely based on its signature. Key here is that chain_ref only takes a single parameter: &mut self. We therefore know that it can (and almost certainly will) mutate self in some way. We also know that it is probably pure relative to self, such that the same value for self will produce the same mutation, since chain_ref takes no other parameters to influence its behavior.

But what does returning &mut Self tell us about chain_ref? Normally, the return type would tell us what the result of the operation is. But in this case, the returned value actually has nothing to do with the internal logic of chain_ref, it’s only there to enable method chaining, which is completely orthogonal to chain_ref itself.

This becomes especially problematic if your function has an actual return value. Take HashMap::insert as an example. insert returns the previous value if one was replaced, however it’s not always necessary to check the return value. In some cases, I may want to insert many elements into a hash map, in which case using a method chain would be clear and concise:

let map = HashMap::new()
    .insert("foo", 1)
    .insert("bar", 2)
    .insert("baz", 3)
    .insert("quux", 4);

But there’s no way to make this work while still returning a value from insert: You can either return a value or you can return self, but not both.

The fundamental problem with returning self solely for the purpose of enabling method chaining is that you’re contorting your API in order to enable something that’s completely orthogonal to what your API is doing. Your function’s signature should reflect its behavior, and should be usable in a method chain regardless of its return type.

We’re Only Talking About Method Chains

At this point I’ve covered the practical issues with returning self and the more conceptual reason why it doesn’t make sense. Before I move on to discussing alternate solutions, I want to emphasize an important point: Returning self is only an issue if it’s being done solely to enable method chaining. It’s entirely reasonable to return self from a function if doing so is semantically meaningful, and I am in no way trying to say that it is never appropriate to return self from a method in Rust. It only becomes an issue if you’re returning self from a function for no reason other than to allow users to chain those methods together.

Method Cascades

As is often the case, we don’t need to invent a whole new solution to this problem when we could simply steal good ideas from another programming language.

Dart provides first-class support for method chaining in the form of method cascades. The .. operator is the the “cascaded method invocation operator”, and behaves similarly to . except that discards the result of the method invocation and returns the original receiver instead. This allows any method to be chained in Dart, without requiring the author to have thought ahead of time to return self.

In Dart, the syntax looks something like this:

final addressBook = (AddressBookBuilder()
      ..name = 'jenny'
      ..email = '[email protected]'
      ..phone = (PhoneNumberBuilder()
            ..number = '415-555-0100'
            ..label = 'home')
          .build())
    .build();

While there’s no equivalent syntax built into Rust, we could achieve something very similar with the help of a fairly simple macro. In fact, there’s already the cascade crate which does just that!

let foo = cascade! {
    foo: Foo::default();
    ..chain();
    ..chain();
    ..chain();
    | if some_condition {
        cascade! {
            &mut foo;
            ..chain();
            ..chain();
            ..chain();
        }
    };
    ..chain();
    ..chain();
    ..chain();
};
consume_ref(&mut foo);
consume_move(foo);

Since this pattern hasn’t yet seen wide usage in the Rust community, I expect that it will take some time and iteration to fully adapt it to Rust as a language (though the cascade crate is certainly a good start). Looking to the future, I would personally like to see this pattern become “official” in some regards, either through inclusion in the standard library or 🤞 a native syntax 🤞.

Conclusion

So in summary:

Don’t return self from methods if you’re only doing so to enable chaining.
Start using the cascade crate instead!

Comments and discussion can be found online:

randomPoison

Continuous Delivery for the Discerning Game Developer

Integrating Changes

Build and Deployment

Testing

Continuous Testing

Test-Driven Development

Architecting Code for Testability

Testing Art and Data

Verify Changes Before Merging

A Note on Manual QA

Conclusion

The State of the Unity Package Ecosystem

The Bad Old Days

A New Hope

Hosting Packages

Testing Open Source Projects

Generating Documentation

The Not-So-Bright Side

Closing Thoughts

Handling Variant Data: A Journey in Three-And-A-Half Parts

Prologue

Part I: JSON

Interlude: Goals and Criteria

Part II: JavaScript (and dynamic languages in general)

Part III: C#

Epilogue: Rust

Conclusion

Sharing C# Code with Unity

Part One: Technical Issues

Sharing Code Directly

Exporting a DLL

Incompatible Dependency Management

Incompatible Software Ecosystems

Part Two: Assessment

Using async/await in Unity

No Minimum Delay

Execution Order Stays The Same

Starting and Stopping Tasks

Cancel Task When Game Object is Destroyed

Perform Cleanup When Task is Cancelled

Exceptions and Callstacks

Compatibility with Coroutines

Debugging

The Brilliance of SpatialOS’s Modular Inspector

Queries, Not Hierarchies

Modular, Composable Tools

Different Visualizations for Different Situations

It Looks Really Good

Applying This to Other Engines/Editors

Chaining Functions Without Returning Self

Chaining by Returning self

Single Method Chain

Use Before Consuming

Modifying an Owned Value

Chaining Within a Function

No Chaining At All

A Real-World Example

Method Chaining is Orthogonal to Return Value

We’re Only Talking About Method Chains

Method Cascades

Conclusion

Chaining by Returning `self`