Namespace DotBoxD.Abstractions
Classes
Section titled “Classes”Gates an event property behind a capability. Reading the property from kernel IR contributes
DotBoxD.Abstractions.CapabilityAttribute.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).
GeneratePluginRegistrationAccumulatorAttribute
Requests a generated client-side registration accumulator for a control type. The generated accumulator
queues calls to DotBoxD.Abstractions.GeneratePluginRegistrationAccumulatorAttribute.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.
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.
Declares one supported subtype for a DotBoxD.Abstractions.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.
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
DotBoxD.Abstractions.HookAttribute.ResultType, and persists DotBoxD.Abstractions.HookAttribute.Name as the runtime hook-point identity.
The `DotBoxD.Abstractions.HookAttribute.ResultType` must be a readonly partial record struct decorated with
`DotBoxD.Abstractions.HookResultAttribute` that declares a bool Success and a string? Reason
field (see that attribute for the contract).
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.
Marks a host-service method as a sandbox binding the DotBoxD.Kernels generator may call from verified IR.
A kernel reaches the service through DotBoxD.Abstractions.HookContext.Host or a constructor-injected
service field; the generator lowers that call to a CallExpression(bindingId, …), records the
capability and effects, and expects the host to register a matching binding. Set DotBoxD.Abstractions.HostBindingAttribute.IsAsync
when that registered binding declares asynchronous host work.
Excludes a method from explicit, automatic, and DotBoxD.Abstractions.HostBindingObjectAttribute host binding resolution.
Exposes eligible public instance methods declared by an SDK value object as receiver-forwarding host
bindings. Binding ids derive from DotBoxD.Abstractions.HostBindingObjectAttribute.BindingPrefix, the method name, and parameter types;
methods inherit the default capability and effects unless they declare DotBoxD.Abstractions.HostBindingAttribute.
Declares the capability and host-state effects required by an analyzer-visible host binding contract.
Marks an optional DotBoxD.Abstractions.IRFunc parameter as the generated IR body of another
delegate parameter on the same method.
Builds sandbox IR expressions for hand-authored lowered pipeline steps.
IRFunc<TInput, TContext, TOutput>
Typed public carrier for an IR body generated from a delegate that receives an element and context.
Typed public carrier for the IR body generated from a delegate argument.
IRInvocation<TDelegate, TReturn>
Public carrier for a generated anonymous server invocation. The generated plugin facade consumes the package factory as its concrete plugin package type, while abstractions remain independent of the plugin hosting assembly.
IRInvocation<TCaptures, TDelegate, TReturn>
Public carrier for a generated anonymous server invocation whose delegate is paired with an explicit capture bag.
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.
Marks a delegate parameter whose lambda body should be lowered into a mergeable IR step.
The method must expose a sibling overload accepting DotBoxD.Abstractions.LoweredPipelineStep.
Marks a method whose lambda argument should be lowered into a generated anonymous IR package.
Merges an ordered sequence of mergeable-IR DotBoxD.Abstractions.LoweredPipelineStep fragments into one complete,
verifiable DotBoxD.Kernels.SandboxModule. This is the runtime counterpart to the source generator’s
build-time hook-chain fusion: a consumer that collected steps from a custom pipeline surface can combine
them by hand, which is exactly what “delete the attribute and hand-write it” requires.
Inputs for DotBoxD.Abstractions.LoweredPipelineComposer.Compose(DotBoxD.Abstractions.LoweredPipelineComposition). Carries the ordered mergeable-IR
DotBoxD.Abstractions.LoweredPipelineStep fragments plus the small amount of module identity a fragment
deliberately does not know (see docs/design/mergeable-ir-fragments).
Experimental public carrier for one lowered pipeline stage. A later composer can merge ordered
steps into a complete DotBoxD.Kernels.SandboxModule.
Marks a server-authored context helper as native-only and unavailable to lowered IR.
Marks a fluent pipeline/stage type as a recognized event-pipeline surface, replacing the generator’s hardcoded receiver-type allow-list. Stage and terminal calls on a marked surface expose explicit IR companion parameters; the source generator supplies those companions through interceptors.
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.
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 DotBoxD.Abstractions.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 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
Section titled “Interfaces”A domain control that can host plugin-owned server extensions.
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 DotBoxD.Abstractions.HookResultAttribute
record (its Success field implements the member), so authors never write it by hand.
Strongly typed live-settings tuner for an installed kernel.
IPluginEventValueWriter<TEvent>
Optional low-allocation event adapter path. Implement this when event values can be written
directly into the runtime input buffer; DotBoxD.Abstractions.IPluginEventValueWriter.EventValueCount must match
DotBoxD.Abstractions.IPluginEventAdapter.Parameters.
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.
Wire client used by generated server-extension proxies.
The root plugin-service control verbs exposed by a generated plugin facade.
GeneratedPluginServerRegistryKind
Explicit host-service effects for analyzer-visible auto bindings.
Describes method-level source-generator lowering into verified IR.
Describes the pipeline semantics of a delegate argument lowered into a mergeable IR step.
Whether a pipeline surface runs entirely in-host or ships its lowered kernel across the remote transport.
Delegates
Section titled “Delegates”RemoteServerInvocation<TWorld, TCaptures, TReturn>
Lambda shape for the explicit capture-bag invoke overload on DotBoxD.Abstractions.IPluginServer.