Quick Start Guide

This guide will help you get fCavEX up and running on your Nintendo Wii or PC. Choose your platform below.

Prerequisites

Before building fCavEX, you’ll need to download several dependencies manually. These libraries are required for all platforms.

Required Dependencies

Download and place the following libraries in your source directory:

Library	Files	Destination
LodePNG	`lodepng.h` and `lodepng.c`	`source/lodepng/`
cglm	`include/cglm/`	`source/cglm/`
cNBT	`buffer.c`, `buffer.h`, `list.h`, `nbt_loading.c`, `nbt_parsing.c`, `nbt_treeops.c`, `nbt_util.c` and `nbt.h`	`source/cNBT/`
parson	`parson.h` and `parson.c`	`source/parson/`
M*LIB	any root `*.h`	compiler include path

Building for Wii

Install devkitPro

Install the devkitPro Wii/Gamecube development environment.

Install Dependencies

Use devkitPro’s package manager to install required libraries:

dkp-pacman -S wii-dev ppc-zlib

Configure Video Settings (Optional)

Edit source/graphics/gfx_settings.h to adjust graphics settings for optimal Wii performance:

// Disable clouds for better performance
// #define GFX_CLOUDS

// Use fast liquids on Wii for better FPS
// #define GFX_FANCY_LIQUIDS

// Recommended GUI scale for Wii (480p)
#define GFX_GUI_SCALE 2

You must recompile after changing video settings for them to take effect.

Build the Game

Load the cross-compiler environment and run make:

source /etc/profile.d/devkit-env.sh
make

If you use fish shell instead of bash, you’ll need to source the environment file first.

Prepare SD Card

A boot.dol file will be created in the root directory. Set up your SD card’s apps/ folder with this structure:

cavex
├── assets
│   ├── terrain.png
│   ├── items.png
│   ├── anim.png
│   ├── default.png
│   ├── gui.png
│   └── gui2.png
├── saves
│   ├── world
│   └── ...
├── boot.dol
├── config.json
├── icon.png
└── meta.xml

When building for Wii, replace config.json with config_wii.json from the source directory.

Launch on Wii

Insert your SD card into your Wii and launch fCavEX through the Homebrew Channel.

Building for PC (GNU/Linux)

The PC version runs on any system with OpenGL 2.0 support and can be played with keyboard and mouse.

Install System Dependencies

Install required libraries using your system package manager:

# Ubuntu/Debian
sudo apt-get install zlib1g-dev libglfw3-dev libglew-dev cmake gcc

# Fedora
sudo dnf install zlib-devel glfw-devel glew-devel cmake gcc

# Arch Linux
sudo pacman -S zlib glfw glew cmake gcc

Configure Video Settings (Optional)

Edit source/graphics/gfx_settings.h to set your preferred resolution and graphics options:

// Enable fancy liquids on PC
#define GFX_FANCY_LIQUIDS

// Set your preferred window size
#define GFX_PC_WINDOW_WIDTH 640
#define GFX_PC_WINDOW_HEIGHT 400

// GUI scale (2 for 640x480, adjust for your resolution)
#define GFX_GUI_SCALE 2

Build with CMake

Create a build directory and compile:

mkdir build_pc
cd build_pc
cmake ..
make

Prepare Assets

Copy the shader files from resources/ directory next to your assets/ directory.Ensure your game directory has:

assets/ folder with texture files
saves/ folder for world saves
config.json (use config.json or config_pc.json)
Shader files from resources/

Run the Game

Launch fCavEX from the build directory. The game will use the configuration from config.json.

PC Controls

The default PC keyboard and mouse controls are defined in config.json:

{
  "input": {
    "player_forward": [87],      // W key
    "player_backward": [83],     // S key
    "player_left": [65],         // A key
    "player_right": [68],        // D key
    "player_jump": [32],         // Spacebar
    "player_sneak": [340],       // Left Shift
    "item_action_left": [1000],  // Left mouse button
    "item_action_right": [1001], // Right mouse button
    "scroll_left": [49],         // 1 key
    "scroll_right": [50],        // 2 key
    "inventory": [69],           // E key
    "open_menu": [257],          // Enter key
    "screenshot": [291]          // F2 key
  }
}

Wii Controls

fCavEX supports multiple Wii controller types:

Wiimote

D-pad for movement, A/B for actions, +/- for menu navigation, Home button for pause

Nunchuk

Joystick for movement, Z/C buttons for actions and camera control

Classic Controller

Full controller support with dual joysticks and multiple action buttons

