Leonid PershinandClaude Fable 5
3438ed77f6
CI / build-test (push) Successful in 1m16s
Browsers can't speak UDP, so WebSocket is the engine's one transport. The server side is a dependency-free RFC 6455 implementation over TcpListener (handshake, frame codec with masking and fragmentation, ping/pong — unit-tested against the RFC example vectors); the client wraps ClientWebSocket, which works on desktop and maps to the browser WebSocket in Blazor WASM. Both sit behind the poll-based INetConnection so simulation systems drain messages from their own thread; client sends are chained fire-and-forget (no blocking — wasm-safe). Replication is server-authoritative: games register unmanaged component types in a ReplicationSchema (same order both sides, up to 32 types), ReplicationServer snapshots entities carrying NetId once per send and ships each connection only the components that changed since its last snapshot — a reliable ordered transport needs no acks for deltas. New connections receive the full state through the same path; despawns are tracked by set difference. ReplicationClient applies snapshots to a local EntityStore and raises EntitySpawned so the game can decorate replicated entities with presentation components. Covered by 16 tests including a real loopback exchange between WebSocketClient and WebSocketServer. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
147 lines
9.2 KiB
Markdown
147 lines
9.2 KiB
Markdown
# 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`).
|
||
- **`Net`** — multiplayer building blocks, browser-compatible by design: a dependency-free
|
||
RFC 6455 WebSocket server over `TcpListener` (browsers can't speak UDP, so WebSocket is
|
||
the engine's one transport), a `ClientWebSocket`-based client (works in Blazor WASM),
|
||
both behind the poll-based `INetConnection`; server-authoritative component replication
|
||
(`ReplicationSchema` of unmanaged components, `ReplicationServer` sending per-connection
|
||
deltas — no acks needed over a reliable ordered transport, `ReplicationClient` applying
|
||
snapshots to a local store, `NetId`). → `Core`.
|
||
- **`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.
|