Novolis Inertial Frame Stack — adapted specification

Maps the Inertial Frame Stack (IFS) to current Novolis repos, NuGet packages, and types. Use this when introducing novolis-spatial and the first IFS implementation.

Status: specification (no novolis-spatial repo yet). Related: simulation-layer-policy.md, naming.md.

Purpose

Inertial Frame Stack is the spatial locality layer.

It defines where a simulation frame is evaluated from, and provides coordinate projection to express relevant world-space state in a local, origin-stable frame.

It does not decide what participates, simulate physics, render, or replicate network state.

IFS           = where
PreCulling    = what        (future: Novolis.Spatial.PreCulling)
FrameScene    = prepared work (future: Novolis.Spatial.FrameScene)
Adapters      = execution   (render / physics / net hosts)

Placement in the Novolis stack

flowchart TB
  subgraph math [novolis-math]
    Geo[Novolis.Math.Geometry]
    Arr[Novolis.Math.Arrays]
  end

  subgraph physics [novolis-physics]
    Num[Novolis.Physics.Numerics]
    Abs[Novolis.Physics.Abstractions]
  end

  subgraph sim [novolis-simulation]
    SimAbs[Novolis.Simulation.Abstractions NEW]
    View[Novolis.Simulation.View]
    World[Novolis.Simulation.World]
  end

  subgraph spatial [novolis-spatial NEW]
    SpAbs[Novolis.Spatial]
    IFS[Novolis.InertialFrames]
    Pre[PreCulling future]
  end

  Num --> SpAbs
  SimAbs --> IFS
  SpAbs --> IFS
  IFS --> Pre
  View -.->|ViewPose to anchor only| IFS
  Geo -.->|float matrices at adapter edge| Adapters

Novolis.Simulation.View.ViewPose is an observer convenience (float Vector3 + yaw/pitch). It is not FrameContext. Hosts may convert ViewPose → FrameAnchor.Pose at a double-precision boundary when building a frame.

Repositories and packages

Target repo

novolis-spatial

Per naming.md: domain repo novolis-spatial, packages Novolis.Spatial.*.

Packages (v1)

Future (same repo, not v1):

Must not depend on

Novolis.Raylib.*
Novolis.Physics.Collision.*
Novolis.Physics.Motion / Gravity / Ballistics / …
Novolis.Messaging.*
Rendering hosts, Stride, Vulkan
Game-specific assemblies (SCR product code, DoomLite3D)

Novolis.InertialFrames may reference:

Novolis.Physics.Numerics     (double 3D algebra only)
Novolis.Spatial
Novolis.Simulation.Abstractions

Do not reference the aggregate Novolis.Physics metapackage or simulation world/kinematics packages (avoids cycles and hidden physics coupling).

Type mapping (spec → Novolis)

Precision split (aligned with existing code)

World-space is truth. Frame-space is cache.

Dependencies (concrete)

Novolis.InertialFrames
  → Novolis.Physics.Numerics
  → Novolis.Spatial
  → Novolis.Simulation.Abstractions

Novolis.Spatial
  → Novolis.Physics.Numerics

Novolis.Simulation.Abstractions
  → (none required for v1; optional reference to Novolis.Spatial for WorldPosition on EntityView)

If EntityView carries positions, prefer Novolis.Simulation.Abstractions → Novolis.Spatial rather than duplicating coordinates in simulation.

Core responsibility

Given:

IWorldSnapshot          (Novolis.Simulation.Abstractions)
FrameAnchor             (entity / pose / position)
FrameBands + interest radius

Produce:

FrameContext            (Novolis.InertialFrames)

FrameContext supplies origin, orientation, optional velocity baseline, interest region, distance bands, IFrameProjector, and band classification helpers.

Core types

Namespaces shown as intended layout.

Identifiers and frame state (`Novolis.InertialFrames`)

namespace Novolis.InertialFrames;

public readonly record struct InertialFrameId(Guid Value);

public readonly record struct InertialFrame(
    InertialFrameId Id,
    WorldPose Origin,
    WorldVector Velocity);

World-space (`Novolis.Spatial`)

namespace Novolis.Spatial;

/// <summary>Authoritative world-space point. v1: wraps <see cref="Novolis.Physics.Numerics.Vector3d"/>; later may add sector/origin metadata.</summary>
public readonly record struct WorldPosition(Vector3d Value);

public readonly record struct WorldVector(Vector3d Value);

public readonly record struct WorldPose(WorldPosition Position, Quaterniond Rotation);

/// <summary>Interest/query region in world space. v1: axis-aligned box.</summary>
public readonly record struct WorldRegion(AxisAlignedBox3d Bounds)
{
    public bool Contains(WorldPosition position) => Bounds.Contains(position.Value);
}

ISpatialQuery (optional v1): minimal read surface used by builders — e.g. try get pose/position by EntityId. Implementations live in simulation or product hosts, not in IFS.

Frame-space (`Novolis.InertialFrames`)

Uses numerics directly (no duplicate vector types):

public readonly record struct FramePosition(Vector3d Value);

public readonly record struct FrameVector(Vector3d Value);

public readonly record struct FramePose(FramePosition Position, Quaterniond Rotation);

Bands

public readonly record struct FrameBand(
    string Name,
    double EnterDistance,
    double ExitDistance);

public sealed record FrameBands(
    FrameBand Interactive,
    FrameBand Tactical,
    FrameBand Strategic,
    FrameBand Background)
{
    public static FrameBands Default { get; } = /* governed defaults */;
}