Guitar Hero 3

Yes, you can play with a guitar controller! Fret buttons and strum bar supported.

For detailed controller mapping, see the controls.md file in the source repository.

Setting Up World Saves

Create a Beta 1.7.3 World

fCavEX can load world saves created in Minecraft Beta 1.7.3. Use the original game or a world generator to create a world.

Copy World to Saves Folder

Place your world folder in the saves/ directory. Your world should contain:

level.dat
Region files in the region/ folder

Health Adjustment (Optional)

fCavEX uses 160 max health (10 hearts × 16 HP) instead of the original 20 health.

If you load a save from the original game, you’ll start with only one heart. Fix this by:

Eating food to restore health, or
Editing the health value in level.dat

This won’t be necessary once fCavEX gets its own world generator.

Launch and Play

Select your world from the world selection screen and start playing!

Performance Tips

For Wii Users

To maximize performance on Wii hardware:

Disable clouds: Comment out #define GFX_CLOUDS in gfx_settings.h
Use fast liquids: Comment out #define GFX_FANCY_LIQUIDS
Keep render distance at 5 chunks (default)
Use GUI scale 2 for 480p output

For PC Users

If you experience low FPS on PC:

Lower resolution: Reduce GFX_PC_WINDOW_WIDTH and GFX_PC_WINDOW_HEIGHT
Disable fancy liquids: Comment out #define GFX_FANCY_LIQUIDS
Adjust GUI scale: Lower values for lower resolutions (320x240 = 1, 640x480 = 2)
Ensure OpenGL 2.0+ support: Check your graphics drivers

Troubleshooting

Game Won’t Build

Verify all dependencies are installed in the correct directories
Check that you’ve sourced the devkitPro environment (Wii builds)
Ensure you have the required system libraries (PC builds)

Low FPS on Wii

Disable clouds and fancy liquids in video settings
Recompile after changing gfx_settings.h
Ensure you’re using config_wii.json as config.json

World Won’t Load

Verify the world is from Minecraft Beta 1.7.3 or earlier
Check that level.dat exists in the world folder
Ensure the saves/ path is correctly configured in config.json

Chests/Signs from CavEX Not Working

This is expected behavior. fCavEX uses an incompatible save format for chests and signs.

To fix:

Break and replace chests to enable storage
Break and replace signs to edit their text
Your items will be lost from CavEX chests; remove valuable items before converting

Next Steps

Video Settings

Learn about all available video settings and how to optimize performance

Gameplay Guide

Discover fCavEX-specific gameplay mechanics and features

Controller Configuration

Customize controls for your preferred input device

Contributing

Help improve fCavEX by contributing to the project

Getting Help

If you encounter issues not covered in this guide:

Check the CHANGES.md for known differences from CavEX
Visit the CavEX GitHub repository for the original project
Review build logs for specific error messages

Happy mining!

Getting Started

Building

Gameplay

Configuration

Quick Start Guide

Quick Start Guide

Prerequisites

Required Dependencies

Building for Wii

Building for PC (GNU/Linux)

PC Controls

Wii Controls

Wiimote

Nunchuk

Classic Controller

Guitar Hero 3

Setting Up World Saves

Performance Tips

For Wii Users

For PC Users

Troubleshooting

Game Won’t Build

Low FPS on Wii

World Won’t Load

Chests/Signs from CavEX Not Working

Next Steps

Video Settings

Gameplay Guide

Controller Configuration

Contributing

Getting Help

Build docs developers (and LLMs) love

Getting Started

Building

Gameplay

Configuration

​Quick Start Guide

​Prerequisites

​Required Dependencies

​Building for Wii

​Building for PC (GNU/Linux)

​PC Controls

​Wii Controls

Wiimote

Nunchuk

Classic Controller

Guitar Hero 3

​Setting Up World Saves

​Performance Tips

​For Wii Users

​For PC Users

​Troubleshooting

​Game Won’t Build

​Low FPS on Wii

​World Won’t Load

​Chests/Signs from CavEX Not Working

​Next Steps

Video Settings

Gameplay Guide

Controller Configuration

Contributing

​Getting Help

Build docs developers (and LLMs) love

Quick Start Guide

Prerequisites

Required Dependencies

Building for Wii

Building for PC (GNU/Linux)

PC Controls

Wii Controls

Setting Up World Saves

Performance Tips

For Wii Users

For PC Users

Troubleshooting

Game Won’t Build

Low FPS on Wii

World Won’t Load

Chests/Signs from CavEX Not Working

Next Steps

Getting Help