phyxel-gamedev

Phyxel

A voxel game engine and development application built with C++17, Vulkan, and Bullet Physics. Phyxel provides a reusable engine library (phyxel_core) for building voxel-based games, and a full-featured editor application for world building, scripting, and AI-assisted game creation.

Architecture

Phyxel follows a clean engine/editor separation:

┌──────────────────────────────────────────────────────┐
│  phyxel_core  (engine/)                              │
│  Reusable static library — the game engine           │
│                                                      │
│  Rendering (Vulkan)  ·  Physics (Bullet)  ·  Audio   │
│  Chunk System (32³)  ·  Entity Registry  ·  Camera   │
│  World Gen  ·  UI System  ·  Scripting (Python)      │
│  Story Engine  ·  Dialogue  ·  NPC Behaviors         │
│  HTTP API  ·  SQLite World Storage                   │
├──────────────────────────────────────────────────────┤
│  phyxel_editor  (editor/)                            │
│  Development application — world editing, debugging, │
│  MCP server, Python console, AI integration          │
├──────────────┬───────────────────────────────────────┤
│  Your Game   │  examples/minimal_game/               │
│  (standalone)│  Reference GameCallbacks impl          │
│  Links only  │                                       │
│  phyxel_core │                                       │
└──────────────┴───────────────────────────────────────┘

Build Target	Directory	What It Is
phyxel_core	engine/	The game engine — a reusable C++ static library
phyxel_editor	editor/	Editor/dev-tool library (Application, input, scripting, AI)
phyxel	editor/src/main.cpp	Editor executable (world building, debugging, MCP)
phyxel_minimal_game	examples/minimal_game/	Reference standalone game using GameCallbacks

Making a Game

Standalone games link only against phyxel_core and implement the GameCallbacks interface:

#include "core/GameCallbacks.h"
#include "core/EngineRuntime.h"

class MyGame : public Phyxel::Core::GameCallbacks {
    bool onInitialize(Phyxel::Core::EngineRuntime& engine) override;
    void onUpdate(Phyxel::Core::EngineRuntime& engine, float dt) override;
    void onRender(Phyxel::Core::EngineRuntime& engine) override;
    void onShutdown() override;
};

int main() {
    Phyxel::Core::EngineRuntime engine;
    Phyxel::Core::EngineConfig config;
    engine.initialize(config);
    MyGame game;
    engine.run(game);
}

Scaffold a new project: python tools/create_project.py MyGame

See docs/GameCreationGuide.md for the full workflow.

Features

Engine (phyxel_core)

• Vulkan Rendering — Instanced voxel rendering, dual pipeline (static + dynamic), face culling, shadow maps, day/night cycle
• 32³ Chunk System — Scalable world with SQLite persistence, streaming, cross-chunk occlusion
• Bullet Physics — Rigid body dynamics, ragdoll characters, physics-based entities
• Materials — 9 built-in materials (Wood, Metal, Glass, Rubber, Stone, Ice, Cork, Glow, Default) with per-face textures
• Animated Characters — 19-state FSM, animation blending, multiple character types (humanoid, spider, dragon, wolf)
• World Generation — Perlin noise, flat, mountains, caves, city, random — with multi-material terrain
• NPC System — Behaviors (idle, patrol, story-driven), interaction triggers, speech bubbles
• Dialogue System — Branching dialogue trees, typewriter effect, choice selection
• Story Engine — Story arcs, character agents, event bus, LLM integration
• Direct LLM Client — WinHTTP-based API client for Claude/OpenAI/Ollama, context-aware NPC conversations, SQLite conversation memory
• UI System — Custom menu screens (main menu, pause, HUD, inventory, settings) + ImGui overlays
• Audio — Spatial audio via miniaudio, background music playlist (Sequential/Shuffle)
• Health & Respawn — Per-entity health, death callbacks, automatic respawn with configurable delay
• Player Profile — Camera, health, spawn point, inventory persistence to SQLite
• Objectives — Priority-sorted quest/objective tracking with HUD rendering
• Inventory & Crafting — 36-slot inventory, hotbar, creative mode, JSON recipes
• Equipment & Combat — 6-slot equipment, sphere+cone attack, knockback, invulnerability
• Day/Night Cycle — Sun/ambient animation, time phases, day counter
• Behavior Trees — Composable BT framework, utility AI, perception, blackboard
• Python Scripting — Embedded interpreter via pybind11
• HTTP API — REST API on port 8090 for external tool integration