Namespace DotBoxD.Abstractions

Classes

CapabilityAttribute: Gates an event property behind a capability. Reading the property from kernel IR contributes id to the manifest's required capabilities, so a kernel that touches the property only installs under a policy granting it. Unannotated properties stay ungated (default-allow).

EventKernelAttribute

GeneratePluginRegistrationAccumulatorAttribute: Requests a generated client-side registration accumulator for a control type. The generated accumulator queues calls to methodName and flushes them in order when the plugin builder starts.

GeneratePluginRegistrationRootAccumulatorAttribute: Requests a generated root registration accumulator that exposes child accumulators for annotated child control properties.

GeneratePluginServerAttribute: Requests a generated plugin facade and builder for the annotated partial class.

GeneratedKernelMethodDescriptorAttribute: Analyzer-visible generated IR for server-authored SDK context [KernelMethod] helpers.

GeneratedPluginServerRegistryAttribute: Identifies a generated plugin-server hook or subscription registry and the context type its parameterless On<TEvent> method uses.

HandleSubtypeAttribute: Declares one supported subtype for a PolymorphicHandleAttribute handle. The analyzer lowers handle is T local to {BindingPrefix}.is(key), and instance host-binding calls on the declared subtype receive that key as their leading sandbox argument.

HookAttribute

Associates a hook context type with a stable hook name and exactly one result type, so context.Server.Hooks.On<TContext>() can resolve the result type from the context alone (rather than requiring a second generic argument at the call site). The analyzer reads this attribute to validate that a .Register(...) / .RegisterLocal(...) terminal produces ResultType, and persists Name as the runtime hook-point identity.

The ResultType must be a readonly partial record struct decorated with HookResultAttribute that declares a bool Success and a string? Reason field (see that attribute for the contract).

HookContext

HookResultAttribute

Marks a readonly partial record struct as a hook result: a value a .Register(...) / .RegisterLocal(...) terminal returns and the host applies. The DotBoxD generator emits builder members the user did not declare manually — Ok(), Reject(string? reason = null), and a With<Field>(value) per non-discriminator field — so result construction reads fluently and lowers to verified record.new IR.

A hook result must be a top-level readonly partial record struct that declares a bool Success field and a string? Reason field. Success = false means "abstain, fall through to the next matching registration"; a successful result may still carry a domain veto such as CanDie = false, so abstain and veto never overload the same field.

HostBindingAttribute: Marks a host-service method as a sandbox binding the DotBoxD.Kernels generator may call from verified kernel IR. A kernel reaches the service through Host<THost>() or through a constructor-injected service field (e.g. _world.GetHealth(id)); the generator lowers that call to a CallExpression(bindingId, …), records capability in the manifest's required capabilities, and adds effects to the manifest's effects. The host registers a matching binding (same id, capability, and effects) so install-time policy and effect validation gate the call. Set IsAsync when that registered binding declares asynchronous host work.

HostCapabilityAttribute: Declares the capability and host-state effects required by an analyzer-visible host binding contract.

InMemoryPluginMessageSink

KernelMethodAttribute

Marks a reusable helper method whose body the DotBoxD.Kernels generator inlines into the kernel/hook IR at every call site, so plugin authors can factor shared gate/handler logic out of a Where/Select/Run lambda (or a kernel-class ShouldHandle/Handle) without leaving the sandbox. The helper can be a static method, or an instance method called on the generated server-context parameter. For example:

server.Hooks.On<MonsterAggroEvent>()
    .Where((e, ctx) => IsBullying(e.MonsterLevel, e.PlayerLevel))
    .Run((e, ctx) => ctx.Messages.Send(e.MonsterId, "calm"));

[KernelMethod]
public static bool IsBullying(int monsterLevel, int playerLevel) => monsterLevel - playerLevel >= 3;

The call lowers exactly as if the body were written inline: each parameter is replaced by its already-lowered argument IR, and any [HostBinding] calls or [Capability]-gated reads inside the body contribute their capabilities to the calling kernel's manifest.

Static helpers may be called through ordinary static-call syntax or extension-method syntax, and named arguments plus supported optional parameter defaults are bound before lowering.

