alien

# ALIEN — Repository Instructions

ALIEN is an artificial life simulation built on a 2D CUDA particle engine for soft
bodies and fluids. Mainly C++23 and CUDA, built with CMake + vcpkg (manifest mode).
An NVIDIA CUDA GPU is required for engine functionality and the engine tests.
The GUI uses Dear ImGui.

## Language

Converse in the language the user used, but **everything that is committed, pushed,
or created on GitHub must be in English**: commit messages, branch slugs, PR titles
and bodies, code comments, identifiers. Keep commit messages short and imperative.

## Code style

- 4 spaces, no tabs
- Allman braces
- camelCase for variables and functions
- PascalCase for classes
- UPPER_SNAKE_CASE for constants
- `.h` for C++ headers, `.cuh` for CUDA headers, `.cpp` / `.cu` for implementations
- Avoid unnecessary comments; prefer self-documenting code
- Prefer `.at()` over `[]` for `std::vector` access unless there is a strong local reason

## Hard rules

- Do **not** run CodeQL / `codeql_checker` / any CodeQL security scanning
- Do **not** run `git submodule update`
- `external/vcpkg` is a pinned submodule — never modify or commit it. If it shows as
  modified, restore with `git restore external/vcpkg`. Never `git add external/vcpkg`.
- Do not cancel long-running builds or tests; they can take several minutes.

## Build (Windows)

Build with the repo-root script, not the default Visual Studio generator:

```
build-windows-ninja.bat          # Release (default)
build-windows-ninja.bat Debug    # Debug
```

It sets up MSVC via vcvars64 and uses the "Ninja Multi-Config" CMake preset
(`cmake --preset ninja` + `cmake --build --preset ninja-release`), compiling the CUDA
translation units in parallel. Executables land under **`build-ninja\Release\`**
(e.g. `alien.exe`, `cli.exe`, `EngineTests.exe`) — not the older `build\Release\`.

A struct / constant-memory / kernel `.cuh` change needs a clean rebuild, otherwise
stale kernels linger and weak tests can pass against old code.

## Tests

Executables under `build-ninja\Release\`:

```
EngineInterfaceTests.exe   (<1s)
NetworkTests.exe           (<1s)
PersisterTests.exe         (~1.4s)
EngineTests.exe            (~150s — needs the GPU; do not cancel)
```

GUI-only changes under `source/Gui/` that do not touch engine, network, persistence,
CLI, or shared code do not strictly need tests, but still build. For a targeted CUDA
failure: `EngineTests.exe -d --gtest_filter=Suite.Test` (debug mode is much slower —
use it for single tests only, not the full suite).

## Formatting

The clang-format **version matters**: format with **19.1.5** (bundled with Visual
Studio 2022 Community — bare `clang-format` on PATH resolves to it). Do **not** use the
VS Insiders v22 binary — same `source/_clang-format` config, but it reflows lines
differently and creates churn. Format only the files you modified, and only if they are
already clean at HEAD:

```
clang-format --style=file:source/_clang-format --dry-run --Werror <file>
```

Several committed files are not clang-format-clean, so running a whole-file format on
them reflows unrelated lines. ColumnLimit is 160; clang-format does not always wrap long
builder-chain assignments beyond 160, and that is accepted.

## Layout

```
source/Base/                 Common utilities, math, logging
source/Cli/                  Command-line interface
source/EngineGpuKernels/     CUDA kernels
source/EngineImpl/           CPU-side engine implementation
source/EngineInterface/      Abstract simulation APIs
source/EngineInterfaceTests/ EngineInterface unit tests
source/EngineTests/          CUDA engine integration tests
source/Gui/                  Dear ImGui GUI
source/Network/              HTTP / cloud features
source/PersisterImpl/        File I/O and serialization
external/                    Third-party dependencies incl. the pinned vcpkg submodule
resources/                   Runtime assets
```

# ALIEN - Artificial Life Environment

**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.**

## Project Overview
ALIEN 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.

## Security Configuration

### CodeQL Security Checks
**DO NOT use CodeQL security checks on this repository.** The repository is too large for CodeQL analysis to complete successfully. 

- Do NOT run the `codeql_checker` tool
- Do NOT attempt any CodeQL security scanning
- Skip all security vulnerability scanning steps that involve CodeQL

### Git Submodule Configuration
**DO NOT update the vcpkg submodule in external/vcpkg.** The vcpkg version is pinned to a specific commit for stability.

- Do NOT run `git submodule update` commands
- Do NOT modify the external/vcpkg submodule pointer
- Do NOT commit changes to external/vcpkg
- If you see external/vcpkg changes in `git status`, use `git restore external/vcpkg` to discard them
- The vcpkg submodule is managed separately by repository maintainers

## Working Effectively

### Bootstrap, Build, and Test the Repository
**NEVER CANCEL long-running commands. Build may take 4-5 minutes. Use long timeouts.**

```bash
cmake --build build --config Release -j32
```

### Run Tests
```bash
cd build

