mrgameeng/CLAUDE.md

# mrgameeng

2D game engine built on MonoGame 3.8.4 (DesktopGL), .NET 8, C#.
ECS-first: Friflo.Engine.ECS 3.6 is tightly integrated into the core — all gameplay
state lives in components, all logic in systems.

Design docs and developer documentation live in `docs/` and are written in **Russian**.
Keep them up to date when architecture or conventions change.

## Solution layout

```
src/      MrGameEng.* engine libraries (grouped by role, not one-per-feature)
tests/    xUnit test projects, one per engine library
tools/    CLI tools (atlas packer)
docs/     architecture, conventions, roadmap (Russian)
```

Libraries are grouped by architectural role rather than split per feature, to avoid a
sprawl of two-file projects. A feature lives in a subfolder of its host library and
keeps its own `MrGameEng.<Feature>` namespace (namespaces are independent of the
assembly), so `using MrGameEng.Tilemaps;` etc. still resolve after a merge.

The engine has no sample project: the **LittleSim** game
(https://gitea.hsrv.site/mrleo1nid/LittleSim, this repo as the `engine/` submodule)
is the living showcase — new engine features are demonstrated there.

Engine libraries (each feature is a namespaced subfolder of its host):

- **`Core`** — the platform-free kernel: ECS world, scenes and transition timing, time
  (`GameClock` with `TimeScale`; `GameSpeed` for discrete pause/1×/3×/6× speed control over
  the clock, `context.UseGameSpeed(...)`; `Calendar` turning scaled time into in-game days,
  `context.UseCalendar(secondsPerDay)`; `Climate` — continuous seasonal/daily temperature
  and season over the calendar, `context.UseClimate(settings)`), services, logging, and
  **`HeadlessHost`** — a fixed-timestep loop without a window or GPU (dedicated servers,
  batch simulation, tests). Depends only on Friflo.Engine.ECS — no MonoGame, no platform.
- **`Host`** — the windowed MonoGame host: `GameHost` (wraps `Game`, owns the window and
  `GraphicsDeviceManager`, publishes `GraphicsDevice` as a service), visual scene
  transitions (`OverlayTransition`, `Transitions.Fade/Wipe`, `TransitionRenderer`), plus
  **Input** (`MrGameEng.Input`: `InputManager`, `ActionMap`, `InputSystem`, in
  `Host/Input/`). Nothing depends on `Host` except the game itself. → `Core`.
- **`Graphics`** — custom batched renderer, camera, sprites, plus **Tilemaps**
  (`MrGameEng.Tilemaps`: code-built tile grids rendered through the batcher,
  `scene.UseTilemaps()` after `UseRenderer2D()`, in `Graphics/Tilemaps/`) and **Lighting**
  (`MrGameEng.Lighting`, `Graphics/Lighting/`: day/night ambient over the `Calendar` driving
  `Renderer2D.AmbientLight` on world layers, `scene.UseDayNight(renderer)`; plus a per-cell
  **lightmap** — `LightmapBuilder` (ambient × occlusion + point lights with grid-traced shadows),
  `PointLight` component, multiplied over the world via `scene.UseLighting(...)`, sampleable with
  `Lighting.SampleAt` for the simulation). → `Core`.
- **`Audio`** — ogg playback (NVorbis); `AudioManager` with `SoundVolume`/`MasterVolume`
  (one knob for effects + music). → `Core`.
- **`Content`** — the asset/content pipeline: **Assets** (`MrGameEng.Assets`: runtime
  loading, no MGCB pipeline; FontStash), **Atlases** (`MrGameEng.Atlases`: texture-atlas
  builder + runtime loader, CLI wrapper in `tools/MrGameEng.AtlasTool`; StbImage), and
  **Mods** (`MrGameEng.Mods`: mod discovery + load order from `About/About.json`, JSON
  `Defs/` with parent inheritance and later-mod override, `Languages/<code>/`
  localization, merged texture content trees; the game ships its content as the `Core`
  mod). → `Core`, `Graphics` (Atlases needs `Texture2DRegion`).
- **`Simulation`** — deterministic gameplay primitives that own no world data:
  **Pathfinding** (`MrGameEng.Pathfinding`: grid A*/Dijkstra/BFS and flow fields over a
  game-implemented `IPathGrid`), **AI** (`MrGameEng.AI`: utility-AI primitives —
  `ResponseCurve`, `Consideration<TContext>`, `UtilityAction<TContext>`,
  `UtilityAi<TContext>` selector, `Blackboard`; generic over a game context), and
  **Collisions** (`MrGameEng.Collisions`: `Collider` component, spatial hash rebuilt per
  tick, pairs/queries/raycast, `scene.UseCollisions()` after movement systems).
  → `Core`, `Graphics` (Collisions needs `Transform2D`, `RectF`).
- **`UI`** — Myra integration (`scene.UseUI()` after `UseRenderer2D()`),
  **DevConsole** (`MrGameEng.DevConsole`: in-game console capturing `Core.Log`,
  `scene.UseDevConsole()` last in OnLoad) and **Inspector** (`MrGameEng.Inspector`: a
  Chrome-DevTools-style ECS debugger overlay — entity tree by archetype, component/field
  view with simple-field editing, world-pick with selection highlight, renderer perf tab;
  `scene.UseInspector(renderer)`, toggle F1). → `Core`, `Graphics` (the inspector picks
  entities and reads renderer timings; Myra renders with its own SpriteBatch internally).
- **`Assets.Generator`** — Roslyn source generator for typed asset handles; standalone
  netstandard2.0 analyzer.

Dependency rule: a library may depend only on `Core` and `Graphics`; `Core` depends only
on Friflo.Engine.ECS (no MonoGame — the simulation must run headless). MonoGame is pulled
in by the platform/graphics libraries (`Host`, `Graphics`, `Audio`). Platform resources
(e.g. `GraphicsDevice`) are published by hosts as services in `EngineContext.Services`;
graphics code reaches the device via `context.GetGraphicsDevice()` (extension in
`Graphics`). Features grouped into one library share its package set (e.g. `Content`
carries both FontStash and StbImage) — keep optional/heavy deps (Myra, NVorbis) in their
own library so the rest of the engine stays free of them.

## Commands

```
dotnet build MrGameEng.sln
dotnet test MrGameEng.sln
```

Building requires the .NET 10+ SDK (Roslyn 5.3 packages used by the asset-handles
generator do not load under the SDK 8 compiler); the target framework stays net8.0.

## Architecture rules

- ECS-first: components are plain data (`struct` implementing `IComponent`),
  behavior goes into Friflo systems (`QuerySystem`), wired through `SystemRoot`.
  No `Update()` methods on game objects, no inheritance-based entities.
- Hot paths (per-frame systems) must be allocation-free below the renderer's parallel
  threshold; above it Parallel.For scheduler overhead is the accepted trade.
  A Friflo chunk holds a whole archetype — parallelize by slicing chunks into segments,
  never by chunk alone. Measure in Release only, using the Renderer2D phase timings.
- Rendering: custom batcher in `Graphics` (vertex buffers, layer→depth→texture sort,
  atlas support); `SpriteBatch` is not used in engine code. Draw systems write vertices
  directly from Friflo chunk iteration. Orthographic camera (one active per scene),
  registered render layers (World or Screen space, optional Y-sort), AABB culling
  against the camera rect before vertices are written.
- No MGCB content pipeline. Assets are raw files under `Assets/`, loaded at runtime
  (textures via `Texture2D.FromFile`, fonts via FontStashSharp, ogg via NVorbis,
  shaders precompiled by `dotnet-mgfxc` at build time). Game code references assets
  only through generated typed handles (`AssetRef<T>`), never string paths.
- New engine functionality goes into the host library for its role (a namespaced
  subfolder, e.g. a new render feature under `Graphics/`), not a fresh project. Add a
  new `MrGameEng.<Area>` library only when the area is a genuinely new role or needs an
  isolated heavy/optional dependency — never into `Core` by default, never a
  two-file project per feature.
- Every public engine feature must be covered by tests where logic is testable
  without a GPU, and demonstrated in the LittleSim game (the engine's showcase).

## Code conventions

- Nullable reference types enabled, warnings as errors, file-scoped namespaces.
- Public engine API requires XML doc comments (English).
- Tests: xUnit, named `Method_Scenario_Expectation`.
- Formatting: all C# code is formatted with **CSharpier**. Match its output —
  run `csharpier format .` (or let the editor's format-on-save handle it) before
  committing; never hand-format against it.

## Memory (echovault MCP)

- At session start, call `memory_context` to load prior decisions for this project;
  call `memory_search` before working on a topic that may have prior context
  (e.g. "renderer", "transitions", "generator").
- Before ending a session where you decided, fixed or learned something, save it with
  `memory_save`: decisions (X over Y + why), bug root causes, non-obvious gotchas
  (e.g. Friflo/Myra API traps). Write for a future agent with zero context.
- Don't save what the repo already records (code, docs/, git history) or trivia.