Beetle Engine

A Vulkan 1.3 3D engine written in Zig, hand-tuned for the machine it lives on: a Wincor Nixdorf BEETLE /MIII — a retail point-of-sale box from the 2010s that now renders 3D. The engine is named after the machine. The machine is the spec.

┌─────────────────────────────────────────────┐
│  Wincor Nixdorf BEETLE /MIII  (POS chassis) │
│  Celeron G3900 · 12 GB · Quadro K620        │
│  Windows 10 IoT Enterprise LTSC             │
└─────────────────────────────────────────────┘

Status

Phase 3 complete — RGB triangle rendered through a full Vulkan graphics pipeline, screenshot-verified. Assets + vertex buffers (phase 4) is next. See PLAN.md for the full log.

The Machine

CPU	Intel Celeron G3900 — 2 cores / 2 threads, 2.8 GHz, SSE4.2 only (no AVX/AVX2/FMA — verified by cpuid at runtime; Intel's Celeron segmentation)
RAM	12 GB DDR4-2133, dual channel
GPU	NVIDIA Quadro K620 — Maxwell GM107, compute capability 5.0, 2 GB DDR3, ~29 GB/s bandwidth, Vulkan 1.3 via final Maxwell driver (582.78)
Storage	128 GB SATA SSD
OS	Windows 10 IoT Enterprise LTSC 21H2

This is a deliberately constrained target: no many-core CPU, no RT cores, no mesh shaders, no tensor cores, 2 GB of VRAM. Every design decision flows from the hardware.

Design Rules

1. Two threads. Main (simulation + render submission) and one worker (assets, physics). No job-system framework — a 2/2 CPU would spend more on coordination than work.
2. SSE4.2 is the SIMD ceiling. Don't chase AVX — the CPU doesn't have it.
3. GPU bandwidth is the wall, not FLOPS. BC-compressed textures, fp16/normalized-byte vertex attributes, meshoptimizer LODs.
4. GPU-driven rendering (compute culling → vkCmdMultiDrawIndexedIndirect, bindless via descriptor indexing) — the biggest draw-call win a 2-core CPU can buy.
5. 2 GB VRAM budget: ≤1.2 GB textures.
6. Vulkan 1.3 core features only (dynamic rendering, push descriptors, timeline semaphores) — the Maxwell feature set is frozen; the final driver is a stable target, not a moving one.
7. C dependencies only — Zig can't consume C++ directly. Every dependency must be drop-in.

Building

Requires Zig 0.16.0 on PATH. No other toolchain, no SDK, no package installs.

git clone <repo>
cd FutureIsNow
zig build            # builds zig-out\bin\engine.exe
zig build run        # build + launch
zig build test       # unit tests
.\zig-out\bin\engine.exe --selftest   # automated window/pump/input check

The engine prints its runtime findings at startup (CPU brand, feature bits, Zig version). Current build is ReleaseSafe by default; flips to ReleaseFast in the performance phase.

Roadmap

Phase	Goal	Status
0	Toolchain + skeleton + runtime hardware probe	✅
1	Win32 window, input, message pump	✅
2	Vulkan instance/device/swapchain, animated clear	✅
3	Triangle: GLSL → SPIR-V pipeline, dynamic rendering	✅
4	Assets: glTF mesh + texture, vertex buffers, normalization	✅
4.5	Lua 5.4 scripting + engine API + agent.md	✅
5	GPU-driven rendering: compute culling, indirect draws	⬜
6	Physics (C lib) on the worker thread	⬜
7	Profiling pass: Tracy + RenderDoc, ReleaseFast, 16 ms budget	⬜
8	Audio, polish, packaging	⬜

Philosophy

The fastest engine for a machine is the one that respects what the machine actually is — not what marketing wished it was. Beetle Engine probes its hardware at startup, treats the 29 GB/s VRAM bandwidth as the enemy, and treats the frozen Maxwell feature set as a stable contract. Constraints aren't the obstacle here; they're the whole point.

A beetle is small, armored, and extremely hard to kill.