Skip to content

Authoring Bundles

Everything about writing the code that runs inside BlackICE's sandbox. A realm is one side of the platform.

The server realm references logic running on the dedicated game server, every connected player runs logic in their own client realm.

Definition of a bundle

A bundle is a folder with up to four parts:

  • A server-side component - a .wasm file that runs in the server realm. This is where the shared state of your code is supposed to be. Tracking who is connected, what entities are spawned, scoring and game mode flow
  • A client-side component - a .wasm file that runs in each client realm once the bundle has been streamed to that client. It handles the per-player side, like interfacing with the existing game logic, hydrating the UI and talking to the server realm via net events
  • A web UI (ReUi) - optional web content shown in an overlayed iframe on each client. See Web UIs
  • A manifest - config.toml at the bundle root, describing all of the above. See Bundle Config

Both components are C# compiled ahead of time to WebAssembly. You write plain .NET code against official NuGet packages, without having to interact with the native BlackICE source code. See Toolchain Setup for the full requirements.

Entry point

Each component defines a static App class with a Start() method. When the script host activates your bundle it runs App.Start() once:

  • On the server realm when the bundle starts
  • In each client realm when that client has entered a certain connection stage
App.cs
public static class App
{
    public static void Start()
    {
        // Runs once when the bundle is started
    }
}

Everything you need to set up at start goes here. Registering commands, hooks and event handlers to be specific. After Start() returns, your code runs in response to what the game or runtime does. Commands, events, hooks, scheduled Futures are the regular "entry points" into your code. What you can register, and why it must happen inside Start(), is covered in Script API.

To understand where the server realm sits in relation to players, read The Networking Model before designing your server-side code.

In this section

  • Toolchain Setup - SDK requirements, NuGet packages, and the first build
  • Project Layout - Structure and conventions of a bundle project
  • Bundle Config - The config.toml manifest and every option it supports
  • Script API - Commands, hooks, events. What the runtime exposes to your code, and the registration rules
  • Comparing Game Objects - How objects and structs compare, and when not to use them as dictionary keys
  • Bundle IO - Console output, logging and the server-side file area (VFS)
  • Web UIs - Building the optional ReUi interface and talking to your client-side code