From 9f97dd5c479949b17b605cd34a7e0363328ec4bc Mon Sep 17 00:00:00 2001 From: Adam Martin Date: Sun, 2 Nov 2025 18:06:23 -0600 Subject: [PATCH] Add initial documentation for AI agent instructions and coding standards --- .github/copilot-instructions.md | 46 +++ AGENTS.md | 508 ++++++++++++++++++++++++++++++++ CODE_STYLE_GUIDE.md | 357 ++++++++++++++++++++++ 3 files changed, 911 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 AGENTS.md create mode 100644 CODE_STYLE_GUIDE.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..01e24487 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,46 @@ +# Copilot Instructions for Trillek Engine C + +## 🚨 CRITICAL: Read AGENTS.md First 🚨 + +**Before doing ANY work, read `AGENTS.md` completely.** It contains: +- Mandatory environment setup steps (vcpkg, CMake) +- Execution protocol and workflow +- Documentation policy (what NOT to create) +- Build verification requirements +- Coding standards +- All project constraints and guidelines + +**AGENTS.md is the single source of truth for all project rules.** + +## Quick Reference (Full details in AGENTS.md) + +**⚠️ PREREQUISITES FIRST**: Before building, you MUST install: +1. **System deps** (Linux): `sudo apt-get install -y build-essential pkg-config tar curl zip unzip gdb libgl1-mesa-dev xorg-dev libglu1-mesa-dev libxinerama-dev libxcursor-dev p7zip-full` +2. **vcpkg**: Clone, bootstrap, set `VCPKG_ROOT` environment variable +3. **CMake**: 3.20 or higher +4. **Ninja**: Build tool (optional but recommended) + +**Build Commands**: +- **Configure**: `cmake --preset=ninja-multi-vcpkg` +- **Build Debug**: `cmake --build --preset=ninja-multi-vcpkg-debug` +- **Build Release**: `cmake --build --preset=ninja-multi-vcpkg-release` +- **Build Release with Debug Info**: `cmake --build --preset=ninja-multi-vcpkg-release-dbginfo` +- **Tests**: Enable with `-DBUILD_TESTS=ON`, then run `ctest --preset=ninja-multi-vcpkg-debug` or `ninja-multi-vcpkg-release` +- **Documentation**: `cmake --build --preset=ninja-multi-docs` (requires doxygen, doxybook2, mkdocs) + +**Presets**: Use `ninja-multi-vcpkg` config preset with appropriate build preset. Ninja Multi-Config generator is preferred. + +**Project Options**: +- `BUILD_CLIENT` (default ON) - Build the client +- `BUILD_SERVER` (default ON) - Build the server +- `BUILD_TESTS` (default OFF) - Build tests +- `BUILD_DOCS` (default OFF) - Build documentation + +**Note**: +- `VCPKG_ROOT` must be set as an environment variable +- Linux requires `gcc10/g++10` or `clang-13` minimum +- Project uses traditional headers (`.hpp`/`.cpp`), not C++20 modules + +**Tech Stack**: C++20, CMake 3.20+, vcpkg, protobuf (networking), Bullet3 (physics), ImGui (debug UI), GLFW3 (windowing), OpenGL (rendering), OpenAL (audio), Lua + sol3 (scripting), spdlog (logging) + +**Rule of Thumb**: If you're unsure about anything, check AGENTS.md. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..0da48343 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,508 @@ +# AI Agent Instructions for Trillek Engine C (TEC) + +**Purpose**: Internal process guidelines for AI agents working on TEC +**Audience**: AI assistants only (not user documentation) +**Status**: Active + +--- + +## ⚠️ MANDATORY FIRST STEPS - READ THIS BEFORE ANY ACTION ⚠️ + +**CRITICAL**: Follow these steps IN ORDER before attempting ANY build or code work. Skipping steps will cause build failures. + +### Complete Setup Checklist + +**For All Builds:** +1. ✅ Install system dependencies +2. ✅ Clone and bootstrap vcpkg +3. ✅ Set VCPKG_ROOT environment variable +4. ✅ Install CMake 3.20+ and Ninja +5. ✅ Run CMake configure +6. ✅ Build + +--- + +### Step 1: Install System Dependencies + +**Linux**: +```bash +# Install ALL dependencies in one command +sudo apt-get update && sudo apt-get install -y \ + build-essential \ + pkg-config \ + tar \ + curl \ + zip \ + unzip \ + gdb \ + cmake \ + ninja-build \ + libgl1-mesa-dev \ + xorg-dev \ + libglu1-mesa-dev \ + libxinerama-dev \ + libxcursor-dev \ + p7zip-full +``` + +**What these are for**: +- `build-essential` - GCC/G++ 10+ and build tools +- `cmake` - Build system generator (3.20+ required) +- `ninja-build` - Fast build tool (required by CMake presets) +- `pkg-config` - Library detection +- `libgl1-mesa-dev`, `libglu1-mesa-dev` - OpenGL libraries +- `xorg-dev`, `libxinerama-dev`, `libxcursor-dev` - X11 libraries for GLFW3 +- `p7zip-full`, `tar`, `curl`, `zip`, `unzip` - Archive/download tools for vcpkg + +**Compiler Requirements**: +- Linux: `gcc10/g++10` or `clang-13` minimum (C++20 support) +- Windows: Visual Studio 2019+ with C++ tools +- macOS: Xcode Command Line Tools + +--- + +### Step 2: Clone and Bootstrap vcpkg + +```bash +# Clone vcpkg (can be anywhere) +git clone https://github.com/microsoft/vcpkg.git + +# Bootstrap vcpkg +cd vcpkg +./bootstrap-vcpkg.sh # Linux/macOS +bootstrap-vcpkg.bat # Windows + +# Verify bootstrap +./vcpkg --version # Should show vcpkg version +``` + +--- + +### Step 3: Set Environment Variables + +**Linux/macOS**: +```bash +# Set VCPKG_ROOT environment variable (REQUIRED) +export VCPKG_ROOT=/path/to/vcpkg # Adjust to your vcpkg location + +# Verify +echo $VCPKG_ROOT # Should show path +``` + +**Windows (CMD)**: +```cmd +set VCPKG_ROOT=C:\path\to\vcpkg +``` + +**Windows (PowerShell)**: +```powershell +$env:VCPKG_ROOT = "C:\path\to\vcpkg" +``` + +--- + +### Step 4: Configure CMake + +**IMPORTANT**: Only run configure once unless you need to reconfigure. + +**Using Ninja Multi-Config (Recommended)**: +```bash +cd tec +cmake --preset=ninja-multi-vcpkg +``` + +This will take 5-15 minutes the first time as vcpkg builds all dependencies (protobuf, bullet3, glfw3, imgui, openal, lua, sol3, spdlog, etc.). + +--- + +### Step 5: Build + +```bash +# Debug build +cmake --build --preset cli-native-debug --parallel 4 + +# Release build +cmake --build --preset cli-native-release --parallel 4 +``` + +--- + +### Platform Triplets Reference + +- `x64-windows` - Windows native (must specify on command line) +- `x64-linux` - Linux native (Clang-18+) +- `x64-osx` - macOS native + +--- + +### Using setup-cpp for Automated Setup (Web Coding Environments) + +If you're in a web-based coding environment like GitHub Codespaces, use the `aminya/setup-cpp` action to automate tool installation: + +```yaml +# In GitHub Actions or Codespaces +- name: Setup C++ environment + uses: aminya/setup-cpp@v1 + with: + compiler: clang + clang: 18 + cmake: true + ninja: true + vcpkg: true +``` + +This automatically installs Clang-18, CMake, Ninja, and vcpkg without manual steps. + +--- + +**These steps are NOT optional. Complete ALL steps IN ORDER before proceeding with any task.** + +--- + +## Core Directives + +### 1. Required Reading Before Any Work + +**Read CODE_STYLE_GUIDE.md for coding standards** before making changes. + +**Future pattern guides**: +- ImGui UI patterns and immediate mode GUI architecture +- ECS patterns with the engine's entity-component system +- Networking patterns with protobuf serialization +- Lua scripting API usage + +These guides will define correct implementation patterns. Don't improvise - follow documented patterns when they exist. + +### 2. Planning is Internal Only + +- **Never create plan documentation files** unless explicitly requested +- Plans, strategies, and implementation approaches are working memory only +- Execute directly without documenting the plan +- Exception: AGENTS.md (this file) is allowed as it improves AI process + +### 3. Temporary Files Must Be Cleaned Up + +- **Never leave temporary test programs, scripts, or exploration code** in the repository +- If you create temporary files for investigation (e.g., testing a hypothesis, exploring an API): + - Delete them immediately after use + - Use `.gitignore`d locations if they must persist briefly +- Clean up at the end of your task before reporting completion +- Examples of temporary files to avoid: test programs, debug scripts, scratch files + +### 4. Documentation Policy + +**NEVER create summary documents, reports, or reviews** of work completed. These are working memory only. + +**Do NOT create** unless explicitly requested: + +- HOWTOs, tutorials, guides +- Implementation summaries, work summaries, review summaries +- Design notes or architecture docs +- Supplementary documentation of any kind +- Status reports, completion reports, or any "summary" documents + +**Only create NEW documentation if**: + +- User explicitly requests it (e.g., "create a document explaining X") +- It documents a human workflow/process users must follow (e.g., build instructions, setup steps) +- It directly improves automated tooling or AI code generation + +**When creating NEW documentation files**: + +- You MUST provide a justification in your response explaining: + - Why this needs to be a persistent file vs. chat response + - What specific future use case requires this reference + - How it differs from existing documentation +- Updating existing documentation does NOT require justification + +**Rule of thumb**: If you're just going to tell the user about it anyway, don't create a file for it. + +**CRITICAL**: If the justification for creating documentation is NOT immediately obvious: +1. **DO NOT create the file** +2. **Explain your reasoning to the user first** +3. **Wait for explicit approval** +4. If unclear whether documentation is needed, **update AGENTS.md to clarify the policy** rather than guess + +### 5. No Standalone Applications + +- Do not create standalone test applications +- Test features by integrating into existing code (e.g., main menu) + +--- + +## Execution Protocol + +### Before Any Task + +1. Read request carefully +2. Identify files to modify (surgical changes only) +3. Execute changes directly without creating plan documents +4. Build and test to verify changes + +### Making Changes + +- **Minimal modifications only**: Change as few lines as possible +- Do not delete/remove/modify working code unless absolutely necessary +- Ignore unrelated bugs or broken tests +- Update documentation only if directly related to changes + +### Build Verification (REQUIRED) + +**Build/test MUST succeed before completing any task.** + +**Compiler Requirements**: +- **Linux**: gcc10/g++10 or clang-13 minimum (C++20 support) +- **Windows**: Visual Studio 2019+ with C++ tools +- **macOS**: Xcode Command Line Tools + +**System Dependencies** (already covered in Step 1 above) + +Before completing any work: + +1. **Ensure VCPKG_ROOT is set** (see Step 3 above) + +2. **Configure** (first time only): + ```bash + cmake --preset=ninja-multi-vcpkg + ``` + +3. **Build**: + ```bash + # Debug build + cmake --build --preset=ninja-multi-vcpkg-debug + + # Release build + cmake --build --preset=ninja-multi-vcpkg-release + ``` + +4. **Verify**: No errors or warnings +5. **If errors**: Fix and rebuild +6. **Do not mark complete until build succeeds** + +**Build Targets**: +- Client executable in `builds/ninja-multi-vcpkg/client/` +- Server executable in `builds/ninja-multi-vcpkg/server/` +- Common library linked by both + +### Test Verification (REQUIRED) + +After successful build, run tests before completing work: + +1. **Configure tests (first time)**: + ```bash + cmake --preset=ninja-multi-vcpkg -DBUILD_TESTS=ON + ``` + +2. **Build tests**: + ```bash + cmake --build --preset=ninja-multi-vcpkg-debug + ``` + +3. **Run all tests**: + ```bash + ctest --preset=ninja-multi-vcpkg-debug + ``` + + Or run directly: + ```bash + cd builds/ninja-multi-vcpkg + ctest -C Debug --output-on-failure + ``` + +4. **Verify**: All tests pass (100% success rate) +5. **If tests fail**: + - Only fix failures related to your changes + - Ignore pre-existing test failures unrelated to your work + - Document any known issues +6. **Do not mark complete until tests pass** + +**Note**: See `TESTING.md` for detailed test documentation and advanced usage. + +--- + +## Project Constraints + +### Technical Requirements + +- **C++20**: Strict requirement +- **CMake 3.28+**: Required +- **vcpkg**: Use for dependencies +- **ImGui**: UI framework (with GLFW + OpenGL3 bindings) +- **GLFW3**: Windowing and input +- **OpenGL**: Rendering backend +- **flecs**: ECS framework + +### Platform Support + +- Windows: MSVC or MinGW-w64 GCC 10+ +- Linux: GCC 10+ or Clang 10+ +- macOS: Xcode 12+ / Clang 10+ + +### Code Standards + +#### Modern C++20 Requirements + +- **C++20 features**: Use ranges, concepts, coroutines (when appropriate) +- **RAII**: All resource management (files, memory, locks) via RAII types +- **Smart pointers**: + - `std::unique_ptr` for exclusive ownership + - `std::shared_ptr` only when truly shared ownership needed + - Raw pointers for non-owning references + - Never use `new`/`delete` directly +- **Containers**: Prefer standard library containers over manual memory management +- **Algorithms**: Use `` and `` over raw loops when clearer + +#### Modern C++ Patterns + +```cpp +// CORRECT: Use ranges instead of raw loops +auto filtered = data + | std::views::filter([](const auto& item) { return item.active; }) + | std::views::transform([](const auto& item) { return item.value; }); + +// CORRECT: Smart pointers for ownership +auto entity = std::make_unique(); +scene->AddEntity(std::move(entity)); // Transfer ownership + +// CORRECT: RAII for resources +class ResourceManager { + std::unique_ptr resource_; // Automatically cleaned up +}; + +// CORRECT: Small, focused functions +auto FindEntity(int id) const -> std::optional { + auto it = std::ranges::find_if(entities_, + [id](const auto& e) { return e.id == id; }); + return it != entities_.end() ? std::optional{*it} : std::nullopt; +} +``` + +#### Composition Over Inheritance + +- **Prefer composition** for building functionality +- **Use inheritance** only for polymorphism (Gang of Four patterns like Strategy, Observer, Composite) +- Keep inheritance hierarchies shallow (max 2-3 levels) + +```cpp +// CORRECT: Composition for building features +class GameWorld { + SceneManager scene_manager_; // Has-a + EntityRegistry entity_registry_; // Has-a + SystemManager system_manager_; // Has-a +}; + +// CORRECT: Inheritance for polymorphism (Strategy pattern) +class System { +public: + virtual void Update(float delta_time) = 0; + virtual void Render() const = 0; +}; + +class PhysicsSystem : public System { /* ... */ }; +class RenderSystem : public System { /* ... */ }; + +// WRONG: Inheritance for code reuse +class PlayerEntity : public Entity { // Avoid - use composition/ECS instead +}; +``` + +#### Gang of Four Patterns (Use When Appropriate) + +- **Observer**: Event callbacks, reactive updates +- **Strategy**: Interchangeable algorithms (rendering backends, input handlers) +- **Factory**: Entity/component creation in ECS +- **Command**: Action history, undo/redo systems +- **Singleton**: Use sparingly, only for true single instances (engine core, resource managers) + +#### Code Organization + +- **Small functions**: Max 20-30 lines, single responsibility +- **Comments**: Only for complex logic or non-obvious design decisions +- **Const correctness**: Use `const` everywhere possible +- **Type safety**: Prefer `enum class` over plain `enum` or integers + +--- + +## File Organization + +### Source Structure + +- `client/` - Client-specific code (rendering, GUI, input) +- `server/` - Server-specific code (networking, simulation) +- `common/` - Shared code (ECS, physics, events, resources) +- `tests/` - Unit and integration tests (GTest) +- `docs/` - User-facing documentation (mkdocs format) + - `docs/engine/` - Engine API docs (generated by doxybook2, committed) +- `assets/` - Game assets (textures, models, shaders) +- `proto/` - Protocol buffer definitions + +### Documentation Files + +- `README.md` - Build instructions, quick start +- `CONTRIBUTING.md` - Contribution guidelines +- `CODE_STYLE_GUIDE.md` - Coding standards (THIS FILE defines style) +- `AGENTS.md` - AI agent instructions (this file) +- `docs/` - Mkdocs user documentation + +--- + +## Documentation Guidelines + +### User Documentation (README.md) + +- Focus on build instructions and quick start +- User-oriented content (how to build, run, contribute) +- Not implementation details or architecture discussions + +### Code Comments + +- Only for complex logic explanation or non-obvious design decisions +- Don't comment on "what" changed - that's in version control +- Don't explain obvious code +- Self-documenting code preferred + +--- + +## Process Checklist + +When given a task: + +- [ ] Understand requirement (no plan doc needed) +- [ ] Identify minimal changes +- [ ] Execute changes directly +- [ ] Build and verify +- [ ] Clean up any temporary files created during investigation +- [ ] No standalone tests/demos created +- [ ] No unnecessary documentation created +- [ ] Changes are surgical and minimal + +--- + +## Error Handling + +### Build Errors + +- Fix immediately +- Rebuild to verify +- Do not proceed until clean build + +### Breaking Changes + +- Avoid at all costs +- Opt-in features only +- Maintain backward compatibility + +--- + +## Key Principles + +1. **Execute, don't document the plan** +2. **Minimal changes, surgical precision** +3. **Test in production code, not standalone apps** +4. **Build verification is mandatory** +5. **No supplementary documentation** +6. **When in doubt, ask the user** + +--- + +**Status**: This file is the only internal process documentation permitted. Follow these directives strictly. diff --git a/CODE_STYLE_GUIDE.md b/CODE_STYLE_GUIDE.md new file mode 100644 index 00000000..c9ded43c --- /dev/null +++ b/CODE_STYLE_GUIDE.md @@ -0,0 +1,357 @@ +# Trillek Engine C (TEC) - C++20 Code Style Guide + +> **Consistent coding standards for the Trillek Engine C project** + +## Overview + +This document defines the coding standards and style guidelines for Citrus Engine. Consistency in code style +improves readability, maintainability, and collaboration. + +## Naming Conventions + +### Functions and Methods + +- **Style**: PascalCase +- **Examples**: + ```cpp + void InitializeRenderer(); + bool LoadTexture(const std::string& path); + Mat4 GetViewMatrix() const; + ``` + +### Variables and Parameters + +- **Style**: snake_case +- **Examples**: + ```cpp + int entity_count; + float delta_time; + const std::string& file_path; + ``` + +### Classes and Structs + +- **Style**: PascalCase +- **Examples**: + ```cpp + class EntityManager; + struct Transform; + class TextureManager; + ``` + +### Enums and Enum Values + +- **Style**: PascalCase for enum class, PascalCase for values +- **Examples**: + ```cpp + enum class ProjectionType { + Perspective, + Orthographic + }; + + enum class TextureFormat { + RGB8, + RGBA8, + RGBA16F + }; + ``` + +### Constants + +- **Style**: PascalCase for const variables, UPPER_CASE for macros +- **Examples**: + ```cpp + constexpr float DefaultFov = 60.0f; + const Color WhiteColor{1.0f, 1.0f, 1.0f, 1.0f}; + + #define ENGINE_VERSION_MAJOR 1 + ``` + +### Member Variables + +- **Style**: snake_case with trailing underscore for private members +- **Examples**: + ```cpp + class Camera { + public: + Vec3 position{0.0f}; // Public members: no underscore + + private: + Vec3 position_{0.0f}; // Private members: trailing underscore + bool view_dirty_ = true; + }; + ``` + +### Namespaces + +- **Style**: snake_case +- **Examples**: + ```cpp + namespace engine::platform {} + namespace engine::rendering {} + ``` + +### Template Parameters + +- **Style**: PascalCase +- **Examples**: + ```cpp + template + template + template + ``` + +## File Naming + +### Header Files + +- **Style**: kebab-case with .hpp extension +- **Examples**: `entity-manager.hpp`, `physics-system.hpp`, `render-system.hpp` + +### Source Files + +- **Style**: kebab-case with .cpp extension +- **Examples**: `entity-manager.cpp`, `physics-system.cpp` + +### Directory Structure + +- **Style**: lowercase, sometimes with underscores +- **Examples**: `client/`, `server/`, `common/`, `docs_targets/` + +## Code Formatting + +### Indentation + +- **4 spaces** (no tabs) +- Consistent indentation for all nested blocks + +### Braces + +- **K&R style** for all situations (opening brace on same line) + +```cpp +class MyClass { +public: + void MyFunction() { + if (condition) { + // Do something + } else { + // Do something else + } + + for (int i = 0; i < count; ++i) { + // Loop body + } + } +}; +``` + +### Line Length + +- **Maximum 120 characters** per line +- Break long lines at logical points (parameters, operators) + +### Spacing + +- Space after keywords: `if (`, `for (`, `while (` +- Space around operators: `a + b`, `x == y` +- No space before semicolons: `func();` +- Space after commas: `func(a, b, c);` + +## C++20 Specific Guidelines + +### Headers (Traditional) + +- Use `#pragma once` for header guards (preferred over `#ifndef`) +- Include order: own header, standard library, third-party, project headers +- Use forward declarations where possible to reduce compile times + +```cpp +#pragma once + +#include // Standard library +#include + +#include // Third-party + +#include "entity.hpp" // Project headers +#include "components/transform.hpp" +``` + +### Concepts + +- Use PascalCase for concept names +- Place concepts before template declarations + +```cpp +template +concept Component = std::is_trivially_copyable_v && std::is_standard_layout_v; + +template +void RegisterComponent(); +``` + +### Auto and Type Deduction + +- Use `auto` for complex type names and lambda expressions +- Avoid `auto` when type clarity is important + +```cpp +auto texture_manager = GetTextureManager(); // Good: complex type +auto count = 5; // Bad: unclear type +int count = 5; // Good: clear intent +``` + +## Documentation + +### Comments + +- Use `//` for single-line comments +- Use `/* */` for multi-line comments +- Document public interfaces with brief descriptions + +```cpp +/// Get the current frame rate in frames per second +/// @return Current FPS as a double value +double GetCurrentFps() const; + +/** + * Create a new texture from image file + * @param path File path to the image + * @param format Desired texture format + * @return Texture ID or INVALID_TEXTURE on failure + */ +TextureId CreateTexture(const fs::Path& path, TextureFormat format); +``` + +### Module Documentation + +- Each module interface should have a header comment explaining its purpose +- Document major design decisions and constraints + +## Error Handling + +### Return Values + +- Use meaningful return types (not just bool) +- Prefer exceptions for exceptional cases +- Use `std::optional` for operations that may fail + +```cpp +std::optional LoadTexture(const fs::Path& path); +void InitializeRenderer(); // Throws on critical failure +bool IsValid(TextureId id) const; // Simple validation +``` + +### Assertions + +- Use assertions for development-time checks +- Use graceful error handling for runtime errors + +```cpp +assert(entity.IsValid()); // Development check +if (!file.IsOpen()) { // Runtime error handling + return std::nullopt; +} +``` + +## Performance Guidelines + +### Memory Management + +- Prefer stack allocation over heap allocation +- Use smart pointers for ownership management +- Consider custom allocators for high-frequency allocations + +### Function Design + +- Pass large objects by const reference +- Return small objects by value +- Use move semantics for expensive-to-copy objects + +```cpp +void ProcessEntity(const Transform& transform); // Large object by const ref +Vec3 GetPosition() const; // Small object by value +std::unique_ptr CreateTexture(TextureCreateInfo&& info); // Move semantics +``` + +## Example: Well-Formatted Code + +```cpp +#pragma once + +#include +#include +#include +#include + +#include + +namespace tec { + + class TextureManager { + public: + TextureManager(); + ~TextureManager(); + + /// Create a new texture from the provided creation info + TextureId CreateTexture(const TextureCreateInfo& info); + + /// Load texture from file path + std::optional LoadTexture(const std::string& path); + + /// Get texture dimensions + glm::vec2 GetTextureDimensions(TextureId id) const; + + /// Check if texture ID is valid + bool IsValidTexture(TextureId id) const; + + private: + std::unordered_map textures_; + TextureId next_id_ = 1; + + bool ValidateTextureData(const TextureCreateInfo& info) const; + }; + +} // namespace tec +``` + +## Project-Specific Patterns + +### Entity-Component-System (ECS) + +TEC uses a custom ECS architecture. Follow these patterns: + +```cpp +// Components are POD structs +struct Transform { + glm::vec3 position; + glm::quat orientation; + glm::vec3 scale{1.0f, 1.0f, 1.0f}; +}; + +// Entities are simple ID types +using EntityId = std::uint64_t; + +// Systems operate on components +class PhysicsSystem { +public: + void Update(double delta_time); +private: + // System implementation +}; +``` + +### Protobuf Serialization + +Network messages use Protocol Buffers. Place `.proto` files in `common/proto/`. + +### Lua Scripting + +TEC integrates Lua via sol3. Script bindings go in dedicated `*-lua.cpp` files. + +### ImGui Integration + +Debug UI uses Dear ImGui with immediate mode patterns. See `imgui-system.cpp` for examples. + +This style guide ensures consistency across the TEC codebase while leveraging modern C++20 features effectively.