# Tests
./EngineInterfaceTests  # <1 second
./NetworkTests          # <1 second
./PersisterTests        # ~1.4 seconds
./EngineTests           # >4 min

# Debug mode for EngineTests (use -d for precise kernel failure info)
./EngineTests -d --gtest_filter=TestSuite.TestName  # Much slower, use for debugging specific tests only
```

**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.

### Run the Applications
```bash
cd build

# GUI application (requires X11 display and NVIDIA GPU)
./alien

# Command-line interface (requires .sim and .settings.json files)
./cli --help
./cli -i input.sim -o output.sim -t 1000
```

## Validation

## Validation

### Build Validation
- **Build succeeds** and produces all expected executables: `alien`, `cli`, `EngineTests`, `EngineInterfaceTests`, `NetworkTests`, `PersisterTests`
- **Build time**: ~1 min on 32-core system with `-j32` parallelization
- **Clean configuration**: ~6 seconds
- **No build errors or warnings** when following the exact commands above

### Test Validation  
- **EngineInterfaceTests**: tests pass in <1 second
- **NetworkTests**: tests pass in <1 second
- **PersisterTests**: tests pass in ~1.4 seconds
- **EngineTests**: tests pass in >4 min
- Pure GUI-only changes in `source/Gui/` that do not affect engine, network, persistence, or CLI logic do **not** require running tests
- For all other changes, run `./EngineInterfaceTests && ./NetworkTests && ./PersisterTests && ./EngineTests` to verify your changes don't break core functionality
- `./EngineTests` are most important and contain the entire simulation logic written in CUDA

### Application Validation
- **CLI works**: `./cli --help` shows usage information
- **GUI requires**: NVIDIA GPU + X11 display (cannot run in headless CI environments)
- **GUI error handling**: Provides clear error messages when GPU requirements aren't met
- **Simulation files**: CLI expects `.sim` and `.settings.json` files (not included in main repo)

### Validation Workflow for Changes
```bash
# Always run this validation sequence after making code changes:

# 1. Format code (if modified)
clang-format --style=file:source/_clang-format -i path/to/modified/files.cpp

# 2. Build (NEVER CANCEL - ~ 1 minute)
cmake --build build --config Release -j32

# 3. Run core tests (required unless the change is pure GUI-only in source/Gui)
cd build && ./EngineInterfaceTests && ./NetworkTests && ./PersisterTests & ./EngineTests

# 4. Test CLI functionality
./cli --help
```

### Code Formatting
```bash
# Format code using project's clang-format config
clang-format --style=file:source/_clang-format --dry-run --Werror source/path/to/file.cpp

