Welcome to the API documentation for the V Engine — a commercial-grade, custom Vulkan game engine built for the third-person action-adventure title C.A.T. (CatGame).

This reference covers the public API surface across six major modules: the engine core, the game layer, the neural network inference library, the personal intelligence agent library, the Super NES devkit library, and the tooling suite. All content is generated from Doxygen-annotated source and reflects the current project version.

Modules

Engine (`engine/`)

The V Engine is a data-oriented, ECS-driven game engine targeting modern desktop platforms with explicit Vulkan 1.3 support.

Rendering — Deferred G-buffer pipeline with compute shader post-processing, bindless resources, PBR materials, and debug line rendering
Entity-Component-System — Tag-first scene composition, BaseSystem + Singleton<T> system pattern, component-as-pure-data convention
Physics — Kinematic sphere/box colliders, step-assist traversal, slope detection, impulse-based resolution
Audio — SDL3 audio system with VPak-streamed sound banks
Camera — Third-person follow camera with hover-look, orbit, and cutscene modes
Input — Context-driven input mapping (gameplay, cutscene, UI, tool) with priority-based dispatch
Scene Management — TOML-serialized scene definitions, persistent vs. transient scene flags, fade-overlay transitions
Asset Pipeline — Custom binary formats: Vmesh (geometry), Vtex (textures), Vpak (archives), Vanim (skeletal animation), Vnn (neural network weights), Vvo (vocab), Vemb (embeddings)
Job System — Lock-free work-stealing job queue for frame-parallel workload distribution
Event System — Decoupled publish/subscribe event bus with type-safe dispatch
Memory — Arena and pool allocators for zero-allocation hot paths
UI — ECS-based UI system with transforms, renderables, text labels, and z-order layering

Game (`game/`)

The game layer implements C.A.T.-specific gameplay systems on top of the engine:

Player Controller — Kinematic rolling sphere physics, step-assist, slope traversal, camera-relative movement
Cat Creator — Character creation system with plinth, backdrop, and emissive materials
Game State — Scene-phase management, save/load coordination, quest state tracking
Reinforcement Learning — Go board state, MCTS tree search, PPO training infrastructure
Compute Systems — GPU compute shader dispatch for game-specific effects

Neural Network Library (`nn/`)

A standalone inference library (libv_nn) for on-device neural network evaluation, designed for edge deployment and engine integration:

Inference Session — Full BERT-family transformer inference (embedding lookup, QKV projection, multi-head attention, FFN, layer normalization, pooling)
Math Kernels — AVX2 + FMA SIMD-optimized linear forward, GELU, layer norm, softmax, and attention with multithreaded batched GEMM
Model Lowering — Pre-computed weight pointers and buffer offsets at init time (LLVM IRTranslator pattern), zero heap allocation during inference
Buffer Allocator — Non-owning, 64-byte aligned bump allocator with O(1) reset, externally-provided pool support
Thread Pool — Persistent worker pool replacing per-call std::thread spawn for GEMM parallelization
Weight Binder — Typed tensor name resolution to model weight memory
Text Preprocessor — WordPiece tokenizer with HuggingFace-compatible token parity
SafeTensors Scanner — Hand-rolled JSON parser for safetensors header metadata
VNN Reader/Writer — Custom binary format serialization (.vnn, .vvo, .vemb)
PCA Optimizer — Power iteration + deflation for dimensionality reduction
VocabHashSet — Hash-based vocabulary lookup with cosine similarity search

Personal Intelligence Library (`pi/`)

A local, on-device LLM agent library (libv_pi) that brings personal intelligence into the engine and tools:

Agent — Multi-turn chat driver with tool registration, event streaming, and background worker thread
Provider — Pluggable LLM provider interface with llama.cpp/llama-server implementation
Tool System — Declarative tool definitions and parallel tool-call execution registry
JSON Codec & SSE Parser — Chat completion serialization and streaming response parsing
HTTP Client — Synchronous HTTP client with http+unix:// Unix-domain socket support
PiDaemon / PiServer — Singleton daemon and child-process supervisor for local inference lifecycle
PiConfig — TOML-loaded configuration for endpoints, models, workspace, and daemon paths

PI Daemon and Agent Library details

Super NES Devkit Library (`sn/`)

A device management and ROM development library (libv_snes) for the SNES Classic Mini and physical SNES cartridges:

Device Management — USB FEL-mode detection and SSH/RNDIS shell access
ROM Subsystem — Header parsing, checksum calculation, mapping detection, and ROM assembly
SFROM Converter — .sfc ↔ .sfrom conversion and copier header handling
Cartridge Database — Enhancement chip, ROM chip, and PCB specification lookup
LLVM-MOS Backend — C/C++ to WDC 65C816 machine code compilation
Devkit System — End-to-end pipeline from source to ROM to cartridge spec
TOML Configuration — config/tools/sn.toml for device, paths, tools, and build defaults

SNES Classic Devkit Library details

Tools (`tools/`)

Command-line and GUI tools for asset authoring, compilation, and verification:

Asset Importer — Multi-format asset processor (models, audio, neural networks) with VPak packaging
Asset Viewer — Interactive model and animation preview with Vulkan rendering
VPak Builder — Parallel zstd-compressed archive builder with deterministic output
Level Editor — Full-featured level editing environment with viewport rendering and entity manipulation
Tileset Editor — WYSIWYG tileset definition editor with collision shape editing
Dialogue Editor — Visual node-based editor for branching dialogue trees
VFX Studio — WYSIWYG particle effect editor with live Vulkan preview
Animus — Skeletal animation authoring and pose manipulation tool
Agentic Personas — Personality catalog generator for AI agent characterization
Edge Runner — Neural network inference benchmarking and edge deployment tool
Lean Workspace — Lean 4 formal proof workspace for mathematical foundations

Tools Overview

Architecture Principles

Data-Oriented Design

Components are pure data structures — no methods, no inheritance, no hidden logic. All behavior is implemented in systems following the BaseSystem + Singleton<T> pattern. Scenes use tag-first composition with optional naming.

Zero-Allocation Hot Paths

Inference, rendering, and gameplay update loops are designed for zero heap allocation. Arena and pool allocators provide bump-allocated memory with O(1) reset. The NN inference library accepts externally-provided buffer pools from the engine's ArenaAllocator.

SIMD-First Compute

Math kernels are written with explicit AVX2 + FMA intrinsics, with scalar fallbacks for non-AVX platforms. GEMM operations use multithreaded batched execution with configurable thread pools.

Explicit Lifecycle

No RAII for engine resources. All systems follow init() / shutdown() lifecycle protocols with constructor dependency injection (CDI) via the SystemManager IoC container.

C++20 Concepts

The codebase uses C++20 concepts extensively for constraining templates — component types, system interfaces, and allocator contracts are all concept-guarded.

Navigation

Namespaces — All public namespaces across engine, game, NN, PI, SNES, and tools
Classes — Core types, systems, components, entities, NN, PI, SNES, and tool structures
Concepts — C++20 concepts used throughout the codebase
Files — Header and implementation files organized by module

Legal Notice

This documentation describes the public API surface of the V Engine and associated libraries. Implementation details, proprietary algorithms, and internal source code are intentionally excluded from this generated website. All content is proprietary and confidential to CatGame Research.