diff --git a/desing_planning/README.md b/desing_planning/README.md deleted file mode 100644 index 900e5e5..0000000 --- a/desing_planning/README.md +++ /dev/null @@ -1,49 +0,0 @@ -# 📑 Caffeine Planning & Architecture - -**O Cérebro da Engine: Documentação de Design, Decisões e Roadmap.** - -> ⚠️ Para uma visão **completa e consolidada** do projeto, consulte [`docs/MASTER.md`](../docs/MASTER.md). - ---- - -## 📂 Conteúdo da Pasta - -| Documento | Descrição | Relação | -|---|---|---| -| **`SPECS.md`** | Regras de desenvolvimento, estilo e padrões | Complemento direto ao MASTER §2, §5 | -| **`ROADMAP.md`** | Status das 6 fases e gates entre elas | Resumo executivo — MASTER §4 | -| **`architecture_specs.md`** | Especificações técnicas ECS, Job System, RHI | Técnico detalhado — MASTER §3 | -| **`memory_model.md`** | Especificações detalhadas dos Custom Allocators | Técnico detalhado — MASTER §8 | - ---- - -## 🛠️ Fluxo de Planejamento - -Seguimos o ciclo **R.I.C.O.** (Research, Idea, Conflict, Order): - -1. **Research (Pesquisa):** Investigamos como o SDL3 ou o C++ lidam com um problema específico. -2. **Idea (Ideia):** Propomos uma solução que se encaixe na nossa filosofia de baixa dependência. -3. **Conflict (Conflito):** Discutimos no Discord se essa solução fere o desempenho ou a portabilidade 3D futura. -4. **Order (Ordem):** Documentamos a decisão final aqui nesta pasta e iniciamos a implementação. - ---- - -## 🚦 Status das Fases - -| Fase | Descrição | Status | Responsável | -| :--- | :--- | :--- | :--- | -| **0** | **Setup Inicial & Docs** | 🕒 Em Progresso | Guilda Codex | -| **1** | **Fundação Atômica (Memória/Tipos)** | 📅 Planejado | Architects | -| **2** | **Concorrência & Loop** | 📅 Planejado | Architects | -| **3** | **RHI & 2D Foundation** | 📅 Planejado | Artisans/Architects | - ---- - -## ⚖️ Regras de Ouro para Documentação - -1. **Mantenha Simples:** Se a explicação de um sistema for mais complexa que o código, o sistema precisa ser simplificado. -2. **Agnosticismo Dimensional:** Toda spec escrita aqui deve prever que o dado pode ser 2D ou 3D. -3. **Sincronia:** Se o código mudar drasticamente, o documento de planejamento correspondente **deve** ser atualizado no mesmo Commit. - ---- -> *"Planejar é trazer o futuro para o presente, para que possamos fazer algo a respeito agora."* diff --git a/desing_planning/RULES.md b/desing_planning/RULES.md deleted file mode 100644 index 6b1e72c..0000000 --- a/desing_planning/RULES.md +++ /dev/null @@ -1,203 +0,0 @@ -# 📜 Dev Manifesto: Regras e Padrões de Desenvolvimento - -Este documento estabelece as **regras fundamentais** para o desenvolvimento da Caffeine Engine. Para contexto, filosofia e visão macro, consulte [`docs/MASTER.md`](../docs/MASTER.md) §2 e §5. - ---- - -## 🛡️ 1. Regras de Segurança - -### 1.1 Memória — The Golden Rule - -``` -╔════════════════════════════════════════════════════════════╗ -║ PROIBIDO: new e delete soltos no código da aplicação. ║ -║ TODA alocação deve passar pelos Custom Allocators. ║ -╚════════════════════════════════════════════════════════════╝ -``` - -| Padrão | Detalhes | -|---|---| -| **System Allocator** | Única exceção — usa `malloc` uma vez para bootstrap | -| **Linear Allocator** | Memória volátil por frame, `reset()` limpa tudo | -| **Pool Allocator** | Blocos de tamanho fixo (partículas, projéteis) | -| **Stack Allocator** | Escopos aninhados (níveis de jogo) | - -### 1.2 Ownership e Ponteiros - -| Situação | Abordagem | -|---|---| -| Ciclo de vida gerenciado pelo Core | `raw pointer` (acesso rápido) | -| Escopo estrito, único owner | `std::unique_ptr` | -| Shared ownership necessária | `std::shared_ptr` (raro — evitar) | -| Leitura sem ownership | `T&` ou `const T&` | -| Ponteiro opaco (outro sistema aloca) | `T*` com documentação clara | - -### 1.3 Versionamento e Code Review - -| Regra | Detalhe | -|---|---| -| **Code Review obrigatório** | Nenhum código entra na `main` sem approval de 1 Architect | -| **Branch naming** | `feature/fase-N-nome`, `fix/fase-N-descrição`, `docs/nome` | -| **Merge strategy** | Squash merge para manter histórico limpo | -| **Breaking changes** | Documentados com `BREAKING CHANGE:` no commit | -| **`.gitignore`** | Verificar a cada novo diretório criado | - -### 1.4 Boundary Checks - -| Modo | Comportamento | -|---|---| -| **Debug** | Todos os containers validam limites (`CF_ASSERT`) | -| **Release** | Checagens removidas — performance máxima | -| **CI/CD** | Sanitizers obrigatórios: ASan, MSan, TSan, UBSan | - ---- - -## 🏗️ 2. Padrões de Código (Style Guide) - -Para convenções completas de nomenclatura, consulte MASTER.md §5. - -### 2.1 Resumo de Nomenclatura - -``` -Namespace: Caffeine::ModuleName -Classe/Struct: PascalCase → ThreadManager -Função/Método: camelCase → initSdl() -Variável: camelCase → entityCount -Variável privada: m_prefixo → m_isRunning -Membro estático: s_prefixo → s_instanceCount -Constante/Macro: UPPER_CASE → MAX_THREADS -Header: PascalCase.hpp → LinearAllocator.hpp -Source: PascalCase.cpp → LinearAllocator.cpp -``` - -### 2.2 Estrutura de Arquivos - -Cada módulo segue a estrutura: - -``` -module/ -├── ModuleName.hpp # Interface pública (API) -├── ModuleName.inl # Implementação inline (se necessário) -└── ModuleName.cpp # Implementação não-inline -``` - -### 2.3 Headers — Padrão de Inclusão - -```cpp -#pragma once // Não usar include guards tradicionais - -// 1. Header do módulo (self) -#include "ModuleName.hpp" - -// 2. Headers internos do mesmo módulo -#include "RelatedStruct.hpp" - -// 3. Headers de outros módulos da Caffeine -#include -#include - -// 4. Headers externos (SDL3, etc.) -#include - -// 5. Headers do sistema (evitar) -#include -``` - -### 2.4 Documentação de APIs - -Toda função pública **deve** ter documentação no header: - -```cpp -// ============================================================================ -// @brief Aloca um bloco de memória do pool. -// @param size Tamanho do bloco a alocar (em bytes). -// @param alignment Alinhamento do bloco (deve ser potência de 2). -// @return Ponteiro para o bloco alocado, ou nullptr se pool cheio. -// @note Não causa fragmentação — alinhamento pode desperdiçar espaço. -// @see LinearAllocator::reset() -// ============================================================================ -void* allocate(usize size, usize alignment = 8); -``` - ---- - -## 📈 3. Padrões de Crescimento - -### 3.1 Critérios para Avançar de Fase - -Uma fase só termina quando **todos** os critérios são atingidos: - -| Critério | Descrição | -|---|---| -| **Stress Test Passed** | Sistema não vaza memória nem crasha sob carga | -| **API Estável** | Interface pública não mudou nos últimos 2 ciclos | -| **Documentação Completa** | Specs e Doxygen 100% | -| **Code Review** | Pelo menos 1 Architect aprovou cada arquivo | -| **Testes** | Cobertura mínima 80% nos módulos core | - -### 3.2 Modificações na API - -| Tipo | Regra | -|---|---| -| **Adicionar** | Sempre permitido — adicionar, não modificar o existente | -| **Deprecar** | Manter por 2 fases com warning | -| **Remover** | Só na próxima versão `MAJOR` | - -### 3.3 Portabilidade - -| Regra | Detalhe | -|---|---| -| **Core agnóstico** | `/src/core/` não sabe o que é Windows ou Linux | -| **Platform layer** | Código específico de OS em `/src/platform/` | -| **Teste obrigatório** | Código novo compila em Windows E Linux E macOS | -| **CI/CD** | Build matrix: Windows (MSVC), Linux (GCC/Clang), macOS (Clang) | - ---- - -## ⚖️ 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."* - -### 4.1 O Que Isso Significa na Prática - -| Comportamento | Evitar | -|---|---| -| Escrever código que seja óbvio | "Clever code" que precisa de comentário para ser entendido | -| Nomear coisas pelo que fazem | Nomes vagos (`data`, `temp`, `tmp`) | -| Preferir simples a elegante | Abstrações prematuras (YAGNI) | -| Documentar decisões, não obviedades | Comentários que repetem o código | -| Entender cada dependência que incluímos | `// TODO: remove this later` | - -### 4.2 Quando Questionar - -Se uma decisão de design atender **todos** estes critérios, está certa: - -- [ ] Resolve um problema **real** (não hipotético) -- [ ] Não aumenta complexidade sem benefício mensurável -- [ ] Se encaixa na filosofia de baixa dependência -- [ ] Não prejudica performance em mais de 1% -- [ ] Pode ser explicada a um novo membro da guilda em 5 minutos - ---- - -## 📋 Checklist de Código - -Use antes de abrir PR: - -``` -□ Nenhum new/delete solto no código da aplicação -□ Allocator usado (Linear, Pool ou Stack) -□ Nomenclatura segue Style Guide -□ Variáveis privadas com prefixo m_ -□ Macros em UPPER_CASE -□ Header com #pragma once -□ Doxygen em toda função pública -□ Ordem de includes correta -□ static_assert para tamanhos de tipos -□ Code Review pendente -□ Documentação atualizada (mesmo commit) -□ Compila em todas as plataformas -□ Stress test executado -□ Sem TODO sem issue associada -□ Sanitizers limpos (ASan, TSan, UBSan) -``` diff --git a/docs/README.md b/docs/README.md index c093fb9..ccd8a8f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -659,21 +659,16 @@ caffeine/ ├── CMakeLists.txt # Build principal ├── .gitignore │ -├── desing_planning/ # ← Documentação de design (atual) -│ ├── README.md -│ ├── dev_manifesto.md # Leis do projeto -│ ├── roadmap.md # Fases de 1 a 6 -│ ├── architecture_specs.md # (futuro) ECS, Job System, RHI specs -│ ├── memory_model.md # (futuro) Specs de allocators -│ └── master_plan.md # (futuro) Roadmap detalhado +├── 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 │ -├── docs/ # ← Documentação pública -│ ├── MASTER.md # Este arquivo -│ ├── architecture/ -│ ├── api/ -│ └── guides/ -│ -├── src/ # ← Código-fonte (a criar na Fase 1) +├── src/ # ← Código-fonte (Fase 1+) │ ├── Caffeine.hpp # Header principal de inclusão │ ├── Caffeine.cpp # Entry point mínimo │ │ diff --git a/desing_planning/ROADMAP.md b/docs/ROADMAP.md similarity index 60% rename from desing_planning/ROADMAP.md rename to docs/ROADMAP.md index 8326cf6..7301f3b 100644 --- a/desing_planning/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,14 +1,24 @@ # 🗺️ Roadmap de Desenvolvimento -Visão executiva das 6 fases do projeto. Para **detalhes técnicos completos** de cada fase (arquitetura, arquivos, critérios de progresso), consulte [`docs/MASTER.md`](../docs/MASTER.md) §4 e [`architecture_specs.md`](architecture_specs.md) para APIs completas. +Visão executiva das 6 fases do projeto. Para **detalhes técnicos completos** de cada fase (arquitetura, arquivos, critérios de progresso), consulte [`docs/README.md`](docs/README.md) §4 e [`architecture_specs.md`](architecture_specs.md) para APIs completas. + +> **Legenda de Princípios:** +> - **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 +> - **KISS** = Keep It Simple, Stupid — simplicidade acima de tudo +> - **RHI** = Rendering Hardware Interface — abstração sobre a API gráfica +> - **ECS** = Entity Component System — arquitetura de dados para jogos +> - **Lock-free** = Algoritmo que não usa locks, apenas atômicos +> - **SIMD** = Single Instruction Multiple Data — instruções vetoriais da CPU +> - **Cache Locality** = Padrão de acesso à memória que maximiza hits de cache --- ## 📊 Status Geral ``` -Fase 0: Setup & Docs █████████░░░░░░ 70% ← ATUAL -Fase 1: Fundação Atômica ░░░░░░░░░░░░░░░ 0% +Fase 0: Setup & Docs █████████░░░░░░ 80% ← ATUAL +Fase 1: Fundação Atômica █████████████████ 100% ✅ COMPLETO Fase 2: Concorrência ░░░░░░░░░░░░░░░ 0% Fase 3: RHI & 2D ░░░░░░░░░░░░░░░ 0% Fase 4: ECS & Sistemas ░░░░░░░░░░░░░░░ 0% @@ -18,39 +28,37 @@ Fase 6: Caffeine Studio IDE ░░░░░░░░░░░░░░░ 0% --- -## 🔧 Fase 0: Setup Inicial & Documentação - -**Responsável:** Guilda Codex -**Status:** 🕒 Em Progresso - -| Tarefa | Status | -|---|:---:| -| README.md criado | ✅ | -| Manifesto de desenvolvimento criado | ✅ | -| Roadmap de 6 fases documentado | ✅ | -| Fluxo R.I.C.O. estabelecido | ✅ | -| `docs/MASTER.md` criado | ✅ | -| `architecture_specs.md` criado | ✅ | -| `memory_model.md` criado | ✅ | -| Estrutura de diretórios `/src` planejada | 🔄 | -| `.gitignore` verificado | ⏳ | -| CMakeLists.txt base criado | ⏳ | -| `Caffeine.h` com tipos básicos criado | ⏳ | - -### Próximos Marcos -1. Criar `/src/core/Types.hpp` com tipos (`u32`, `f64`, etc.) -2. Criar `CMakeLists.txt` base -3. Criar `.gitignore` completo - ---- - ## 🧱 Fase 1: Fundação Atômica **Responsável:** Architects -**Status:** 📅 Planejado +**Status:** ✅ Completo (testes passando em CI) > Criar independência total da `std` e garantir controle absoluto do hardware. +### DOD (Data-Oriented Design) +- **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 +- **Allocators**: Linear (frame), Pool (slots), Stack (markers) — nenhum malloc após bootstrap + +### RFs (Requisitos Funcionais) + +| ID | Requisito | Critério de Aceitação | +|----|-----------|----------------------| +| **RF1.1** | Tipos de largura fixa (u8..u64, i8..i64, f32, f64) | `static_assert` confirma tamanhos | +| **RF1.2** | Macros de plataforma (Windows/Linux/macOS) | Compila em todas as plataformas | +| **RF1.3** | Sistema de assertions customizável | CF_ASSERT funciona em debug | +| **RF1.4** | LinearAllocator com reset() O(1) | 1M allocs + reset < 10ms | +| **RF1.5** | PoolAllocator O(1) amortizado | Alocação de slots fixos | +| **RF1.6** | StackAllocator com markers | freeToMarker() funciona | +| **RF1.7** | Vector cache-friendly | pushBack() não fragmenta memória | +| **RF1.8** | HashMap O(1) lookup | Inserção e busca constant time | +| **RF1.9** | Math library (Vec2/3/4, Mat4) | Operações vetoriais corretas | + +### Critério de Progresso +**Stress test:** 1M allocs → zero memory leaks, fragmentação < 0.1%. + ### Entregáveis ``` @@ -77,8 +85,25 @@ src/ └── Math.hpp # Utility functions ``` -### Critério de Progresso -**Stress test:** 1M allocs → zero memory leaks, fragmentação < 0.1%. +### Testes CI +- ✅ test_core.cpp: 8 testes (Types, Constants, Platform, Compiler, Assertions) +- ✅ test_allocators.cpp: 16 testes + 3 stress tests (Linear, Pool, Stack) +- ✅ test_containers.cpp: 14 testes + 1 stress test (Vector, HashMap, StringView, FixedString) +- ✅ test_math.cpp: 18 testes (Vec2, Vec3, Vec4, Mat4, Math utilities) + +--- + +## 📊 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% +``` --- @@ -135,6 +160,25 @@ flowchart TB style PARALLEL fill:none,stroke:#666,stroke-dasharray: 5 5 ``` +### DOD (Data-Oriented Design) +- **Job System**: Filas lock-free com atomic operations, zero locking overhead +- **Thread Pool**: Work-stealing algorithm para balanceamento de carga +- **Game Loop**: Fixed timestep buffer para consistência entre frames +- **Timer**: High-resolution via SDL_GetPerformanceCounter + +### RFs (Requisitos Funcionais) + +| ID | Requisito | Critério de Aceitação | +|----|-----------|----------------------| +| **RF2.1** | High-Resolution Timer | Precisão de microssegundos | +| **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 | + ### Critério de Progresso **Physics demo:** 10K partículas, todos os núcleos a 80%+ carga, `tsan` clean. @@ -185,6 +229,24 @@ flowchart TB style DRAW fill:#4a1a1a,stroke:#f94,color:#fff ``` +### DOD (Data-Oriented Design) +- **RHI**: Command buffer com batch automático, grouping por pipeline+texture+layer +- **Batch Renderer**: 50K sprites → 1 draw call através de instanced rendering +- **Texture Atlas**: Bin-packing para UV coordinates, cache-friendly +- **Camera**: Matriz 4×4 column-major, view/projection separation + +### RFs (Requisitos Funcionais) + +| ID | Requisito | Critério de Aceitação | +|----|-----------|----------------------| +| **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 | + ### Critério de Progresso **Demo:** 50K sprites na tela a **60fps estável**. @@ -240,6 +302,26 @@ flowchart TB style S3 fill:#2d5016,stroke:#4a9,color:#fff ``` +### DOD (Data-Oriented Design) +- **ECS Archetype-based**: Entidades agrupadas por conjunto de componentes (cache locality) +- **Component Pools**: Arrays contíguos por tipo, não objetos por entidade +- **Query System**: Iteração sobre entidades que possuem X componentes +- **Event Bus**: Pub/sub sem acoplamento, fila com prioridade + +### RFs (Requisitos Funcionais) + +| ID | Requisito | Critério de Aceitação | +|----|-----------|----------------------| +| **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 | + ### Componentes ECS Pré-definidos ```cpp @@ -284,6 +366,22 @@ Name, SceneRef | **Camera3D** | Projeção perspectiva, lookAt | Math, Camera | | **Skeletal Animation** | Bones, skinning, blend trees | Animation | +### DOD (Data-Oriented Design) +- **Quaternions**: Representação 4D para rotações 3D, SLERP interpolation +- **Octree**: Spatial partitioning para 3D, broad-phase collision +- **Mesh data**: Vertex buffers contíguos, index buffers, LOD support + +### RFs (Requisitos Funcionais) + +| ID | Requisito | Critério de Aceitação | +|----|-----------|----------------------| +| **RF5.1** | Quaternion math | Multiplicação, SLERP, look rotation | +| **RF5.2** | Mesh loader | .obj e .gltf carregamento | +| **RF5.3** | Shader system | HLSL (Windows) / GLSL (Linux/macOS) | +| **RF5.4** | Octree spatial | Broad-phase collision detection | +| **RF5.5** | Camera 3D | Projeção perspectiva, lookAt | +| **RF5.6** | Frustum culling | Objetos fora da view não renderizam | + ### Critério de Progresso **Demo:** Mesh 3D carregada, shader customizado, **60fps**. @@ -305,6 +403,22 @@ Name, SceneRef | **Asset Pipeline** | Processador de textures/áudio → `.caf` bundles | | **Scripting (TBD)** | Possível integração com Lua/AngelScript | +### DOD (Data-Oriented Design) +- **ImGui immediate mode**: Rendering direto ao buffer, sem scenegraph +- **Scene Editor**: Entity Inspector, Hierarchy view, Transform gizmos +- **Asset Pipeline**: Binary bundles (.caf), mipmap generation + +### RFs (Requisitos Funcionais) + +| ID | Requisito | Critério de Aceitação | +|----|-----------|----------------------| +| **RF6.1** | Embedded UI | Dear ImGui integrado | +| **RF6.2** | Profiler | Frame timing, memory profiling | +| **RF6.3** | Scene Editor | Drag-drop, inspector, hierarchy | +| **RF6.4** | Transform gizmos | Translate/Rotate/Scale visual | +| **RF6.5** | Asset Pipeline | Processador → .caf bundles | +| **RF6.6** | Hot-reload runtime | Textures/shaders recarregáveis | + ### Critério de Progresso **Primeiro game completo** feito 100% na Caffeine. diff --git a/desing_planning/SPECS.md b/docs/SPECS.md similarity index 100% rename from desing_planning/SPECS.md rename to docs/SPECS.md diff --git a/desing_planning/architecture_specs.md b/docs/architecture_specs.md similarity index 100% rename from desing_planning/architecture_specs.md rename to docs/architecture_specs.md diff --git a/desing_planning/memory_model.md b/docs/memory_model.md similarity index 100% rename from desing_planning/memory_model.md rename to docs/memory_model.md