docs: update all docs for publication
- README.md: new — features, quick start, controls, MCP tools, requirements - AGENTS.md: rewritten for pure P/Invoke Vulkan 1.3 (was Raylib/OpenGL) - CORTEX_ENGINE_ARCHITECTURE.md: complete rewrite — current architecture, frame loop, UBO layout, push constants, shadow mapping, PBR, AI/MCP, physics, ImGui, video recording, content, testing - VULKAN_IMPLEMENTATION_PLAN.md: marked as COMPLETE with all 21 phases - scripts/run.sh: updated examples - .gitignore: added Videos/, imgui.ini, cortex.mp4 - Removed tracked imgui.ini and video files
This commit is contained in:
emil28092005
@@ -2,7 +2,7 @@
|
||||
|
||||
## Project Overview
|
||||
|
||||
Cortex Engine is a C# (.NET 9) AI-Native 3D game engine. The primary render backend is Raylib-cs (OpenGL). A Vulkan backend exists but is deferred.
|
||||
Cortex Engine is a C# (.NET 9) AI-Native 3D game engine with a pure P/Invoke Vulkan 1.3 render backend. No wrapper libraries (Silk.NET, Vortice, OpenTK) — direct Vulkan API calls via `vkGetInstanceProcAddr`/`vkGetDeviceProcAddr`.
|
||||
|
||||
## Build Commands
|
||||
|
||||
@@ -10,31 +10,28 @@ Cortex Engine is a C# (.NET 9) AI-Native 3D game engine. The primary render back
|
||||
# Build (Debug)
|
||||
dotnet build CORTEX_ENGINE.sln -c Debug
|
||||
|
||||
# Build (Release)
|
||||
dotnet build CORTEX_ENGINE.sln -c Release
|
||||
|
||||
# Run the engine
|
||||
./scripts/run.sh
|
||||
|
||||
# Run with test scene + camera tour (headless screenshot capture)
|
||||
dotnet run --project src/CortexEngine.App/CortexEngine.App.csproj -c Release -- --test-scene --camera-tour --mcp-port 0
|
||||
# Run with MCP server (AI control via HTTP/SSE)
|
||||
./scripts/run.sh -- --mcp-port 5000
|
||||
|
||||
# Run with MCP server
|
||||
./scripts/run.sh --mcp-port 5000
|
||||
# Run tests
|
||||
dotnet test tests/Engine.Tests/Engine.Tests.csproj -c Debug
|
||||
```
|
||||
|
||||
## Lint / Typecheck
|
||||
|
||||
No separate lint command. `dotnet build` with 0 warnings is the standard. Run `dotnet build CORTEX_ENGINE.sln -c Release` to verify.
|
||||
No separate lint command. `dotnet build` with 0 errors is the standard. Run `dotnet build CORTEX_ENGINE.sln -c Debug` to verify. 227 xUnit tests cover Vulkan struct sizes, enum values, OBJ loading, vertex layout, shadow mapping, camera controllers, AI commands.
|
||||
|
||||
## Architecture
|
||||
|
||||
- **Engine.Core** — `IWindow`, `IInputState`, `Key` enum, `Sdl3Window`, camera controllers, ECS components (`Transform`, `Mesh`, `Material`, `Light`, `Camera`), `Timing`
|
||||
- **Engine.Graphics** — HAL interfaces (`IRenderContext`, `IRenderer`), `RenderBackendFactory`, mesh loaders (`ObjLoader`, `GltfLoader`)
|
||||
- **Engine.Graphics.Raylib** — Primary backend. `RaylibWindow` (GLFW), `RaylibInputState`, `RaylibRenderer` with custom GLSL 330 shader (Fresnel, ACES, gamma)
|
||||
- **Engine.Graphics.Vulkan** — Deferred backend. Compiles but untested. Uses `Sdl3Window` for Vulkan surface.
|
||||
- **Engine.AI** — `AiCommandProcessor` (7 commands), MCP HTTP + stdio servers
|
||||
- **CortexEngine.App** — Entry point, main loop, scene setup
|
||||
- **Engine.Core** — `IWindow`, `IInputState`, `Key` enum, `Sdl3Window` (SDL3 + Vulkan surface), camera controllers (`FreeFly`, `Orbit`), ECS components (`Transform`, `Mesh`, `Material`, `Light`, `Camera`, `RigidBody`), `Vertex` struct, `Timing`
|
||||
- **Engine.Graphics** — HAL interfaces (`IRenderContext`, `IRenderer`, `IScreenshotProvider`), `RenderBackendFactory`, `ObjLoader`, `MeshMath`, `ProceduralMesh`, `SceneSerializer`
|
||||
- **Engine.Graphics.Vulkan** — Pure P/Invoke Vulkan 1.3 backend. Vulkan 1.3 features: dynamic rendering, synchronization2, imageCubeArray. Multi-light PBR with cubemap array shadows. ImGui integration. Video recording via FFmpeg pipe.
|
||||
- **Engine.Physics** — JoltPhysicsSharp wrapper, `PhysicsWorld`, `RigidBody` component (box/sphere colliders)
|
||||
- **Engine.AI** — `AiCommandProcessor` (7 commands), `AiCommandQueue` (thread-safe), MCP HTTP server (Kestrel + SSE), stdio MCP server
|
||||
- **CortexEngine.App** — Entry point, main loop, scene setup, ImGui debug panels
|
||||
|
||||
## Key Conventions
|
||||
|
||||
@@ -42,25 +39,26 @@ No separate lint command. `dotnet build` with 0 warnings is the standard. Run `d
|
||||
- Input is backend-agnostic via `IInputState` + `Key` enum. No SDL3 types in app code.
|
||||
- Camera controllers use `IInputState`, not `InputMapping` directly.
|
||||
- `RenderBackendFactory.Create(name, width, height, validation)` — backends register by name.
|
||||
- Custom mesh CPU data uses `NativeMemory.Alloc` (not `Marshal.AllocHGlobal`) to match Raylib's `RL_FREE`.
|
||||
- `SetShaderValue` uses `float[]` for vectors, not `Vector3`/`Vector4` (marshaling reliability).
|
||||
- Backface culling disabled (`Rlgl.DisableBackfaceCulling`) for mixed-winding meshes.
|
||||
|
||||
## Current Roadmap
|
||||
|
||||
See `CORTEX_ENGINE_ARCHITECTURE.md` §11 for the full roadmap. Short-term priorities:
|
||||
- Unit tests
|
||||
- Texture loading verification
|
||||
- ImGui integration (medium-term)
|
||||
- Vulkan types split into `VulkanHandles.cs`, `VulkanEnums.cs`, `VulkanStructs.cs` — struct sizes verified by tests against C headers.
|
||||
- Push constants: single range, `Vertex|Fragment`, 64B (main pipeline) or 160B (shadow pipeline).
|
||||
- Light data in SceneUBO (448B): `mat4 vp` + `int numLights` + `int numShadowLights` + `LightData[8]` + `shadowParams[4]` + `ambientColor`.
|
||||
- Shadow cubemap array: 24 layers (4 lights × 6 faces), `samplerCubeArray` in shader, 16-tap Poisson disk PCF.
|
||||
- `vkCmdCopyImageToBuffer` for video recording, BGRA format, FFmpeg pipe.
|
||||
- Matrix convention: `view * proj` (row-major, no `row_major` in GLSL). `proj.M22 *= -1` for Vulkan Y-down.
|
||||
|
||||
## Files Not to Edit
|
||||
|
||||
- `src/Engine.Graphics.Vulkan/Shaders/*.spv` — compiled SPIR-V, regenerate from `.vert`/`.frag` with `glslangValidator -V`
|
||||
- `CORTEX_ENGINE_ARCHITECTURE.md` — canonical architecture reference, update only when architecture changes
|
||||
- `src/Engine.Graphics.Vulkan/Shaders/*.spv` — compiled SPIR-V, regenerate from `.vert`/`.frag` with glslangValidator
|
||||
|
||||
## Environment
|
||||
|
||||
- .NET 9 SDK at `$HOME/.dotnet`
|
||||
- `DOTNET_ROOT` and `PATH` must include `$HOME/.dotnet`
|
||||
- Raylib-cs 8.0.0 (Raylib 6.0 native library bundled in NuGet)
|
||||
- Display required (X11/Wayland) for Raylib window
|
||||
- SDL3 (ppy.SDL3-CS 2026.520.0, bundled native libSDL3.so)
|
||||
- ImGui.NET 1.91.6.1
|
||||
- JoltPhysicsSharp 2.21.0
|
||||
- Vulkan 1.3+ (validation layers recommended for development)
|
||||
- FFmpeg (for video recording feature)
|
||||
- glslangValidator (for shader compilation: `sudo apt install glslang-tools`)
|
||||
- Display required (X11/Wayland) for Vulkan window
|
||||
|
||||
Reference in New Issue
Block a user