ZOA Foundation

DefinitionId

struct

Stable identifier for an authoring-time definition asset. Persisted in save files and used as the registry key, so it must outlive asset renames and re-imports.

• readonly string Value
• static DefinitionId Empty
• static DefinitionId New()
• static bool TryParse(string value, out DefinitionId id)
• bool IsEmpty

InstanceId

struct

Stable identifier for a runtime instance: an item, a placed stack, a weapon instance, an attachment node, a world container. Same normalisation rules as DefinitionId, and a distinct type so the two cannot be swapped at a call site.

• readonly string Value
• static InstanceId Empty
• static InstanceId New()
• static bool TryParse(string value, out InstanceId id)

IDefinitionRegistry

interface

Runtime resolution of definition assets by id, type, or tag. A plain C# object with no singleton accessor, so a composition root owns one and a test can build another.

• bool Contains(DefinitionId id)
• bool TryGet<T>(DefinitionId id, out T definition) where T : DefinitionBase
• T Get<T>(DefinitionId id) where T : DefinitionBase
• IReadOnlyList<T> GetAll<T>() where T : DefinitionBase
• IReadOnlyList<DefinitionBase> GetByTag(string tag)

DefinitionRegistry

class

The shipped registry implementation. Builds id, exact-type, and tag indexes in a single pass over the database and reports duplicate ids according to the configured policy.

• static DefinitionRegistry Build(GameDatabase database, DefinitionRegistryBuildOptions? options = null)
• static DefinitionRegistry BuildFromResources(string resourcesPath = GameDatabasePaths.DefaultResourcesPath, DefinitionRegistryBuildOptions? options = null, bool throwIfMissing = true)

DuplicateDefinitionIdPolicy

enum

Throw, KeepFirst, or KeepLast. Strict build options throw, which is the right default during development because a duplicate id means two assets are competing for the same save-file reference.

GridCoord

struct

Row/column coordinate in a row-major grid. Carries an explicit Invalid sentinel of (-1, -1) so a failed placement search returns a coordinate rather than a nullable.

• readonly int Row
• readonly int Col
• static GridCoord Invalid
• bool IsValid

GridSize

struct

Width/height footprint in cells. Pair it with GridSizeExtensions.Oriented to get the effective footprint under a given orientation.

• readonly int Width
• readonly int Height
• bool IsValid
• GridSize Oriented(this GridSize size, Orientation orientation)

Orientation

enum

Normal or Rotated, backed by a byte. Two states because a rectangle rotated twice is the same rectangle, so a four-way enum would encode a difference no fit test can observe.

InventoryCapabilities

enum

Flags enum declaring what an inventory supports: Stacking, Rotation, Weight, Reservations, EquipmentSlots, SizeChange. It lives in Foundation rather than in Inventory because shape definitions, equipment slots, and UI all need to read it.

DefinitionBase

class

Abstract ScriptableObject base for every authored definition in the product. Owns the stable id, an optional display-name override that falls back to the asset name, and the tag list the registry indexes.

• DefinitionId Id
• string IdString
• string DisplayName
• IReadOnlyList<string> Tags
• void EnsureId()

ZOALog

class

The gated logging facade. Diagnostic levels consult ZOADiagnosticsGate before emitting; errors and exceptions always emit. Use IsEnabled or the Func<string> overload to keep hot paths free of wasted string building.

• static void Diag(ZOADebugCategory category, string message, Object context = null)
• static void Diag(ZOADebugCategory category, Func<string> message, Object context = null)
• static void Info(string message, Object context = null)
• static void Warn(ZOADebugCategory category, string message, Object context = null)
• static void Error(string message, Object context = null)
• static bool IsEnabled(ZOADebugCategory category)

ZOADiagnosticsGate

class

Process-wide diagnostics authority. Holds the current mode and category mask, raises Changed when either moves, and resets to Production/None at SubsystemRegistration so a stale editor session cannot leak into the next play.

