Home

🚀 LplPlugin — FullDive Engine

Goal: Build a real Sword Art Online (SAO) — a FullDive VR experience where the boundary between physical and virtual worlds disappears, driven by real neural signals.

LplPlugin is a high-performance, data-oriented closed-loop BCI platform written in C++23 (with C for the kernel module). It is organized as 20 independent modules built by xmake, combining a Linux kernel module for zero-copy UDP ingestion, a full ECS simulation engine, a software + Vulkan renderer, and a standalone BCI module (OpenBCI Cyton, 8ch/250Hz) that computes scientifically-grounded neural metrics in real time — feeding back into the simulation loop.

---

✨ Key Highlights

Metric	Value
Language	C++23 (-fno-rtti, -fno-exceptions)
Build System	xmake 2.9+
Modules	20 static libraries + 3 executables
Frame time	62.55 µs average (Phase 1 milestone)
Packet loss	0.00% (1000/1000)
Throughput	~495 pkt/s
Physics (50 entities)	0.055 ms/frame
BCI channels	8 ch / 250 Hz (OpenBCI Cyton)
Renderer	Software rasterizer + Vulkan backend
Unit tests	24 / 24 ✅

---

🏗️ Architecture at a Glance

[OpenBCI Cyton — 8 ch / 250 Hz] ──────────────────────────────┐
    ↓ USB serial / raw parse                              [bci/ module]
    FFT + SignalMetrics R(t) + RiemannianGeometry δ_R + D_M
    NeuralMetrics::from_state() → ECS ComponentID::NEURAL
    ↓ ─────────────────────────────────────────────────┘

UDP Packet (port 7777)                                [net/ + kernel/]
    ↓
Netfilter Hook (kernel module — NF_INET_PRE_ROUTING)
    ↓
RxRingBuffer (mmap'd LplSharedMemory, atomic head/tail)
    ↓
Network::network_consume_packets() → dispatch to WorldPartition chunks
    ↓
SystemScheduler ECS (auto DAG: RingConsume → ClientIO → Physics → Neural)
    ↓
WorldPartition::step()
    ├─ GPU path: CUDA kernel (PhysicsKernel.cu)
    └─ CPU path: physicsTick (current)
    ↓
Inter-chunk migration (backward iteration + swap-and-pop)
    ↓
swapBuffers() → atomic write↔read toggle
    ↓
Network::broadcast_state() → TxRingBuffer → ioctl kick → kernel TX thread → UDP

---

📁 Module Structure

LplPlugin/
├── core/           — Platform abstraction, types, assertions, logging
├── math/           — Vec3, Quat, Fixed32, CORDIC, BoundaryBox
├── memory/         — PinnedAllocator (CUDA zero-copy), pool allocators
├── container/      — FlatAtomicsHashMap, Morton encoding, sparse sets
├── concurrency/    — ThreadPool, SpinLock, atomic utilities
├── ecs/            — Entity registry, Partition (SoA double-buffered chunks)
├── physics/        — WorldPartition, collision (AABB, octree broadphase)
├── net/            — UDP transport (kernel driver / socket fallback), protocol
├── gpu/            — CUDA physics kernels, GPU lifecycle
├── input/          — InputManager (keys, axes, neural state per entity)
├── platform/       — Host backends (clock/display/gpu-memory/input)
├── render/         — Software + Vulkan renderer, ImGui integration
├── image/          — 2D software imaging (Surface, Painter, Codec)
├── scene/          — Scene graph (Scene, Transform2D)
├── audio/          — Spatial audio (stub)
├── haptic/         — Haptic/vestibular feedback (stub)
├── bci/            — OpenBCI driver, FFT, DSP, SignalMetrics, Riemannian, calibration
├── serial/         — State serialization & deterministic replay
├── bench/          — Benchmark harness
├── engine/         — Top-level facade aggregating all modules, game loop
├── kernel/         — Linux kernel module (lpl_kmod.c)
├── apps/           — Executables (lpl-server, lpl-client, lpl-benchmark)
└── samples/        — Example code

Each module is a static library (lpl-<name>) with include/lpl/<name>/ headers and src/ implementations.

---

📖 Wiki Contents

Project Overview

• Vision & Objectives — Ultimate goal, scientific ambition, motivation
• Philosophy & Principles — Core design principles (DOD, Zero-Copy, Server-Authoritative…)
• Architecture — Zero-copy pipeline, memory layout, double buffering, client-server protocol

Technical Reference

• Tech Stack & Build — xmake, C++23, prerequisites, build targets
• Modules — All 20 modules (core through engine)
• Architectural Decisions — ADRs with rationale and benchmarks

Status & Results

• Performance Results — Network metrics, frame timing, CPU benchmarks
• Implementation Status — Feature matrix and completion scores
• Executables — Server, client, benchmark

Planning

• Roadmap — Phases 1–5 with success criteria
• Future Ideas — RTOS, advanced physics, BCI, NeRF, server meshing…

Research

• Scientific Contributions — Proposed publications, original contributions
• Lessons Learned — Performance, kernel dev, architecture and methodology insights
• References — Inspirations, technologies, academic references