Leonid Pershin
fd6343bd09
CI / build-test (push) Failing after 1m8s
Add MrGameEng.AI utility-AI module; format codebase with CSharpier New MrGameEng.AI module (ResponseCurve, Consideration, UtilityAction, UtilityAi selector, Blackboard) plus CSharpier formatting applied across the whole engine. Documents the CSharpier convention in CLAUDE.md. @
97 lines
5.3 KiB
Markdown
97 lines
5.3 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 (one per functional area)
|
|
tests/ xUnit test projects, one per engine library
|
|
tools/ CLI tools (atlas packer)
|
|
docs/ architecture, conventions, roadmap (Russian)
|
|
```
|
|
|
|
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 modules: `Core` (game loop, ECS world, scenes, time), `Graphics` (custom batched
|
|
renderer, camera, sprites), `Input`, `Audio`, `Assets` (runtime loading, no content
|
|
pipeline), `Assets.Generator` (Roslyn source generator for typed asset handles),
|
|
`Atlases` (texture-atlas builder + runtime loader; CLI wrapper in `tools/MrGameEng.AtlasTool`),
|
|
`Tilemaps` (code-built tile grids rendered through the batcher; `scene.UseTilemaps()`
|
|
after `UseRenderer2D()`), `Pathfinding` (grid A*/Dijkstra/BFS and flow fields over a
|
|
game-implemented `IPathGrid`; Core-only, owns no world data),
|
|
`AI` (utility-AI primitives — `ResponseCurve`, `Consideration<TContext>`, `UtilityAction<TContext>`,
|
|
`UtilityAi<TContext>` selector, and a `Blackboard`; deterministic, generic over a game context,
|
|
Core-only, owns no world data), `Collisions` (`Collider`
|
|
component, spatial hash rebuilt per tick, pairs/queries/raycast; `scene.UseCollisions()`
|
|
after movement systems), `UI` (Myra integration: `scene.UseUI()` after `UseRenderer2D()`),
|
|
`DevConsole` (in-game console capturing `Core.Log`; `scene.UseDevConsole()` last in OnLoad),
|
|
`Mods` (mod discovery + load order from `About/About.json`, JSON `Defs/` with parent
|
|
inheritance and later-mod override, `Languages/<code>/` localization, merged content
|
|
trees for textures; the game ships its own content as the `Core` mod).
|
|
Dependency rule: every module may depend only on `Core`; `Core` depends only on
|
|
MonoGame and Friflo.Engine.ECS. `Assets.Generator` is a netstandard2.0 analyzer.
|
|
Documented exceptions: Myra renders with its own SpriteBatch internally; `Atlases`
|
|
depends on `Graphics` (Texture2DRegion) and `Assets` (loader registration);
|
|
`Tilemaps` depends on `Graphics` (regions, layers, renderer);
|
|
`Collisions` depends on `Graphics` (Transform2D, RectF).
|
|
|
|
## 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 matching module, or a new
|
|
`MrGameEng.<Area>` library if it is a distinct area — never into `Core` by default.
|
|
- 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.
|