• static ZOAProductionMode Mode
• static ZOADebugCategory EnabledCategories
• static bool IsEnabled(ZOADebugCategory category)
• static void Apply(ZOAProductionMode mode, ZOADebugCategory enabledCategories)
• static event Action Changed

ZOADebugCategory

enum

Flags mask of independently toggleable diagnostic channels: General, NetworkSync, PlayerRig, Weapon, Ai, Inventory, Overlay, Performance. Gates both log call sites and debug HUDs, so one toggle silences a subsystem end to end.

IZOADebugComponent

interface

Implemented by every debug HUD so the production manager can discover and gate it without referencing each concrete type. Implementers must also self-check the gate in OnEnable, because a HUD can spawn after the gate was applied.

• ZOADebugCategory DebugCategory
• string DebugLabel
• void SetDiagnosticsActive(bool active)

IPrefabPoolService

service

Project-wide pool registry keyed by prefab reference. Registered into FoundryServiceRegistry by PrefabPoolSceneInstaller and resolved from anywhere that spawns at high frequency.

• IPrefabPool GetOrCreate(GameObject prefab, Transform poolParent = null, int initialCapacity = 8, int maxSize = 256)
• GameObject Spawn(GameObject prefab, Vector3 position, Quaternion rotation, Transform parent = null)
• void Despawn(GameObject instance)
• void Warmup(GameObject prefab, int count)
• bool HasPool(GameObject prefab)

IPrefabPool

interface

A pool for one prefab. Spawn activates, positions, parents, and fires the pooled lifecycle hook; Despawn is idempotent on unknown, null, or already-returned instances.

• GameObject Prefab
• int InstanceCount
• int AvailableCount
• GameObject Spawn(Vector3 position, Quaternion rotation, Transform parent = null)
• void Despawn(GameObject instance)
• void Warmup(int count)

IPooledLifecycle

interface

Opt-in reuse hooks for components on pooled prefabs. Implement it when Awake-once semantics are wrong and the object needs a genuine per-spawn reset.

• void OnSpawnedFromPool()
• void OnReturnedToPool()

PrefabPoolSceneInstaller

component

Constructs a PrefabPoolService on Awake at execution order -9700 and registers it, deferring to any service that registered first. Pool containers parent under this component, so scene unload disposes every pooled instance with no cleanup pass.

• IPrefabPoolService Service

ZOAInputSuppression

class

Reference-counted gate for gameplay input while modal UI is open. Owners are tracked in a set so two overlapping panels cannot restore input while the other is still showing; ForceReleaseAll exists for scene transitions where the owning UI was destroyed mid-suppression.

• static bool IsSuppressed
• static void SetSuppressed(object owner, bool suppressed)
• static void ForceReleaseAll()
• static event Action<bool> SuppressionStateChanged

ZOACursorCapture

class

Reference-counted cursor unlock for UI over a first-person camera. Saving of the pre-capture cursor state is deferred to the first LateUpdate tick, so a controller that locks the cursor in Start does not get the UI's unlocked state recorded as the value to restore.

• static bool IsCaptured
• static void Acquire(UnityEngine.Object owner)
• static void Release(UnityEngine.Object owner)
• static event Action<bool> CaptureChanged

ZOAInputActionRegistry

class

Runtime roster of notable InputActions with a category, label, and description. Components register on enable and unregister on disable, so the key-bindings viewer renders a live list instead of a hand-maintained one.

• static void Register(UnityEngine.Object owner, InputAction action, string category, string displayName, string description = null)
• static void UnregisterOwner(UnityEngine.Object owner)
• static IReadOnlyList<Entry> Entries
• static event Action RegistryChanged

ZOAInputHelper

class

Resolves an InputActionProperty that may hold a reference, an inline action, or nothing, creating a default only in the last case. Components use it so they work in a bare scene without an authored InputActionAsset.

• static InputAction ResolveAction(ref InputActionProperty property, string actionName, string defaultBinding)
• static InputAction ResolveAction(ref InputActionProperty property, Func<InputAction> createDefault)
• static bool WasTriggered(InputAction action)

ZOALayers

class

