- EVENGINE_ENABLE_STRICT_WARNINGS option: MSVC /W4 /WX, GCC/Clang
-Wall -Wextra -Werror, with documented noise suppressions and
-isystem/-external:I for third-party headers; enabled on the
Windows/Linux debug CI jobs.
- Fix warnings across engine, modules and tests exposed by the gate,
including real bugs (incomplete-type deletes, Timespan microsecond
overflow, overload hiding, enum switch gaps, dead code).
- Add Linux ASan+UBSan job, example smoke step, python-tools test
job, ruff config (scripts+tools), weekly Linux coverage job and a
CodeQL workflow.
DevLab's hot-reload test was failing deterministically on Linux: any --debug
run that reloads a script hit 'state reload: capture failed: root
'spritestack' is a class instance' because every module instance lives in the
Squirrel root table and Snapshot's auto-scan treated the first instance root
as a fatal capture error. With break-on-error enabled the engine paused at
the reported error, and a subsequent eve_eval deadlocked the pause pump.
- Snapshot::resolveRoots: drop OT_INSTANCE from the automatic root scan so
module singletons / class instances are skipped instead of aborting the
capture (plain-data roots such as gameState/lab are still captured).
- Debugger::waitWhilePaused: make the pause pump re-entrant so bytecode run
by eve_eval / watches / breakpoint conditions while paused no longer blocks
on the same thread's line hook (deadlock).
- test: new devtools.snapshot.skipsInstanceRootInAutoScan case.
Verified in WSL (Linux/GCC, software Vulkan + Xvfb): devlab MCP hot-reload
test 12/12 rounds, full ctest 1656/1656, all 37 example smokes pass.
- Capture full call stack + throw-site in the Squirrel runtime error hook
(new common/ScriptError.{h,cpp}) and surface it through ScriptException
(line/column/function/stackTrace/reported accessors).
- Runtime installs its own error hook and drives execute() with a raw
sq_call, fixing a null-deref when DevTool's hook replaces ssq's default
runtime error handler.
- Compile errors now carry source line/column plus a snippet with caret.
- REPL/MCP/Debugger eval paths return the real error text instead of
generic 'compile failed' / 'runtime failed'.
- Run() skips a second DevTool report for hook-reported script errors.
- ECS bootstrap compile/run failures are printed instead of swallowed.
* chore(ci): add clang-format gate, CODEOWNERS and agent collaboration rules
* refactor(modules): clear remaining back-edges and split the largest TUs
Three known dependency back-edges are gone (module_depgraph.py KNOWN_BACK_EDGES
is now empty; --check passes with 0 violations, 0 cycles):
- window -> graphics: window queries the new IWindowSurfaceHost capability
(common/WindowSurfaceHost.h) instead of holding a Graphics pointer;
Window::setGraphics was removed and all call sites updated.
- window -> image: Window::setIcon was replaced by setIconRGBA(const uint8_t*,
w, h); the window no longer decodes ImageData.
- scene -> graphics: pickScreenAt / collectFrustumIdsAt implementations moved
to graphics/ScenePicking.cpp (graphics -> scene is a legal downward edge);
scene now depends only on spatial.
TU splits (pure moves, verified identical method sets and brace balance):
- vulkan/Graphics.cpp (5118 lines) -> Graphics.cpp (lifecycle), GraphicsPipeline,
Graphics2D, Graphics3D, GraphicsMesh + shared GraphicsInternal.h.
- scene/Scene.cpp -> Scene.cpp (script layer / host lifecycle / serialization)
+ SceneNodes.cpp + shared SceneInternal.h.
Verified with a real build (MSVC 19.51, prebuilt third-party): full build green;
window.* and Scene.* suites pass, including scene picking/culling and GPU cases.
* refactor(graphics): narrow Graphics interfaces and clear public-header leaks
Step 4 — interface segregation:
- New lean interfaces: IGraphics2D, IGraphics3D, IResourceFactory, IPostFX
(pure virtuals, forward-declared types only; graphics/Color.h extracted from
Canvas.h so modules that only need the color type stop pulling Canvas.h).
- Graphics now implements all four facets; consumers can depend on the narrow
interface they use instead of the 129-method god class.
- Migrated voxel (VoxelWorld::drawVisible -> IGraphics3D*) and model3d
(ModelRenderer::buildRenderable(s) -> IResourceFactory&).
- Graphics.h slims from 24 sub-header includes to a handful of small type
headers + forward declarations; the destructor moved out-of-line so
unique_ptr effect members are destroyed where types are complete.
Step 5 — header leaks (module_depgraph.py '*' marks: 14 -> 7):
- map/TileLayer.h, particles/ParticleEmitter.h, avatar/AvatarInstance.h,
animation/SpineAnim.h, map/TileSystem.h, model3d/ModelData.h,
model3d/ModelRenderer.h, audio/Audio.h + Source.h, image/ImageData.h +
Image.h, dialogue/Dialogue.h, procgen Palette/OutputSpec/TextureRecipe/
PbrMaterial -> forward declarations, includes moved to .cpp.
- voxel/VoxelWorld.h: terrain sampler Pimpl'd (unique_ptr + out-of-line
destructor), removing the procgen header dependency.
- gpgpu/vulkan backend headers stop pulling graphics/vulkan/Graphics.h.
- Remaining '*' marks are deliberate: tiny POD/enum headers (GridConfig,
MapObject, BlendMode, Color), an internal backend header
(GraphicsInternal.h -> filesystem), and lean interface references.
Verified with a full clean build (MSVC) and tests: window/Scene/voxel/
RenderSystem/Quad/shader/TextureSampler/resourceLifetime pass; broad suite
only shows the pre-existing PHYSFS-init filesystem-environment failures.
* feat(resources): revive ResourceManager as unified IAssetReloader-backed cache
* fix(resources): leak ResourceManager singleton to avoid exit-time teardown crashes
Cached CPU resources may own third-party handles (FreeType faces, Assimp
scenes, image decode handlers) whose libraries are torn down at process
exit in an unspecified TU order; destroying cached entries from the
singleton destructor can segfault at exit (seen on CI Windows in
model3d.materialApi.objMtl). Keep the singleton alive until OS reclaim;
explicit unload()/clear() still release entries during the run.
* refactor(devtools): consume business modules through capability interfaces
DevTools / cmdline no longer include business-module headers, so trimming
scene / physics / procgen / particles / audio / ui / graphics no longer
requires disabling devtools, and devtools can be switched off with
-DEVENGINE_MODULE_DEVTOOLS=OFF.
New capability interfaces in common/:
- ISceneQuery (scene) - host/node inspection + mutation + transform sync
- IRenderCapture (graphics) - render status, PNG capture, camera control,
visible-entity snapshot, entity-ID mask, G-buffer PNGs
- IPhysicsQuery (physics) - 2D world lifecycle + ray casts
- IProcgenQuery (procgen) - recipe listing, map/mesh generation
- IParticlesQuery (particles) - emitter status + one-shot emit
- IAudioQuery (audio) - volume / stop-all
- IEditorHost (ui) - declarative editor host (used by cmdline too)
Providers register in their module constructors. DevTools rewires McpServer
(render/scene/procgen/physics/particles/audio/host tools), SceneInspect
(now delegates to ISceneQuery + IRenderCapture) and RenderVision (uses
IRenderCapture::capturePngDataUrl); cmdline/Mcp.cpp uses IEditorHost.
manifest: devtools DEPS graphics scene physics procgen particles audio ui
image event filesystem -> event; cmdline DEPS filesystem ui -> filesystem.
Verified: full build green; devtools.mcp.* tests pass; broad suite shows
only the pre-existing PHYSFS-init filesystem-environment failures.
* style: apply clang-format to changed lines after dev merge
* fix(webgpu): include RenderControl/TextureSampler explicitly after Graphics.h slimming
* fix(webgpu): provide newFont/print stubs to satisfy IGraphics2D/IResourceFactory vtables
* fix(common): make ProcgenQuery.h self-sufficient (cstdint/utility for GCC)
Runtime now validates stackSize before constructing the Squirrel VM (previously the check ran after member initialization). DevTools singletons (AiPanel/ConsolePanel/McpServer/RenderVision) keep their process-immortal lifetime - required by the detached stdio reader thread and cross-singleton calls - but move from scattered raw new leaks to a single documented Immortal holder.
Normalize all header comments to Doxygen @brief form and fill in missing class/method docs across engine common, cmdline, and module headers (~2368 @brief entries). Add root Doxyfile, 'make docs' target, CMake docs target, .gitignore for docs/api, README/docs/dev updates, and a Windows (native) + code-conventions section in AGENTS.md.
A scene link keeps an external object in step with the node it hangs off. The
kinds were a closed enum with a switch in TransformSystem, so scene had to
include graphics, physics and audio to do the casts, and no other module could
ever attach to the tree without editing SceneHost.h -- particles, voxel,
spritestack, avatar and weather all had to stay outside it.
Kinds are registered now (scene/SceneLink.h). The module owning the target type
supplies pushWorld / pullWorld / alive, keeps the casts on its own side where
the type is complete, and scene never learns what a Renderable3D is. Dispatch is
a function-pointer table rather than virtual calls, since link sync runs for
every dirty node every frame.
The six typed helpers (linkRenderable2D and friends) stay as conveniences and
now resolve their kind by name, so they return false rather than crash when the
module that registers it was trimmed out. The script API already named kinds
with strings, which is exactly the registry key, so it is unchanged.
Direction is now the right way round: graphics, physics and audio depend on
scene rather than scene on them, and scene drops from L5 to L1. What remains is
scene -> graphics from pickScreenAt / collectFrustumIdsAt, which take a Camera3D
and read its projection; that is recorded in the back-edge whitelist as the next
thing to move.
Each provider lives in a SceneLinks.cpp, sharing the basename so the three come
out of the build together when scene is disabled.
Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>
Adds 'eve mcp': a desktop-only headless MCP host (stdio by default, --port for TCP, --root for the project). It runs the full runtime, attaches DevTools (eve_eval / eve_run_script / snapshot), and starts the new EditorHost module that renders JSON-defined editor Views (ImGui) bound two-way to Squirrel ViewModel tables (MVVM), persists editors under editors/, and exposes the eve_host_* tool family (apply/state/set_value/events/capture/script/shutdown...). The stdio transport uses a background stdin reader and keeps stdout JSON-RPC-only; script print() is routed to stderr.
Tests: stdio handshake + tools/list round trip, host editor binding (VM<->View sync, set_value -> VM write + onChange events, save/reload persistence). Docs updated (AI与MCP支持.md, 命令行设计.md, tools/eve-mcp README) with the editor JSON protocol and Codex stdio setup.
Add the scene_director Squirrel kit (src/scripts/scene_director.nut) with
spawn/move/scale/rotate/remove/material/lighting/camera/cameras/info/modify/
reset, embedded into the engine and exposed to host games as
eve.sceneDirectorScript. New MCP tools (eve_scene_director_install/status,
eve_scene_reset, eve_scene_modify, eve_scene_info, eve_camera_generate) are
thin dispatchers over the kit, so agents can place props, set lighting,
frame cameras, inspect truth and reset the stage through MCP alone.
The kit's cross-references are written explicitly as scene_director.<field>
to avoid Squirrel table-closure his resolution, and cameras() uses a
fixed 6-way compass table (no math-lib dependency) so it works both in the
engine and in plain ssq test VMs.
- Fixed the JSON schema for the 'capture_render_frame' tool by adding a missing closing brace.
- Ensured proper structure for the input schema to maintain consistency and prevent potential parsing errors.
Adds a vision-model bridge (devtools/RenderVision) that captures the
current frame (Graphics readback -> PNG data URL) and sends it with
engine render parameters to an OpenAI-compatible vision model over
plain HTTP, returning prose that describes the frame and explains the
render-parameter <-> visual-result correspondence for other LLM agents.
- New MCP tools:
- eve_render_describe (fresh/reason; cached otherwise)
- eve_render_vision_config (set/read config, key masked)
- Breakpoint hit and runtime-error pause auto-flag a pending dump that
McpServer::poll performs on the main (render) thread.
- Config via env (EVE_VISION_BASE_URL/API_KEY/MODEL/PATH/TIMEOUT_MS)
or the config tool.
- No TLS/OpenSSL is linked, so the endpoint must be plain HTTP (works
with local Ollama/vLLM/LM Studio).
- Compiles cleanly on MSVC (C++20); tests extended for new tools.
ImageData::getConstant is declared but never defined, causing LNK2019 /
undefined-reference link failures on all CI platforms. Use the
medialoader::FormatHandler::ENCODED_PNG constant directly for the
eve_screenshot PNG encode.
Add 18 new MCP tools to the embedded McpServer so agents can drive
the live game beyond the debugger surface:
- scene/entity query + transform mutation
- procgen recipe enumeration, map grid generation, mesh build
- 2D physics world create/list/raycast/remove
- render status + frame screenshot (PNG)
- particle emitter spawn, audio master control
Tool handlers use ModuleManager to reach Scene/Procgen/Physics/
Graphics/Particles/Audio and degrade gracefully when a module is
not mounted. Extend the tools/list and unit-test coverage.
The Squirrel native debug hook is invoked as a direct C call, so the top of the call stack (level 0) is the current script frame. The debugger, DAP adapter, and DevTool read locals/stack at level 1, which skipped the current frame: stackTrace omitted the innermost frame and the variables panel showed the caller's locals instead.
Read stack frames/locals at level 0 across Debugger::stackTrace, Debugger::locals, Debugger::evaluate, Debugger::scriptStackDepth, DebugAdapter variables requests, and DevTool local sampling.
Adds debugger_audit.cpp (breakpoint hits, stepInto/stepOver/stepOut, call stack at nested breakpoint, locals at breakpoint) and a threaded DAP end-to-end test that runs a real script and verifies the stopped event and the full call stack.
- Introduced AiPanel for managing AI-related debugging information, including logging and visibility controls.
- Added McpServer to facilitate communication with the debugging interface, supporting JSON-RPC for various commands.
- Updated CMake configurations to include new dependencies and libraries for the devtools.
- Enhanced Vulkan SDK detection in CMake for improved compatibility on Windows platforms.
- Refactored existing CMakeLists for better organization and readability.
Forward-declare McpServer/AiPanel in DevTool.hpp, bridge MCP away from
DevTool.hpp inside DebugAdapter's TU, emit tools/resources/prompts lists
as static JSON (fewer Poco template exports), and drop the ImGuiBackend
AI drawer that instantiated more imgui inlines under WINDOWS_EXPORT_ALL_SYMBOLS.
Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>
Fold McpServer and AiPanel implementations into DebugAdapter.cpp and
DevTool.cpp via .inc includes so WINDOWS_EXPORT_ALL_SYMBOLS does not add
extra Poco JSON-heavy object files (LNK1189). Keep prior macOS singleton
and ImGui drawer fixes.
Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>
Windows failed with LNK1189 after AiPanel.cpp included imgui.h under
WINDOWS_EXPORT_ALL_SYMBOLS. Keep AiPanel data-only and register the ImGui
drawer from ImGuiBackend on desktop.
macOS MCP tests aborted after pass with mutex lock failed during static
destruction; leak McpServer/AiPanel singletons so teardown order cannot
invalidate their mutexes.
Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>
Raw `new Object()` values stored in Dynamic::Var broke Stringifier with
BadCast during tools/list. Wrap nested objects/arrays in Ptr, emit
compact JSON for newline framing, and convert request fields safely.
Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>
Expose a localhost MCP JSON-RPC server (--mcp-port) alongside DAP so AI
agents can pause, eval, snapshot, and slice errors on a live session.
Add DevTools AI session log/ImGui panel (eve.dev.ai, F9) and a Cursor
stdio bridge under tools/eve-mcp.
Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>
- Added support for DAP (Debug Adapter Protocol) in the DebugAdapter, allowing for better integration with IDEs like VS Code.
- Implemented new debugging commands: stepInto, stepOver, and stepOut, enhancing script execution control.
- Updated CallGraph to use a fixed ring buffer for event storage, improving performance and memory management.
- Introduced methods for resolving source paths and managing script aliases, facilitating smoother debugging experiences.
- Enhanced documentation to reflect new features and usage instructions for debugging tools.
These changes significantly improve the debugging workflow and provide developers with more robust tools for script management and error tracing.
* feat(devtools): pause, breakpoints, watches, snapshots, and VS Code DAP
Add a script-centric debugger: Pause key / DAP frame pause, Squirrel
breakpoints with watches, JSON snapshot of script state (stateless
engine), TCP Debug Adapter Protocol server, and a VS Code extension
under tools/vscode-eve-debug.
Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>
* fix(devtools): correct Snapshot JSON (Poco Ptr) and DAP includes
Use Poco::JSON::Object/Array::Ptr for script-state capture/restore so
round-trips no longer BadCast; include TimeoutException via Exception.h.
Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>
* fix(devtools): move DebugAdapter ctor to cpp for MSVC unique_ptr
MSVC rejects unique_ptr of forward-declared Poco sockets when the
default constructor is defined in the header (incomplete-type delete).
Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>
* fix(devtools): disable Poco auto-link on EVDevTools for MSVC
Including Poco Net/JSON without POCO_NO_AUTOMATIC_LIBS makes the
Windows linker request PocoFoundationd.lib instead of PocoFoundationmdd.
Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
* feat(devtools): add dynamic slicer for script error tracing
Record call/return/line and Def/Use data-flow in CallGraph, attach a
Squirrel native debug hook via DevTool, and emit a Weiser-style backward
slice report on failures when running with `eve run --debug`.
Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>
* fix(devtools): use one-in-one-out ring buffer for trace events
Replace half-window drops with a deque ring buffer: when full, each new
event evicts exactly one oldest event, with monotonic ids and index cleanup.
Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>
* feat(devtools): add render-pipeline error tracing
Introduce common RenderTrace hooks and a RenderFlow slicer so Graphics
passes/binds/draws are attributed on failure. Wire RenderSystem 2D/3D,
mark Exception sites, and merge render reports into DevTool --debug output.
Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>
* test(devtools): expand CallGraph and RenderFlow coverage
Add extensive unit tests for source locations, data-flow slicing,
ring-buffer eviction, nested passes/binds, Exception hooks, and RAII
scopes (54 cases / 202 assertions under ^devtools\.).
Co-authored-by: 西风逍遥游 <sunxfancy@gmail.com>
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
西风逍遥游