Skip to main content
This guide assumes you’ve already built the project. Let’s get you into the game!

​
Running the Game

1

Navigate to Build Directory

cd build
The executable and assets should all be in this directory after building.
2

Launch MC-CPP

.\MC-CPP.exe
On first launch, a startup menu will appear for adjusting music volume before entering the game.
3

Start Playing

Once in-game, the mouse will be captured for camera control. Use ESC to release the cursor.

​
Basic Controls

​
Movement

KeyAction
WMove forward
AMove left (strafe)
SMove backward
DMove right (strafe)
SpaceJump
Left ShiftSprint (increases FOV dynamically)
MouseLook around (captured mode)

​
Block Interaction

ControlAction
Left ClickBreak block (raycast targeting)
Right ClickPlace block
Mouse WheelChange selected block type
The game uses physics-based collision detection - you can walk on blocks and jump between platforms naturally.

​
World & Display

KeyAction
F3Toggle debug overlay (FPS, position, render stats)
F11Toggle fullscreen mode
OSave world to save/ directory (NBT format)
ESCRelease/capture mouse cursor

​
Understanding the Display

​
Crosshair

The white crosshair in the center indicates:
  • Your aiming point for block placement/breaking
  • The direction you’re facing
  • Raycast hit detection for block interaction

​
Debug Overlay (F3)

Press F3 to see detailed information:
  • FPS - Current frames per second
  • Position - Player coordinates (x, y, z)
  • Rotation - Camera pitch/yaw angles
  • Chunks - Visible/loaded chunk count
  • Render distance - Current setting from Options::RENDER_DISTANCE
  • Shadow info - Cascade count, resolution (if enabled)

​
World Saves

MC-CPP uses NBT (Named Binary Tag) format with gzip compression for world persistence.

​
Save Location

build/
├── MC-CPP          # Executable
├── assets/         # Shaders, textures, audio
├── data/           # Block definitions
└── save/           # World chunks (created on first save)
    └── *.dat       # Chunk files (NBT + gzip)

​
Manual Save

Press O to save all loaded chunks. The game also:
  • Saves chunks when unloading them (distance-based streaming)
  • Automatically loads nearby chunks as you move
World saves are tied to the save/ directory in your build folder. Deleting it will reset your world.

​
Performance Tuning

You can adjust settings in src/options.h (source:/home/daytona/workspace/source/src/options.h:1) before building:

​
Render Distance

inline int RENDER_DISTANCE = 8;  // Chunks (16x16x128 blocks each)
Higher values = more visible terrain but lower FPS. Recommended: 8-16.

​
Field of View

inline float FOV = 90.0f;  // Degrees
Standard FPS range is 80-110. Sprint dynamically increases FOV.

​
Chunk Updates per Frame

inline int CHUNK_UPDATES = 4;  // Subchunks per tick
Controls how many chunk meshes rebuild per frame. Lower = smoother FPS when streaming new terrain.

​
Lighting Performance

inline int LIGHT_STEPS_PER_TICK = 2048;  // BFS steps per frame
Reduces lighting calculation stutters when loading new chunks. See info.md (source:/home/daytona/workspace/source/info.md:1) for details.

​
Shadow Quality

inline bool SHADOWS_ENABLED = true;
inline int SHADOW_MAP_RESOLUTION = 2048;  // Per-cascade
inline int SHADOW_CASCADES = 4;           // 1-4 supported
Shadows use Cascaded Shadow Maps (CSM). Disable for +20-40% FPS on lower-end GPUs.
Changes to options.h require rebuilding the project:
cmake --build build --parallel

​
Troubleshooting

​
Game Won’t Launch

“Cannot find assets/”: 
# Ensure you're running from the build/ directory
cd build
./MC-CPP
“OpenGL error” or black screen:
  • Update GPU drivers
  • Verify OpenGL 3.3+ support: 
    glxinfo | grep "OpenGL version"  # Linux

​
Low FPS

  1. Reduce render distance: Edit Options::RENDER_DISTANCE to 4-6
  2. Disable shadows: Set Options::SHADOWS_ENABLED = false
  3. Lower shadow resolution: Change SHADOW_MAP_RESOLUTION to 1024
  4. Disable VSync: Set Options::VSYNC = false (may cause tearing)

​
Stuttering When Moving

This is chunk streaming overhead. The game loads/unloads chunks as you explore:
  • Already optimized: info.md documents FPS improvements from asynchronous chunk building
  • Increase CHUNK_UPDATES (faster meshing, more CPU usage)
  • Increase LIGHT_STEPS_PER_TICK (faster lighting, more CPU usage)
The game uses incremental updates (source:/home/daytona/workspace/source/info.md:14) - new chunks build gradually over several frames to maintain smooth FPS.

​
Missing Textures

Blocks appear black/magenta:
  • Check assets/textures/ exists in build directory
  • Verify data/blocks.mccpp is present
  • See AGENTS.md shadow debugging section (source:/home/daytona/workspace/source/AGENTS.md:110) for texture atlas issues

​
Advanced Features

​
Shadow System

MC-CPP implements directional shadows with cascades:
  • 4 cascades - Different resolutions for near/far objects
  • PCF filtering - Soft shadow edges (configurable radius)
  • Dynamic updates - Shadows follow sun direction (day/night cycle)
See AGENTS.md (source:/home/daytona/workspace/source/AGENTS.md:16) for technical details on the CSM implementation.

​
Lighting System

Two independent light sources:
  • Skylight - Top-down sunlight propagation
  • Block light - Emissive blocks (torches, lava, etc.)
Both use BFS queues with incremental updates for smooth performance.

​
Physics

Player movement uses:
  • Gravity with drag coefficients
  • AABB collision with swept tests
  • Dynamic acceleration (walk/sprint states)
  • Interpolated rendering for smooth motion at any FPS

​
Next Steps

Explore the Source

Check out AGENTS.md for a complete architecture overview

Modify Block Types

Edit data/blocks.mccpp to add custom blocks

Customize Shaders

Modify assets/shaders/colored_lighting/ for visual effects

Performance Profiling

Run mc_bench to identify hotspots

Build docs developers (and LLMs) love

Get started for freeTalk to us