Skip to content

Player Builds

Toolbox is already capable of generating C# projects for use in development, and this is already in use for Socially Distant. But....you don't want to ship the editor build of your game!

Challenge: I'm strict about assets

We can't ship source assets. That is, if I bring in ritchie.png as a texture, I don't want the game decoding the PNG file when I publish. Assets should be stored in engine-native formats so we can just deserialize and go. We're not an engine unless we can't go vroom vroom.

Challenge: Scriptable builds

I want to be able to script parts of the player build. To be able to package the game with or without Steam support, to be able to control preprocessor defines, run validations, whatever I happen to need to do. Ideally, in C#, with access to engine APIs.

Challenge: Demo Players

While I don't want to ship source assets alongside a published build of a game, there are times where I just want to boot the game under a debugger without having to use the editor. Maybe I want to play the game as a player would experience it, just with the added convenience of being able to also edit or debug things. I'd personally use this when writing or recording devlogs.

A demo player could be achieved by doing the usual editor codegen for compiling a game, compiling the resulting project, and launching the editor in demo mode. It already knows how to bootstrap the game, since it needs to do so during editing anyway. This could be integrated into IDEs by launching demo mode via CLI arguments, via the IDE's debug configurations.

Another use case would be for creating sample projects with Toolbox. A.K.A, actual demos of the engine. If you just want to see the thing work, you clone the repo and tell Toolbox to run it. Just like dotnet run.

What needs to happen?

  1. User instructs Toolbox to publish a project.
    1. By command-line (CI/CD would do this)
    2. By GUI (humans do this)
  2. The user is asked "where do you want the project to be published?"
  3. If no existing publish settings are configured for the project, the user has to set them. Either by CLI arguments or by GUI.
  4. The game is compiled to a temporary directory. This is compile pass 1.
  5. The pass 1 build is used to import and process the game's source assets. They are then indexed inside and written to package files.
  6. Once we know where the boot scene was imaged into, we generate a player project that loads the package file and loads the scene.
  7. The game's source code should then be compiled as part of this player build, as a .NET publish task. This is compile pass 2.
  8. The compiled game can now optionally launch.

What could go wrong?

We should try to catch potential "shit we're gonna crash" issues inside assets. If it can't be imported into the editor successfully then it shouldn't go in the build and the build should be considered bad.

If the code can't compile without editor APIs, then this is a problem the maintainer must fix. We should set a preprocessor define when building projects for the editor.

Some libraries included in the project are only there for editing, and should be able to be stripped. That'll also cause compilation issues in poorly-maintained projects.

We need to be able to handle not having a boot scene. That's an error condition, though.