AdvancedValidated 1.0.0

Extension design and ownership rules

Use case

Start here before project code implements, registers, persists, or disposes a Grid Toolkit extension contract.

Contract and ownership

Choose one public contract family for one responsibility:

extensions store project-owned data;
policies and structure behaviors make gameplay decisions;
selection, topology, and layout contracts describe reusable logical or spatial rules;
authoring adapters and renderer modules integrate those rules with Unity.

For example, use IGridBoardStateExtension for data owned by one live board. Do not use reflection or internal access to bypass a supported contract.

Use stable IDs as persistence and registration keys.
Return independent clones when a runtime owner accepts mutable data.
Return detached immutable read models to consumers.
Freeze definition-owned values before runtime use.
Dispose subscriptions and owned resources from the same owner that created them.
Keep Unity scene objects out of board snapshot payloads.

Implementation

Put runtime contracts in a runtime assembly and editor registrations in a separate Editor-only assembly. Reference only the product assemblies the feature uses, through public or protected Grid Toolkit contracts.

Registration

Register project contracts from one explicit startup location. If a registry is editor-only, pair registration with unregistration so domain reload and tests remain deterministic.

Verification

Reject invalid configuration before mutation and include stable IDs, scope, and the failed invariant. Do not silently substitute an incompatible resolver, topology, or renderer capability.

Tests

Test through the same supported public contracts that the project uses at runtime. Cover the behaviors that apply to the chosen extension family: cloning, independent reads, stable ordering and IDs, duplicate handling, restoration, registration cleanup, and disposal.

Supported customization boundary

Supported customization begins at a public type listed with an ExtensionPoint or EditorIntegration role in the API reference. Those contracts cover:

runtime extensions, snapshot resolvers, policies, and structure behaviors;
selection patterns, topologies, and layout providers;
authoring clone and validation contracts, editor registries, renderer modules, and capability requirements;
the public module-specific contracts for Cell Metadata, Inventory, and uGUI.

The boundary does not include internal types, private serialized fields, reflection into shipped objects, product source changes, demo implementations, or assumptions about physical renderer handles. Preview and Experimental extension points remain supported only at their stated tier.

Done when

The extension has one explicit owner, uses only public contracts, survives the required lifecycle, and can be removed without leaving registrations or disposed objects behind.

Table of Contents