Simulation contracts (`Novolis.Simulation.Abstractions`)

namespace Novolis.Simulation.Abstractions;

public readonly record struct SimulationTick(ulong Value);

public readonly record struct EntityId(Guid Value);

public readonly record struct EntityView(
    EntityId Id,
    WorldPosition Position,
    WorldPose? Pose = null);

public interface IWorldSnapshot
{
    SimulationTick Tick { get; }
    bool TryGetEntity(EntityId id, out EntityView view);
}

Sealed WorldSnapshot record implementations belong in simulation or app layers, not in IFS.

`FrameContext`

public sealed record FrameContext(
    InertialFrame Frame,
    WorldRegion InterestRegion,
    FrameBands Bands,
    SimulationTick Tick,
    IFrameProjector Projector)
{
    public double InterestRadiusSquared { get; init; }

    public FrameBandKind Classify(WorldPosition position)
        => FrameBandClassifier.Default.Classify(this, position);
}

Projection API (v1)

No Matrix4x4d. Projector holds origin pose and cached inverse orientation.

public interface IFrameProjector
{
    FramePosition Project(WorldPosition position);
    WorldPosition Unproject(FramePosition position);

    FrameVector Project(WorldVector vector);
    WorldVector Unproject(FrameVector vector);

    FramePose Project(WorldPose pose);
    WorldPose Unproject(WorldPose pose);

    double DistanceSquaredTo(WorldPosition position);
}

Implementation sketch: Project(position) => origin.Rotation⁻¹ * (position - origin.Position) using Quaterniond from Novolis.Physics.Numerics (same inverse-rotate approach as SemiImplicitEulerRigidBodyIntegrator).

v2 optional: ToSinglePrecisionTransform() → Novolis.Math.Geometry.Transform for render adapters only.

Frame building API

public interface IFrameContextBuilder
{
    FrameContext Build(IWorldSnapshot snapshot, FrameRequest request);
}

public sealed record FrameRequest(
    FrameAnchor Anchor,
    FrameBands Bands,
    double InterestRadius);

public abstract record FrameAnchor
{
    public sealed record Entity(EntityId EntityId) : FrameAnchor;
    public sealed record Pose(WorldPose Pose) : FrameAnchor;
    public sealed record Position(WorldPosition Position) : FrameAnchor;
}

Convenience:

public static class FrameRequests
{
    public static FrameRequest CenteredOn(EntityId entityId, double interestRadius = 100_000)
        => new(
            Anchor: new FrameAnchor.Entity(entityId),
            Bands: FrameBands.Default,
            InterestRadius: interestRadius);
}

Simple usage

var frame = frameBuilder.Build(snapshot, FrameRequests.CenteredOn(playerShipId));
var local = frame.Projector.Project(enemy.Position);
var band = frame.Classify(enemy.Position);

Band classification

IFS classifies distance, not participation.

public enum FrameBandKind
{
    Interactive,
    Tactical,
    Strategic,
    Background,
    Outside
}

public interface IFrameBandClassifier
{
    FrameBandKind Classify(FrameContext frame, WorldPosition position);
}

Hysteresis: use EnterDistance / ExitDistance per FrameBand (e.g. enter tactical 10 km, exit 12 km). Classifier reads prior band from host state if needed; classifier itself stays pure given that state input.

Relationship to PreCulling (future)

IWorldSnapshot
  → IFrameContextBuilder.Build
      FrameContext
  → IPreCullPipeline.Run
      PreCullResult
  → FrameScene
  → Adapters (Raylib, physics islands, replication)

Novolis.Spatial.PreCulling depends on Novolis.InertialFrames + Novolis.Simulation.Abstractions. It must not reference Raylib.

What IFS may / must not do

Unchanged from the conceptual spec:

May: resolve origin/orientation, interest region, bands, project/unproject, distance classification.

Must not: select renderables, physics bodies, replication sets; integrate motion; collision; draw calls; renderer/physics APIs; client/server roles.

Determinism

Same IWorldSnapshot contents
Same FrameRequest
Same FrameBands configuration
Same tick
= same FrameContext

No wall-clock time, RNG, renderer feedback, physics engine internals, network latency, or mutable statics in the build path.

Performance

• Prefer readonly struct / records and IFrameProjector instances that cache inverse orientation.
• Squared distance comparisons in band classifier.
• No LINQ in hot paths; allocation-free steady state for Build + Project.
• AxisAlignedBox3d for interest region tests.

Debug invariants (v1)

Debug.Assert(frame.Projector.Project(frame.Frame.Origin.Position).Value.LengthSquared() < 1e-12);
Debug.Assert(frame.InterestRegion.Contains(frame.Frame.Origin.Position));
// Monotonic enter distances: Interactive < Tactical < Strategic < Background

Minimal v1 surface (ship first)

Defer: FrameVector project/unproject if unused, ISpatialQuery, Novolis.Spatial.PreCulling, GPU matrix helpers.

Integration notes for current repos

Wave checklist (suggested)

1. Add Novolis.Simulation.Abstractions to novolis-simulation (packable, no raylib).
2. Create novolis-spatial from template; add Novolis.Spatial + Novolis.InertialFrames + TUnit tests.
3. Local NuGet pack; dogfood from one host with a fake IWorldSnapshot.
4. Add governance cross-link from simulation-layer-policy.md (one paragraph: spatial layer between simulation truth and adapters).
5. Implement Novolis.Spatial.PreCulling when a second consumer needs shared “what” selection.

Original → adapted quick reference