Table of Contents

DotBoxD documentation

DotBoxD is a source-generated, contract-first .NET extension runtime. One C# contract can be used in three ways:

New here? Install via Getting started, then work through the three Tutorials — the mode links below go straight to the deep-dive concepts.

  • Services — the host implements a contract; clients call it remotely (RPC).
  • Kernels — a client supplies validated logic the host runs safely inside a metered sandbox (restricted IR — an intermediate representation — never C#/IL/reflection).
  • Pushdown — a kernel composes the host's own services server-side, so many small remote calls collapse into one validated round-trip.
flowchart LR
    Client["Client / Plugin"] -->|remote call| Services
    Client -->|submit validated IR| Kernels
    Client -->|one submission| Pushdown
    Services --> Host["Host process"]
    Kernels --> Host
    Pushdown --> Kernels
    Pushdown --> Services

Choosing a mode

Same contract, three delivery strategies. What differs is where the author's logic runs and what crosses the wire:

Mode What it solves Direction Round-trips Where the author's logic runs
Services (RPC) Typed request/response interop; no hand-written marshaling, and no runtime reflection on the hot path (it compiles ahead-of-time / AOT, so it runs on Unity's IL2CPP compiler). client → host, response back 1 per call host runs the hand-written implementation; the client invokes the typed proxy
Query (RunLocal) Server-side filter + projection, so only the data you need is pushed to the plugin. server → plugin, one-way push 0 Where/Select lower (compile down) to server-side sandboxed IR; only the RunLocal delegate is native plugin C#
Pushdown Collapse N per-entity calls into one server-side batch, next to the host's data. client → host, one submission 1, replacing N the author's batch method lowers to server-side sandboxed IR, looping the host's existing bindings

Decision rules:

  • Services — a one-shot request/response (fetch a price, compute a cart total). The interface is the single source of truth, so proxy and impl cannot drift.
  • Query (RunLocal) — you react to a high-frequency server event stream but only need a subset/summary locally. Because the filter runs as validated, fuel-metered IR, you can accept that logic from untrusted plugins safely.
  • Pushdown — a chatty for each id: Kill(id) loop that should be one batch. The server is never recompiled; the plugin ships the batch, which runs as verified, capability-gated, fuel-metered IR (real sandbox, not a trusted plugin).

Query and Pushdown both run author-supplied logic server-side as sandboxed kernels — the only difference is push-to-plugin (Query) vs aggregate-and-return (Pushdown). Services instead runs a hand-written host implementation, with no sandbox involved.

Map

Runnable Example

The maintained GameServer sample demonstrates service IPC (inter-process communication), event kernels, live settings, host bindings, policy-gated execution, server extensions, and unload-on-disconnect:

dotnet run -c Release --project samples/GameServer/Examples.GameServer.Server/Examples.GameServer.Server.csproj
Edit this page