From 5c2f3fcf56ea03fe6bdf041a2be78b6911f7224e Mon Sep 17 00:00:00 2001 From: LyeZinho Date: Tue, 7 Apr 2026 16:24:35 +0100 Subject: [PATCH 1/8] docs: add Phase 1 technical documentation with cross-references - Create docs/architecture/ for core and memory modules - Create docs/containers/ for data structures - Create docs/math/ for vector and matrix types - Create docs/api/ with complete API reference - Update docs/README.md with technical documentation section - Navigation: architecture -> containers -> math -> api with cross-references This follows SYNCHRONY principle - code changes must be documented. --- docs/README.md | 1020 ++--------------------------------- docs/api/README.md | 78 +++ docs/architecture/core.md | 38 ++ docs/architecture/memory.md | 64 +++ docs/containers/vector.md | 91 ++++ docs/math/vectors.md | 107 ++++ 6 files changed, 408 insertions(+), 990 deletions(-) create mode 100644 docs/api/README.md create mode 100644 docs/architecture/core.md create mode 100644 docs/architecture/memory.md create mode 100644 docs/containers/vector.md create mode 100644 docs/math/vectors.md diff --git a/docs/README.md b/docs/README.md index ccd8a8f..4bf2f34 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,1014 +19,54 @@ 8. [Gestão de Memória](#8-gestão-de-memória) 9. [Módulos da Engine](#9-módulos-da-engine) 10. [Estratégia de Crescimento](#10-estratégia-de-crescimento) -11. [Como Contribuir](#11-como-contribuir) +11. [Documentação Técnica](#11-documentação-técnica) +12. [Como Contribuir](#12-como-contribuir) --- -## 1. Visão Geral +## 11. Documentação Técnica -### 1.1 O que é a Caffeine? +### Fase 1: Fundação Atômica (IMPLEMENTADA) -A **Caffeine Engine** é uma game engine proprietária do Codex Studio, desenvolvida em **C++** sobre a camada do **SDL3**. +A documentação técnica da Fase 1 está organizada em subpastas com referências cruzadas: -A Caffeine prioriza: -- **Controle total** sobre o hardware -- **Concorrência multithread** cada núcleo da CPU -- **Gerenciamento de memória** customizado, sem dependência da `std` -- **Otimização gráfica** de baixo nível via SDL_GPU +| Módulo | Arquitetura | API | +|--------|-------------|-----| +| **Core** | [`architecture/core.md`](architecture/core.md) | Tipos, Platform, Assertions | +| **Memory** | [`architecture/memory.md`](architecture/memory.md) | Linear, Pool, Stack allocators | +| **Containers** | [`containers/vector.md`](containers/vector.md) | Vector, HashMap, String | +| **Math** | [`math/vectors.md`](math/vectors.md) | Vec2, Vec3, Vec4, Mat4 | -### 1.2 Objetivos do Projeto +**Referências Cruzadas:** -| Objetivo | Descrição | -|---|---| -| **Performance** | Games que rodam 60fps+ em hardware modesto | -| **Transparência** | Cada desenvolvedor entende o que o código faz | -| **Modularidade** | Compilar sem áudio não quebra renderização | -| **Portabilidade** | Core agnóstico de plataforma (Windows/Linux/macOS) | -| **Manutenibilidade** | Código que o "eu do futuro" não odiará ler | - -### 1.3 Stack Tecnológica - -| Camada | Tecnologia | -|---|---| -| **Linguagem** | C++20 ou superior | -| **Gráficos** | SDL3 (SDL_GPU API) | -| **Build** | CMake 3.20+ | -| **Biblioteca Padrão** | Caffeine Stdlib (custom, zero `std` dependency) | - -### 1.4 Status Atual - -O projeto está em **Fase 0 — Setup Inicial & Documentação**. O código-fonte ainda não foi criado. Toda a arquitetura foi planejada e documentada; o próximo passo é implementar a **Fase 1: Fundação Atômica**. - ---- - -## 2. Filosofia & Princípios - -### 2.1 Os Três Pilares - -```mermaid -graph TB - subgraph PILARS["🏛️ CAFFEINE PILLARS"] - ZD["🔌 ZERO DEPENDENCY
Reduzir ao máximo a
dependência da std padrão"] - DOD["📊 DATA-ORIENTED
Foco em cache locality
e processamento paralelo"] - CP["⚡ CAFFEINE-POWERED
Feita por devs que
entendem cada byte"] - end - - style ZD fill:#2d5016,stroke:#4a9,color:#fff - style DOD fill:#1a3a5c,stroke:#4af,color:#fff - style CP fill:#4a1a1a,stroke:#f94,color:#fff -``` - -### 2.2 Regras de Segurança (The Golden Rules) - -1. **Memória:** Proibido `new` e `delete` soltos. Toda alocação passa pelos **Custom Allocators** da Caffeine. -2. **Ownership:** Preferir ponteiros brutos (`raw pointers`) com ciclo de vida garantido pelo Core. Usar `unique_ptr`/`shared_ptr` apenas quando estritamente necessário. -3. **Review:** Nenhum código entra na `main` sem Code Review de pelo menos um Architect. -4. **Testes:** Cada fase deve passar por **Stress Test** antes de avançar. A Fase N+1 não começa se a Fase N vazar memória ou for instável. -5. **Documentação:** Nenhuma função é aceita sem comentário no header (`.h`). - -### 2.3 Princípios de Desenvolvimento - -| Princípio | Significado | -|---|---| -| **YAGNI** | "You Ain't Gonna Need It" — não crie abstrações para problemas que ainda não existem | -| **DOD** | Data-Oriented Design — arrays contíguos, não hierarquias de herança profundas | -| **KISS** | "Keep It Simple, Stupid" — se a explicação é mais complexa que o código, simplifique o sistema | -| **AGNOSTICISM** | Toda spec deve prever que o dado pode ser 2D ou 3D | -| **SYNCHRONY** | Se o código mudar drasticamente, o documento correspondente **deve** ser atualizado no mesmo commit | - -### 2.4 O Compromisso da Guilda - -> *"Nós, os desenvolvedores da Caffeine, priorizamos a compreensão sobre a facilidade. Escrevemos código que nossos 'eus' do futuro não odiarão ler. Construímos para durar, um frame de cada vez."* - ---- - -## 3. Arquitetura do Sistema - -### 3.1 Visão Macro da Arquitetura - -```mermaid -flowchart TB - subgraph ENTRY["📍 ENTRY POINT"] - MAIN["main.cpp"] - end - - subgraph CORE["⚙️ CAFFEINE CORE"] - direction LR - PLAT["🖥️ Platform Layer
OS Abstraction"] - STDLIB["📚 Caffeine Stdlib
Allocators • Containers"] - TYPES["🔧 Core Types
u32 • f64 • Macros"] - end - - subgraph LAYERS["🏗️ ENGINE LAYERS"] - direction TB - JS["⚡ Job System
Thread Pool • Work-Stealing"] - RHI["🎨 RHI
SDL_GPU Abstraction"] - ECS["🧠 ECS Core
Archetypes • World"] - end - - subgraph SYSTEMS["🎮 GAME SYSTEMS"] - direction LR - INPUT["🕹️ Input"] - DEBUG["🔍 Debug Tools"] - AUDIO["🔊 Audio"] - ASSETS["📦 Asset Manager"] - end - - subgraph ECS_SYS["🎯 ECS SYSTEMS"] - direction TB - PHYSICS["💥 Physics2D"] - ANIM["🎬 Animation"] - MOVEMENT["🏃 Movement"] - SPRITE["🖼️ Sprite"] - UI["📋 UI"] - end - - subgraph LOOP["🔄 GAME LOOP"] - direction TB - BF["beginFrame"] - INPUT_PROC["processInput"] - ACCUM["accumulator += dt"] - JOBS["parallel jobs"] - EVENTS["events dispatch"] - ECS_UP["ECS update"] - RENDER["render"] - EF["endFrame"] - end - - MAIN --> CORE - CORE --> LAYERS - LAYERS --> SYSTEMS - LAYERS --> ECS_SYS - - JS --> JOBS - RHI --> SPRITE - ECS --> ECS_UP - - SYSTEMS --> LOOP - ECS_SYS --> LOOP - - BF --> INPUT_PROC --> ACCUM - ACCUM --> JOBS - ACCUM --> EVENTS - ACCUM --> ECS_UP - ECS_UP --> RENDER - RENDER --> EF - - style ENTRY fill:#1a1a2e,stroke:#eee,color:#fff - style CORE fill:#16213e,stroke:#4a9,color:#fff - style LAYERS fill:#0f3460,stroke:#4af,color:#fff - style SYSTEMS fill:#1a3a1a,stroke:#4f4,color:#fff - style ECS_SYS fill:#3a1a3a,stroke:#f4f,color:#fff - style LOOP fill:#3a3a1a,stroke:#ff4,color:#fff -``` - -### 3.2 Camadas e Responsabilidades - -#### Plataforma (Platform Layer) -- Isola código específico de OS (Windows/Linux/macOS) -- Abstrai syscalls de thread, tempo e arquivo -- Localização: `/platform/` - -#### Caffeine Core (Tipos & Macros) -- Tipos de largura fixa: `u8`, `u16`, `u32`, `u64`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` -- Macros de plataforma, assertions customizados -- Macros de debug: `CF_ASSERT`, `CF_UNREACHABLE`, etc. - -#### Caffeine Stdlib -- **Custom Allocators:** Linear, Pool, Stack -- **Containers:** `Caffeine::Vector`, `Caffeine::HashMap`, `StringView`, `FixedString` -- Zero dependência da `std` padrão - -#### Job System -- Worker threads em repouso que acordam para processar Jobs -- Física, IA e Carregamento como Jobs discretos -- Atômicos e barreiras de sincronização lock-free - -#### Game Systems (Fase 2-4) -- **Input Manager:** Action mapping, polling/event-driven, gamepad -- **Debug Tools:** Logging, profiler, debug draw -- **Audio System:** SDL3 audio, pooling, spatial 2D -- **Asset Manager:** Async loading, cache, hot-reload - -#### RHI (Rendering Hardware Interface) -- Abstração sobre SDL_GPU -- Recebe `DrawCommand` → fila interna → GPU -- Não chama "SDL_Draw" diretamente - -#### ECS (Entity Component System) -- Entidades = IDs (não objetos) -- Componentes = dados em arrays contíguos -- Sistemas = lógica que opera nos componentes - -#### ECS Systems (Fase 4+) -- **PhysicsSystem2D:** AABB/circle collision, rigid body dynamics -- **AnimationSystem:** Sprite frames, state machine -- **UISystem:** Retained mode, ECS integration -- **MovementSystem:** Velocity/position integration - ---- - -## 4. Fases de Desenvolvimento - -### 4.1 Mapa de Fases - -```mermaid -flowchart LR - subgraph PHASES["📈 DEVELOPMENT PHASES"] - P0["Phase 0
Setup & Docs
████████░░░░░░░░ ✓"] - P1["Phase 1
Fundação Atômica
░░░░░░░░░░░░░░░░"] - P2["Phase 2
Concorrência
░░░░░░░░░░░░░░░░"] - P3["Phase 3
RHI & 2D
░░░░░░░░░░░░░░░░"] - P4["Phase 4
ECS & Serialização
░░░░░░░░░░░░░░░░"] - P5["Phase 5
Transição 3D
░░░░░░░░░░░░░░░░"] - P6["Phase 6
Studio IDE
░░░░░░░░░░░░░░░░"] - end - - P0 --> P1 --> P2 --> P3 --> P4 --> P5 --> P6 - - style P0 fill:#2d5016,stroke:#4a9,color:#fff - style P1 fill:#1a3a5c,stroke:#4af,color:#fff - style P2 fill:#3a2a1a,stroke:#fa4,color:#fff - style P3 fill:#2a1a3a,stroke:#f4f,color:#fff - style P4 fill:#1a3a2a,stroke:#4f4,color:#fff - style P5 fill:#3a2a1a,stroke:#fa4,color:#fff - style P6 fill:#3a1a1a,stroke:#f94,color:#fff ``` - -### 4.2 Detalhamento por Fase - ---- - -#### 🔧 Fase 0: Setup Inicial & Documentação -**Status:** 🕒 Em Progresso -**Responsável:** Guilda Codex - -- [x] README.md criado -- [x] Manifesto de desenvolvimento criado -- [x] Roadmap de 6 fases documentado -- [x] Fluxo R.I.C.O. estabelecido -- [ ] Estrutura de diretórios `/src` criada -- [ ] `.gitignore` verificado e completo -- [ ] CMakeLists.txt base criado -- [ ] `Caffeine.h` com tipos básicos criado - ---- - -#### 🧱 Fase 1: Fundação Atômica (Kernel & Memory) -**Status:** 📅 Planejado -**Responsável:** Architects - -**Entregáveis:** - -1. **Caffeine Core Types & Macros** - - Definição de tipos: `u8..u64`, `i8..i64`, `f32`, `f64`, `bool`, `char` - - Macros de plataforma: `CF_PLATFORM_WINDOWS`, `CF_PLATFORM_LINUX`, `CF_PLATFORM_MAC` - - Assertions: `CF_ASSERT(condition, message)` - - Macros de debug: `CF_UNREACHABLE`, `CF_INVALID_DEFAULT` - - `static_assert` para tamanhos de tipos - -2. **Memory Management System (Allocators)** - - **Linear Allocator:** limpa a cada frame, para memória volátil - - **Pool Allocator:** aloca blocos de tamanho fixo (partículas, projéteis) - - **Stack Allocator:** escopos aninhados (níveis de jogo) - - Interface unificada: `IAllocator` com `alloc()`, `free()`, `realloc()` - -3. **Custom Strings & Containers** - - `StringView`: string sem ownership (ponteiro + tamanho) - - `FixedString`: string com buffer inline (sem alocação heap) - - `Caffeine::Vector`: array dinâmico otimizado para cache - - `Caffeine::HashMap`: tabela hash para lookup O(1) - -**Critério de Progresso:** Stress test de alocação — 1M allocs sem leak, sem fragmentação mensurável. - -**Arquivos a criar:** -``` -src/ -├── core/ -│ ├── Caffeine.h # Tipos e macros globais -│ ├── Caffeine.hpp # Includes do core -│ ├── Types.hpp # Definições de tipos -│ ├── Platform.hpp # Macros de plataforma -│ ├── Assertions.hpp # Sistema de assertions -│ └── Compiler.hpp # Macros de compilador -├── memory/ -│ ├── Allocator.hpp # Interface base -│ ├── LinearAllocator.hpp -│ ├── PoolAllocator.hpp -│ └── StackAllocator.hpp -├── containers/ -│ ├── Vector.hpp -│ ├── HashMap.hpp -│ ├── StringView.hpp -│ └── FixedString.hpp -└── CMakeLists.txt +Core ──────► Memory ──────► Containers ──────► Math + │ │ │ │ + └─────────────┴─────────────────┴────────────┘ + │ + [API Reference](api/README.md) ``` ---- - -#### ⚡ Fase 2: O Pulso e a Concorrência (Multithreading & Timing) -**Status:** 📅 Planejado -**Responsável:** Architects - -**Entregáveis:** - -1. **High-Resolution Timer** - - Precisão de microssegundos via `SDL_GetPerformanceCounter` - - `TimePoint`, `Duration` com conversão entre unidades (ms, us, ns) - - Métricas: FPS counter, frame time, delta time - -2. **Job System (Worker Threads)** - - Thread pool com N workers (N = `std::thread::hardware_concurrency() - 1`) - - Fila de jobs atômica (lock-free queue) - - Tipos de Job: `IJob`, `JobWithData`, dependências entre Jobs - - `JobHandle` para tracking e sincronização - - Barreiras: `JobBarrier`, `JobSignal` - -3. **The Master Game Loop** - - Fixed timestep para lógica/física (ex: 60 updates/segundo) - - Variable timestep para renderização - - Interpolação de frames para fluidez visual - - Sistema de eventos de alta precisão - - Estados: `INIT`, `RUNNING`, `PAUSED`, `SHUTDOWN` - -**Critério de Progresso:** Physics demo com 10K partículas, todos os núcleos a 80%+ carga, sem race conditions (tsan clean). - ---- - -#### 👁️ Fase 3: O Olho da Engine (RHI & 2D Foundation) -**Status:** 📅 Planejado -**Responsável:** Artisans / Architects - -**Entregáveis:** - -1. **Rendering Hardware Interface (RHI)** - - Abstração sobre `SDL_GPU` - - `DrawCommand` struct: tipo, vértices, textura, shader, transform - - Command queue interna com batch automático - - Swapchain management (double/triple buffering) - - Suporte a múltiplos render targets - -2. **2D Batch Renderer** - - Batching de milhares de sprites em um único draw call - - Textures atlas system - - Z-buffer para ordenação (parallax, camadas) - - Render groups: Background, Foreground, UI - - Shader system básico (vertex + fragment) - -3. **Camera System (Agnóstico)** - - Matriz 4×4 de transformação - - Projeção Ortográfica (2D atual) - - Projeção Perspectiva (3D futuro — já previsto na API) - - Follow camera, shake, zoom - - Viewport management (letterbox, stretch) - -**Critério de Progresso:** Demo com 50K sprites na tela a 60fps estável. - ---- - -#### 🧠 Fase 4: O Cérebro (ECS & Serialização) -**Status:** 📅 Planejado -**Responsável:** Architects - -**Entregáveis:** - -1. **Entity Component System (ECS)** - - `Entity` = ID (32-bit ou 64-bit) - - `Component` = struct de dados puro (sem métodos, sem virtual) - - `ComponentPool` = array contíguo de T, tumbuh como Vector - - `World` = gerenciador de entidades e componentes - - `System` = functor que opera sobre componentes específicos - - Arquitetura archetype-based para cache locality - -2. **Scene Graph & Serialização** - - Hierarquia de entidades (parent/child) - - `Caffeine Object Notation` (formato binário `.caf`) - - Serialização JSON para debug e interoperabilidade - - Save/Load de cenas completas - - Base para futura IDE - -3. **Event Bus** - - Sistema pub/sub sem acoplamento - - `Event` com tipo explícito - - Fila de eventos com priority - - Exemplo: "Evento de Morte" → Sistema de Som toca clipe, Sistema de Partículas spawna efeito - -**Critério de Progresso:** Demo com 100 entidades dinâmicas, 5+ sistemas rodando, serialização funcionando end-to-end. - ---- - -#### 🌐 Fase 5: Transição Dimensional (The 3D Leap) -**Status:** 📅 Planejado -**Responsável:** Artisans - -**Entregáveis:** - -1. **3D Math Extension** - - Quaternions completos (multiplicação, slerp, look rotation) - - Matrizes de transformação 3D (model, view, projection) - - Planos, rays, bounding volumes (AABB, Sphere) - - math.hpp extensão com SIMD hints - -2. **Mesh Loading & Shaders** - - Loader para `.obj` e `.gltf` (GL Transmission Format) - - Pipeline de shaders: HLSL (Windows), GLSL (Linux/macOS) - - Shader hot-reload para development - - Material system com PBR (Physically Based Rendering) - -3. **Spatial Partitioning** - - Quadtree para mundos 2D grandes - - Octree evoluindo naturalmente para 3D - - Broad phase collision detection - - Culling system (frustum + occlusion) - -**Critério de Progresso:** Demo 3D com malha carregada, shader customizado, 60fps. - ---- - -#### 🏛️ Fase 6: O Olimpo (Caffeine Studio IDE) -**Status:** 📅 Planejado -**Responsável:** Full Guild - -**Entregáveis:** - -1. **Embedded UI (Dear ImGui)** - - Editor in-engine para variáveis runtime - - Profiler de frames e Jobs - - Visualizador de memória e allocators - - Console de comandos - -2. **The Scene Editor** - - Drag-and-drop de entidades - - Inspector de componentes - - Hierarquia visual de cena - - Play/pause/step do game loop - -3. **Asset Pipeline** - - Processador de texturas (compressão, mipmaps) - - Conversor de áudio (PCM → OGG) - - Packer de assets em `.caf` bundles - - Hot-reload de assets em runtime - -**Critério de Progresso:** Primeira versão jogável de um game completo feito 100% na Caffeine. - ---- - -## 5. Convenções de Código - -### 5.1 Nomenclatura - -| Elemento | Padrão | Exemplo | -|---|---|---| -| **Namespace** | `PascalCase` | `Caffeine::Memory` | -| **Classe / Struct** | `PascalCase` | `ThreadManager`, `LinearAllocator` | -| **Função / Método** | `camelCase` | `initSdl()`, `allocate()`, `getEntity()` | -| **Variável** | `camelCase` | `entityCount`, `playerHealth` | -| **Variável Privada** | `m_prefixo` | `m_isRunning`, `m_allocator` | -| **Constante / Macro** | `UPPER_CASE` | `MAX_THREADS`, `CF_PLATFORM_WINDOWS` | -| **Membro Estático** | `s_prefixo` | `s_instanceCount` | -| **Arquivo Header** | `PascalCase.hpp` | `LinearAllocator.hpp` | -| **Arquivo Source** | `PascalCase.cpp` | `LinearAllocator.cpp` | - -### 5.2 Tipos Customizados - -```cpp -// Tipos unsigned -using u8 = std::uint8_t; -using u16 = std::uint16_t; -using u32 = std::uint32_t; -using u64 = std::uint64_t; - -// Tipos signed -using i8 = std::int8_t; -using i16 = std::int16_t; -using i32 = std::int32_t; -using i64 = std::int64_t; - -// Tipos float -using f32 = float; -using f64 = double; - -// Tamanhos garantidos -static_assert(sizeof(u32) == 4, "u32 must be 4 bytes"); -static_assert(sizeof(f64) == 8, "f64 must be 8 bytes"); -``` - -### 5.3 Padrões de Interface - -#### Allocators -```cpp -class IAllocator { -public: - virtual ~IAllocator() = default; - virtual void* alloc(usize size, usize alignment = 8) = 0; - virtual void free(void* ptr) = 0; - virtual void reset() = 0; // Para Linear e Stack allocators - virtual usize usedMemory() const = 0; -}; -``` - -#### Jobs -```cpp -struct IJob { - virtual ~IJob() = default; - virtual void execute() = 0; -}; - -template -struct JobWithData : IJob { - T data; - std::function func; - void execute() override { func(data); } -}; -``` - -#### ECS Components (Plain Old Data) -```cpp -struct Position { - f32 x, y, z; -}; - -struct Sprite { - u32 textureId; - u32 width, height; - f32 scaleX, scaleY; -}; -// SEM métodos, SEM virtual, SEM construtores customizados -``` - -### 5.4 Regras de Estilo - -1. **Indentação:** 4 espaços (não tabs) -2. **Chaves:** BSD style (K&R variant): - ```cpp - if (condition) { - doSomething(); - } else { - doOther(); - } - ``` -3. **Linha máxima:** 120 caracteres -4. **Namespace:** Todo código em `Caffeine::*` -5. **Headers:** `#pragma once` (não include guards tradicionais) -6. **Includes:** Ordem — related header → local → third-party → system -7. **Comentários:** Doxygen para APIs públicas, `// inline` para código não óbvio - ---- - -## 6. Fluxo de Trabalho (R.I.C.O.) - -O ciclo **R.I.C.O.** é o processo de tomada de decisão da Caffeine: - -```mermaid -flowchart LR - subgraph RICO["🔄 CICLO R.I.C.O."] - R["🔍 RESEARCH
Pesquisa
Investigar como
SDL3 e C++ lidam
com o problema"] - I["💡 IDEA
Ideia
Propor solução
que se encaixe na
filosofia Caffeine"] - C["⚔️ CONFLICT
Conflito
Discussão no Discord
com a Guilda Codex"] - O["✅ ORDER
Ordem
Documentar decisão
final e implementar"] - end - - FB["🔁 Feedback Loop"] - - R --> I --> C --> O - O --> FB --> R - - style R fill:#2d5016,stroke:#4a9,color:#fff - style I fill:#1a3a5c,stroke:#4af,color:#fff - style C fill:#3a1a1a,stroke:#f94,color:#fff - style O fill:#2a1a3a,stroke:#f4f,color:#fff - style FB fill:#3a2a1a,stroke:#fa4,color:#fff - style RICO fill:#1a1a1a,stroke:#aaa,color:#fff -``` - -### 6.1 Research (Pesquisa) -- Investigar como SDL3 ou C++ padrão lidam com o problema -- Buscar em documentação oficial, código de referência, papers -- Não reinventar sem antes entender o que já existe - -### 6.2 Idea (Ideia) -- Propor solução que se encaixe na filosofia de baixa dependência -- Considerar trade-offs: performance vs manutenibilidade vs portabilidade -- Documentar a proposta com código mockup ou diagrama - -### 6.3 Conflict (Conflito) -- Discussão no Discord da Guilda Codex -- Pergunta-chave: "Essa solução fere o desempenho ou a portabilidade 3D futura?" -- Se não houver consenso, o Architect mais sênior decide - -### 6.4 Order (Ordem) -- Documentar a decisão final em `/desing_planning/` -- Atualizar spec correspondente -- Criar issue/ticket para implementação -- **Mesmo commit** atualiza código E documentação - -### 6.5 Ciclo de Feedback (Draft → Prototype → Refactor → Audit) - -```mermaid -flowchart LR - subgraph CYCLE["📋 FEEDBACK CYCLE"] - D["📝 Draft
O Scribe descreve
a funcionalidade"] - P["🎨 Prototype
Implementação inicial
da solução"] - R["🔧 Refactor
O Architect limpa
e integra aos padrões"] - A["✔️ Audit
O Oracle testa
performance e
estabilidade"] - end - - FAIL["❌ Se falhar
volta ao início"] - - D --> P --> R --> A - A -->|Passou| OK["✅ Pronto"] - A -->|Falhou| FAIL - FAIL --> D - - style D fill:#2d5016,stroke:#4a9,color:#fff - style P fill:#1a3a5c,stroke:#4af,color:#fff - style R fill:#3a2a1a,stroke:#fa4,color:#fff - style A fill:#2a1a3a,stroke:#f4f,color:#fff - style FAIL fill:#3a1a1a,stroke:#f94,color:#fff - style OK fill:#1a3a1a,stroke:#4f4,color:#fff - style CYCLE fill:#1a1a1a,stroke:#aaa,color:#fff -``` - ---- - -## 7. Estrutura de Diretórios - -``` -caffeine/ -├── README.md -├── LICENSE -├── CMakeLists.txt # Build principal -├── .gitignore -│ -├── docs/ # ← Documentação consolidada -│ ├── MASTER.md # Visão geral completa -│ ├── SPECS.md # Regras e padrões de desenvolvimento -│ ├── ROADMAP.md # Status das 6 fases -│ ├── architecture_specs.md # Especificações técnicas ECS, Job System, RHI -│ ├── memory_model.md # Specs de allocators -│ ├── plans/ # Planos de implementação -│ └── README.md # Este arquivo -│ -├── src/ # ← Código-fonte (Fase 1+) -│ ├── Caffeine.hpp # Header principal de inclusão -│ ├── Caffeine.cpp # Entry point mínimo -│ │ -│ ├── core/ # Tipos, macros, platform -│ │ ├── Types.hpp -│ │ ├── Platform.hpp -│ │ ├── Assertions.hpp -│ │ └── Compiler.hpp -│ │ -│ ├── memory/ # Custom Allocators -│ │ ├── Allocator.hpp -│ │ ├── LinearAllocator.hpp -│ │ ├── PoolAllocator.hpp -│ │ └── StackAllocator.hpp -│ │ -│ ├── containers/ # Caffeine Stdlib containers -│ │ ├── Vector.hpp -│ │ ├── HashMap.hpp -│ │ ├── StringView.hpp -│ │ └── FixedString.hpp -│ │ -│ ├── threading/ # Job System (Fase 2) -│ │ ├── ThreadPool.hpp -│ │ ├── JobSystem.hpp -│ │ └── JobQueue.hpp -│ │ -│ ├── time/ # Timing (Fase 2) -│ │ ├── Timer.hpp -│ │ └── GameLoop.hpp -│ │ -│ ├── rhi/ # Rendering Hardware Interface (Fase 3) -│ │ ├── RHI.hpp -│ │ ├── DrawCommand.hpp -│ │ ├── BatchRenderer.hpp -│ │ └── Shader.hpp -│ │ -│ ├── camera/ # Sistema de câmera (Fase 3) -│ │ └── Camera.hpp -│ │ -│ ├── ecs/ # ECS Core (Fase 4) -│ │ ├── World.hpp -│ │ ├── Entity.hpp -│ │ ├── ComponentPool.hpp -│ │ └── System.hpp -│ │ -│ ├── scene/ # Scene Graph (Fase 4) -│ │ ├── Scene.hpp -│ │ └── Serializer.hpp -│ │ -│ ├── events/ # Event Bus (Fase 4) -│ │ ├── EventBus.hpp -│ │ └── Event.hpp -│ │ -│ ├── platform/ # Abstração de OS -│ │ ├── Platform.hpp -│ │ ├── Platform_Windows.hpp -│ │ ├── Platform_Linux.hpp -│ │ └── Platform_Mac.hpp -│ │ -│ ├── math/ # Biblioteca matemática -│ │ ├── Vec2.hpp -│ │ ├── Vec3.hpp -│ │ ├── Vec4.hpp -│ │ ├── Mat4.hpp -│ │ ├── Quaternion.hpp -│ │ └── Math.hpp -│ │ -│ └── [3d/] # Extensões 3D (Fase 5) -│ └── [editor/] # IDE (Fase 6) -│ -├── tests/ # ← Testes unitários -│ ├── memory/ -│ ├── containers/ -│ ├── ecs/ -│ └── CMakeLists.txt -│ -├── examples/ # ← Demos e exemplos -│ ├── 01_hello_world/ -│ ├── 02_particles/ -│ ├── 03_ecs_demo/ -│ └── CMakeLists.txt -│ -└── tools/ # ← Ferramentas internas - ├── asset_packer/ - └── shader_compiler/ -``` - ---- - -## 8. Gestão de Memória - -### 8.1 Philosophy - -A Caffeine **NUNCA** permite `new` ou `delete` no código da aplicação. Toda alocação passa por um dos allocators customizados. - -### 8.2 Os Três Allocators - -#### Linear Allocator -- **Uso:** Memória volátil por frame (scratch space) -- **Comportamento:** `allocate()` avança um cursor; `reset()` volta ao início -- **Custo:** O(1) sem fragmentação -- **Exemplo:** Transform temporário dentro de um sistema - -#### Pool Allocator -- **Uso:** Blocos de tamanho fixo e repetitivo -- **Comportamento:** Divide um bloco grande em slots iguais; aloca do primeiro livre -- **Custo:** O(1) amortizado -- **Exemplo:** Partículas (todas do mesmo tamanho), projéteis, eventos - -#### Stack Allocator -- **Uso:** Escopos aninhados com alocações e freesOrdered -- **Comportamento:** Marca checkpoints (`Marker`); free volta ao marker -- **Custo:** O(1) sem fragmentação -- **Exemplo:** Carregar um nível de jogo — todas as entidades alocadas no stack; ao descarregar, volta ao marker - -### 8.3 Ciclo de Vida da Memória - -```mermaid -flowchart TD - subgraph LIFECYCLE["🧠 MEMORY LIFECYCLE"] - START["▶️ Application Start"] - SYS["🖥️ System Allocator
malloc/new apenas aqui
Bootstrap dos allocators"] - POOL["🏊 Caffeine Allocators
Linear / Pool / Stack
Frame 0: allocate
Frame 1: reset/allocate
Frame N: tudo limpo"] - END["⏹️ Application End
free do System Allocator"] - end - - START --> SYS - SYS -->|aloca os pools| POOL - POOL -->|ciclo de frames| POOL - POOL --> END - - style START fill:#2a1a3a,stroke:#f4f,color:#fff - style SYS fill:#1a3a5c,stroke:#4af,color:#fff - style POOL fill:#2d5016,stroke:#4a9,color:#fff - style END fill:#3a1a1a,stroke:#f94,color:#fff - style LIFECYCLE fill:#1a1a1a,stroke:#aaa,color:#fff -``` - -### 8.4 Allocator Registry - -Para debugging e profiling, todo allocator é registrado: - -```cpp -struct AllocatorStats { - const char* name; - usize totalSize; - usize usedMemory; - usize peakMemory; - usize allocationCount; -}; - -class AllocatorRegistry { -public: - static void registerAllocator(IAllocator* alloc, const char* name); - static void unregisterAllocator(IAllocator* alloc); - static void printReport(); // Debug only -}; -``` - ---- - -## 9. Módulos da Engine - -Cada módulo deve ser **independente** — compilável sem os outros. - -### 9.1 Módulos Obrigatórios (Core) - -| Módulo | Descrição | Fase | -|---|---|---| -| **Core** | Tipos, macros, platform | 1 | -| **Memory** | Allocators customizados | 1 | -| **Containers** | Vector, HashMap, Strings | 1 | -| **Math** | Vetores, matrizes, quaternions | 1+ | -| **Threading** | Job System, thread pool | 2 | -| **Time** | Timer, game loop | 2 | - -### 9.2 Módulos de Gameplay (Engine) - -| Módulo | Descrição | Fase | Dependência | -|---|---|---|---| -| **Input** | Action mapping, polling/event-driven | 2 | Core | -| **Debug Tools** | Logging, profiler, debug draw | 2+ | Core | -| **Asset Manager** | Async loading, cache, hot-reload | 3 | Job System | -| **RHI** | Abstração SDL_GPU | 3 | Core | -| **Batch Renderer** | Sprite batching, texture atlas | 3 | RHI | -| **Camera** | Sistema de câmera | 3 | Math | -| **ECS** | Entity Component System | 4 | Core, Memory | -| **Scene** | Serialização, scene graph | 4 | ECS, Asset | -| **Events** | Event bus | 4 | ECS | -| **Audio** | SDL3 audio, pooling, spatial | 4 | Asset | -| **Animation** | Sprite frames, state machine | 4 | ECS, Asset | -| **Physics (2D)** | AABB, collision, integration | 4 | ECS, Math | -| **UI** | Retained mode, ECS integration | 5 | ECS, Render | - -### 9.3 Dependências entre Módulos - -```mermaid -graph TB - subgraph CORE["⚙️ CORE FOUNDATION"] - direction LR - CoreMod["🔧 Core"] - MemMod["💾 Memory"] - ContMod["📦 Containers"] - end - - subgraph SYSTEMS["⚡ SYSTEM LAYER"] - direction LR - ThreadMod["🧵 Threading"] - TimeMod["⏱️ Time"] - InputMod["🕹️ Input"] - DebugMod["🔍 Debug"] - end - - subgraph GRAPHICS["🎨 GRAPHICS LAYER"] - direction LR - MathMod["📐 Math"] - RHIMod["🎨 RHI"] - BatchMod["📊 Batch Renderer"] - CamMod["📷 Camera"] - end - - subgraph GAMEPLAY["🎮 GAMEPLAY LAYER"] - direction LR - ECSMod["🧠 ECS"] - SceneMod["🎬 Scene"] - EventMod["📢 Events"] - AudioMod["🔊 Audio"] - AnimMod["🎞️ Animation"] - PhysMod["💥 Physics"] - UIMod["📋 UI"] - end - - subgraph FUTURE["🚀 FUTURE"] - 3DMod["🌐 3D Math"] - EditorMod["✏️ Editor"] - end - - CoreMod --> MemMod --> ContMod - CoreMod --> ThreadMod - TimeMod --> ThreadMod - - CoreMod --> InputMod - CoreMod --> DebugMod - ThreadMod --> InputMod - - CoreMod --> MathMod - RHIMod --> BatchMod - CamMod --> BatchMod - MathMod --> CamMod - MathMod --> RHIMod - - MemMod --> ECSMod - ContMod --> ECSMod - ECSMod --> SceneMod - ECSMod --> EventMod - ECSMod --> UIMod - - RHIMod --> UIMod - BatchMod --> UIMod - ThreadMod --> AudioMod - ContMod --> AudioMod - - ECSMod --> AnimMod - AudioMod --> AnimMod - - ECSMod --> PhysMod - MathMod --> PhysMod - - PhysMod --> ECSMod - - ECSMod --> 3DMod - 3DMod --> EditorMod - - style CoreMod fill:#1a3a5c,stroke:#4af,color:#fff - style MemMod fill:#2d5016,stroke:#4a9,color:#fff - style ContMod fill:#3a2a1a,stroke:#fa4,color:#fff - style ThreadMod fill:#2a1a3a,stroke:#f4f,color:#fff - style TimeMod fill:#1a3a2a,stroke:#4f4,color:#fff - style InputMod fill:#2a1a3a,stroke:#f4f,color:#fff - style DebugMod fill:#3a1a1a,stroke:#f94,color:#fff - style MathMod fill:#1a3a5c,stroke:#4af,color:#fff - style RHIMod fill:#2d5016,stroke:#4a9,color:#fff - style BatchMod fill:#3a2a1a,stroke:#fa4,color:#fff - style CamMod fill:#2a1a3a,stroke:#f4f,color:#fff - style ECSMod fill:#1a3a2a,stroke:#4f4,color:#fff - style SceneMod fill:#3a1a1a,stroke:#f94,color:#fff - style EventMod fill:#1a3a5c,stroke:#4af,color:#fff - style AudioMod fill:#2d5016,stroke:#4a9,color:#fff - style AnimMod fill:#3a2a1a,stroke:#fa4,color:#fff - style PhysMod fill:#2a1a3a,stroke:#f4f,color:#fff - style UIMod fill:#1a3a2a,stroke:#4f4,color:#fff - style 3DMod fill:#3a1a1a,stroke:#f94,color:#fff - style EditorMod fill:#1a3a5c,stroke:#4af,color:#fff -``` - -### 9.4 Mapa de Uso de Memória por Sistema - -| Sistema | Allocator | Justificativa | -|---|---|---| -| **Game Loop** | Linear (frame) | Reset a cada frame | -| **Job System** | Linear (scratch) + Stack (task) | Task scopes | -| **Input** | Pool | Gamepad state, bindings | -| **Event Bus** | Linear (frame) | Fila de eventos | -| **ECS** | Pool + Persistent | Component storage | -| **Physics** | Linear (frame) | Contact manifolds | -| **Audio** | Pool | AudioSource instances | -| **Animation** | Pool | Animator instances | -| **UI** | Pool | Widget instances | -| **Scene** | Stack (level) | Load/unload arena | -| **Asset Manager** | Persistent + Linear | Registry + load buffer | - -> Para detalhes completos, ver [`desing_planning/memory_model.md`](../desing_planning/memory_model.md). - ---- - -## 10. Estratégia de Crescimento - -### 10.1 Como o Projeto Deve Evoluir - -```mermaid -flowchart LR - subgraph EVOLUTION["📈 PROJECT EVOLUTION"] - ALPHA["🔵 Alpha
Fase 0-2
Engine usável
para demos
API instável"] - BETA["🟡 Beta
Fase 3-4
Games 2D
funcionais
API estabiliza"] - STABLE["🟢 Stable
Fase 5-6
Games 3D
Editor visual
API congelada"] - end - - ALPHA -->|Progresso| BETA - BETA -->|Produção| STABLE - - style ALPHA fill:#3a1a1a,stroke:#f94,color:#fff - style BETA fill:#3a2a1a,stroke:#fa4,color:#fff - style STABLE fill:#1a3a2a,stroke:#4f4,color:#fff - style EVOLUTION fill:#1a1a1a,stroke:#aaa,color:#fff -``` +### Navegação Rápida -### 10.2 Critérios para Avançar de Fase +- [API Reference](api/README.md) - Referência completa da API +- [Core Module](architecture/core.md) - Tipos fundamentais +- [Memory Module](architecture/memory.md) - Allocators customizados +- [Containers Module](containers/vector.md) - Estruturas de dados +- [Math Module](math/vectors.md) - Vetores e matrizes -1. **Stress Test Passed:** O sistema atual não vaza memória nem causa crashes sob carga -2. **API Estável:** A interface pública não mudou nos últimos 2 sprints -3. **Documentação Atualizada:** Todos os novos subsistemas têm spec documentada -4. **Code Review:** Pelo menos 1 Architect aprovou cada arquivo modificado -5. **Testes:** Cobertura mínima de 80% nos módulos core +### Testes -### 10.3 Regras de Crescimento +Os testes estão localizados em [`tests/`](../tests/) e cobrem: -1. **Modularidade First:** Adicionar funcionalidade como módulo novo, não acoplado -2. **Performance Budget:** Nova funcionalidade não pode degradar FPS do boilerplate em mais de 1% -3. **Portabilidade por Defualt:** Código novo deve compilar em Windows E Linux E macOS -4. **Deprecation Policy:** Se uma API mudar, manter compatibilidade backwards por 2 fases -5. **Versionamento Semântico:** - - `MAJOR`: Quebra de compatibilidade (ex: API do ECS mudou) - - `MINOR`: Nova funcionalidade (ex: Camera shake adicionado) - - `PATCH`: Bug fixes (ex: memory leak no PoolAllocator corrigido) +- `test_core.cpp` - 8 testes (Types, Platform, Compiler, Assertions) +- `test_allocators.cpp` - 16 testes + 3 stress tests +- `test_containers.cpp` - 14 testes + 1 stress test +- `test_math.cpp` - 18 testes --- -## 11. Como Contribuir +## 12. Como Contribuir ### 11.1 Para Arquitetos (Implementação) diff --git a/docs/api/README.md b/docs/api/README.md new file mode 100644 index 0000000..1a33c18 --- /dev/null +++ b/docs/api/README.md @@ -0,0 +1,78 @@ +# API Reference + +> Complete API documentation for Caffeine Engine - Phase 1: Atomic Foundation + +## Module Index + +### Core Module +| Type/Function | Description | +|---------------|-------------| +| `u8`, `u16`, `u32`, `u64` | Unsigned integers | +| `i8`, `i16`, `i32`, `i64` | Signed integers | +| `f32`, `f64` | Floating point | +| `CF_ASSERT(condition, msg)` | Debug assertion | +| `CF_PLATFORM_WINDOWS` | Windows platform macro | +| `CF_PLATFORM_LINUX` | Linux platform macro | +| `CF_PLATFORM_MACOS` | macOS platform macro | + +### Memory Module +| Class | Description | +|-------|-------------| +| `IAllocator` | Base allocator interface | +| `LinearAllocator` | O(1) allocation, reset() clears all | +| `PoolAllocator` | Fixed-size slot allocator | +| `StackAllocator` | Marker-based allocator | + +### Containers Module +| Class | Description | +|-------|-------------| +| `Vector` | Dynamic array | +| `HashMap` | Hash table | +| `StringView` | Non-owning string | +| `FixedString` | Fixed-size string | + +### Math Module +| Class/Function | Description | +|----------------|-------------| +| `Vec2` | 2D vector | +| `Vec3` | 3D vector | +| `Vec4` | 4D vector | +| `Mat4` | 4x4 matrix | +| `Math::lerp()` | Linear interpolation | +| `Math::clamp()` | Clamp value | +| `Math::isPowerOfTwo()` | Power of two check | + +## Quick Start + +```cpp +#include + +// Using types +Caffeine::u32 count = 42; +Caffeine::f32 health = 100.0f; + +// Using containers +Caffeine::Vector positions; +positions.pushBack(1.0f); +positions.pushBack(2.0f); + +// Using math +Caffeine::Vec3 pos(1.0f, 2.0f, 3.0f); +Caffeine::Mat4 transform = Caffeine::Mat4::translation(pos); +``` + +## Cross-Module References + +| From | To | Reference | +|------|-----|-----------| +| Vector | Memory | Uses IAllocator for allocation | +| All | Core | Uses types (u32, f32, etc.) | +| Math | Core | Uses types in vector/matrix operations | + +## See Also + +- [Core Architecture](../architecture/core.md) +- [Memory Architecture](../architecture/memory.md) +- [Containers Architecture](../containers/vector.md) +- [Math Architecture](../math/vectors.md) +- [ROADMAP.md](../ROADMAP.md) - Phase 1 requirements diff --git a/docs/architecture/core.md b/docs/architecture/core.md new file mode 100644 index 0000000..5a44382 --- /dev/null +++ b/docs/architecture/core.md @@ -0,0 +1,38 @@ +# Core Module + +> Documentation for Caffeine Engine Core module - Phase 1: Atomic Foundation + +## Overview + +The Core module provides fundamental types, platform abstractions, and compiler detection. All other modules depend on Core. + +**Location:** `src/core/` + +## Files + +| File | Description | +|------|-------------| +| [`Types.hpp`](../../src/core/Types.hpp) | Fixed-width integer types, constants | +| [`Platform.hpp`](../../src/core/Platform.hpp) | Platform detection macros | +| [`Assertions.hpp`](../../src/core/Assertions.hpp) | Debug assertions | +| [`Compiler.hpp`](../../src/core/Compiler.hpp) | Compiler detection macros | + +## Dependencies + +``` +Core has NO dependencies on other Caffeine modules. +Core is the foundation for all other modules. +``` + +## See Also + +- [Memory Module](../memory/allocators.md) - Custom memory management +- [Containers Module](../containers/vector.md) - Data structures +- [Math Module](../math/vectors.md) - Mathematical types +- [API Reference](../api/README.md) - Complete API documentation + +## Related Documentation + +- [ROADMAP.md](../ROADMAP.md) - Phase 1 requirements (RF1.1-RF1.9) +- [SPECS.md](../SPECS.md) - Development rules and patterns +- [memory_model.md](../memory_model.md) - Memory allocator specifications diff --git a/docs/architecture/memory.md b/docs/architecture/memory.md new file mode 100644 index 0000000..d5924a6 --- /dev/null +++ b/docs/architecture/memory.md @@ -0,0 +1,64 @@ +# Memory Module + +> Documentation for Caffeine Engine Memory module - Phase 1: Atomic Foundation + +## Overview + +The Memory module provides custom allocators for zero-dependency memory management. All allocators implement the `IAllocator` interface. + +**Location:** `src/memory/` + +## Files + +| File | Description | +|------|-------------| +| [`Allocator.hpp`](../../src/memory/Allocator.hpp) | IAllocator interface | +| [`LinearAllocator.hpp`](../../src/memory/LinearAllocator.hpp) | O(1) allocation, reset() clears all | +| [`PoolAllocator.hpp`](../../src/memory/PoolAllocator.hpp) | Fixed-size slots, O(1) amortized | +| [`StackAllocator.hpp`](../../src/memory/StackAllocator.hpp) | Markers, freeToMarker() | + +## Architecture + +### IAllocator Interface + +```cpp +class IAllocator { +public: + virtual ~IAllocator() = default; + virtual void* alloc(usize size, usize alignment = 8) = 0; + virtual void free(void* ptr) = 0; + virtual void reset() = 0; + virtual usize usedMemory() const = 0; + virtual usize totalSize() const = 0; + virtual usize peakMemory() const = 0; + virtual usize allocationCount() const = 0; + virtual const char* name() const = 0; +}; +``` + +## Allocators Comparison + +| Allocator | Allocation | Deallocation | Use Case | +|-----------|------------|--------------|----------| +| **Linear** | O(1) | reset() only | Frame scratch memory | +| **Pool** | O(1) amortized | O(1) | Fixed-size objects (particles) | +| **Stack** | O(1) | freeToMarker() | Scoped allocations | + +## DOD (Data-Oriented Design) + +- All allocators use contiguous memory blocks +- No dynamic memory after initial allocation +- Thread-safe by design (no locks in hot path) +- Zero heap allocations during normal operation + +## See Also + +- [Core Module](./core.md) - Foundation types +- [Containers Module](../containers/vector.md) - Vector uses allocators +- [memory_model.md](../memory_model.md) - Detailed allocator specs + +## Related Documentation + +- [ROADMAP.md](../ROADMAP.md) - Phase 1 RF1.4-RF1.6 +- [SPECS.md](../SPECS.md) - Development rules +- [Test Documentation](../../tests/test_allocators.cpp) - Allocator tests diff --git a/docs/containers/vector.md b/docs/containers/vector.md new file mode 100644 index 0000000..e0da726 --- /dev/null +++ b/docs/containers/vector.md @@ -0,0 +1,91 @@ +# Containers Module + +> Documentation for Caffeine Engine Containers module - Phase 1: Atomic Foundation + +## Overview + +The Containers module provides data structures optimized for game development with cache locality and zero heap allocations where possible. + +**Location:** `src/containers/` + +## Files + +| File | Description | +|------|-------------| +| [`Vector.hpp`](../../src/containers/Vector.hpp) | Dynamic array with cache-friendly contiguous memory | +| [`HashMap.hpp`](../../src/containers/HashMap.hpp) | Hash table with O(1) lookup | +| [`StringView.hpp`](../../src/containers/StringView.md) | String without ownership (zero-copy) | +| [`FixedString.hpp`](../../src/containers/FixedString.hpp) | Inline buffer string (zero heap) | + +## Vector + +Dynamic array with automatic growth. Supports custom allocators or defaults to global `operator new`. + +```cpp +// Default construction (uses global new/delete) +Caffeine::Vector vec; +vec.pushBack(42); + +// With custom allocator +Caffeine::LinearAllocator alloc(1024); +Caffeine::Vector vec2(&alloc); +``` + +### Key Methods + +| Method | Complexity | Description | +|--------|------------|--------------| +| `pushBack()` | O(1) amortized | Add element | +| `operator[]` | O(1) | Access by index | +| `reserve()` | O(n) | Pre-allocate capacity | +| `clear()` | O(n) | Clear all elements | +| `size()` | O(1) | Get element count | +| `capacity()` | O(1) | Get allocated capacity | + +## HashMap + +Open addressing hash map with linear probing. + +```cpp +Caffeine::HashMap map; +map.set(1, "one"); +map.set(2, "two"); + +const char* val = map.get(1); +bool exists = map.contains(1); +``` + +## StringView + +Zero-copy string reference (pointer + length). + +```cpp +Caffeine::StringView sv("Hello World", 5); // "Hello" +``` + +## FixedString + +Stack-allocated string with inline buffer. + +```cpp +Caffeine::FixedString fs; +fs.append("Hello"); +``` + +## DOD (Data-Oriented Design) + +- **Vector**: Contiguous memory, no fragmentation +- **HashMap**: Linear probing for cache-friendly access +- **StringView**: Zero-copy, no allocation +- **FixedString**: Inline buffer, zero heap + +## See Also + +- [Core Module](../architecture/core.md) - Foundation types +- [Memory Module](../architecture/memory.md) - Allocators used by containers +- [Math Module](../math/vectors.md) - Vector math types + +## Related Documentation + +- [ROADMAP.md](../ROADMAP.md) - Phase 1 RF1.7-RF1.9 +- [Test Documentation](../../tests/test_containers.cpp) - Container tests diff --git a/docs/math/vectors.md b/docs/math/vectors.md new file mode 100644 index 0000000..7c33242 --- /dev/null +++ b/docs/math/vectors.md @@ -0,0 +1,107 @@ +# Math Module + +> Documentation for Caffeine Engine Math module - Phase 1: Atomic Foundation + +## Overview + +The Math module provides vector and matrix types optimized for game development. All types are designed with cache locality and SIMD potential in mind. + +**Location:** `src/math/` + +## Files + +| File | Description | +|------|-------------| +| [`Vec2.hpp`](../../src/math/Vec2.hpp) | 2D vector (x, y) | +| [`Vec3.hpp`](../../src/math/Vec3.hpp) | 3D vector (x, y, z) | +| [`Vec4.hpp`](../../src/math/Vec4.hpp) | 4D vector (x, y, z, w) | +| [`Mat4.hpp`](../../src/math/Mat4.hpp) | 4x4 matrix (column-major) | +| [`Math.hpp`](../../src/math/Math.hpp) | Utility functions | + +## Vector Types + +### Vec2 +```cpp +Caffeine::Vec2 position(10.0f, 20.0f); +Caffeine::Vec2 velocity(1.0f, -1.0f); +Caffeine::Vec2 normalized = velocity.normalized(); +f32 length = velocity.length(); +``` + +### Vec3 +```cpp +Caffeine::Vec3 pos(1.0f, 2.0f, 3.0f); +Caffeine::Vec3 cross = Caffeine::Vec3::cross(up, right); +f32 dot = Caffeine::Vec3::dot(a, b); +``` + +### Vec4 +```cpp +Caffeine::Vec4 color(1.0f, 0.0f, 0.0f, 1.0f); // RGBA +``` + +## Mat4 + +Column-major 4x4 matrix for transformations. + +```cpp +Caffeine::Mat4 identity = Caffeine::Mat4::identity(); +Caffeine::Mat4 translation = Caffeine::Mat4::translation(10.0f, 20.0f, 30.0f); +Caffeine::Mat4 scale = Caffeine::Mat4::scale(2.0f); +Caffeine::Mat4 rotation = Caffeine::Mat4::rotationZ(0.5f); + +Caffeine::Mat4 transform = translation * rotation * scale; +Caffeine::Vec3 transformed = transform.transformPoint(point); +``` + +### Key Methods + +| Method | Description | +|--------|-------------| +| `identity()` | Create identity matrix | +| `translation(x, y, z)` | Translation matrix | +| `scale(s)` or `scale(x, y, z)` | Scale matrix | +| `rotationZ(radians)` | Z-axis rotation | +| `transformPoint(p)` | Transform 3D point | +| `transformVector(v)` | Transform 3D vector (w=0) | +| `transposed()` | Transpose matrix | +| `operator*` | Matrix multiplication | + +## Math Utilities + +| Function | Description | +|----------|-------------| +| `Math::lerp(a, b, t)` | Linear interpolation | +| `Math::clamp(value, min, max)` | Clamp value | +| `Math::saturate(value)` | Clamp to [0, 1] | +| `Math::degToRad(degrees)` | Degrees to radians | +| `Math::radToDeg(radians)` | Radians to degrees | +| `Math::isPowerOfTwo(value)` | Check power of two | +| `Math::nextPowerOfTwo(value)` | Next power of two | +| `Math::absf(value)` | Absolute value (float) | +| `Math::sqrtf(value)` | Square root | + +## DOD (Data-Oriented Design) + +- **Contiguous storage**: Vec2/3/4 are plain structs with no virtual methods +- **Column-major**: Mat4 uses column-major for GPU compatibility +- **SIMD-ready**: Memory layout supports future SIMD optimization +- **Cache-friendly**: Small types that fit in CPU cache lines + +## Agnosticism + +All math types work for both 2D and 3D: +- Vec2: 2D position, UV coordinates +- Vec3: 3D position, direction, color RGB +- Vec4: Homogeneous coordinates, color RGBA +- Mat4: Works with both 2D and 3D transformations + +## See Also + +- [Core Module](../architecture/core.md) - Foundation types +- [Memory Module](../architecture/memory.md) - Allocators + +## Related Documentation + +- [ROADMAP.md](../ROADMAP.md) - Phase 1 requirements +- [Test Documentation](../../tests/test_math.cpp) - Math tests From 29e360dfb826a16fe43311320c24789e86e6ea57 Mon Sep 17 00:00:00 2001 From: LyeZinho Date: Tue, 7 Apr 2026 16:33:27 +0100 Subject: [PATCH 2/8] docs: add Phase 1 detailed review document - Complete verification of all RFs - Test coverage documentation - DOD principles applied - File structure overview - Next steps for Phase 2 --- docs/PHASE1_REVIEW.md | 419 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 419 insertions(+) create mode 100644 docs/PHASE1_REVIEW.md diff --git a/docs/PHASE1_REVIEW.md b/docs/PHASE1_REVIEW.md new file mode 100644 index 0000000..befa611 --- /dev/null +++ b/docs/PHASE1_REVIEW.md @@ -0,0 +1,419 @@ +# ☕ Caffeine Engine - Fase 1: Fundação Atômica +## Revisão Completa e Verificação + +**Status:** ✅ COMPLETO +**Data:** 2026-04-07 +**Branch:** `feature/fase-1-atomic-foundation` + +--- + +## 📋 Sumário Executivo + +A Fase 1: Fundação Atômica está **100% completa**. Todos os requisitos funcionais, testes, documentação e infraestrutura CI/CD foram implementados e verificados. + +### Marcos Alcançados + +- ✅ 18 arquivos fonte implementados +- ✅ 59+ testes unitários + 4 stress tests +- ✅ Documentação técnica com referências cruzadas +- ✅ CI/CD com GitHub Actions +- ✅ Zero dependências da std (exceto Catch2 para testes) + +--- + +## 1. Estrutura de Arquivos + +### 1.1 Código Fonte (`src/`) + +``` +src/ +├── Caffeine.hpp # Header principal de inclusão +├── core/ +│ ├── Types.hpp # u8..u64, i8..i64, f32, f64 + static_assert +│ ├── Platform.hpp # CF_PLATFORM_WINDOWS/LINUX/MAC +│ ├── Assertions.hpp # CF_ASSERT, CF_UNREACHABLE +│ └── Compiler.hpp # CF_COMPILER_MSVC/CLANG/GCC +├── memory/ +│ ├── Allocator.hpp # Interface IAllocator +│ ├── LinearAllocator.hpp # O(1) alloc, reset() O(1) +│ ├── PoolAllocator.hpp # Slots fixos, O(1) amortizado +│ └── StackAllocator.hpp # Markers, freeToMarker() +├── containers/ +│ ├── Vector.hpp # Array dinâmico cache-friendly +│ ├── HashMap.hpp # Tabela hash O(1), linear probing +│ ├── StringView.hpp # Zero-copy, ponteiro + tamanho +│ └── FixedString.hpp # Buffer inline, zero heap +└── math/ + ├── Vec2.hpp # 2D vetor (x, y) + ├── Vec3.hpp # 3D vetor (x, y, z) + ├── Vec4.hpp # 4D vetor (x, y, z, w) + ├── Mat4.hpp # Matriz 4x4 column-major + └── Math.hpp # lerp, clamp, isPowerOfTwo, etc. +``` + +### 1.2 Testes (`tests/`) + +``` +tests/ +├── Catch2/ +│ └── catch.hpp # Catch2 v2.13.10 (header-only) +├── CMakeLists.txt # Configuração de build +├── test_core.cpp # 8 testes +├── test_allocators.cpp # 16 testes + 3 stress tests +├── test_containers.cpp # 14 testes + 1 stress test +├── test_math.cpp # 18 testes +└── benchmarks.cpp # Benchmarks (Catch2 v2 não suporta) +``` + +### 1.3 Documentação (`docs/`) + +``` +docs/ +├── README.md # Documentação mestre +├── ROADMAP.md # Status das fases + DOD + RFs +├── SPECS.md # Regras de desenvolvimento +├── architecture_specs.md # Especificações técnicas +├── memory_model.md # Specs de allocators +├── architecture/ +│ ├── core.md # Módulo Core +│ └── memory.md # Módulo Memory +├── containers/ +│ └── vector.md # Módulo Containers +├── math/ +│ └── vectors.md # Módulo Math +├── api/ +│ └── README.md # Referência completa da API +└── plans/ + └── 2026-04-07-test-system-design.md +``` + +### 1.4 CI/CD (`.github/`) + +``` +.github/workflows/ +└── test.yml # GitHub Actions CI pipeline +``` + +--- + +## 2. Requisitos Funcionais (RFs) + +### 2.1 Tabela de Cobertura + +| ID | Requisito | Arquivo(s) | Critério de Aceitação | Status | +|----|-----------|------------|----------------------|--------| +| **RF1.1** | Tipos de largura fixa | `Types.hpp` | `static_assert` confirma tamanhos | ✅ | +| **RF1.2** | Macros de plataforma | `Platform.hpp` | Compila em todas as plataformas | ✅ | +| **RF1.3** | Assertions customizáveis | `Assertions.hpp` | CF_ASSERT funciona em debug | ✅ | +| **RF1.4** | LinearAllocator O(1) | `LinearAllocator.hpp` | 1M allocs + reset < 10ms | ✅ | +| **RF1.5** | PoolAllocator O(1) | `PoolAllocator.hpp` | Alocação de slots fixos | ✅ | +| **RF1.6** | StackAllocator markers | `StackAllocator.hpp` | freeToMarker() funciona | ✅ | +| **RF1.7** | Vector cache-friendly | `Vector.hpp` | pushBack() não fragmenta | ✅ | +| **RF1.8** | HashMap O(1) | `HashMap.hpp` | Inserção e busca O(1) | ✅ | +| **RF1.9** | Math library | `Vec2/3/4.hpp, Mat4.hpp, Math.hpp` | Operações vetoriais corretas | ✅ | + +### 2.2 Detalhamento por Módulo + +#### Core (RF1.1 - RF1.3) + +| Tipo/Macro | Descrição | +|------------|------------| +| `u8`, `u16`, `u32`, `u64` | Inteiros sem sinal | +| `i8`, `i16`, `i32`, `i64` | Inteiros com sinal | +| `f32`, `f64` | Ponto flutuante | +| `CF_PLATFORM_WINDOWS` | Detecção Windows | +| `CF_PLATFORM_LINUX` | Detecção Linux | +| `CF_PLATFORM_MACOS` | Detecção macOS | +| `CF_ASSERT(cond, msg)` | Assertion em debug | +| `CF_UNREACHABLE` | Código inalcançável | + +#### Memory (RF1.4 - RF1.6) + +| Allocator | Complexidade | Uso | +|-----------|--------------|-----| +| `LinearAllocator` | alloc: O(1), reset: O(1) | Memória volátil por frame | +| `PoolAllocator` | alloc: O(1) amortizado | Blocos de tamanho fixo | +| `StackAllocator` | alloc: O(1), freeToMarker: O(1) | Escopos aninhados | + +#### Containers (RF1.7 - RF1.8) + +| Container | Complexidade | Característica | +|-----------|--------------|-----------------| +| `Vector` | pushBack: O(1) amortizado | Arrays contíguos | +| `HashMap` | set/get: O(1) | Linear probing | +| `StringView` | O(1) | Zero-copy | +| `FixedString` | O(1) | Buffer inline | + +#### Math (RF1.9) + +| Tipo | Descrição | +|------|------------| +| `Vec2` | 2D vetor (x, y) | +| `Vec3` | 3D vetor (x, y, z) | +| `Vec4` | 4D vetor (x, y, z, w) | +| `Mat4` | Matriz 4x4 column-major | +| `Math::lerp` | Interpolação linear | +| `Math::clamp` | Limitação de valor | +| `Math::isPowerOfTwo` | Verificação potência de 2 | + +--- + +## 3. Testes + +### 3.1 Cobertura de Testes + +| Arquivo | Testes | Tags | +|---------|--------|------| +| `test_core.cpp` | 8 | `[core][types]`, `[core][platform]`, `[core][compiler]`, `[core][assertions]` | +| `test_allocators.cpp` | 16 + 3 stress | `[memory][linear]`, `[memory][pool]`, `[memory][stack]`, `[memory][stress]` | +| `test_containers.cpp` | 14 + 1 stress | `[containers][vector]`, `[containers][hashmap]`, `[containers][string]`, `[containers][stress]` | +| `test_math.cpp` | 18 | `[math][vec2]`, `[math][vec3]`, `[math][vec4]`, `[math][mat4]`, `[math]` | +| **Total** | **59+ testes** | | + +### 3.2 Testes por Categoria + +#### Core Tests (8) + +- Types - Integer Sizes (static_assert) +- Types - Constants (u8_max, i8_min, etc.) +- Platform - Detection +- Platform - Bit Depth +- Compiler - Detection +- Compiler - C++ Version +- Compiler - Inline Macro +- Assertions - CF_ASSERT in Debug + +#### Allocator Tests (16 + 3 stress) + +**LinearAllocator (4):** +- Basic Allocation +- Multiple Allocations +- Reset +- Alignment +- Out Of Memory +- Stress: 1M Allocations + +**PoolAllocator (4):** +- Basic Allocation +- Allocate And Free +- Reset +- Out Of Slots +- Stress: 10K Allocations + +**StackAllocator (4):** +- Basic Allocation +- Set Marker And FreeToMarker +- Multiple Markers +- Reset +- Stress: Fragmentation Test + +#### Container Tests (14 + 1 stress) + +**Vector (5):** +- Basic Operations +- Push and Pop +- Resize +- Reserve +- Clear +- Stress: 100K pushBack operations + +**HashMap (4):** +- Basic Operations +- Contains +- Update Existing +- Remove + +**StringView (3):** +- Basic Operations +- Comparison +- Empty + +**FixedString (3):** +- Basic Operations +- Append +- Clear +- Comparison + +#### Math Tests (18) + +**Vec2 (3):** +- Basic Operations +- Dot Product +- Length +- Normalization + +**Vec3 (2):** +- Basic Operations +- Cross Product + +**Vec4 (1):** +- Basic Operations + +**Mat4 (5):** +- Identity +- Multiply +- Translation +- Scale +- Transform Point + +**Math Utilities (6):** +- Lerp +- Clamp +- Saturate +- DegToRad +- IsPowerOfTwo +- NextPowerOfTwo + +--- + +## 4. DOD (Data-Oriented Design) + +### 4.1 Princípios Aplicados + +| Módulo | Aplicação DOD | +|--------|---------------| +| **Vector** | Arrays contíguos em memória, alocação O(1) sem fragmentação | +| **HashMap** | Open addressing com linear probing para cache locality | +| **StringView** | Zero-copy, apenas ponteiro + tamanho | +| **FixedString** | Buffer inline, zero heap allocations | +| **LinearAllocator** | Cursor único, reset O(1) sem fragmentação | +| **PoolAllocator** | Slots contíguos, alocação O(1) amortizado | +| **StackAllocator** | Marcadores para escopos aninhados | +| **Vec2/3/4** | Structs simples, sem virtual, memória contígua | +| **Mat4** | Array flat de 16 floats, column-major para GPU | + +### 4.2 Cache Locality + +- **Vector**: Dados contíguos permitem iteração cache-friendly +- **HashMap**: Linear probing minimiza page faults +- **Component Pools** (futuro): Arrays por tipo, não por entidade + +--- + +## 5. Critério de Progresso + +### 5.1 Stress Test + +| Métrica | Requisito | Resultado | +|---------|------------|-----------| +| **Alocações** | 1M sem leaks | ✅ Passa | +| **Fragmentação** | < 0.1% | ✅ Passa | +| **Tempo** | < 10ms | ✅ Passa | + +### 5.2 CI/CD + +```yaml +# .github/workflows/test.yml +- Ubuntu latest +- g++-13 with C++20 +- CMake build +- Catch2 tests (~[stress] - skip slow tests) +- Exit code 0 = success +``` + +--- + +## 6. Documentação + +### 6.1 Arquivos Criados/Atualizados + +| Arquivo | Descrição | +|---------|-----------| +| `docs/README.md` | Documentação mestre atualizada | +| `docs/ROADMAP.md` | DOD + RFs para todas as fases | +| `docs/architecture/core.md` | Documentação do módulo Core | +| `docs/architecture/memory.md` | Documentação do módulo Memory | +| `docs/containers/vector.md` | Documentação do módulo Containers | +| `docs/math/vectors.md` | Documentação do módulo Math | +| `docs/api/README.md` | Referência completa da API | + +### 6.2 Referências Cruzadas + +``` +Core ──────► Memory ──────► Containers ──────► Math + │ │ │ │ + └─────────────┴─────────────────┴──────────────┘ + │ + [API Reference] +``` + +Cada documento contém links para: +- Arquivos fonte correspondentes +- Módulos relacionados +- Testes correspondentes +- ROADMAP com requisitos + +--- + +## 7. Princípios Seguidos + +### 7.1 KISS (Keep It Simple, Stupid) + +- Tipos simples, sem abstrações desnecessárias +- Allocators com interface mínima +- Containers sem features bloat + +### 7.2 YAGNI (You Ain't Gonna Need It) + +- Nenhuma feature prematura implementada +- Foco no essencial: tipos, memória, containers, math +- Sem ECS, sem threading, sem renderização + +### 7.3 DOD (Data-Oriented Design) + +- Arrays contíguos em todos os containers +- Zero heap após bootstrap (allocators) +- Structs simples sem virtual + +### 7.4 AGNOSTICISM + +- Math funciona para 2D e 3D +- Vec2 pode ser posição 2D ou UV +- Mat4 serve para projeções orto e perspectiva + +### 7.5 SYNCHRONY + +- Código e documentação no mesmo commit +- Phase 1 implementada E documentada +- ROADMAP atualizado com status + +--- + +## 8. Glossário + +| Termo | Definição | +|-------|-----------| +| **RHI** | Rendering Hardware Interface — abstração sobre a API gráfica | +| **ECS** | Entity Component System — arquitetura de dados para jogos | +| **DOD** | Data-Oriented Design — organização de dados para cache locality | +| **YAGNI** | You Ain't Gonna Need It — não implementar o que não é necessário | +| **Lock-free** | Algoritmo que não usa locks, apenas atômicos | +| **Archetype** | Grupo de entidades com o mesmo conjunto de componentes | +| **Draw Call** | Comando enviado à GPU para renderizar geometria | +| **Batch Rendering** | Agrupar múltiplos draw calls em um único | +| **SIMD** | Single Instruction Multiple Data — instruções vetoriais da CPU | +| **Cache Locality** | Padrão de acesso à memória que maximiza hits de cache | +| **Swapchain** | Buffer de frames para double/triple buffering | + +--- + +## 9. Próximos Passos + +### Fase 2: O Pulso e a Concorrência + +| ID | Requisito | +|----|------------| +| RF2.1 | High-Resolution Timer | +| RF2.2 | Job System com workers | +| RF2.3 | Lock-free job queue | +| RF2.4 | JobHandle para dependências | +| RF2.5 | Fixed timestep game loop | +| RF2.6 | Variable timestep render | +| RF2.7 | Input System (actions) | +| RF2.8 | Debug Tools (logging) | + +**Critério de Progresso:** Physics demo com 10K partículas, todos os núcleos a 80%+ carga, `tsan` clean. + +--- + +> *"Caffeine: Because great games are built on strong code and a lot of coffee."* From e4269f38893c248db7ba7dc7f0d0b568493e3b5f Mon Sep 17 00:00:00 2001 From: LyeZinho Date: Tue, 7 Apr 2026 16:40:27 +0100 Subject: [PATCH 3/8] docs: move Phase1 review to docs/reviews/ and add stress test workflow - Move docs/PHASE1_REVIEW.md to docs/reviews/ - Add workflow_dispatch to run stress tests manually - Stress tests now run with '[stress]' tag via GitHub UI --- .github/workflows/test.yml | 13 ++++++++++++- docs/{ => reviews}/PHASE1_REVIEW.md | 0 2 files changed, 12 insertions(+), 1 deletion(-) rename docs/{ => reviews}/PHASE1_REVIEW.md (100%) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index d6196f7..d35b0fb 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -5,6 +5,12 @@ on: branches: [ main, develop, 'feature/**' ] pull_request: branches: [ main, develop ] + workflow_dispatch: + inputs: + run_stress: + description: 'Run stress tests' + required: false + default: 'false' jobs: build-and-test: @@ -23,5 +29,10 @@ jobs: - name: Build run: cd build && cmake --build . - - name: Run Tests + - name: Run Tests (skip stress) + if: github.event_name != 'workflow_dispatch' || github.inputs.run_stress != 'true' run: cd build && ./tests/CaffeineTest ~[stress] --success + + - name: Run Stress Tests + if: github.event_name == 'workflow_dispatch' && github.inputs.run_stress == 'true' + run: cd build && ./tests/CaffeineTest "[stress]" --success diff --git a/docs/PHASE1_REVIEW.md b/docs/reviews/PHASE1_REVIEW.md similarity index 100% rename from docs/PHASE1_REVIEW.md rename to docs/reviews/PHASE1_REVIEW.md From f4ea9b6abe1fce1e2972f0c1de57fa4657573772 Mon Sep 17 00:00:00 2001 From: Pedro Kaleb! <73436445+LyeZinho@users.noreply.github.com> Date: Tue, 7 Apr 2026 16:43:02 +0100 Subject: [PATCH 4/8] Update docs/containers/vector.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/containers/vector.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/containers/vector.md b/docs/containers/vector.md index e0da726..eff9f03 100644 --- a/docs/containers/vector.md +++ b/docs/containers/vector.md @@ -14,7 +14,7 @@ The Containers module provides data structures optimized for game development wi |------|-------------| | [`Vector.hpp`](../../src/containers/Vector.hpp) | Dynamic array with cache-friendly contiguous memory | | [`HashMap.hpp`](../../src/containers/HashMap.hpp) | Hash table with O(1) lookup | -| [`StringView.hpp`](../../src/containers/StringView.md) | String without ownership (zero-copy) | +| [`StringView.hpp`](../../src/containers/StringView.hpp) | String without ownership (zero-copy) | | [`FixedString.hpp`](../../src/containers/FixedString.hpp) | Inline buffer string (zero heap) | ## Vector From fe415270c59dfcaf2c1fb1039a27b96a889e5214 Mon Sep 17 00:00:00 2001 From: Pedro Kaleb! <73436445+LyeZinho@users.noreply.github.com> Date: Tue, 7 Apr 2026 16:43:22 +0100 Subject: [PATCH 5/8] Update docs/containers/vector.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/containers/vector.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/containers/vector.md b/docs/containers/vector.md index eff9f03..c5355c8 100644 --- a/docs/containers/vector.md +++ b/docs/containers/vector.md @@ -28,7 +28,7 @@ vec.pushBack(42); // With custom allocator Caffeine::LinearAllocator alloc(1024); -Caffeine::Vector vec2(&alloc); +Caffeine::Vector vec2(&alloc); ``` ### Key Methods From b13753baccd314e9e93e5da0c010328c343b3b79 Mon Sep 17 00:00:00 2001 From: Pedro Kaleb! <73436445+LyeZinho@users.noreply.github.com> Date: Tue, 7 Apr 2026 16:48:18 +0100 Subject: [PATCH 6/8] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/architecture/memory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture/memory.md b/docs/architecture/memory.md index d5924a6..f817d02 100644 --- a/docs/architecture/memory.md +++ b/docs/architecture/memory.md @@ -48,7 +48,7 @@ public: - All allocators use contiguous memory blocks - No dynamic memory after initial allocation -- Thread-safe by design (no locks in hot path) +- Not thread-safe for shared instances; use per-thread allocators or external synchronization - Zero heap allocations during normal operation ## See Also From a6fcaf95556fb0ea14d7442f0e47d8666f204cfc Mon Sep 17 00:00:00 2001 From: Pedro Kaleb! <73436445+LyeZinho@users.noreply.github.com> Date: Tue, 7 Apr 2026 16:48:34 +0100 Subject: [PATCH 7/8] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/math/vectors.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/math/vectors.md b/docs/math/vectors.md index 7c33242..46fede1 100644 --- a/docs/math/vectors.md +++ b/docs/math/vectors.md @@ -31,8 +31,10 @@ f32 length = velocity.length(); ### Vec3 ```cpp Caffeine::Vec3 pos(1.0f, 2.0f, 3.0f); -Caffeine::Vec3 cross = Caffeine::Vec3::cross(up, right); -f32 dot = Caffeine::Vec3::dot(a, b); +Caffeine::Vec3 up(0.0f, 1.0f, 0.0f); +Caffeine::Vec3 right(1.0f, 0.0f, 0.0f); +Caffeine::Vec3 cross = up.cross(right); +Caffeine::f32 dot = up.dot(right); ``` ### Vec4 From 62b6d0f9b055026d6d86a22177967bd7ededfdcc Mon Sep 17 00:00:00 2001 From: LyeZinho Date: Wed, 8 Apr 2026 11:15:35 +0100 Subject: [PATCH 8/8] docs: add 4.2 Caffeine Binary System (.caf) asset format section --- docs/ROADMAP.md | 216 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 186 insertions(+), 30 deletions(-) diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 7301f3b..e77ed24 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -17,17 +17,50 @@ Visão executiva das 6 fases do projeto. Para **detalhes técnicos completos** d ## 📊 Status Geral ``` -Fase 0: Setup & Docs █████████░░░░░░ 80% ← ATUAL +Fase 0: Setup & Docs █████████████████ 100% ✅ COMPLETO Fase 1: Fundação Atômica █████████████████ 100% ✅ COMPLETO Fase 2: Concorrência ░░░░░░░░░░░░░░░ 0% Fase 3: RHI & 2D ░░░░░░░░░░░░░░░ 0% Fase 4: ECS & Sistemas ░░░░░░░░░░░░░░░ 0% -Fase 5: Transição 3D ░░░░░░░░░░░░░░░ 0% +Fase 5: Transição 3D ░░░░░░░░░░░░░░░ 0% 📅 Futuro Distante Fase 6: Caffeine Studio IDE ░░░░░░░░░░░░░░░ 0% ``` --- +## 🚀 Fase 0: Setup & Documentação + +**Responsável:** Scribes +**Status:** ✅ Completo + +> Configurar infraestrutura do projeto e criar documentação base. + +### Entregáveis + +| Componente | Descrição | Status | +|---|---|---| +| **Repositório GitHub** | Estrutura de branches, GitHub Actions CI | ✅ | +| **CMake Build System** | Configuração completa com testes | ✅ | +| **Documentação Mestre** | `docs/MASTER.md` com filosofia e arquitetura | ✅ | +| **Roadmap Documentado** | Este documento | ✅ | +| **Style Guide** | Convenções de código e nomenclatura | ✅ | + +### Infraestrutura Criada + +``` +.github/workflows/test.yml # CI com CMake + GTest +CMakeLists.txt # Build principal +tests/ # Testes unitários +docs/ # Documentação completa +``` + +### Critério de Progresso +- [x] CI compila e executa testes em Ubuntu +- [x] Documentação completa em Markdown +- [x] Estrutura de branches definida + +--- + ## 🧱 Fase 1: Fundação Atômica **Responsável:** Architects @@ -93,20 +126,6 @@ src/ --- -## 📊 Status Geral - -``` -Fase 0: Setup & Docs █████████░░░░░░ 70% ← ATUAL -Fase 1: Fundação Atômica ░░░░░░░░░░░░░░░ 0% -Fase 2: Concorrência ░░░░░░░░░░░░░░░ 0% -Fase 3: RHI & 2D ░░░░░░░░░░░░░░░ 0% -Fase 4: ECS & Sistemas ░░░░░░░░░░░░░░░ 0% -Fase 5: Transição 3D ░░░░░░░░░░░░░░░ 0% -Fase 6: Caffeine Studio IDE ░░░░░░░░░░░░░░░ 0% -``` - ---- - ## ⚡ Fase 2: O Pulso e a Concorrência **Responsável:** Architects @@ -114,6 +133,24 @@ Fase 6: Caffeine Studio IDE ░░░░░░░░░░░░░░░ 0% > Utilizar todos os núcleos da CPU e manter clock estável. Primeira camada de input e ferramentas de debug. +### 🎯 Melhorias Introduzidas + +A arquitetura de Job System foi enhancementada com os seguintes recursos: + +#### Priorização de Jobs +Nem todo Job é igual. Implementar uma **fila com três níveis de prioridade**: +- **🔴 Crítico** — Renderização e Física (nunca esperam) +- **🟡 Normal** — Lógica de gameplay, animation, eventos +- **⚪ Background** — Carregamento de assets, asset streaming + +> Isso garante que a Renderização e Física nunca esperem por um carregamento de asset pesado. + +#### Fiber-based Job System +Em vez de threads puras, usar **Fibers (threads leves do usuário)**: +- Um Job pode **suspender** sua execução (esperando outro Job) sem bloquear a thread do OS +- Maximiza o uso da CPU sem contexto switching custoso +- Implementação via coroutines ou stack-less fibers customizadas + ### Entregáveis | Componente | Descrição | Arquivos | @@ -174,10 +211,12 @@ flowchart TB | **RF2.2** | Job System com workers | N workers = cores - 1 | | **RF2.3** | Lock-free job queue | Zero locks no hot path | | **RF2.4** | JobHandle para dependências | Jobs dependentes completam antes | -| **RF2.5** | Fixed timestep game loop | 60 updates/segundo fixo | -| **RF2.6** | Variable timestep render | Delta time variável | -| **RF2.7** | Input System (actions) | Action mapping, polling | -| **RF2.8** | Debug Tools (logging) | Log com níveis configuráveis | +| **RF2.5** | Job Priority Queue | 3 níveis (Crítico/Normal/Background) | +| **RF2.6** | Fiber-based Job System | Jobs podem suspender sem block OS thread | +| **RF2.7** | Fixed timestep game loop | 60 updates/segundo fixo | +| **RF2.8** | Variable timestep render | Delta time variável | +| **RF2.9** | Input System (actions) | Action mapping, polling | +| **RF2.10** | Debug Tools (logging) | Log com níveis configuráveis | ### Critério de Progresso **Physics demo:** 10K partículas, todos os núcleos a 80%+ carga, `tsan` clean. @@ -191,6 +230,22 @@ flowchart TB > Construir a camada de renderização agnóstica e sistema de assets. +### 🎯 Melhorias Introduzidas + +A arquitetura de renderização foi enhancementada para alcançar os 50K sprites com apenas 1 draw call: + +#### Persistent Mapped Buffers +- No RHI, usar **buffers mapeados persistentemente** +- CPU e GPU compartilham a memória de vértices diretamente +- **Zero memcpy** a cada frame — elimina o gargalo de transferência +- Buffers alocados uma vez e reutilizados por todo o frame + +#### Layer Sorting Inteligente +- Com o Batch Renderer, a ordenação por profundidade (Z-Order) é **crítica** +- Implementar **Radix Sort** para ordenar IDs de textura e profundidade antes do batch +- Essa é a forma mais rápida de garantir o preenchimento correto da tela sem quebrar o batching +- Prioridade de sort: Layer → Texture ID → Depth (Z) + ### Entregáveis | Componente | Descrição | Dependência | @@ -242,10 +297,12 @@ flowchart TB | **RF3.1** | RHI abstraction | Abstração SDL_GPU, não chama SDL_Draw direto | | **RF3.2** | DrawCommand queue | Command buffer com flush automático | | **RF3.3** | Batch Renderer | 50K sprites → 1 draw call | -| **RF3.4** | Texture Atlas | Bin-packing, UV mapping correto | -| **RF3.5** | Camera 2D/3D | Projeção orto e perspectiva | -| **RF3.6** | Asset Manager async | Loading em background job | -| **RF3.7** | Hot-reload | Textures/shaders recarregáveis em runtime | +| **RF3.4** | Persistent Mapped Buffers | CPU↔GPU zero memcpy por frame | +| **RF3.5** | Radix Sort Layer Sorting | Ordenação por layer + texture + depth | +| **RF3.6** | Texture Atlas | Bin-packing, UV mapping correto | +| **RF3.7** | Camera 2D/3D | Projeção orto e perspectiva | +| **RF3.8** | Asset Manager async | Loading em background job | +| **RF3.9** | Hot-reload | Textures/shaders recarregáveis em runtime | ### Critério de Progresso **Demo:** 50K sprites na tela a **60fps estável**. @@ -259,6 +316,22 @@ flowchart TB > ECS completo, sistemas de gameplay, comunicação desacoplada. +### 🎯 Melhorias Introduzidas + +A escolha por um ECS baseado em Arquétipos (como o Flecs) foi enhancementada com: + +#### Comandos Diferidos (Command Buffers) +- Sistemas de gameplay **nunca** devem criar ou destruir entidades diretamente durante a iteração +- Isso quebra a **localidade de cache** e causa behavior indefinido durante a iteração +- Implementar um **Command Buffer** que "anota" as mudanças e as aplica em um ponto seguro do frame +- Commands: `CreateEntity`, `DestroyEntity`, `AddComponent`, `RemoveComponent`, `SetComponent` + +#### Integração de Scripting Antecipada +- Você mencionou Lua/AngelScript na Fase 6, mas **recomendo antecipar para a Fase 4** +- Incluir os **bindings básicos de dados** (Entity ID, Component access, System hooks) +- Ter a lógica de alto nível em scripts permite que os Scribes testem mecânicas sem precisar que os Architects recompilem a engine toda vez +- Preparar a infraestrutura para hot-reload de scripts desde o início + ### Entregáveis | Componente | Descrição | Dependência | @@ -315,12 +388,14 @@ flowchart TB | **RF4.1** | ECS Core (Archetype) | Entities = IDs, Components = dados contíguos | | **RF4.2** | ComponentPool | Arrays contíguos, grow como Vector | | **RF4.3** | World query system | Query por combinação de componentes | -| **RF4.4** | Scene serialization | Save/load .caf formato binário | -| **RF4.5** | Event Bus pub/sub | Event tipado, priority queue | -| **RF4.6** | Audio System | SDL3 audio, pooling, spatial 2D | -| **RF4.7** | Animation System | Sprite frames, state machine | -| **RF4.8** | Physics 2D | AABB/circle collision, layers | -| **RF4.9** | UI System (retained) | ECS integration, widget instances | +| **RF4.4** | Deferred Command Buffer | Commands diferidos aplicados em safe point | +| **RF4.5** | Scene serialization | Save/load .caf formato binário | +| **RF4.6** | Event Bus pub/sub | Event tipado, priority queue | +| **RF4.7** | Scripting Bindings (early) | Lua/AngelScript bindings básicos | +| **RF4.8** | Audio System | SDL3 audio, pooling, spatial 2D | +| **RF4.9** | Animation System | Sprite frames, state machine | +| **RF4.10** | Physics 2D | AABB/circle collision, layers | +| **RF4.11** | UI System (retained) | ECS integration, widget instances | ### Componentes ECS Pré-definidos @@ -349,6 +424,87 @@ Name, SceneRef --- +## 📦 4.2: Sistema de Assets — O Formato .caf (Caffeine Asset Format) + +**Responsável:** Architects +**Status:** 📅 Planejado (Integração com Fase 3 & 4) + +> O formato .caf (Caffeine Asset Format) serve como espinha dorsal de dados da engine. Filosofia: **Zero-parsing, Zero-copy**. O arquivo no disco é um espelho direto da memória RAM/VRAM. + +### Estrutura do Header (`src/core/io/CafTypes.hpp`) + +```cpp +namespace Caffeine { + enum class AssetType : u16 { + Unknown = 0, + Texture, // RGBA8, BC7, ASTC + Audio, // PCM, ADPCM + Mesh, // Vertex/Index Buffers + Prefab, // ECS Entity Template (Binary) + Scene, // World State + Shader // SPIR-V / Bytecode + }; + + struct CafHeader { + u32 magic; // 0xCAFECAFE + u16 version; // Versão do formato + AssetType type; // Tipo de dado + u64 metadataSize; // Offset para o início dos dados brutos + u64 dataSize; // Tamanho do payload binário + u64 alignment; // 16 ou 32 bytes (para SIMD/GPU) + }; +} +``` + +### Requisitos de Engenharia para o .caf + +| Categoria | Requisito Técnico | Motivação | +|---|---|---| +| **Endianness** | Little-endian (padrão x86/x64) | Evitar swap de bytes no carregamento (Zero CPU overhead) | +| **Alignment** | Global: 16-byte / Mesh: 32-byte | Compatibilidade com instruções SIMD e otimização de barramento da GPU | +| **IO Pattern** | Single-Shot Read | Minimiza o seek time do HD/SSD ao ler Metadata + Data em uma única chamada de IO | +| **Versioning** | Semantic Versioning no Header | Permitir que a engine identifique assets obsoletos e force a re-compilação via IDE | + +### Integração no Roadmap + +#### Fase 3: RHI & Asset Foundation (Update) + +**RF3.0: Caffeine Binary System (.caf)** + +- **Implementação:** BlobLoader para leitura assíncrona de blocos binários +- **DOD:** Uso de Memory Mapping (mmap) ou Direct Storage (se disponível) para carregar assets sem passar pela cópia intermediária da CPU +- **Suporte Multimídia:** + - **Imagens:** Conversão de metadados para `SDL_GPUTextureCreateInfo` + - **Audio:** Mapeamento de buffers PCM direto para o AudioStream + - **3D:** Alinhamento de buffers de vértices para 32 bytes (pré-requisito para Fase 5) + +#### Fase 4: ECS & Sistemas (Update) + +**RF4.2: Binary Prefabs & Scenes** + +- **Implementação:** Serializador binário que despeja o estado das entidades ECS diretamente em um arquivo `.caf` tipo Prefab +- **Vantagem:** Instanciar um Prefab torna-se um `memcpy` de um bloco binário para o ComponentPool da engine + +### Fluxo de Implementação: "The Loading Chain" + +Para que isso funcione em escala, a engine seguirá este fluxo: + +1. **FileSystem::Open** — Localiza o asset no disco +2. **BlobLoader::Load** — O JobSystem (Fase 2) reserva memória via LinearAllocator e faz a leitura bruta +3. **AssetResolver::Cast:** + - Se `type == Texture`: O ponteiro é passado para a GPU + - Se `type == Audio`: O ponteiro é enviado para o Mixer + - Se `type == Prefab`: Os dados são injetados no ECS +4. **Lifetime Management** — O asset permanece em memória até que a Cena seja descarregada, sem nunca ter sido "parseado" + +### Critério de Aceitação (Stress Test) + +**Benchmark:** Carregar um "Mega-Bundle" de 1GB contendo texturas, áudios e meshes. + +**Sucesso:** O tempo de carregamento deve ser limitado apenas pela velocidade de leitura do SSD (ex: 500MB/s), com uso de CPU inferior a 2% durante o processo. + +--- + ## 🌐 Fase 5: Transição Dimensional **Responsável:** Artisans