# Project Architecture Layout > Quick map of engine layout and key systems. Use this skill when you need to understand where files should be located. Use when this capability is needed. - Skill: `tomevault-io/project-architecture-layout` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/project-architecture-layout` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/project-architecture-layout/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/project-architecture-layout --- # Project Layout ## When to use this skill - You need to know where to place or find engine code, public headers, shaders, examples, or tests. - You are wiring new features into the engine and want the correct header/implementation/test locations. - You are orienting an AI agent to the repo so it can navigate modules without guessing. ## Directory map (top-level) - include/vde/ – Public engine API (Window, VulkanContext, Camera, Texture, BufferUtils, ShaderCache, UniformBuffer, DescriptorManager, Types, helpers). - include/vde/api/ – Game-facing API layer (Game, Scene, Entity, Mesh, CameraBounds, GameCamera, LightBox, WorldBounds, WorldUnits, input types). - src/ – Engine implementations matching include/vde/ (VulkanContext, Window, Texture, BufferUtils, ShaderCompiler/ShaderCache, ImageLoader, HexGeometry, HexPrismMesh, DescriptorManager, UniformBuffer, ShaderHash, stb impl). - src/api/ – Implementations for the gameplay API (Game, Scene, Entity, Mesh, GameCamera, CameraBounds, LightBox, GameTypes). - shaders/ – GLSL sources for core examples (triangle, sprite, mesh variants). - examples/ – Sample apps demonstrating engine usage (triangle, sprite demo, simple_game, world_bounds_demo). Each has its own CMake target. - tests/ – Google Test suite covering engine and game API components (Camera, Window, VulkanContext-adjacent helpers, HexGeometry, Mesh, Scene, GameCamera, WorldBounds, etc.). Registered via tests/CMakeLists.txt. - scripts/ – Build/test helpers (PowerShell build-and-test.ps1). - docs/ – Project docs (ARCHITECTURE, API guides, getting started). - build/, build_ninja/ – Generated build trees; do not edit. - third_party/ – Vendored dependencies (stb) and CMake-managed externals (GLFW, GLM, glslang, GTest via FetchContent). ## Key modules and their homes - Core: Window + VulkanContext handle GLFW surface + Vulkan instance/device/swapchain/render pass/command buffers/sync; lives in include/vde/{Window,VulkanContext}.h and src/{Window,VulkanContext}.cpp. - Rendering helpers: Texture (image load + staging + sampler/view), BufferUtils (buffer creation/copies), DescriptorManager, UniformBuffer utilities; headers in include/vde/, impls in src/. - Shaders: ShaderCompiler (glslang runtime compile) and ShaderCache (hash + cache) in include/vde/{ShaderCompiler,ShaderCache}.h and src/{ShaderCompiler,ShaderCache,ShaderHash}.cpp. - Geometry: HexGeometry + HexPrismMesh generation utilities in include/vde/{HexGeometry,HexPrismMesh}.h with src counterparts. - Math/Types: Types.h defines shared structs (vertices, uniforms); QueueFamilyIndices/SwapChainSupportDetails provide Vulkan selection helpers. - Game API: High-level gameplay layer in include/vde/api/ with impls in src/api/ for Game, Scene, Entity, Mesh, GameCamera/Bounds, LightBox, GameTypes. - Umbrella header: include/vde/Core.h re-exports public engine API for consumers. ## Build + test entry points - CMake project root: CMakeLists.txt (engine + examples + tests). Generated builds live under build/ (VS solution) or build_ninja/. - Scripted flow: scripts/build-and-test.ps1 (configure, build, run Google Tests). Accepts -BuildConfig and -Filter. - Tests: built test binary under build/.../tests/Debug/vde_tests.exe when using the default VS generator. ## Placement guidance - New public engine API: add header in include/vde/, implementation in src/, register target in root CMakeLists.txt, and include via Core.h if part of the main surface. - New gameplay-facing API: add header in include/vde/api/, implementation in src/api/, register in CMake, and add coverage in tests/ with matching CMakeLists entry. - New sample: add under examples/, update examples/CMakeLists.txt, provide shader assets in shaders/ if needed. - New shader assets: place in shaders/, referenced by examples or engine runtime loaders. ## Notes for agents - Namespace is vde::; prefer RAII around Vulkan handles. Check conventions skill for style details. - Generated build directories should stay untouched; source edits belong in include/, src/, src/api/, shaders/, tests/, and examples/. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/derekdk) — claim your Tome and manage your conversions.