{"owner":"chrxh","repo":"alien","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md",".github/copilot-instructions.md"],"skills":{"CLAUDE.md":"# ALIEN — Repository Instructions\n\nALIEN is an artificial life simulation built on a 2D CUDA particle engine for soft\nbodies and fluids. Mainly C++23 and CUDA, built with CMake + vcpkg (manifest mode).\nAn NVIDIA CUDA GPU is required for engine functionality and the engine tests.\nThe GUI uses Dear ImGui.\n\n## Language\n\nConverse in the language the user used, but **everything that is committed, pushed,\nor created on GitHub must be in English**: commit messages, branch slugs, PR titles\nand bodies, code comments, identifiers. Keep commit messages short and imperative.\n\n## Code style\n\n- 4 spaces, no tabs\n- Allman braces\n- camelCase for variables and functions\n- PascalCase for classes\n- UPPER_SNAKE_CASE for constants\n- `.h` for C++ headers, `.cuh` for CUDA headers, `.cpp` / `.cu` for implementations\n- Avoid unnecessary comments; prefer self-documenting code\n- Prefer `.at()` over `[]` for `std::vector` access unless there is a strong local reason\n\n## Hard rules\n\n- Do **not** run CodeQL / `codeql_checker` / any CodeQL security scanning\n- Do **not** run `git submodule update`\n- `external/vcpkg` is a pinned submodule — never modify or commit it. If it shows as\n  modified, restore with `git restore external/vcpkg`. Never `git add external/vcpkg`.\n- Do not cancel long-running builds or tests; they can take several minutes.\n\n## Build (Windows)\n\nBuild with the repo-root script, not the default Visual Studio generator:\n\n```\nbuild-windows-ninja.bat          # Release (default)\nbuild-windows-ninja.bat Debug    # Debug\n```\n\nIt sets up MSVC via vcvars64 and uses the \"Ninja Multi-Config\" CMake preset\n(`cmake --preset ninja` + `cmake --build --preset ninja-release`), compiling the CUDA\ntranslation units in parallel. Executables land under **`build-ninja\\Release\\`**\n(e.g. `alien.exe`, `cli.exe`, `EngineTests.exe`) — not the older `build\\Release\\`.\n\nA struct / constant-memory / kernel `.cuh` change needs a clean rebuild, otherwise\nstale kernels linger and weak tests can pass against old code.\n\n## Tests\n\nExecutables under `build-ninja\\Release\\`:\n\n```\nEngineInterfaceTests.exe   (<1s)\nNetworkTests.exe           (<1s)\nPersisterTests.exe         (~1.4s)\nEngineTests.exe            (~150s — needs the GPU; do not cancel)\n```\n\nGUI-only changes under `source/Gui/` that do not touch engine, network, persistence,\nCLI, or shared code do not strictly need tests, but still build. For a targeted CUDA\nfailure: `EngineTests.exe -d --gtest_filter=Suite.Test` (debug mode is much slower —\nuse it for single tests only, not the full suite).\n\n## Formatting\n\nThe clang-format **version matters**: format with **19.1.5** (bundled with Visual\nStudio 2022 Community — bare `clang-format` on PATH resolves to it). Do **not** use the\nVS Insiders v22 binary — same `source/_clang-format` config, but it reflows lines\ndifferently and creates churn. Format only the files you modified, and only if they are\nalready clean at HEAD:\n\n```\nclang-format --style=file:source/_clang-format --dry-run --Werror <file>\n```\n\nSeveral committed files are not clang-format-clean, so running a whole-file format on\nthem reflows unrelated lines. ColumnLimit is 160; clang-format does not always wrap long\nbuilder-chain assignments beyond 160, and that is accepted.\n\n## Layout\n\n```\nsource/Base/                 Common utilities, math, logging\nsource/Cli/                  Command-line interface\nsource/EngineGpuKernels/     CUDA kernels\nsource/EngineImpl/           CPU-side engine implementation\nsource/EngineInterface/      Abstract simulation APIs\nsource/EngineInterfaceTests/ EngineInterface unit tests\nsource/EngineTests/          CUDA engine integration tests\nsource/Gui/                  Dear ImGui GUI\nsource/Network/              HTTP / cloud features\nsource/PersisterImpl/        File I/O and serialization\nexternal/                    Third-party dependencies incl. the pinned vcpkg submodule\nresources/                   Runtime assets\n```\n",".github/copilot-instructions.md":"# ALIEN - Artificial Life Environment\n\n**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**\n\n## Project Overview\nALIEN is an artificial life simulation tool based on a specialized 2D particle engine in CUDA for soft bodies and fluids. Each simulated body consists of a network of particles that can be upgraded with higher-level functions, ranging from pure information processing capabilities to physical equipment (such as sensors, muscles, weapons, constructors, etc.) whose executions are orchestrated by neural networks. The bodies can be thought of as agents or digital organisms operating in a common environment.\n\n## Security Configuration\n\n### CodeQL Security Checks\n**DO NOT use CodeQL security checks on this repository.** The repository is too large for CodeQL analysis to complete successfully. \n\n- Do NOT run the `codeql_checker` tool\n- Do NOT attempt any CodeQL security scanning\n- Skip all security vulnerability scanning steps that involve CodeQL\n\n### Git Submodule Configuration\n**DO NOT update the vcpkg submodule in external/vcpkg.** The vcpkg version is pinned to a specific commit for stability.\n\n- Do NOT run `git submodule update` commands\n- Do NOT modify the external/vcpkg submodule pointer\n- Do NOT commit changes to external/vcpkg\n- If you see external/vcpkg changes in `git status`, use `git restore external/vcpkg` to discard them\n- The vcpkg submodule is managed separately by repository maintainers\n\n## Working Effectively\n\n### Bootstrap, Build, and Test the Repository\n**NEVER CANCEL long-running commands. Build may take 4-5 minutes. Use long timeouts.**\n\n```bash\ncmake --build build --config Release -j32\n```\n\n### Run Tests\n```bash\ncd build\n\n# Tests\n./EngineInterfaceTests  # <1 second\n./NetworkTests          # <1 second\n./PersisterTests        # ~1.4 seconds\n./EngineTests           # >4 min\n\n# Debug mode for EngineTests (use -d for precise kernel failure info)\n./EngineTests -d --gtest_filter=TestSuite.TestName  # Much slower, use for debugging specific tests only\n```\n\n**Note on `-d` flag**: The `-d` parameter enables debug mode which synchronizes CUDA after each kernel call. This provides more precise information about which kernel is failing, but significantly increases test execution time. Only recommended when debugging specific failing tests, not for full test suite runs.\n\n### Run the Applications\n```bash\ncd build\n\n# GUI application (requires X11 display and NVIDIA GPU)\n./alien\n\n# Command-line interface (requires .sim and .settings.json files)\n./cli --help\n./cli -i input.sim -o output.sim -t 1000\n```\n\n## Validation\n\n## Validation\n\n### Build Validation\n- **Build succeeds** and produces all expected executables: `alien`, `cli`, `EngineTests`, `EngineInterfaceTests`, `NetworkTests`, `PersisterTests`\n- **Build time**: ~1 min on 32-core system with `-j32` parallelization\n- **Clean configuration**: ~6 seconds\n- **No build errors or warnings** when following the exact commands above\n\n### Test Validation  \n- **EngineInterfaceTests**: tests pass in <1 second\n- **NetworkTests**: tests pass in <1 second\n- **PersisterTests**: tests pass in ~1.4 seconds\n- **EngineTests**: tests pass in >4 min\n- Pure GUI-only changes in `source/Gui/` that do not affect engine, network, persistence, or CLI logic do **not** require running tests\n- For all other changes, run `./EngineInterfaceTests && ./NetworkTests && ./PersisterTests && ./EngineTests` to verify your changes don't break core functionality\n- `./EngineTests` are most important and contain the entire simulation logic written in CUDA\n\n### Application Validation\n- **CLI works**: `./cli --help` shows usage information\n- **GUI requires**: NVIDIA GPU + X11 display (cannot run in headless CI environments)\n- **GUI error handling**: Provides clear error messages when GPU requirements aren't met\n- **Simulation files**: CLI expects `.sim` and `.settings.json` files (not included in main repo)\n\n### Validation Workflow for Changes\n```bash\n# Always run this validation sequence after making code changes:\n\n# 1. Format code (if modified)\nclang-format --style=file:source/_clang-format -i path/to/modified/files.cpp\n\n# 2. Build (NEVER CANCEL - ~ 1 minute)\ncmake --build build --config Release -j32\n\n# 3. Run core tests (required unless the change is pure GUI-only in source/Gui)\ncd build && ./EngineInterfaceTests && ./NetworkTests && ./PersisterTests & ./EngineTests\n\n# 4. Test CLI functionality\n./cli --help\n```\n\n### Code Formatting\n```bash\n# Format code using project's clang-format config\nclang-format --style=file:source/_clang-format --dry-run --Werror source/path/to/file.cpp\n\n# Format all files (if needed)\nfind source -name \"*.cpp\" -o -name \"*.h\" | xargs clang-format --style=file:source/_clang-format -i\n```\n\n## Technology Stack & Requirements\n- **Languages**: C++23, CUDA 20, Python (for CLI tools)\n- **Build System**: CMake 3.31+, vcpkg package manager\n- **GPU Computing**: NVIDIA CUDA (requires compute capability 7.5+)\n- **GUI Framework**: Dear ImGui with custom widgets\n- **Dependencies**: All managed via vcpkg manifest mode (`vcpkg.json`)\n\n## Repository Structure & Navigation\n- `source/`: Main C++ and CUDA source code\n  - `source/Base/`: Common utilities, math, logging\n  - `source/Cli/`: Command-line interface\n  - `source/EngineGpuKernels/`: CUDA kernels for simulation\n  - `source/EngineImpl/`: CPU-side engine implementation\n  - `source/EngineInterface/`: Abstract simulation APIs\n  - `source/EngineInterfaceTests/`: Unit tests for EngineInterface\n  - `source/EngineTests/`: Integration tests for engine\n  - `source/Gui/`: ImGui-based user interface\n  - `source/Network/`: HTTP client for cloud features\n  - `source/PersisterImpl/`: File I/O and serialization\n  - `source/_clang-format`: Code formatting configuration\n- `external/`: Third-party libraries (vcpkg submodule)\n- `resources/`: Runtime assets (shaders, fonts, icons)\n- `scripts/CLI-Tools/`: Python automation tools\n- `vcpkg.json`: Dependency manifest for package management\n\n## Common Development Tasks\n\n### Command-Line Interface (CLI)\nThe project includes a CLI for headless simulation execution:\n```bash\n# Basic simulation run (requires existing .sim and .settings.json files)\n./cli -i example.sim -o output.sim -t 1000\n\n# The CLI generates three outputs:\nPython automation tools are available in `scripts/CLI-Tools/`:\n- `FindFortunateTimeline.py`: Automated simulation with savepoints and rollback logic\n\n### Code Style & Formatting\n- **Formatting config**: `source/_clang-format` file contains project style rules\n- **Line length**: 160 characters maximum\n- **Indentation**: 4 spaces, no tabs\n- **Braces**: Allman style (opening brace on new line)\n- **Comments**: Avoid unnecessary comments - code should be self-documenting\n- **Vector access**: Always use `.at()` instead of `[]` for `std::vector` element access to enable bounds checking\n\n### Naming Conventions\n- **Classes**: PascalCase (`SimulationFacade`)\n- **Variables/functions**: camelCase (`calculateEnergy`)\n- **Constants**: UPPER_SNAKE_CASE (`MAX_PARTICLES`)\n- **Files**: `.h` for C++ headers, `.cuh` for CUDA headers, `.cpp/.cu` for implementation\n\n### Architecture Overview\nThe engine follows a layered architecture:\n- **Interface Layer** (`EngineInterface/`): Abstract APIs for simulation operations\n- **Implementation Layer** (`EngineImpl/`): CPU-side coordination and data management\n- **GPU Compute Layer** (`EngineGpuKernels/`): CUDA kernels for parallel simulation\n- **GUI Layer** (`Gui/`): User interface built on Dear ImGui\n\n### Testing Guidelines\n- **Test naming**: `*Tests.cpp` files, descriptive test method names\n- **Test types**: Unit tests (preferred), integration tests, performance tests\n- **GPU tests**: Require NVIDIA hardware, will fail in CI without GPU\n- **Always run**: `./EngineInterfaceTests && ./NetworkTests && ./PersisterTests` to verify core functionality\n\n### Performance & Debugging\n- **CUDA debugging**: Use `cuda-gdb` or Nsight Compute for kernel debugging\n- **Memory profiling**: Use CUDA memory checker for leak detection\n- **Build issues**: Clean vcpkg cache and rebuild dependencies if needed\n- **GPU requirements**: Compute capability 6.0+ required for all GPU functionality\n\n## External Resources\n- [Project Documentation](https://alien-project.gitbook.io/docs)\n- [Architecture Overview](https://alien-project.gitbook.io/docs/under-the-hood)\n- [NVIDIA CUDA Programming Guide](https://docs.nvidia.com/cuda/cuda-c-programming-guide/)\n- [Dear ImGui Documentation](https://github.com/ocornut/imgui)\n"},"files":{"CLAUDE.md":"# ALIEN — Repository Instructions\n\nALIEN is an artificial life simulation built on a 2D CUDA particle engine for soft\nbodies and fluids. Mainly C++23 and CUDA, built with CMake + vcpkg (manifest mode).\nAn NVIDIA CUDA GPU is required for engine functionality and the engine tests.\nThe GUI uses Dear ImGui.\n\n## Language\n\nConverse in the language the user used, but **everything that is committed, pushed,\nor created on GitHub must be in English**: commit messages, branch slugs, PR titles\nand bodies, code comments, identifiers. Keep commit messages short and imperative.\n\n## Code style\n\n- 4 spaces, no tabs\n- Allman braces\n- camelCase for variables and functions\n- PascalCase for classes\n- UPPER_SNAKE_CASE for constants\n- `.h` for C++ headers, `.cuh` for CUDA headers, `.cpp` / `.cu` for implementations\n- Avoid unnecessary comments; prefer self-documenting code\n- Prefer `.at()` over `[]` for `std::vector` access unless there is a strong local reason\n\n## Hard rules\n\n- Do **not** run CodeQL / `codeql_checker` / any CodeQL security scanning\n- Do **not** run `git submodule update`\n- `external/vcpkg` is a pinned submodule — never modify or commit it. If it shows as\n  modified, restore with `git restore external/vcpkg`. Never `git add external/vcpkg`.\n- Do not cancel long-running builds or tests; they can take several minutes.\n\n## Build (Windows)\n\nBuild with the repo-root script, not the default Visual Studio generator:\n\n```\nbuild-windows-ninja.bat          # Release (default)\nbuild-windows-ninja.bat Debug    # Debug\n```\n\nIt sets up MSVC via vcvars64 and uses the \"Ninja Multi-Config\" CMake preset\n(`cmake --preset ninja` + `cmake --build --preset ninja-release`), compiling the CUDA\ntranslation units in parallel. Executables land under **`build-ninja\\Release\\`**\n(e.g. `alien.exe`, `cli.exe`, `EngineTests.exe`) — not the older `build\\Release\\`.\n\nA struct / constant-memory / kernel `.cuh` change needs a clean rebuild, otherwise\nstale kernels linger and weak tests can pass against old code.\n\n## Tests\n\nExecutables under `build-ninja\\Release\\`:\n\n```\nEngineInterfaceTests.exe   (<1s)\nNetworkTests.exe           (<1s)\nPersisterTests.exe         (~1.4s)\nEngineTests.exe            (~150s — needs the GPU; do not cancel)\n```\n\nGUI-only changes under `source/Gui/` that do not touch engine, network, persistence,\nCLI, or shared code do not strictly need tests, but still build. For a targeted CUDA\nfailure: `EngineTests.exe -d --gtest_filter=Suite.Test` (debug mode is much slower —\nuse it for single tests only, not the full suite).\n\n## Formatting\n\nThe clang-format **version matters**: format with **19.1.5** (bundled with Visual\nStudio 2022 Community — bare `clang-format` on PATH resolves to it). Do **not** use the\nVS Insiders v22 binary — same `source/_clang-format` config, but it reflows lines\ndifferently and creates churn. Format only the files you modified, and only if they are\nalready clean at HEAD:\n\n```\nclang-format --style=file:source/_clang-format --dry-run --Werror <file>\n```\n\nSeveral committed files are not clang-format-clean, so running a whole-file format on\nthem reflows unrelated lines. ColumnLimit is 160; clang-format does not always wrap long\nbuilder-chain assignments beyond 160, and that is accepted.\n\n## Layout\n\n```\nsource/Base/                 Common utilities, math, logging\nsource/Cli/                  Command-line interface\nsource/EngineGpuKernels/     CUDA kernels\nsource/EngineImpl/           CPU-side engine implementation\nsource/EngineInterface/      Abstract simulation APIs\nsource/EngineInterfaceTests/ EngineInterface unit tests\nsource/EngineTests/          CUDA engine integration tests\nsource/Gui/                  Dear ImGui GUI\nsource/Network/              HTTP / cloud features\nsource/PersisterImpl/        File I/O and serialization\nexternal/                    Third-party dependencies incl. the pinned vcpkg submodule\nresources/                   Runtime assets\n```\n",".github/copilot-instructions.md":"# ALIEN - Artificial Life Environment\n\n**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**\n\n## Project Overview\nALIEN is an artificial life simulation tool based on a specialized 2D particle engine in CUDA for soft bodies and fluids. Each simulated body consists of a network of particles that can be upgraded with higher-level functions, ranging from pure information processing capabilities to physical equipment (such as sensors, muscles, weapons, constructors, etc.) whose executions are orchestrated by neural networks. The bodies can be thought of as agents or digital organisms operating in a common environment.\n\n## Security Configuration\n\n### CodeQL Security Checks\n**DO NOT use CodeQL security checks on this repository.** The repository is too large for CodeQL analysis to complete successfully. \n\n- Do NOT run the `codeql_checker` tool\n- Do NOT attempt any CodeQL security scanning\n- Skip all security vulnerability scanning steps that involve CodeQL\n\n### Git Submodule Configuration\n**DO NOT update the vcpkg submodule in external/vcpkg.** The vcpkg version is pinned to a specific commit for stability.\n\n- Do NOT run `git submodule update` commands\n- Do NOT modify the external/vcpkg submodule pointer\n- Do NOT commit changes to external/vcpkg\n- If you see external/vcpkg changes in `git status`, use `git restore external/vcpkg` to discard them\n- The vcpkg submodule is managed separately by repository maintainers\n\n## Working Effectively\n\n### Bootstrap, Build, and Test the Repository\n**NEVER CANCEL long-running commands. Build may take 4-5 minutes. Use long timeouts.**\n\n```bash\ncmake --build build --config Release -j32\n```\n\n### Run Tests\n```bash\ncd build\n\n# Tests\n./EngineInterfaceTests  # <1 second\n./NetworkTests          # <1 second\n./PersisterTests        # ~1.4 seconds\n./EngineTests           # >4 min\n\n# Debug mode for EngineTests (use -d for precise kernel failure info)\n./EngineTests -d --gtest_filter=TestSuite.TestName  # Much slower, use for debugging specific tests only\n```\n\n**Note on `-d` flag**: The `-d` parameter enables debug mode which synchronizes CUDA after each kernel call. This provides more precise information about which kernel is failing, but significantly increases test execution time. Only recommended when debugging specific failing tests, not for full test suite runs.\n\n### Run the Applications\n```bash\ncd build\n\n# GUI application (requires X11 display and NVIDIA GPU)\n./alien\n\n# Command-line interface (requires .sim and .settings.json files)\n./cli --help\n./cli -i input.sim -o output.sim -t 1000\n```\n\n## Validation\n\n## Validation\n\n### Build Validation\n- **Build succeeds** and produces all expected executables: `alien`, `cli`, `EngineTests`, `EngineInterfaceTests`, `NetworkTests`, `PersisterTests`\n- **Build time**: ~1 min on 32-core system with `-j32` parallelization\n- **Clean configuration**: ~6 seconds\n- **No build errors or warnings** when following the exact commands above\n\n### Test Validation  \n- **EngineInterfaceTests**: tests pass in <1 second\n- **NetworkTests**: tests pass in <1 second\n- **PersisterTests**: tests pass in ~1.4 seconds\n- **EngineTests**: tests pass in >4 min\n- Pure GUI-only changes in `source/Gui/` that do not affect engine, network, persistence, or CLI logic do **not** require running tests\n- For all other changes, run `./EngineInterfaceTests && ./NetworkTests && ./PersisterTests && ./EngineTests` to verify your changes don't break core functionality\n- `./EngineTests` are most important and contain the entire simulation logic written in CUDA\n\n### Application Validation\n- **CLI works**: `./cli --help` shows usage information\n- **GUI requires**: NVIDIA GPU + X11 display (cannot run in headless CI environments)\n- **GUI error handling**: Provides clear error messages when GPU requirements aren't met\n- **Simulation files**: CLI expects `.sim` and `.settings.json` files (not included in main repo)\n\n### Validation Workflow for Changes\n```bash\n# Always run this validation sequence after making code changes:\n\n# 1. Format code (if modified)\nclang-format --style=file:source/_clang-format -i path/to/modified/files.cpp\n\n# 2. Build (NEVER CANCEL - ~ 1 minute)\ncmake --build build --config Release -j32\n\n# 3. Run core tests (required unless the change is pure GUI-only in source/Gui)\ncd build && ./EngineInterfaceTests && ./NetworkTests && ./PersisterTests & ./EngineTests\n\n# 4. Test CLI functionality\n./cli --help\n```\n\n### Code Formatting\n```bash\n# Format code using project's clang-format config\nclang-format --style=file:source/_clang-format --dry-run --Werror source/path/to/file.cpp\n\n# Format all files (if needed)\nfind source -name \"*.cpp\" -o -name \"*.h\" | xargs clang-format --style=file:source/_clang-format -i\n```\n\n## Technology Stack & Requirements\n- **Languages**: C++23, CUDA 20, Python (for CLI tools)\n- **Build System**: CMake 3.31+, vcpkg package manager\n- **GPU Computing**: NVIDIA CUDA (requires compute capability 7.5+)\n- **GUI Framework**: Dear ImGui with custom widgets\n- **Dependencies**: All managed via vcpkg manifest mode (`vcpkg.json`)\n\n## Repository Structure & Navigation\n- `source/`: Main C++ and CUDA source code\n  - `source/Base/`: Common utilities, math, logging\n  - `source/Cli/`: Command-line interface\n  - `source/EngineGpuKernels/`: CUDA kernels for simulation\n  - `source/EngineImpl/`: CPU-side engine implementation\n  - `source/EngineInterface/`: Abstract simulation APIs\n  - `source/EngineInterfaceTests/`: Unit tests for EngineInterface\n  - `source/EngineTests/`: Integration tests for engine\n  - `source/Gui/`: ImGui-based user interface\n  - `source/Network/`: HTTP client for cloud features\n  - `source/PersisterImpl/`: File I/O and serialization\n  - `source/_clang-format`: Code formatting configuration\n- `external/`: Third-party libraries (vcpkg submodule)\n- `resources/`: Runtime assets (shaders, fonts, icons)\n- `scripts/CLI-Tools/`: Python automation tools\n- `vcpkg.json`: Dependency manifest for package management\n\n## Common Development Tasks\n\n### Command-Line Interface (CLI)\nThe project includes a CLI for headless simulation execution:\n```bash\n# Basic simulation run (requires existing .sim and .settings.json files)\n./cli -i example.sim -o output.sim -t 1000\n\n# The CLI generates three outputs:\nPython automation tools are available in `scripts/CLI-Tools/`:\n- `FindFortunateTimeline.py`: Automated simulation with savepoints and rollback logic\n\n### Code Style & Formatting\n- **Formatting config**: `source/_clang-format` file contains project style rules\n- **Line length**: 160 characters maximum\n- **Indentation**: 4 spaces, no tabs\n- **Braces**: Allman style (opening brace on new line)\n- **Comments**: Avoid unnecessary comments - code should be self-documenting\n- **Vector access**: Always use `.at()` instead of `[]` for `std::vector` element access to enable bounds checking\n\n### Naming Conventions\n- **Classes**: PascalCase (`SimulationFacade`)\n- **Variables/functions**: camelCase (`calculateEnergy`)\n- **Constants**: UPPER_SNAKE_CASE (`MAX_PARTICLES`)\n- **Files**: `.h` for C++ headers, `.cuh` for CUDA headers, `.cpp/.cu` for implementation\n\n### Architecture Overview\nThe engine follows a layered architecture:\n- **Interface Layer** (`EngineInterface/`): Abstract APIs for simulation operations\n- **Implementation Layer** (`EngineImpl/`): CPU-side coordination and data management\n- **GPU Compute Layer** (`EngineGpuKernels/`): CUDA kernels for parallel simulation\n- **GUI Layer** (`Gui/`): User interface built on Dear ImGui\n\n### Testing Guidelines\n- **Test naming**: `*Tests.cpp` files, descriptive test method names\n- **Test types**: Unit tests (preferred), integration tests, performance tests\n- **GPU tests**: Require NVIDIA hardware, will fail in CI without GPU\n- **Always run**: `./EngineInterfaceTests && ./NetworkTests && ./PersisterTests` to verify core functionality\n\n### Performance & Debugging\n- **CUDA debugging**: Use `cuda-gdb` or Nsight Compute for kernel debugging\n- **Memory profiling**: Use CUDA memory checker for leak detection\n- **Build issues**: Clean vcpkg cache and rebuild dependencies if needed\n- **GPU requirements**: Compute capability 6.0+ required for all GPU functionality\n\n## External Resources\n- [Project Documentation](https://alien-project.gitbook.io/docs)\n- [Architecture Overview](https://alien-project.gitbook.io/docs/under-the-hood)\n- [NVIDIA CUDA Programming Guide](https://docs.nvidia.com/cuda/cuda-c-programming-guide/)\n- [Dear ImGui Documentation](https://github.com/ocornut/imgui)\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# ALIEN — Repository Instructions\n\nALIEN is an artificial life simulation built on a 2D CUDA particle engine for soft\nbodies and fluids. Mainly C++23 and CUDA, built with CMake + vcpkg (manifest mode).\nAn NVIDIA CUDA GPU is required for engine functionality and the engine tests.\nThe GUI uses Dear ImGui.\n\n## Language\n\nConverse in the language the user used, but **everything that is committed, pushed,\nor created on GitHub must be in English**: commit messages, branch slugs, PR titles\nand bodies, code comments, identifiers. Keep commit messages short and imperative.\n\n## Code style\n\n- 4 spaces, no tabs\n- Allman braces\n- camelCase for variables and functions\n- PascalCase for classes\n- UPPER_SNAKE_CASE for constants\n- `.h` for C++ headers, `.cuh` for CUDA headers, `.cpp` / `.cu` for implementations\n- Avoid unnecessary comments; prefer self-documenting code\n- Prefer `.at()` over `[]` for `std::vector` access unless there is a strong local reason\n\n## Hard rules\n\n- Do **not** run CodeQL / `codeql_checker` / any CodeQL security scanning\n- Do **not** run `git submodule update`\n- `external/vcpkg` is a pinned submodule — never modify or commit it. If it shows as\n  modified, restore with `git restore external/vcpkg`. Never `git add external/vcpkg`.\n- Do not cancel long-running builds or tests; they can take several minutes.\n\n## Build (Windows)\n\nBuild with the repo-root script, not the default Visual Studio generator:\n\n```\nbuild-windows-ninja.bat          # Release (default)\nbuild-windows-ninja.bat Debug    # Debug\n```\n\nIt sets up MSVC via vcvars64 and uses the \"Ninja Multi-Config\" CMake preset\n(`cmake --preset ninja` + `cmake --build --preset ninja-release`), compiling the CUDA\ntranslation units in parallel. Executables land under **`build-ninja\\Release\\`**\n(e.g. `alien.exe`, `cli.exe`, `EngineTests.exe`) — not the older `build\\Release\\`.\n\nA struct / constant-memory / kernel `.cuh` change needs a clean rebuild, otherwise\nstale kernels linger and weak tests can pass against old code.\n\n## Tests\n\nExecutables under `build-ninja\\Release\\`:\n\n```\nEngineInterfaceTests.exe   (<1s)\nNetworkTests.exe           (<1s)\nPersisterTests.exe         (~1.4s)\nEngineTests.exe            (~150s — needs the GPU; do not cancel)\n```\n\nGUI-only changes under `source/Gui/` that do not touch engine, network, persistence,\nCLI, or shared code do not strictly need tests, but still build. For a targeted CUDA\nfailure: `EngineTests.exe -d --gtest_filter=Suite.Test` (debug mode is much slower —\nuse it for single tests only, not the full suite).\n\n## Formatting\n\nThe clang-format **version matters**: format with **19.1.5** (bundled with Visual\nStudio 2022 Community — bare `clang-format` on PATH resolves to it). Do **not** use the\nVS Insiders v22 binary — same `source/_clang-format` config, but it reflows lines\ndifferently and creates churn. Format only the files you modified, and only if they are\nalready clean at HEAD:\n\n```\nclang-format --style=file:source/_clang-format --dry-run --Werror <file>\n```\n\nSeveral committed files are not clang-format-clean, so running a whole-file format on\nthem reflows unrelated lines. ColumnLimit is 160; clang-format does not always wrap long\nbuilder-chain assignments beyond 160, and that is accepted.\n\n## Layout\n\n```\nsource/Base/                 Common utilities, math, logging\nsource/Cli/                  Command-line interface\nsource/EngineGpuKernels/     CUDA kernels\nsource/EngineImpl/           CPU-side engine implementation\nsource/EngineInterface/      Abstract simulation APIs\nsource/EngineInterfaceTests/ EngineInterface unit tests\nsource/EngineTests/          CUDA engine integration tests\nsource/Gui/                  Dear ImGui GUI\nsource/Network/              HTTP / cloud features\nsource/PersisterImpl/        File I/O and serialization\nexternal/                    Third-party dependencies incl. the pinned vcpkg submodule\nresources/                   Runtime assets\n```\n","category":"root","tokens":981},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","title":"copilot-instructions.md","content":"# ALIEN - Artificial Life Environment\n\n**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**\n\n## Project Overview\nALIEN is an artificial life simulation tool based on a specialized 2D particle engine in CUDA for soft bodies and fluids. Each simulated body consists of a network of particles that can be upgraded with higher-level functions, ranging from pure information processing capabilities to physical equipment (such as sensors, muscles, weapons, constructors, etc.) whose executions are orchestrated by neural networks. The bodies can be thought of as agents or digital organisms operating in a common environment.\n\n## Security Configuration\n\n### CodeQL Security Checks\n**DO NOT use CodeQL security checks on this repository.** The repository is too large for CodeQL analysis to complete successfully. \n\n- Do NOT run the `codeql_checker` tool\n- Do NOT attempt any CodeQL security scanning\n- Skip all security vulnerability scanning steps that involve CodeQL\n\n### Git Submodule Configuration\n**DO NOT update the vcpkg submodule in external/vcpkg.** The vcpkg version is pinned to a specific commit for stability.\n\n- Do NOT run `git submodule update` commands\n- Do NOT modify the external/vcpkg submodule pointer\n- Do NOT commit changes to external/vcpkg\n- If you see external/vcpkg changes in `git status`, use `git restore external/vcpkg` to discard them\n- The vcpkg submodule is managed separately by repository maintainers\n\n## Working Effectively\n\n### Bootstrap, Build, and Test the Repository\n**NEVER CANCEL long-running commands. Build may take 4-5 minutes. Use long timeouts.**\n\n```bash\ncmake --build build --config Release -j32\n```\n\n### Run Tests\n```bash\ncd build\n\n# Tests\n./EngineInterfaceTests  # <1 second\n./NetworkTests          # <1 second\n./PersisterTests        # ~1.4 seconds\n./EngineTests           # >4 min\n\n# Debug mode for EngineTests (use -d for precise kernel failure info)\n./EngineTests -d --gtest_filter=TestSuite.TestName  # Much slower, use for debugging specific tests only\n```\n\n**Note on `-d` flag**: The `-d` parameter enables debug mode which synchronizes CUDA after each kernel call. This provides more precise information about which kernel is failing, but significantly increases test execution time. Only recommended when debugging specific failing tests, not for full test suite runs.\n\n### Run the Applications\n```bash\ncd build\n\n# GUI application (requires X11 display and NVIDIA GPU)\n./alien\n\n# Command-line interface (requires .sim and .settings.json files)\n./cli --help\n./cli -i input.sim -o output.sim -t 1000\n```\n\n## Validation\n\n## Validation\n\n### Build Validation\n- **Build succeeds** and produces all expected executables: `alien`, `cli`, `EngineTests`, `EngineInterfaceTests`, `NetworkTests`, `PersisterTests`\n- **Build time**: ~1 min on 32-core system with `-j32` parallelization\n- **Clean configuration**: ~6 seconds\n- **No build errors or warnings** when following the exact commands above\n\n### Test Validation  \n- **EngineInterfaceTests**: tests pass in <1 second\n- **NetworkTests**: tests pass in <1 second\n- **PersisterTests**: tests pass in ~1.4 seconds\n- **EngineTests**: tests pass in >4 min\n- Pure GUI-only changes in `source/Gui/` that do not affect engine, network, persistence, or CLI logic do **not** require running tests\n- For all other changes, run `./EngineInterfaceTests && ./NetworkTests && ./PersisterTests && ./EngineTests` to verify your changes don't break core functionality\n- `./EngineTests` are most important and contain the entire simulation logic written in CUDA\n\n### Application Validation\n- **CLI works**: `./cli --help` shows usage information\n- **GUI requires**: NVIDIA GPU + X11 display (cannot run in headless CI environments)\n- **GUI error handling**: Provides clear error messages when GPU requirements aren't met\n- **Simulation files**: CLI expects `.sim` and `.settings.json` files (not included in main repo)\n\n### Validation Workflow for Changes\n```bash\n# Always run this validation sequence after making code changes:\n\n# 1. Format code (if modified)\nclang-format --style=file:source/_clang-format -i path/to/modified/files.cpp\n\n# 2. Build (NEVER CANCEL - ~ 1 minute)\ncmake --build build --config Release -j32\n\n# 3. Run core tests (required unless the change is pure GUI-only in source/Gui)\ncd build && ./EngineInterfaceTests && ./NetworkTests && ./PersisterTests & ./EngineTests\n\n# 4. Test CLI functionality\n./cli --help\n```\n\n### Code Formatting\n```bash\n# Format code using project's clang-format config\nclang-format --style=file:source/_clang-format --dry-run --Werror source/path/to/file.cpp\n\n# Format all files (if needed)\nfind source -name \"*.cpp\" -o -name \"*.h\" | xargs clang-format --style=file:source/_clang-format -i\n```\n\n## Technology Stack & Requirements\n- **Languages**: C++23, CUDA 20, Python (for CLI tools)\n- **Build System**: CMake 3.31+, vcpkg package manager\n- **GPU Computing**: NVIDIA CUDA (requires compute capability 7.5+)\n- **GUI Framework**: Dear ImGui with custom widgets\n- **Dependencies**: All managed via vcpkg manifest mode (`vcpkg.json`)\n\n## Repository Structure & Navigation\n- `source/`: Main C++ and CUDA source code\n  - `source/Base/`: Common utilities, math, logging\n  - `source/Cli/`: Command-line interface\n  - `source/EngineGpuKernels/`: CUDA kernels for simulation\n  - `source/EngineImpl/`: CPU-side engine implementation\n  - `source/EngineInterface/`: Abstract simulation APIs\n  - `source/EngineInterfaceTests/`: Unit tests for EngineInterface\n  - `source/EngineTests/`: Integration tests for engine\n  - `source/Gui/`: ImGui-based user interface\n  - `source/Network/`: HTTP client for cloud features\n  - `source/PersisterImpl/`: File I/O and serialization\n  - `source/_clang-format`: Code formatting configuration\n- `external/`: Third-party libraries (vcpkg submodule)\n- `resources/`: Runtime assets (shaders, fonts, icons)\n- `scripts/CLI-Tools/`: Python automation tools\n- `vcpkg.json`: Dependency manifest for package management\n\n## Common Development Tasks\n\n### Command-Line Interface (CLI)\nThe project includes a CLI for headless simulation execution:\n```bash\n# Basic simulation run (requires existing .sim and .settings.json files)\n./cli -i example.sim -o output.sim -t 1000\n\n# The CLI generates three outputs:\nPython automation tools are available in `scripts/CLI-Tools/`:\n- `FindFortunateTimeline.py`: Automated simulation with savepoints and rollback logic\n\n### Code Style & Formatting\n- **Formatting config**: `source/_clang-format` file contains project style rules\n- **Line length**: 160 characters maximum\n- **Indentation**: 4 spaces, no tabs\n- **Braces**: Allman style (opening brace on new line)\n- **Comments**: Avoid unnecessary comments - code should be self-documenting\n- **Vector access**: Always use `.at()` instead of `[]` for `std::vector` element access to enable bounds checking\n\n### Naming Conventions\n- **Classes**: PascalCase (`SimulationFacade`)\n- **Variables/functions**: camelCase (`calculateEnergy`)\n- **Constants**: UPPER_SNAKE_CASE (`MAX_PARTICLES`)\n- **Files**: `.h` for C++ headers, `.cuh` for CUDA headers, `.cpp/.cu` for implementation\n\n### Architecture Overview\nThe engine follows a layered architecture:\n- **Interface Layer** (`EngineInterface/`): Abstract APIs for simulation operations\n- **Implementation Layer** (`EngineImpl/`): CPU-side coordination and data management\n- **GPU Compute Layer** (`EngineGpuKernels/`): CUDA kernels for parallel simulation\n- **GUI Layer** (`Gui/`): User interface built on Dear ImGui\n\n### Testing Guidelines\n- **Test naming**: `*Tests.cpp` files, descriptive test method names\n- **Test types**: Unit tests (preferred), integration tests, performance tests\n- **GPU tests**: Require NVIDIA hardware, will fail in CI without GPU\n- **Always run**: `./EngineInterfaceTests && ./NetworkTests && ./PersisterTests` to verify core functionality\n\n### Performance & Debugging\n- **CUDA debugging**: Use `cuda-gdb` or Nsight Compute for kernel debugging\n- **Memory profiling**: Use CUDA memory checker for leak detection\n- **Build issues**: Clean vcpkg cache and rebuild dependencies if needed\n- **GPU requirements**: Compute capability 6.0+ required for all GPU functionality\n\n## External Resources\n- [Project Documentation](https://alien-project.gitbook.io/docs)\n- [Architecture Overview](https://alien-project.gitbook.io/docs/under-the-hood)\n- [NVIDIA CUDA Programming Guide](https://docs.nvidia.com/cuda/cuda-c-programming-guide/)\n- [Dear ImGui Documentation](https://github.com/ocornut/imgui)\n","category":".github","tokens":2150}]}