Custom services & game layer

Adding a service

1. You should always subclass GnosisServiceBase to create a new service. It provides standard lifecycle hooks and state helpers.
2. Implement Id, Lifetime, GetFunctions(), and InvokeFunction for anything JSON or other services should call.
3. Optionally override CommunicationPolicy to lock down who may call you or whether Unity may bind an adapter.
4. Register the service in the UnityGnosisEngine component (Unity Inspector) by adding a matching GnosisEngineServiceEntry with the correct Id, Lifetime, and adapter binding.

Use OnInitialize, OnRunStarted, OnRunEnded, OnShutdown for lifecycle; use GetNode/SetNode with persistent: true/false for storage.

“Game” service pattern

Most games add a game-specific service (id e.g. Game) that:

• Owns no Unity types in the core if you want purity—or owns them only behind an adapter.
• Exposes functions your rules and JSON invocations can target (GrantExtraLife, ForceNextPiece, …).
• Publishes GnosisEvent for moments other systems should react to.

Keep tight loops (grid step, collision) in normal C#; use the engine for state that other systems care about and data-driven reactions.

Events you define

Event ids are strings. Conventionally:

• Pick stable, namespaced ids (game.line_cleared, ui.screen_opened).
• Document them next to your Publish call sites so rules authors know what exists.

Testing orientation

• Unit-test pure helpers and store mutations with a fresh GnosisStore.
• Integration-test a minimal GnosisEngine with a subset of services before wiring full Unity.

When you want a page expanded (e.g. “Shop only” or “UI navigation only”), note it in review—the skeleton here is intentionally shallow.