Caffeine Ecosystem Three-Phase Implementation Plan
Historical note: Convoy and WaveShaper are no longer part of the Caffeine repository. The references below describe the original plan.
For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
Goal: Implement doppio editor integration (CAP browsing + texture/audio previews + drag-drop), advanced caf-pack features (mesh processor + compression + asset ID header), and tool integration (async loading infrastructure) for a complete unified ecosystem.
Architecture: Phase 1 extends doppio with CAP deserialization and preview rendering. Phase 2 extends caf-pack with mesh support and compression. Phase 3 builds async loading infrastructure and tool exports.
Tech Stack: C++20, ImGui, libpng, zlib, zstd, pthreads
Phase 1: doppio Editor Integration (Step 4)#
Task 1.1: Create CAP Loader Module#
Files:
- Create:
doppio-archived/src/doppio/editor/CapLoader.hpp - Create:
doppio-archived/src/doppio/editor/CapLoader.cpp
Step 1: Write CapLoader header with interface
// src/editor/CapLoader.hpp
#pragma once
#include "core/Types.hpp"
#include "core/io/CafTypes.hpp"
#include <vector>
#include <string>
#include <filesystem>
namespace Caffeine::Editor {
class CapLoader {
public:
struct LoadedAsset {
std::string filename;
AssetType type;
std::vector<u8> cafBlob;
CafHeader metadata;
};
// Load CAP file and extract all assets
static std::vector<LoadedAsset> loadCap(const std::filesystem::path& path);
private:
// Helper to identify asset type from magic bytes in CAF
static AssetType identifyAssetType(const CafHeader& header);
};
} // namespace Caffeine::Editor
Step 2: Implement CAP loader
// src/editor/CapLoader.cpp
#include "editor/CapLoader.hpp"
#include <fstream>
#include <cstring>
namespace Caffeine::Editor {
std::vector<CapLoader::LoadedAsset> CapLoader::loadCap(const std::filesystem::path& path) {
std::vector<LoadedAsset> assets;
std::ifstream file(path, std::ios::binary);
if (!file) {
CF_LOG_ERROR("CapLoader: Failed to open CAP file: {}", path.string());
return assets;
}
// Read CAP header
CapHeader capHeader{};
file.read(reinterpret_cast<char*>(&capHeader), sizeof(CapHeader));
if (capHeader.magic != CapHeader::MAGIC) {
CF_LOG_ERROR("CapLoader: Invalid CAP magic bytes");
return assets;
}
if (capHeader.version != CapHeader::VERSION) {
CF_LOG_ERROR("CapLoader: Unsupported CAP version");
return assets;
}
// Read entry table
std::vector<CapEntry> entries(capHeader.entryCount);
file.read(reinterpret_cast<char*>(entries.data()),
capHeader.entryCount * sizeof(CapEntry));
// Extract each asset
for (const auto& entry : entries) {
file.seekg(entry.offset);
// Read CAF blob
std::vector<u8> cafBlob(entry.size);
file.read(reinterpret_cast<char*>(cafBlob.data()), entry.size);
// Parse CAF header
CafHeader cafHeader{};
std::memcpy(&cafHeader, cafBlob.data(), sizeof(CafHeader));
LoadedAsset asset{
.filename = entry.filename,
.type = identifyAssetType(cafHeader),
.cafBlob = cafBlob,
.metadata = cafHeader
};
assets.push_back(asset);
}
return assets;
}
AssetType CapLoader::identifyAssetType(const CafHeader& header) {
// Type is stored in CafHeader
return static_cast<AssetType>(header.type);
}
} // namespace Caffeine::Editor
Step 3: Add CapLoader to CMakeLists.txt
In src/editor/CMakeLists.txt, add to the doppio-editor target:
CapLoader.hpp
CapLoader.cpp
Step 4: Verify compilation
cd build && cmake .. && make -j4
Expected: No errors, doppio target compiles successfully.
Step 5: Commit
git add src/editor/CapLoader.hpp src/editor/CapLoader.cpp src/editor/CMakeLists.txt
git commit -m "feat: add CAP file loader for Asset Browser"
Task 1.2: Extend Asset Browser with CAP Mode#
Files:
- Modify:
doppio-archived/src/doppio/editor/AssetBrowser.hpp - Modify:
doppio-archived/src/doppio/editor/AssetBrowser.cpp
Step 1: Add CAP mode enum and loading method to header
Find the AssetBrowser class definition and add:
// In AssetBrowser.hpp, after ViewMode enum:
enum class BrowseMode : u8 {
Filesystem,
CapFile
};
// Add to public section after existing methods:
void loadCapFile(const std::filesystem::path& capPath);
BrowseMode browseMode() const { return m_browseMode; }
Step 2: Add CAP mode state variables
In AssetBrowser.hpp private section, add:
BrowseMode m_browseMode = BrowseMode::Filesystem;
std::filesystem::path m_currentCapPath;
std::vector<CapLoader::LoadedAsset> m_capAssets; // Loaded CAP assets
Step 3: Implement loadCapFile method
In AssetBrowser.cpp, add after existing methods:
void AssetBrowser::loadCapFile(const std::filesystem::path& capPath) {
m_capAssets = CapLoader::loadCap(capPath);
m_currentCapPath = capPath;
m_browseMode = BrowseMode::CapFile;
m_entries.clear();
// Convert CapLoader assets to Asset Browser entries
for (const auto& asset : m_capAssets) {
Entry entry{};
entry.name = asset.filename;
entry.type = asset.type;
entry.path = capPath / asset.filename; // Virtual path
entry.fileSize = asset.cafBlob.size();
entry.isDirectory = false;
m_entries.push_back(entry);
}
CF_LOG_INFO("AssetBrowser: Loaded {} assets from CAP", m_entries.size());
}
Step 4: Update refresh() method for CAP mode
In AssetBrowser.cpp, modify the refresh() method:
void AssetBrowser::refresh() {
if (m_browseMode == BrowseMode::CapFile) {
// Reload CAP file
loadCapFile(m_currentCapPath);
return;
}
// Existing filesystem refresh logic...
}
Step 5: Update render to show CAP breadcrumb
In AssetBrowser::renderBreadcrumbs(), add CAP mode indicator:
if (m_browseMode == BrowseMode::CapFile) {
ImGui::Text("CAP: %s", m_currentCapPath.filename().c_str());
ImGui::SameLine();
if (ImGui::SmallButton("Back to Filesystem")) {
m_browseMode = BrowseMode::Filesystem;
m_entries.clear();
navigateTo(m_rootPath);
}
}
Step 6: Verify compilation
cd build && make -j4
Expected: No errors.
Step 7: Commit
git add src/editor/AssetBrowser.hpp src/editor/AssetBrowser.cpp
git commit -m "feat: add CAP file browsing mode to Asset Browser"
Task 1.3: Create Audio Waveform Renderer#
Files:
- Create:
doppio-archived/src/doppio/editor/AudioWaveformRenderer.hpp - Create:
doppio-archived/src/doppio/editor/AudioWaveformRenderer.cpp
Step 1: Write header
// src/editor/AudioWaveformRenderer.hpp
#pragma once
#include "core/Types.hpp"
#include "core/io/CafTypes.hpp"
#include <vector>
#include <memory>
namespace Caffeine::Editor {
class AudioWaveformRenderer {
public:
struct WaveformData {
std::vector<f32> leftChannel;
std::vector<f32> rightChannel;
u32 sampleRate;
bool isStereo;
};
// Generate waveform from CAF audio blob
static WaveformData generateWaveform(
const std::vector<u8>& cafBlob,
u32 targetWidth = 256
);
// Render waveform as texture (returns GPU texture ID)
static u32 renderWaveformTexture(const WaveformData& data, u32 width = 256, u32 height = 64);
};
} // namespace Caffeine::Editor
Step 2: Implement waveform generator
// src/editor/AudioWaveformRenderer.cpp
#include "editor/AudioWaveformRenderer.hpp"
#include <algorithm>
#include <cmath>
namespace Caffeine::Editor {
AudioWaveformRenderer::WaveformData AudioWaveformRenderer::generateWaveform(
const std::vector<u8>& cafBlob,
u32 targetWidth
) {
WaveformData data{};
if (cafBlob.size() < sizeof(CafHeader)) {
return data;
}
// Parse CAF header
CafHeader header{};
std::memcpy(&header, cafBlob.data(), sizeof(CafHeader));
if (header.type != static_cast<u32>(AssetType::Audio)) {
return data;
}
// Get audio metadata
CafAudioMetadata audioMeta{};
std::memcpy(&audioMeta,
cafBlob.data() + sizeof(CafHeader),
sizeof(CafAudioMetadata));
data.sampleRate = audioMeta.sampleRate;
data.isStereo = (audioMeta.channels == 2);
// Extract PCM samples (assuming 16-bit PCM after metadata)
u32 payloadOffset = 32 + 32; // CafHeader + CafAudioMetadata
const i16* samples = reinterpret_cast<const i16*>(cafBlob.data() + payloadOffset);
u32 sampleCount = (cafBlob.size() - payloadOffset) / sizeof(i16);
// Normalize and downsample to targetWidth
u32 samplesPerBin = std::max(1u, sampleCount / (targetWidth * audioMeta.channels));
for (u32 i = 0; i < targetWidth; i++) {
u32 startIdx = i * samplesPerBin * audioMeta.channels;
u32 endIdx = std::min(startIdx + samplesPerBin * audioMeta.channels, sampleCount);
f32 minLeft = 0.0f, maxLeft = 0.0f;
f32 minRight = 0.0f, maxRight = 0.0f;
for (u32 j = startIdx; j < endIdx; j++) {
f32 normalized = static_cast<f32>(samples[j]) / 32768.0f;
if ((j - startIdx) % audioMeta.channels == 0) {
minLeft = std::min(minLeft, normalized);
maxLeft = std::max(maxLeft, normalized);
} else if (audioMeta.channels == 2) {
minRight = std::min(minRight, normalized);
maxRight = std::max(maxRight, normalized);
}
}
data.leftChannel.push_back(maxLeft - minLeft);
if (data.isStereo) {
data.rightChannel.push_back(maxRight - minRight);
}
}
return data;
}
u32 AudioWaveformRenderer::renderWaveformTexture(
const WaveformData& data,
u32 width,
u32 height
) {
// For now, return a placeholder texture ID (0)
// Full implementation would render to texture using RenderDevice
// This is a simplified version that generates the waveform data
return 0; // TODO: Implement texture rendering with RenderDevice
}
} // namespace Caffeine::Editor
Step 3: Add to CMakeLists.txt
AudioWaveformRenderer.hpp
AudioWaveformRenderer.cpp
Step 4: Verify compilation
cd build && make -j4
Step 5: Commit
git add src/editor/AudioWaveformRenderer.hpp src/editor/AudioWaveformRenderer.cpp src/editor/CMakeLists.txt
git commit -m "feat: add audio waveform generator for Asset Browser previews"
Task 1.4: Extend Drag-Drop for Auto-Pack Import#
Files:
- Modify:
doppio-archived/src/doppio/editor/DragDropSystem.hpp - Modify:
doppio-archived/src/doppio/editor/DragDropSystem.cpp
Step 1: Add import handler to DragDropSystem header
// In DragDropSystem.hpp, add to public section:
void importFilesToCapPack(
const std::vector<std::filesystem::path>& files,
const std::filesystem::path& projectRoot
);
// Add callback for when import completes
using ImportCallback = std::function<void(bool success, const std::string& message)>;
void setImportCallback(ImportCallback callback);
Step 2: Implement import handler
// In DragDropSystem.cpp, add:
void DragDropSystem::importFilesToCapPack(
const std::vector<std::filesystem::path>& files,
const std::filesystem::path& projectRoot
) {
// Create temp directory
auto tempDir = std::filesystem::temp_directory_path() /
("caf_import_" + std::to_string(std::time(nullptr)));
std::filesystem::create_directory(tempDir);
// Copy files to temp dir
for (const auto& file : files) {
auto dest = tempDir / file.filename();
std::filesystem::copy(file, dest);
}
// Run caf-pack CLI
std::string capPath = (projectRoot / "game.cap").string();
std::string command = "./caf-pack --input " + tempDir.string() +
" --output " + capPath;
int result = std::system(command.c_str());
// Cleanup temp dir
std::filesystem::remove_all(tempDir);
// Callback
bool success = (result == 0);
std::string message = success ?
"Imported " + std::to_string(files.size()) + " assets" :
"Import failed: caf-pack error";
if (m_importCallback) {
m_importCallback(success, message);
}
}
Step 3: Update drag-drop handler to detect imports
In existing DragDropSystem::handleDragDrop():
// Add to the drag-drop handler:
if (ImGui::BeginDragDropTarget()) {
if (const ImGuiPayload* payload = ImGui::AcceptDragDropPayload("asset_files")) {
std::vector<std::filesystem::path> files;
// Extract file paths from payload
importFilesToCapPack(files, projectRoot);
}
ImGui::EndDragDropTarget();
}
Step 4: Verify compilation
cd build && make -j4
Step 5: Commit
git add src/editor/DragDropSystem.hpp src/editor/DragDropSystem.cpp
git commit -m "feat: add drag-drop auto-pack import to Asset Browser"
Task 1.5: Add Project Auto-Load for game.cap#
Files:
- Modify:
src/caffeine/project/ProjectManager.cpp
Step 1: Find ProjectManager::openProject method
Locate the method that opens a project file.
Step 2: Add CAP auto-load after project opens
void ProjectManager::openProject(const std::filesystem::path& projectPath) {
// Existing project loading logic...
m_currentProjectPath = projectPath;
// NEW: Auto-load game.cap if it exists
std::filesystem::path capPath = projectPath / "game.cap";
if (std::filesystem::exists(capPath)) {
// Get Asset Browser instance from EditorContext
if (auto assetBrowser = m_editorContext->getAssetBrowser()) {
assetBrowser->loadCapFile(capPath);
CF_LOG_INFO("ProjectManager: Auto-loaded game.cap from project");
}
}
}
Step 3: Verify compilation
cd build && make -j4
Step 4: Test manual verification
- Create test project directory
- Create a dummy game.cap (or copy from ecosystem example)
- Open project in doppio
- Verify Asset Browser loads CAP
Step 5: Commit
git add src/editor/ProjectManager.cpp
git commit -m "feat: auto-load game.cap on project open"
Task 1.6: Phase 1 Integration Test#
Files:
- Create:
tests/editor/phase1_integration_test.cpp
Step 1: Write integration test
// tests/editor/phase1_integration_test.cpp
#include <gtest/gtest.h>
#include "editor/CapLoader.hpp"
#include "editor/AssetBrowser.hpp"
#include "editor/AudioWaveformRenderer.hpp"
using namespace Caffeine::Editor;
class Phase1IntegrationTest : public ::testing::Test {
protected:
std::filesystem::path testCapPath;
std::filesystem::path testProjectPath;
void SetUp() override {
// Setup test directories
testProjectPath = std::filesystem::temp_directory_path() / "test_project";
std::filesystem::create_directories(testProjectPath);
}
void TearDown() override {
std::filesystem::remove_all(testProjectPath);
}
};
TEST_F(Phase1IntegrationTest, CanLoadCapFile) {
// This requires a test CAP file to exist
// For now, we verify the loader interface works
AssetBrowser browser;
browser.init((testProjectPath / "assets").string().c_str());
EXPECT_EQ(browser.browseMode(), BrowseMode::Filesystem);
}
TEST_F(Phase1IntegrationTest, CanGenerateWaveform) {
// Test with placeholder CAF blob
std::vector<u8> testBlob(1024, 0);
auto waveform = AudioWaveformRenderer::generateWaveform(testBlob);
EXPECT_FALSE(waveform.leftChannel.empty());
}
Step 2: Add test to CMakeLists.txt
In tests/CMakeLists.txt:
add_executable(Phase1IntegrationTest editor/phase1_integration_test.cpp)
target_link_libraries(Phase1IntegrationTest gtest gtest_main caffeine-core)
add_test(NAME Phase1Integration COMMAND Phase1IntegrationTest)
Step 3: Run tests
cd build && ctest -V
Expected: Tests pass (or fail gracefully for missing resources).
Step 4: Commit
git add tests/editor/phase1_integration_test.cpp tests/CMakeLists.txt
git commit -m "test: add Phase 1 integration tests for CAP browsing"
Phase 2: Advanced caf-pack Features (Parallel)#
Task 2.1: Implement Mesh Processor (OBJ → CAF)#
Files:
- Create:
caf-pack/src/MeshProcessor.hpp - Create:
caf-pack/src/MeshProcessor.cpp - Modify:
caf-pack/src/AssetProcessor.cpp
Step 1: Write MeshProcessor header
// caf-pack/src/MeshProcessor.hpp
#pragma once
#include "caffeine/CafTypes.hpp"
#include <vector>
#include <string>
#include <filesystem>
class MeshProcessor {
public:
struct Vertex {
f32 x, y, z; // Position
f32 nx, ny, nz; // Normal
f32 u, v; // UV
};
struct Mesh {
std::vector<Vertex> vertices;
std::vector<u32> indices;
Vec3 boundsMin, boundsMax;
};
static CafData processMesh(const std::filesystem::path& objPath);
private:
static Mesh parseOBJ(const std::filesystem::path& path);
static void computeBounds(Mesh& mesh);
static std::vector<u8> packMeshToCAF(const Mesh& mesh);
};
Step 2: Implement OBJ parser
// caf-pack/src/MeshProcessor.cpp
#include "MeshProcessor.hpp"
#include <fstream>
#include <sstream>
#include <glm/glm.hpp>
Mesh MeshProcessor::parseOBJ(const std::filesystem::path& path) {
Mesh mesh{};
std::ifstream file(path);
if (!file) {
std::cerr << "Failed to open OBJ: " << path << std::endl;
return mesh;
}
std::vector<glm::vec3> positions;
std::vector<glm::vec3> normals;
std::vector<glm::vec2> texCoords;
std::string line;
while (std::getline(file, line)) {
std::istringstream iss(line);
std::string token;
iss >> token;
if (token == "v") {
glm::vec3 pos;
iss >> pos.x >> pos.y >> pos.z;
positions.push_back(pos);
} else if (token == "vn") {
glm::vec3 norm;
iss >> norm.x >> norm.y >> norm.z;
normals.push_back(glm::normalize(norm));
} else if (token == "vt") {
glm::vec2 uv;
iss >> uv.x >> uv.y;
texCoords.push_back(uv);
} else if (token == "f") {
// Parse face (simplified, assumes triangles)
for (int i = 0; i < 3; i++) {
std::string vertexStr;
iss >> vertexStr;
// Parse vertex indices (format: v/vt/vn)
u32 vIdx, vtIdx = 0, vnIdx = 0;
sscanf(vertexStr.c_str(), "%u/%u/%u", &vIdx, &vtIdx, &vnIdx);
Vertex vertex{};
auto& pos = positions[vIdx - 1];
vertex.x = pos.x; vertex.y = pos.y; vertex.z = pos.z;
if (vnIdx > 0 && vnIdx <= normals.size()) {
auto& norm = normals[vnIdx - 1];
vertex.nx = norm.x; vertex.ny = norm.y; vertex.nz = norm.z;
} else {
vertex.nx = vertex.ny = 0; vertex.nz = 1;
}
if (vtIdx > 0 && vtIdx <= texCoords.size()) {
auto& uv = texCoords[vtIdx - 1];
vertex.u = uv.x; vertex.v = uv.y;
}
mesh.vertices.push_back(vertex);
mesh.indices.push_back(mesh.vertices.size() - 1);
}
}
}
computeBounds(mesh);
return mesh;
}
void MeshProcessor::computeBounds(Mesh& mesh) {
if (mesh.vertices.empty()) return;
mesh.boundsMin = {mesh.vertices[0].x, mesh.vertices[0].y, mesh.vertices[0].z};
mesh.boundsMax = mesh.boundsMin;
for (const auto& v : mesh.vertices) {
mesh.boundsMin.x = std::min(mesh.boundsMin.x, v.x);
mesh.boundsMin.y = std::min(mesh.boundsMin.y, v.y);
mesh.boundsMin.z = std::min(mesh.boundsMin.z, v.z);
mesh.boundsMax.x = std::max(mesh.boundsMax.x, v.x);
mesh.boundsMax.y = std::max(mesh.boundsMax.y, v.y);
mesh.boundsMax.z = std::max(mesh.boundsMax.z, v.z);
}
}
CafData MeshProcessor::processMesh(const std::filesystem::path& objPath) {
CafData data{};
Mesh mesh = parseOBJ(objPath);
// Pack mesh data as CAF blob
std::vector<u8> payload = packMeshToCAF(mesh);
data.header.type = static_cast<u32>(AssetType::Mesh);
data.payload = payload;
return data;
}
Step 3: Update AssetProcessor to route .obj files
In AssetProcessor::process():
if (ext == ".obj") {
return MeshProcessor::processMesh(filePath);
}
Step 4: Update CMakeLists.txt
Add MeshProcessor files and glm dependency.
Step 5: Verify compilation
cd caf-pack && mkdir -p build && cd build && cmake .. && make -j4
Step 6: Test with sample OBJ
./caf-pack --input ../test_mesh.obj --output test_mesh.cap
Step 7: Commit
git add caf-pack/src/MeshProcessor.hpp caf-pack/src/MeshProcessor.cpp caf-pack/src/AssetProcessor.cpp caf-pack/CMakeLists.txt
git commit -m "feat: add mesh processor for OBJ to CAF conversion"
Task 2.2: Implement Compression Support (zstd)#
Files:
- Modify:
caf-pack/CMakeLists.txt - Modify:
caf-pack/src/Packer.cpp - Modify:
doppio-archived/src/doppio/editor/CapLoader.cpp
Step 1: Add zstd to CMakeLists.txt
find_package(zstd REQUIRED)
target_link_libraries(caf-pack zstd::libzstd_shared)
Step 2: Update Packer to compress assets
In Packer.cpp, add compression in packAssets():
#include <zstd.h>
void Packer::packAssets() {
// ... existing code ...
std::ofstream capFile(m_outputPath, std::ios::binary);
// Write CAP header
CapHeader header{};
header.magic = CapHeader::MAGIC;
header.version = CapHeader::VERSION;
header.entryCount = m_assets.size();
capFile.write(reinterpret_cast<char*>(&header), sizeof(CapHeader));
// Write entries and compressed data
u32 offset = sizeof(CapHeader) + header.entryCount * sizeof(CapEntry);
std::vector<CapEntry> entries;
for (auto& asset : m_assets) {
std::vector<u8> compressed;
if (m_compressionLevel > 0) {
// Compress with zstd
size_t compSize = ZSTD_compressBound(asset.cafData.payload.size());
compressed.resize(compSize);
size_t actualSize = ZSTD_compress(
compressed.data(), compSize,
asset.cafData.payload.data(), asset.cafData.payload.size(),
m_compressionLevel
);
compressed.resize(actualSize);
} else {
compressed = asset.cafData.payload;
}
CapEntry entry{};
std::strncpy(entry.filename, asset.name.c_str(), 255);
entry.offset = offset;
entry.size = compressed.size();
entry.compressedSize = (m_compressionLevel > 0) ? compressed.size() : 0;
entries.push_back(entry);
offset += compressed.size();
// Write compressed data
capFile.write(reinterpret_cast<char*>(compressed.data()), compressed.size());
}
// Write entry table
capFile.seekp(sizeof(CapHeader));
capFile.write(reinterpret_cast<char*>(entries.data()),
entries.size() * sizeof(CapEntry));
}
Step 3: Update CapLoader to decompress
// In CapLoader.cpp
if (entry.compressedSize > 0) {
// Decompress with zstd
std::vector<u8> decompressed(entry.size); // Original size stored in CafHeader
ZSTD_decompress(
decompressed.data(), decompressed.size(),
cafBlob.data(), cafBlob.size()
);
cafBlob = decompressed;
}
Step 4: Add --compress flag to CLI
In main.cpp:
// Add to argument parser
if (args["--compress"]) {
packer.setCompressionLevel(std::stoi(args["--compress"]));
}
Step 5: Verify compilation
cd build && cmake .. && make -j4
Step 6: Test compression
./caf-pack --input assets/ --output test_uncompressed.cap
./caf-pack --input assets/ --output test_compressed.cap --compress 10
ls -lh test_*.cap
Expected: test_compressed.cap is smaller.
Step 7: Commit
git add caf-pack/CMakeLists.txt caf-pack/src/Packer.cpp src/editor/CapLoader.cpp
git commit -m "feat: add zstd compression support to caf-pack"
Task 2.3: Implement Asset ID Header Generator#
Files:
- Modify:
caf-pack/src/main.cpp - Create:
caf-pack/src/HeaderGenerator.hpp/cpp
Step 1: Create HeaderGenerator utility
// caf-pack/src/HeaderGenerator.hpp
#pragma once
#include <string>
#include <vector>
#include <filesystem>
struct AssetEntry {
std::string name;
u64 id;
};
class HeaderGenerator {
public:
static void generateHeader(
const std::vector<AssetEntry>& assets,
const std::filesystem::path& outputPath
);
private:
static u64 fnv1aHash(const std::string& str);
static std::string assetNameToIdentifier(const std::string& filename);
};
Step 2: Implement HeaderGenerator
// caf-pack/src/HeaderGenerator.cpp
#include "HeaderGenerator.hpp"
#include <fstream>
#include <algorithm>
u64 HeaderGenerator::fnv1aHash(const std::string& str) {
u64 hash = 14695981039346656037ULL;
for (char c : str) {
hash ^= static_cast<u8>(c);
hash *= 1099511628211ULL;
}
return hash;
}
std::string HeaderGenerator::assetNameToIdentifier(const std::string& filename) {
std::string id = filename;
// Remove extension
size_t dotPos = id.rfind('.');
if (dotPos != std::string::npos) {
id = id.substr(0, dotPos);
}
// Convert to snake_case
std::replace_if(id.begin(), id.end(),
[](char c) { return !std::isalnum(c); }, '_');
return id;
}
void HeaderGenerator::generateHeader(
const std::vector<AssetEntry>& assets,
const std::filesystem::path& outputPath
) {
std::ofstream header(outputPath);
header << "// Auto-generated by caf-pack\n";
header << "#pragma once\n\n";
header << "#include \"core/Types.hpp\"\n\n";
header << "namespace Assets {\n";
for (const auto& asset : assets) {
std::string id = assetNameToIdentifier(asset.name);
header << " constexpr u64 " << id << " = 0x"
<< std::hex << asset.id << std::dec << ";\n";
}
header << "}\n";
}
Step 3: Update main.cpp to handle --gen-ids
// In main(), after packing:
if (args.count("--gen-ids")) {
std::vector<AssetEntry> entries;
for (const auto& asset : packer.getAssets()) {
entries.push_back({
asset.name,
HeaderGenerator::fnv1aHash(asset.name)
});
}
HeaderGenerator::generateHeader(entries, args["--gen-ids"]);
std::cout << "Generated asset header: " << args["--gen-ids"] << std::endl;
}
Step 4: Update CMakeLists.txt
Add HeaderGenerator files.
Step 5: Verify compilation
cd build && make -j4
Step 6: Test header generation
./caf-pack --input assets/ --output game.cap --gen-ids include/game_assets.hpp
cat include/game_assets.hpp
Expected: Valid C++ header with asset IDs.
Step 7: Commit
git add caf-pack/src/HeaderGenerator.hpp caf-pack/src/HeaderGenerator.cpp caf-pack/src/main.cpp caf-pack/CMakeLists.txt
git commit -m "feat: add asset ID header generator (--gen-ids flag)"
Phase 3: Tool Integration (Sequenced)#
Task 3.1: Implement Async Asset Loading Infrastructure#
Files:
- Create:
src/caffeine/engine/AssetLoader.hpp - Create:
src/caffeine/engine/AssetLoader.cpp
Step 1: Design async loader interface
// src/engine/AssetLoader.hpp
#pragma once
#include "core/Types.hpp"
#include <functional>
#include <queue>
#include <memory>
#include <thread>
namespace Caffeine {
using AssetHandle = u64;
using AssetCallback = std::function<void(const std::vector<u8>&)>;
class AssetLoader {
public:
// Load asset asynchronously
AssetHandle loadAssetAsync(u64 assetId, AssetCallback onReady);
// Cancel pending load
void cancelLoad(AssetHandle handle);
// Update (call once per frame)
void update();
// Shutdown
~AssetLoader();
private:
struct LoadJob {
u64 id;
AssetHandle handle;
AssetCallback callback;
};
std::queue<LoadJob> m_pendingLoads;
std::thread m_workerThread;
bool m_running = true;
void workerLoop();
};
} // namespace Caffeine
Step 2: Implement async loader
// src/engine/AssetLoader.cpp
#include "engine/AssetLoader.hpp"
#include <chrono>
namespace Caffeine {
AssetHandle AssetLoader::loadAssetAsync(u64 assetId, AssetCallback onReady) {
static u64 handleCounter = 0;
AssetHandle handle = ++handleCounter;
LoadJob job{assetId, handle, onReady};
m_pendingLoads.push(job);
return handle;
}
void AssetLoader::cancelLoad(AssetHandle handle) {
// Simplified: mark as cancelled in pending queue
// Full implementation would use thread-safe queue
}
void AssetLoader::workerLoop() {
while (m_running) {
if (!m_pendingLoads.empty()) {
auto job = m_pendingLoads.front();
m_pendingLoads.pop();
// Simulate async load
std::this_thread::sleep_for(std::chrono::milliseconds(10));
// Call callback (in real implementation, queue result for main thread)
std::vector<u8> dummyData;
job.callback(dummyData);
}
std::this_thread::sleep_for(std::chrono::milliseconds(1));
}
}
void AssetLoader::update() {
// Process completed loads
}
AssetLoader::~AssetLoader() {
m_running = false;
if (m_workerThread.joinable()) {
m_workerThread.join();
}
}
} // namespace Caffeine
Step 3: Add to CMakeLists.txt
src/engine/AssetLoader.hpp
src/engine/AssetLoader.cpp
Step 4: Verify compilation
cd build && cmake .. && make -j4
Step 5: Commit
git add src/engine/AssetLoader.hpp src/engine/AssetLoader.cpp src/CMakeLists.txt
git commit -m "feat: implement async asset loading infrastructure"
Task 3.2: Documentation and Examples#
Files:
- Create:
docs/ECOSYSTEM_WORKFLOW.md
Step 1: Create complete workflow documentation
flowchart TD ____1__Create_Assets["### 1. Create Assets"] --> ____Texture____Use_Convoy_to_create_text["- **Texture:** Use Convoy to create texture"] ____Texture____Use_Convoy_to_create_text["- **Texture:** Use Convoy to create texture"] --> Export_PNG["Export PNG"] Export_PNG["Export PNG"] --> ____Audio____Use_WaveShaper_to_create_so["- **Audio:** Use WaveShaper to create sound"] ____Audio____Use_WaveShaper_to_create_so["- **Audio:** Use WaveShaper to create sound"] --> Export_WAV["Export WAV"]
bash mkdir raw_assets cp texture.png raw_assets/ cp sound.wav raw_assets/ cp model.obj raw_assets/
caf-pack --input raw_assets/
--output game.cap
--gen-ids include/game_assets.hpp
--compress 10
### 3. Load in Game
```cpp
#include "include/game_assets.hpp"
// Async loading
auto textureHandle = assetMgr->loadAssetAsync(
Assets::texture,
[&](const std::vector<u8>& data) {
gameTexture = renderer->uploadTexture(data);
}
);
```mermaid
flowchart TD
__Browse_assets__see_thumbnails_and_wave["- Browse assets, see thumbnails and waveforms"] --> __Drag_new_PNG_WAV["- Drag new PNG/WAV"]
__Drag_new_PNG_WAV["- Drag new PNG/WAV"] --> auto_packed["auto-packed"]
____WaveShaper_Export["### WaveShaper Export"] --> 1___File["1. "File"]
1___File["1. "File"] --> Export_to_CAP_["Export to CAP""]
____Convoy_Export["### Convoy Export"] --> 1___File["1. "File"]
1___File["1. "File"] --> Export_Texture_to_CAP__or__Export_Mesh_t["Export Texture to CAP" or "Export Mesh to CAP""]
Step 2: Verify documentation
Run spell-check, verify code examples compile conceptually.
Step 3: Commit
git add docs/ECOSYSTEM_WORKFLOW.md
git commit -m "docs: add complete ecosystem workflow guide"
Task 3.3: Phase 2 & 3 Verification Test#
Files:
- Create:
tests/ecosystem/phase2_3_test.cpp
Step 1: Write comprehensive test
// tests/ecosystem/phase2_3_test.cpp
#include <gtest/gtest.h>
#include "engine/AssetLoader.hpp"
class Phase23Test : public ::testing::Test {
// Test async loader, mesh processor, compression
};
TEST_F(Phase23Test, AsyncLoaderWorks) {
Caffeine::AssetLoader loader;
bool called = false;
auto handle = loader.loadAssetAsync(123, [&](const auto& data) {
called = true;
});
loader.update();
EXPECT_TRUE(called);
}
TEST_F(Phase23Test, CompressionReducesSize) {
// Would require actual CAP files to test
// Placeholder for integration test
}
Step 2: Add to CMakeLists.txt
Step 3: Run tests
cd build && ctest -V
Step 4: Commit
git add tests/ecosystem/phase2_3_test.cpp
git commit -m "test: add Phase 2 & 3 integration tests"
Final Verification Checklist#
Phase 1 (doppio Editor Integration)#
- [ ] CAP Loader parses game.cap correctly
- [ ] Asset Browser displays CAP contents
- [ ] Texture thumbnails render
- [ ] Audio waveforms display
- [ ] Drag-drop import works (files packed into game.cap)
- [ ] game.cap auto-loads on project open
Phase 2 (Advanced caf-pack)#
- [ ] caf-pack compiles with zstd
- [ ] Mesh files (.obj) pack correctly
- [ ] Compression reduces file size (--compress flag works)
- [ ] Asset ID header generates valid C++ (--gen-ids flag works)
Phase 3 (Tool Integration)#
- [ ] Async asset loader compiles
- [ ] Can load assets asynchronously without blocking
- [ ] All 4 projects compile together:
cmake .. && make - [ ] caf-pack CLI runs:
./caf-pack --help
Execution Handoff#
Plan saved to docs/plans/2026-05-17-ecosystem-three-phase-implementation.md
Ready to execute. Two options:
- Subagent-Driven (this session) - Fresh subagent per task, review between tasks, iterative refinement
- Parallel Session (separate) - Open new session with executing-plans skill in worktree, batch execution
Which approach would you prefer?