Skip to content

AGENTS.md

Latest commit

 

History

History
117 lines (88 loc) · 5.93 KB

AGENTS.md

File metadata and controls

117 lines (88 loc) · 5.93 KB
Raw

PrismaEngine — Agent Guide

Active branch

  • dev — all development work happens here. main is stable releases only.
  • CI triggers on main, develop, dev.

Build system

  • CMake 3.31+ required. Use --preset (see CMakePresets.json).
  • Prune branch: Only SDL3 + Vulkan + ImGui. DX12/OpenGL/XAudio2 are FORCE-disabled in cmake/DeviceOptions.cmake — do not enable them.
  • Dependency management: FetchContent by default (no vcpkg needed). Set -DPRISMA_USE_FETCHCONTENT=OFF for vcpkg.
  • Targets: Engine (core lib), Launcher (executable), Editor, SDK packaging.
  • Sample projects (in projects/): Prisma2D, PathTracing3D, PacManGame, PrismaCraft, ClusteredForward3D, Deferred3D, MetroidvaniaDemo.
    • CI builds always pass -DPRISMA_BUILD_PROJECT_*_MANAGED=OFF to skip sample projects.
    • Each project has its own CMakeLists.txt and is gated by a PRISMA_BUILD_PROJECT_* option in projects/CMakeLists.txt.

Key build commands

cmake --preset linux-x64-debug                          # Configure
cmake --build build/linux-x64-debug --parallel          # Build everything
cmake --build build/linux-x64-debug --target Engine     # Build only Engine
cmake --build build/linux-x64-debug --target PathTracing3D

C# scripting

  • CoreCLR backend. Set DPRISMA_ENABLE_SCRIPTING=CORECLR (default).
  • Managed assemblies follow the pattern <Project>.Scripts.dll (e.g. Prisma2D.Scripts.dll).
  • InternalsVisibleTo is used — each project's managed DLL is listed in Prisma.Bindings.csproj.
  • Script entry point: ScriptEntry.Bootstrap() / ScriptEntry.OnFrame().
  • Script search path is hardcoded in src/engine/app/Engine.cpp.
  • Termux/restricted VM: .NET 10+ GC region reservation may fail — set DOTNET_GCRegionRange=0x10000000.

Code conventions

  • C++23, PascalCase classes, camelCase functions, m_ member prefix.
  • Namespace PrismaEngine { namespace Graphic { ... } } for engine code.
  • No (void) casts for unused params — use [[maybe_unused]].
  • Third-party warnings (VMA, glaze, SPIRV-Tools) suppressed via CMake flags, never by modifying library source.
  • Mixed Chinese/English comments in source files — normal for this repo.

2D Engine Enhancements (June 2026)

Physics2D

  • src/engine/physics2d/Quadtree2D.h/.cpp — spatial partitioning
  • src/engine/physics2d/Trigger2D.h/.cpp — trigger volumes

2D Lighting

  • src/engine/graphic/2d/ShadowCaster2D.h — shadow caster component
  • src/engine/graphic/2d/Light2DPass.h/.cpp — shadow rendering integration
  • assets/shaders/ShadowGeometry.vert/.frag — shadow geometry shaders

2D Graphics

  • src/engine/graphic/2d/PostProcessPass2D.h/.cpp — Bloom, Grayscale, Distortion
  • src/engine/graphic/Renderer2D.h/.cpp — DrawAnimatedSprite added
  • src/engine/graphic/SpriteAnimation.h/.cpp — GetCurrentUV() added
  • resources/common/shaders/glsl/2d/ — 6 post-processing + instanced tilemap shaders

Tilemap

  • src/engine/tilemap/TilemapRenderer.h/.cpp — GPU instancing added

Audio

  • src/engine/audio/AudioZone2D.h/.cpp — 2D zone audio

LSP / clangd

  • .clangd at repo root has all include paths pre-configured.
  • The compile_commands.json symlink is in .gitignore but regenerated by CMake.

Testing

  • No general test framework. PRISMA_BUILD_TESTING=OFF by default.
  • MCP (Editor layer, not Engine). No general MCP test target currently.
  • enable_testing() is called in LauncherTargets.cmake and EditorPostTargets.cmake for downstream CTest support.

Shaders

  • GLSL source in resources/common/shaders/glsl/, HLSL in resources/common/shaders/hlsl/.
  • .spv files are gitignored — compiled at build time via glslangValidator (for projects) or Gradle (Android).
  • If .spv files are stale or missing, rebuild or delete them; they will be regenerated.

SDK

  • sdk/ contains public headers + CMake config for external projects (find_package(PrismaEngine)).
  • Prebuilt binaries are not in the repo — released on GitHub Releases as PrismaEngine-SDK-* archives.
  • scripts/sync-sdk-headers.sh syncs public headers to sdk/include/.

Git conventions

  • Commit style: semantic (feat:, fix:, refactor:, chore:, docs:).
  • Branch: dev (not main or develop).
  • Do not add Co-authored-by or Ultraworked with footers to commits (user preference).

CI

Platform Workflow Notes
Windows ci-windows.yml VS 2022, Engine + MetroidvaniaDemo
Linux ci-linux.yml Ninja, Engine + MetroidvaniaDemo, dotnet SDK 10.0.x
Android ci-android.yml NDK r28, API 34
Release release.yml All platforms, triggered by tags

CI workflows are in .github/workflows/. Linux CI sets up dotnet SDK 10.0.x and all platform CI builds now include -DPRISMA_BUILD_PROJECT_METROIDVANIADEMO=ON.

Notable quirks

  • MSVC: _DISABLE_CONSTEXPR_MUTEX_CONSTRUCTOR is defined globally (binary compat workaround).
  • project(PRISMA ...) — the CMake project name is PRISMA, not PrismaEngine.
  • Thread pool / job system: src/engine/threading/JobSystem.cpp, ThreadManager.cpp.
  • Physics: src/engine/physics/ — AABB collision, raycast, sweep.
  • 2D Physics: src/engine/physics2d/Quadtree2D.h/.cpp, Trigger2D.h/.cpp — 2D quadtree collision + triggers.
  • 2D Graphics: src/engine/graphic/2d/PostProcessPass2D.h/.cpp (Bloom/Grayscale/Distortion), Light2DPass.h/.cpp (shadow rendering), ShadowCaster2D.h.
  • Audio: src/engine/audio/AudioZone2D.h/.cpp — 2D zone audio.
  • Tilemap: src/engine/tilemap/TilemapRenderer.h/.cpp — GPU instancing tilemap.
  • 2D Shaders: assets/shaders/ShadowGeometry.vert/.frag, PointLight2D.vert/.frag, resources/common/shaders/glsl/2d/ (6 shader files for post-processing + tilemap instancing).
  • MCP (AI agent protocol): src/editor/mcp/, enabled by PRISMA_ENABLE_MCP=ON (Editor scope).
  • CI now includes -DPRISMA_BUILD_PROJECT_METROIDVANIADEMO=ON and dotnet SDK 10.0.x setup.