# Format all files (if needed)
find source -name "*.cpp" -o -name "*.h" | xargs clang-format --style=file:source/_clang-format -i
```

## Technology Stack & Requirements
- **Languages**: C++23, CUDA 20, Python (for CLI tools)
- **Build System**: CMake 3.31+, vcpkg package manager
- **GPU Computing**: NVIDIA CUDA (requires compute capability 7.5+)
- **GUI Framework**: Dear ImGui with custom widgets
- **Dependencies**: All managed via vcpkg manifest mode (`vcpkg.json`)

## Repository Structure & Navigation
- `source/`: Main C++ and CUDA source code
  - `source/Base/`: Common utilities, math, logging
  - `source/Cli/`: Command-line interface
  - `source/EngineGpuKernels/`: CUDA kernels for simulation
  - `source/EngineImpl/`: CPU-side engine implementation
  - `source/EngineInterface/`: Abstract simulation APIs
  - `source/EngineInterfaceTests/`: Unit tests for EngineInterface
  - `source/EngineTests/`: Integration tests for engine
  - `source/Gui/`: ImGui-based user interface
  - `source/Network/`: HTTP client for cloud features
  - `source/PersisterImpl/`: File I/O and serialization
  - `source/_clang-format`: Code formatting configuration
- `external/`: Third-party libraries (vcpkg submodule)
- `resources/`: Runtime assets (shaders, fonts, icons)
- `scripts/CLI-Tools/`: Python automation tools
- `vcpkg.json`: Dependency manifest for package management

## Common Development Tasks

### Command-Line Interface (CLI)
The project includes a CLI for headless simulation execution:
```bash
# Basic simulation run (requires existing .sim and .settings.json files)
./cli -i example.sim -o output.sim -t 1000

# The CLI generates three outputs:
Python automation tools are available in `scripts/CLI-Tools/`:
- `FindFortunateTimeline.py`: Automated simulation with savepoints and rollback logic

### Code Style & Formatting
- **Formatting config**: `source/_clang-format` file contains project style rules
- **Line length**: 160 characters maximum
- **Indentation**: 4 spaces, no tabs
- **Braces**: Allman style (opening brace on new line)
- **Comments**: Avoid unnecessary comments - code should be self-documenting
- **Vector access**: Always use `.at()` instead of `[]` for `std::vector` element access to enable bounds checking

### Naming Conventions
- **Classes**: PascalCase (`SimulationFacade`)
- **Variables/functions**: camelCase (`calculateEnergy`)
- **Constants**: UPPER_SNAKE_CASE (`MAX_PARTICLES`)
- **Files**: `.h` for C++ headers, `.cuh` for CUDA headers, `.cpp/.cu` for implementation

### Architecture Overview
The engine follows a layered architecture:
- **Interface Layer** (`EngineInterface/`): Abstract APIs for simulation operations
- **Implementation Layer** (`EngineImpl/`): CPU-side coordination and data management
- **GPU Compute Layer** (`EngineGpuKernels/`): CUDA kernels for parallel simulation
- **GUI Layer** (`Gui/`): User interface built on Dear ImGui

### Testing Guidelines
- **Test naming**: `*Tests.cpp` files, descriptive test method names
- **Test types**: Unit tests (preferred), integration tests, performance tests
- **GPU tests**: Require NVIDIA hardware, will fail in CI without GPU
- **Always run**: `./EngineInterfaceTests && ./NetworkTests && ./PersisterTests` to verify core functionality

### Performance & Debugging
- **CUDA debugging**: Use `cuda-gdb` or Nsight Compute for kernel debugging
- **Memory profiling**: Use CUDA memory checker for leak detection
- **Build issues**: Clean vcpkg cache and rebuild dependencies if needed
- **GPU requirements**: Compute capability 6.0+ required for all GPU functionality

## External Resources
- [Project Documentation](https://alien-project.gitbook.io/docs)
- [Architecture Overview](https://alien-project.gitbook.io/docs/under-the-hood)
- [NVIDIA CUDA Programming Guide](https://docs.nvidia.com/cuda/cuda-c-programming-guide/)
- [Dear ImGui Documentation](https://github.com/ocornut/imgui)