Project Q Game Engine

A modular game engine implementing a BSP-based FPS using the Bevy game engine. This project follows a strict separation between engine and game logic with event-driven architecture.

Project Overview

This is a first-person shooter game engine with procedurally generated levels using BSP-based voxel generation. The engine implements:

• Extensible architecture with clear separation between engine core and game logic
• Data-oriented design following ECS (Entity-Component-System) patterns
• Event-driven communication between subsystems
• Modular rendering with separate logic and visual systems
• Physics-based player movement using Rapier physics

Project Structure

/docs/rules              # Architecture and code style guidelines
/src
  /engine                # Core engine systems
    /core                # Common utilities and configuration
    /physics             # Physics abstraction and constants
    /rendering           # Rendering systems
    /input               # Input handling
    /ui                  # UI framework (engine-level)
    /world               # World state management (placeholder)
  /game                  # Game-specific implementation
    /logic               # Gameplay systems
      /player            # Player movement and controls
      /enemy             # Enemy AI and behavior
      /combat            # Combat mechanics
      /state             # Game state tracking
    /content             # Game content and data
      /level             # Level generation and BSP logic
    /rendering           # Game-specific visual systems
      /level             # Level mesh and lighting generation
      /enemy             # Enemy visual representation
    /ui                  # Game UI and HUD
  /main.rs               # Application entry point

Requirements / Dependencies

Runtime Dependencies

• Rust: 1.70+ (latest stable recommended)
• Bevy: 0.15
• bevy_rapier3d: 0.28 (physics engine)
• rand: 0.8 (procedural generation)

System Requirements

• Operating System: macOS, Linux, or Windows
• Graphics: OpenGL 3.3+ or Vulkan support

Installing Dependencies

# All Rust dependencies are managed via Cargo
cargo build

Getting Started / Setup

1. Clone the repository:

   git clone <repository-url>
   cd q

2. Build the project:

   cargo build

3. Run in development mode:

   cargo run 2>&1 | tee game.log

Build / Compilation

Development Build

cargo build

Release Build (optimized)

cargo build --release

Build artifacts are located in target/debug/ or target/release/.

Running the Project

Development Mode

cargo run

Release Mode

cargo run --release

Controls

• WASD: Movement
• Space: Jump
• Shift: Run
• Mouse: Look around
• Left Click: Shoot

Development Guide

Running Tests

cargo test

Code Quality Tools

# Check code without building
cargo check

# Format code
cargo fmt

# Run linter
cargo clippy

Code Style

• All code, comments, and identifiers must be in English
• Follow Rust naming conventions (snake_case for functions, PascalCase for types)
• Every module must have a top-level documentation block
• All public functions must have documentation comments
• See docs/rules/code-style.md for detailed guidelines

Debugging and Profiling

• F3: Toggle on-screen debug HUD (FPS, Frame Time, Entity Count, Memory)
• F4: Toggle performance recording to performance_log.csv
• Game Logs: Warnings, errors, and custom info are written to debug_log.txt

The engine includes a built-in profiler that tracks:

• Frame times and FPS with spike detection
• Memory usage (RSS)
• Entity and chunk counts
• Custom system timing

To use the logger from any system:

use crate::engine::debug::plugin::{GameLogEvent, LogLevel, log_debug};

fn my_system(mut log_writer: EventWriter<GameLogEvent>) {
    log_debug(&mut log_writer, LogLevel::Info, "System initialized");
}

Architecture Guidelines

• Engine modules must never depend on game modules
• Separate logic (data/physics) from rendering (visuals)
• Use events for cross-system communication
• See docs/rules/engine-architecture.md for complete guidelines

Configuration & Environment

No environment variables required for basic operation. The game uses default window settings:

• Window Title: "Project Q"
• Resolution: 1280x720
• Resizable: Yes

Game constants can be configured in src/game/constants.rs.

Testing

Unit Tests

cargo test

Tests are located alongside source files using Rust's built-in test framework.

Manual Testing

1. Run the game: cargo run
2. Verify player movement and camera controls
3. Check level generation (new level on each run)
4. Test enemy AI and combat mechanics

Module Organization

Engine Modules

• physics: Contains physics constants, components, systems, and Rapier integration
• rendering: Camera and rendering abstractions (game-agnostic)
• input: Input handling abstractions
• ui: Engine-level UI framework
• world: World state management (currently minimal)

Game Modules

• logic: All gameplay systems (player, enemy, combat, state)
• content: Game content generation (levels, BSP terrain)
• rendering: Game-specific visual systems (level meshes, enemy visuals)
• ui: Game HUD and menus

Architecture Highlights

Separation of Logic and Rendering

Level and enemy systems are split into:

• Logic plugins: Handle entity spawning, physics, and gameplay
• Rendering plugins: Generate meshes and visual effects

Dependency Flow

• Engine never imports from game
• Physics constants live in engine/physics/constants
• Game logic depends on engine, not vice versa

Event-Driven Design

Systems communicate via Bevy's ECS event system rather than direct coupling.

Known Issues / Limitations

• World module is currently a placeholder
• No networking support yet
• Limited error handling in level generation

License

(License information to be added)

Contact / Maintainers

(Contact information to be added)