AdvancedValidated 1.0.0

Placement, admission, and coexistence policies

Use case

Use these contracts when project rules must accept or reject a structure, cell, layer, or coexistence decision during planning.

Contract and ownership

IGridStructurePlacementPolicy evaluates a placement request during planning. Admission policies validate an occupancy write or restore. Coexistence policies decide whether occupants may share cells/layers. All runtime policies expose a stable key and clone.

Policy sets clone their entries and preserve explicit order. Policies read context and append decisions/diagnostics; they do not mutate live board state.

Implementation

Excerpt — reject placement at the topology origin. Tested using public APIs.

public sealed class RejectOriginPlacementPolicy : IGridStructurePlacementPolicy
{
    public GridPolicyKey PolicyKey { get; } = new("game.reject-origin");

    public IGridStructurePlacementPolicy CloneForRuntime() =>
        new RejectOriginPlacementPolicy();

    public void Evaluate(GridStructurePlacementPolicyContext context)
    {
        if (Equals(
                context.Request.Anchor,
                context.Definition.Topology.CoordinateSystem.Origin))
        {
            context.AddFailure(
                GridPlacementFailureCode.PolicyRejected,
                "The origin is reserved.",
                context.Request.Anchor);
        }
    }
}

The example reserves the topology origin and reports a policy-specific failure during preview.

Registration

Compose with CreateDefault().Add, InsertBefore, Replace, or Remove, then pass the set through GridRuntimeConfiguration. Keep placement and admission coexistence sets aligned.

Verification

Use the closest GridPlacementFailureCode, a concrete message, and the offending coordinate. The policy set also records which policy produced the decision; the API calls this policy provenance.

Tests

Test acceptance and rejection, ordering, clone independence, preview/commit parity, restore admission, and coexistence symmetry.

Done when

Preview and apply evaluate the same ordered policy set, failures identify their policy source, and rejected plans leave revision and occupancy unchanged.

Table of Contents