Physics-layer names resolved by name and cached, never by hardcoded index. Separates the locomotion capsule from per-bone hitboxes and ragdoll colliders so a hitscan lands on the mesh rather than on the fat movement capsule.

• const string Player / Hitbox / Ragdoll / FirstPersonWeapon / FirstPersonArms / UI
• static int PlayerLayer, HitboxLayer, RagdollLayer
• static int WeaponHitscanMask
• static int ExcludeLocomotion(int mask)
• static void SetLayerRecursively(GameObject root, int layer)

ZoaAssetPaths

class

The canonical on-disk layout as compile-time constants. Resources-addressable content under Assets/Resources/ZOA, direct-referenced generated content under Assets/ZOA/Generated, and user-owned source art under Assets/ZOA/Bundled.

• const string ResourcesRoot / ResourcesLoadPrefix
• const string GeneratedRoot / BundledRoot
• static class Resources { GameDatabaseAsset, GameDatabaseLoad, ... }
• static class Generated { Definitions, Prefabs, Scenes, Materials, Players, ... }

FoundrySectionAttribute

class

Marks the start of a collapsible inspector section. The attributed field and every field after it in declaration order render in one group until the next marker; collapsed state persists across domain reloads. A pure metadata marker, rendered by the Workbench inspector.

• FoundrySectionAttribute(string title, bool expandedByDefault = true, int order = 0, string icon = null, string tooltip = null)

IGenreBundleRegistry

interface

Resolves genre bundles by DefinitionId or by the human bundle-id string. Foundation declares and implements it but never publishes it; the workbench or runtime host owns registration.

• bool TryGet(DefinitionId id, out GenreBundleDefinition bundle)
• bool TryGetByBundleId(string bundleId, out GenreBundleDefinition bundle)
• IReadOnlyList<GenreBundleDefinition> GetAll()
• GenreBundleDefinition Default

GenreBundleValidation

class

Pure-function validator over a bundle plus a resolver callback that answers whether an id currently resolves. It distinguishes Pending from broken, so an id authored ahead of the asset it points at reports as Pending instead of failing validation.

• static IReadOnlyList<GenreBundleIssue> Validate(GenreBundleDefinition bundle, Func<string, bool> idResolver)

ZOADiagnosticHudLayout

class

Position and size persistence for developer HUD windows, written to a dedicated JSON file under persistentDataPath. It lives here rather than in Persistence because Persistence already depends on Equipment and Inventory to capture their state, and hosting HUD layout there would close the cycle.

• static bool TryGetRect(string id, out Rect rect)
• static bool TryGetPosition(string id, out Vector2 pos)
• static void SetRect(string id, Rect rect)
• static void SetPosition(string id, Vector2 pos)

GameDatabase

asset

The built index of every DefinitionBase asset the runtime needs. One asset, one Resources.Load, deterministic ordering. Create via Tools > ZOA > Foundation > Game Database, or let the rebuild tool author it at the default path.

• static GameDatabase Instance
• IReadOnlyList<DefinitionBase> Definitions
• int Count
• List<DefinitionBase> GetNonNullDefinitions()

GenreBundleDefinition

asset

Groups the content that makes a project feel like a genre: weapon pack, UI theme, input binding set, starter loadout, starter loot table, scene look, HUD style. Every reference is a plain string id rather than an object reference, so a bundle stays serialisable without forcing the referenced packs to be imported first.

• string BundleId
• string WeaponPackId, UiThemeId, InputBindingSetId
• string StarterItemPaletteId, StarterLoadoutId, StarterLootTableId, StarterObjectiveId
• GenreHudStyle HudStyleDefault
• Color SceneAmbientColor, bool SceneFogEnabled

ContentPackInstallMarker

asset

A project-local receipt written when a content pack is installed, recording pack id, version, tags, and a UTC ISO-8601 install timestamp. It extends ScriptableObject, not DefinitionBase, so it never enters the GameDatabase or competes for a DefinitionId.

• string PackId
• string PackName
• string Version
• IReadOnlyList<string> Tags
• string InstalledAtUtcIso8601