Novolis Docs
novolis-governance / architectural-ideals/hexgame-authoritative-core.md

HexGame-aligned authoritative core (informative)

Policies that keep the org coherent

dotnetgovernancenovolis

Status: Informative ideal — not a Novolis BCP 14 RFC and not a mandate to take a HexGame PackageReference. External pattern: HexGame (draft architecture 0.1). Stack law: library-boundaries.md — Math → Physics → Simulation; no Kit layers.

Purpose

Describe how Novolis games can follow HexGame’s loop — commands in, authoritative advance, snapshots and effects out — by composing existing Novolis packages and app-owned application cores, without:

  • Vendoring HexGame.* into the platform
  • Adding a GameKit / Novolis.HexGame.* umbrella
  • Putting game ticks or world orchestration in Physics

Non-goals

  • Re-hosting HexGame’s normative prose as Novolis law
  • Stride Lite or any Stride engine island
  • Requiring dogfood apps to rename types to HexGame names
  • Shipping Novolis.Game.Intent or shared frame DTO packages before 2–3 apps share a shape

Stack roles

LayerOwnsMust not own
MathNumbers, transforms, geometry — no timedt, clocks, ticks, cameras, games
PhysicsForces, integrators, collision, domain solvers with physical dtTick order, SimulationWorld, replay, commands, players, cameras, HexGame frame
SimulationWorlds, systems, SimulationClock / SimulationStep, replay, cameras, intents, orchestrationRaylib/Rendering package refs; product game rules; becoming a full game engine
AppsIGameApplication-shaped Start/Tick/Save/Load, domain rules, effect catalogs, host compositionPushing product rules into Physics or Novolis.Game.* domain models
Raylib / RenderingWindow loop, draw, input bindings, presentersAuthoritative simulation state
Gaming (Novolis.Game.*)Identity, menus, lobby glue, procedural authoring, packagingSimulation/Raylib refs; game domain models; owning Tick

Hard rule — Tick is Simulation + app

HexGame Tick, command dispatch into the core, world systems, replay, and presentation-oriented frame results belong in:

  1. The app application core (owns the frame boundary), and
  2. `Novolis.Simulation.*` (clock, systems, world, replay, platform intents/cameras).

Physics is a callee. A Simulation system or app domain step may invoke Novolis.Physics.* with a physical dt. Physics never owns the HexGame frame or simulation-world tick ordering.

Name trap: Novolis.Physics.Motion.SimulationPipeline is an integrator + force-model pipeline, not simulation orchestration. Do not grow game-loop or tick APIs there. Prefer FixedStepAccumulator only under a Simulation/app tick owner.

Composition

Input adapter (Raylib / Silk / bot / replay)
    → commands / intents
App IGameApplication-shaped core (Start / Tick / Save / Load)
    → advances Novolis.Simulation (clock / systems / world)
        → optional Novolis.Physics (physical evolution inside a system)
    → snapshot + events + effects
Presenters / hosts (Raylib, Rendering, Avalonia) execute effects and present
ConcernLocation
Domain + Start/Tick/Save/LoadApp project
Authoritative world / systems / clock / replayNovolis.Simulation.*
Physical laws if neededNovolis.Physics.* — called from Simulation systems or domain step
Keys → intentsHost input adapter → Simulation.View intents (or future Game.Intent)
Window host loop (non-authoritative)Novolis.Raylib.Hosting / Silk TwoD game host
Present snapshotApp presenter → Raylib / Rendering
Headless testsApp tests → application core → Simulation (+ Physics only if domain uses it)
Lobby / identity / packagingNovolis.Game.*
Launcher shellNovolis.Avalonia.* when needed

Package map (existing homes)

HexGame-shaped ideaNovolis home
Tick / systems / worldNovolis.Simulation.Abstractions, SimulationClock, facets
Replay / determinism harnessNovolis.Simulation.Replay
Cameras / MoveIntent / LookIntentNovolis.Simulation.View
Physical integration / collisionNovolis.Physics.* (callee)
Local graphical host phasesNovolis.Raylib.Hosting
Presentation adaptersNovolis.Rendering.* + app presenters
Editor save pointsNovolis.Snapshots.* / workspaces — not sim step replay
NL / tool parse → queueNovolis.Commands.* — not the game tick inbox
Identity / lobbiesNovolis.Game.Identity.*, Novolis.Game.Multiplayer.*
Tick leadership / rate limitsNovolis.Messaging.Coordination.*

Do not add PackageReference to HexGame.Abstractions, HexGame.Hosting, or HexGame.Testing as platform foundation. Apps may study the external contracts; Novolis ships its own seams.

Deferred (exit criteria)

CandidateHome if extractedWhen
Novolis.Game.Intentnovolis-gaming (BCL-only; no Simulation/Raylib/Physics refs)2–3 apps share the same player-command envelope
Shared frame request/result DTOsNovolis.Simulation.Abstractions or stay app-localSame convergence; never under Physics
Presentation FrameSnapshots facetnovolis-simulationMultiple sims share a presenter-oriented shape; Replay already covers step records
Authoritative host glueApp + Multiplayer / MessagingProduct need; server advances app core → Simulation

Never grow HexGame-style orchestration under Physics.

Conformance checklist

Use in dogfood / PR review for HexGame-aligned games:

  • Engine / GPU objects are projections, not authoritative save state
  • App Tick advances Simulation (same core path local and multiplayer-ready hosts aim for)
  • Physics is not the tick owner; no game command inbox in Physics
  • No HexGame.* PackageReference in platform library csproj files
  • No new GameKit / Novolis.HexGame.* umbrella package
  • novolis-gaming packages do not reference Simulation or Raylib
  • Headless tests can exercise the application core without a renderer when logic is under test
  • Novolis.Commands.* is not used as a substitute for player tick commands unless intentional

Related