Constraints (verified at generation time; a violation fails the chain/kernel safely rather than miscompiling): the method must be static or called on the server-context parameter, have an expression body or a single return statement, and use types the kernel marshaller can represent in the current lowering surface (scalars, supported nullable scalars, enums, GUIDs, records/DTOs, lists, and maps where that surface supports them). Recursion, generic helpers, ref/out/in parameters, and params arrays are not allowed.

LiveSettingAttribute

LocalAttribute: Marks a server-authored context helper as native-only and unavailable to lowered IR.

PluginAttribute

PluginMessage

PolymorphicHandleAttribute: Marks a polymorphic host handle type whose sandbox representation is the scalar value stored in the configured key member. Hook contexts may expose the handle type, while generated verified IR receives only the key and calls host bindings to discriminate or query the concrete host-side entity.

ServerExtensionAttribute

Marks a class as a server extension: a batch operation the plugin ships as verified IR and the server runs request/response in a single roundtrip, so a loop over many entities executes server-side (calling the host's existing bindings) instead of one network call per entity. The generator lowers the class's single public batch method — its body may use locals, a foreach over a list parameter, host bindings via ctx.Host<T>() or constructor-injected service fields, and may build and return complex objects (records/DTOs) and lists of them. For example:

[ServerExtension("monster-killer", typeof(IMonsterKillerService))]
public sealed partial class MonsterKillerKernel
{
    private readonly IGameWorld _world;
    public MonsterKillerKernel(IGameWorld world) => _world = world;

    public List<KillResult> KillMonsters(List<int> monsterIds, HookContext ctx)
    {
        var results = new List<KillResult>();
        foreach (var id in monsterIds)
            results.Add(new KillResult(id, _world.Kill(id)));
        return results;
    }
}
public readonly record struct KillResult(int MonsterId, bool Success);

The trailing HookContext parameter is the lowering marker for host bindings (as in a kernel's Handle) and is not part of the wire signature. Parameters, return type, and DTO fields must use the supported scalar types, lists, or nested DTOs. Supplying the optional service interface type lets the analyzer emit a source-generated plugin-side client that marshals directly to compact server-extension value bytes instead of using a reflection proxy.

ServerExtensionClientAttribute: Requests a generated C# 14 extension property on receiverType that resolves the source-generated server extension client for this service. The receiver type must expose a ServerExtensions property whose value can invoke server extensions and resolve the installed service id.

ServerExtensionMethodAttribute: Requests a generated C# 14 extension method on receiverType that forwards to the source-generated server extension client. When name is omitted, the kernel method name is used; supply a custom name to make the receiver's domain API read naturally or avoid conflicts.

Interfaces

IEventKernel<TEvent>

IExtensibleControl: A domain control that can host plugin-owned server extensions.

IHookResult: The runtime contract every hook result satisfies so dispatch can apply the abstain/fallthrough rule without reflecting on the concrete type: Success == false means "abstain, fall through to the next matching registration". The DotBoxD generator adds this interface to every HookResultAttribute record (its Success field implements the member), so authors never write it by hand.

ILiveSettingsHandle<TKernel>: Strongly typed live-settings tuner for an installed kernel.

IPluginEventAdapter<TEvent>

IPluginEventValueWriter<TEvent>: Optional low-allocation event adapter path. Implement this when event values can be written directly into the runtime input buffer; EventValueCount must match Parameters.

IPluginMessageSink

IPluginServer<TWorld>: Lifecycle and anonymous server-side invocation surface mixed into a generated plugin facade.

IServerExtensionClientAccessor

IServerExtensionClientRegistry: Registry used by generated domain controls to resolve server-extension clients.

IServerExtensionWireClient: Wire client used by generated server-extension proxies.

IServiceControl: The root plugin-service control verbs exposed by a generated plugin facade.

Enums

GeneratedPluginServerRegistryKind

HostBindingEffect: Explicit host-service effects for analyzer-visible auto bindings.

Delegates

RemoteServerInvocation<TWorld, TCaptures, TReturn>: Lambda shape for the explicit capture-bag invoke overload on IPluginServer<TWorld>.

Table of Contents

Namespace DotBoxD.Abstractions

Classes

Interfaces

Enums

Delegates