BuildSystem Integration Design Document
Date: May 16, 2026
** Status:** Approved
**Milestone:**M4 — Advanced Tools & Polish
Issue: #123
Namespace: Caffeine::Editor
Overview#
The BuildSystem Integration transforms Caffeine Studio into a complete game development environment, enabling creators to go from design to execution with one click. This system coordinates the entire compilation pipeline: asset cooking, script validation, runtime linking, and game execution.
Key Capabilities:
- Full-featured build pipeline (Windows_x64 and Linux_x64)
- Incremental builds with asset caching
- Real-time progress tracking and logging
- Automatic game execution with process waiting
- Comprehensive error handling and cleanup
Architecture#
Core Types#
namespace Caffeine::Editor {
enum class BuildPlatform : u8 {
Windows_x64 = 0,
Linux_x64 = 1
};
enum class BuildStatus : u8 {
Idle,
Validating,
PreparingOutput,
CompilingScripts,
CookingAssets,
LinkingExecutable,
GeneratingProject,
Success,
Failed,
Cancelled
};
struct BuildSettings {
std::string projectName;
std::string outputDir;
BuildPlatform platform;
bool isDebug = false;
bool incrementalBuild = true;
bool runAfterBuild = false;
std::vector<std::string> scenesToInclude;
std::string executableName;
std::string icon;
std::string version;
};
struct BuildProgress {
std::atomic<f32> progress = 0.0f; // 0.0 - 1.0
std::atomic<BuildStatus> status = BuildStatus::Idle;
std::atomic<bool> shouldCancel = false;
std::string currentTask;
};
}
BuildSystem Class#
Responsibility: Coordinate pipeline execution in background thread Key Methods:
ExecuteBuild()- Main entry point (runs in JobSystem thread)RunGameAndWait()- Launch and wait for game processValidateSettings(),PrepareOutputDirectory(),CompileScripts(), etc. - Pipeline stages
Design Pattern: Static coordinator with atomic progress tracking for thread-safe UI updates
BuildDialog Class#
Responsibility: ImGui configuration panel and progress display Key Methods:
render()- Draw UI sections (config, progress, logs, buttons)renderConfigSection()- Platform, paths, scene selectionrenderAdvancedSection()- Icon, version, executable namerenderProgressSection()- Progress bar, status, current taskrenderLogSection()- Scrollable build log
Design Pattern: Inherits editor panel patterns; polls atomic progress variables for thread-safe updates
Pipeline Execution Flow#
Stage-by-Stage Breakdown#
-
VALIDATE (0%)
- Check output path exists/writable
- Verify project.caffeine readable
- Validate platform is supported
-
PREPARE OUTPUT (5%)
- Create output directory structure
- Clear any existing build artifacts
-
COMPILE SCRIPTS (10%)
- Use LuaValidator to check syntax
- Report errors to console
- Abort if validation fails
-
COOK ASSETS (20% → 65%)
- Load build cache from
output_dir/.build_cache/ - For each texture: check mtime+hash, skip if cached, otherwise cook PNG/TGA → DDS
- For each shadow: check mtime+hash, skip if cached, otherwise compile GLSL → SPIR-V
- Save updated cache with new mtime/hash/size
- Load build cache from
-
** LINK EXECUTABLE** (65% → 85%)
- Copy CaffeineRuntime binary to output_dir
- Copy assets/ and scripts/ to output_dir/data/
- Set executable permissions on Linux
-
- GENERATE PROJECT* (85% → 95%)
- Create
project.caffeineJSON file - Include startup scenes, version, executable name
- Write to output_dir root
-
SUCCESS (100%)
- If
runAfterBuild == true:- Launch game executable
- Block and wait for process to close
- Log "Build complete" to console
- If
Failure Handling#
On any stage error:
- Log detailed error to console
- Call
CleanupOnFailure()→ Remove entry output dir - Set
status = BuildStatus::Failed - Allow user to fix issues and retry
Incremental Build System#
Cache File Format#
Location: output_dir/.build_cache/build_cache.json
{
"buildDate": "2026-05-16T14:30:00Z",
"platform": "Windows_x64",
"caffeineVersion": "0.2.0",
"assets": {
"textures/skybox_night.png": {
"modifiedTime": 1715867405,
"contentHash": "a3f5d8e2c1b4",
"cookedSize": 2097152,
"cooked": true
}
}
}
Cache Checking Logic#
Before cooking each asset:
- Load cache from
output_dir/.build_cache/ - Get current file mtime
- If cache entry exists:
- Compare mtime: if same, compute content hash
- Compare hash: if same, skip cooking
- If different: re-cook and update cache
- If no cache entry: cook and add to cache
- After all assets cooked: save updated cache
Asset Cooking Implementations#
Texture Cooking#
- Input: PNG, TGA, JPG
- Output: DDS (BC1/BC3 compression based on alpha)
- Uses: Existing
Assets::TextureCompilerAPI
Shader Cooking#
- Input: GLSL source (.vert, .frag, .comp)
- Output: SPIR-V binary format
- Uses: New
ShaderCompilerclass (integrate with existing RHI)
Script Validation#
- Input: Lua source files
- Output: Validation pass/fail + error messages
- Uses: Existing
Script::LuaValidatoror similar
Threading & UI Integration#
Execution Model#
- Main Thread: User clicks "Build & Run", schedules job
- Job Thread: Executes pipeline, updates atomic progress
- UI Thread (Main): Polls progress every frame, renders UI
Progress Updates (Thread-Safe)#
BuildProgress progress;
progress.progress = 0.2f; // Atomic update
progress.status = BuildStatus::CompilingScripts;
progress.currentTask = "Validating player.lua";
Dialog polls each frame:
float pct = m_progress.progress * 100.0f;
ImGui::ProgressBar(m_progress.progress);
ImGui::Text("Status: %s", StatusToString(m_progress.status));
ImGui::Text("Task: %s", m_progress.currentTask.c_str());
Cancellation#
- User clicks "Cancel" button
- Sets
progress.shouldCancel = true - Job checks flag between stages
- On cancel: cleanup and exit gracefully
Game Execution & Process Management#
Execution Flow (runAfterBuild = true)#
- After successful build, launch game:
std::string exePath = settings.outputDir + "/" + settings.executableName;
return RunGameAndWait(exePath);
-
Platform-specific process launching:
- Windows:
CreateProcess()+WaitForSingleObject() - Linux:
fork()+waitpid()orstd::system()
- Windows:
-
UI shows "Game running..." during wait
-
When game closes, return to build dialog
Platform-Specific Implementation#
Windows_x64#
- Runtime:
bin/CaffeineRuntime.exe - Output:
.exe+ data folder - Asset Format: DDS, SPIR-V
- Process launch:
CreateProcess()from<windows.h> - Binary detection: Check for
.exeextension
Linux_x64#
- Runtime:
bin/CaffeineRuntime(no extension) - Output: ELF binary + data folder
- Asset Format: DDS, SPIR-V (same as Windows)
- Process launch:
fork()+execv()from<unistd.h> - Permissions:
chmod +xon output binary
Error Handling Strategy#
Validation Errors#
- Missing/invalid paths
- Unsupported platform
- Action: Fail immediately in dialog, highlight field
Script Compilation Errors#
- Lua syntax errors
- Action: List all errors in console, don't proceed to asset cooking
- Recovery: User fixes script, clicks "Build & Run" again
Asset Cooking Errors#
- Texture not found
- Shader compilation failed
- Action: Log error, skip asset, continue build (allow partial builds)
- Recovery: Fix asset, rebuild
Link/Package Errors#
- Runtime not found
- Permission denied
- Action: Fail, cleanup output_dir completely
Cleanup on Failure#
static bool CleanupOnFailure(const std::string& outputDir) {
std::filesystem::remove_all(outputDir);
// Ensures no partial builds remain
return true;
}
Acceptance Criteria#
- ✅ Dialog allows configurable build settings (platform, debug/release, output path)
- ✅ "Build & Run" executes full pipeline and auto-launches game
- Console displays real-time built progress with detailed logs
- Incremental builds skip unchanged assets
- ✅ Build failure always cleans up output_dir
- Game process waits for close before returning to editor
- ✅ project.caffeine generated with startup scenes
- Supports Windows x64 and Linux x64 platforms
Files to Create#
doppio-archived/src/doppio/editor/BuildSystem.hpp- Core coordinator classdoppio-archived/src/doppio/editor/BuildSystem.cpp- Pipeline implementationdoppio-archived/src/doppio/editor/BuildDialog.hpp- ImGui paneldoppio-archived/src/doppio/editor/BuildDialog.cpp- Panel renderingdoppio-archived/src/doppio/editor/AssetCooker.hpp- Texture/shader cookingdoppio-archived/src/doppio/editor/AssetCooker.cpp- Asset processing
Dependencies#
- Upstream:
src/caffeine/project/ProjectManager.hpp(project config) - Upstream:
src/caffeine/assets/TextureCompiler.hpp(texture cooking) - Upstream:
src/caffeine/threading/JobSystem.hpp(background execution) - Upstream:
doppio-archived/src/doppio/editor/ConsoleWindow.hpp(log display) - New:
src/caffeine/render/ShaderCompiler.hpp(shader cooking) - New:
src/script/LuaValidator.hpp(script validation)
Design approved by: User Approval date: May 16, 2026