Official Gameplay Guide

⌨️

Controls

🖥️

UI Systems

VoxelGame features over 20 different UI panels and interfaces for managing your adventure.

Main UI Elements

Cursor System

The game features a dynamic cursor system that changes based on context:

🎨

Creative Mode

Creative Mode gives you unlimited access to all blocks and items. There is no fall damage or hunger in creative mode.

Opening Creative Inventory

Press I to open the Creative Inventory. It has two tabs: Blocks and Items. Use the scroll wheel to browse, or click the UP/DOWN arrow buttons on the right side.

Creative Keyboard Gates

While the creative inventory is open, most game keys are blocked to prevent accidental actions. Only F3 and F11 work through the overlay.

Flight in Creative

• Double-tap Space to toggle fly mode.
• Hold Space to ascend; hold L-Shift to descend.
• Sprint (L-Ctrl) while flying doubles horizontal speed.

Wings (Survival)

Craft or find Wings and equip them in the Back slot of the Equipment panel. In survival mode:

• Space flaps — tap rapidly for lift.
• Glide by holding Space without flapping.
• Pitch down to convert altitude to speed.

🚀

Getting Started

In VoxelGame, you are dropped into a procedural world filled with diverse biomes and resources. At world origin you'll find the Parthenon — a marble temple inhabited by 10 Human NPCs who can trade and talk.

Companion Picker (New Game)

When starting a fresh game the Companion Picker screen appears first. Choose one of six animal companions that will travel with you for the rest of the playthrough:

Your chosen companion appears in your world immediately as a tamed animal NPC with isCompanion = true. It gains XP, levels up, and learns new powers over time (see Companion Animals).

• Health & Mana: Watch your HP (red) and Mana (blue) HUD bars. HP regenerates slowly out of combat.
• Crosshair: The center reticle is a black cube-corners style — only the four corner marks of a square are drawn, with no center lines. This gives a clean unobstructed view of the block face you are targeting.
• Interacting: Press E or right-click to open chests, furnaces, NPC shops, and pick up Handycams.
• Building: Select a block in your hotbar, right-click to place, left-click to break. Blocks break instantly on the client for responsive feel.
• Crafting Table: Right-click a Crafting Table to open the 3×3 grid. See the Blocks & Recipes guide for all recipes.
• Save/Load: Use ESC → Save to save your world (Save As for a named save). Worlds are stored in the saves/ folder. F2 opens the Skin Editor, not a quick save.

🔊

Sound Settings

Open the Pause Menu (ESC) and click SOUND to open the Sound Settings overlay.

Close the sound overlay by pressing ESC (closes overlay first, then pause menu) or clicking the [X] button.

🎨

Graphics Settings

Open the Pause Menu (ESC) and click GRAPHICS to access the Graphics Settings panel. The panel is split into two columns to fit on 720p displays.

Performance Presets

Quick configuration buttons at the top:

• LOW — 4 chunk render distance, minimal effects
• MEDIUM — 8 chunk render distance, balanced quality
• HIGH — 13+ chunk render distance, all effects enabled

Display Settings (Left Column)

Quality Settings (Right Column)

⚔️

Skills & Stats

VoxelGame features an OSRS-inspired skill system. Performing actions earns you XP, which increases your level in specific disciplines.

🧱

Blocks & Building

VoxelGame features 505 unique block types across 14+ categories for building, crafting, and automation.

Natural Terrain Blocks

• Stone, Dirt, Grass — Basic terrain blocks
• Sand variants — Regular, Red Sand, Tropical Sand
• Snow, Ice, IceSheet — Winter biome blocks
• Gravel, Clay, Terracotta — Sediment blocks
• Biome stones — Canyon Rock, Mountain Rock, Volcanic Rock
• Wetland blocks — Swamp Mud, Ocean Mud
• Skyland blocks — Skyland Stone, Skyland Grass (floating islands)

Wood & Planks (16 Wood Types)

Each wood type has corresponding planks and mossy variants:

• Oak, Birch, Cherry, Dark Oak, Spruce, Maple, Palm, Redwood
• Willow, Magic, Dead, Fir, Jungle
• Mossy variants for 9 wood types

Ores, Metals & Gems

Gem Ores: Diamond, Emerald, Ruby, Sapphire, Amethyst (clusters), Opal, Topaz

Decorative Blocks

• Wool — 16 colors (White through Brown)
• Glass — Regular and Clear variants
• Marble — 6 colors with Pillar and Decor variants
• Alabaster — Block, Pillar, and Slab variants
• Coral — 7 colors including Clownfish
• Crystals — 5 colors plus Crystal Wall

Functional Blocks

• Crafting stations: Crafting Table, Furnace, Anvil, Cauldron, Spell Forge
• Storage: Chest (27 slots), Shop Chest, Guild Chest, Shared Chest, Bank, Display Case
• Utilities: Bookshelf, Bed, Campfire, Torch, Lamp, Scaffolding, Ladder
• Furniture: Chair, Table, Fence, Door

Circuitry & Automation (20+ Blocks)

• Signal: Copper Wire, Copper Wire Lit, Vacuum Tube, Mechanical Relay, Wireless Transmitter
• Input: Lever, Button, Trigger Block, Pressure Plate
• Output: Copper Lamp, Copper Torch, Computer Block, Script Terminal, Television
• Peripherals: Camera Block, Handycam Block, CineCam Block, Zip Folder Block, Satellite Receiver
• Special: Arcade Cabinet, Game Cartridge, Server Rack (+1 oracle signal), Satellite Uplink (+3 oracle signal)

Special & Portal Blocks

• Teleportation: Portal A/B, Warp Portal A/B, Gateway Block
• Movement: Hover Block (anti-gravity), Jump Pad, Jet Pad, Surf Ramp, Rail types
• Dungeon: Portcullis, Iron Bars, Pressure Plate variants, Dungeon Brick
• Interactive: TNT, Billboard, Sign, Action Block, Oracle Terminal, Exhibit Diorama, Grave Marker, Home Deed

Crops & Farming

• Farm Land — Tilled soil for planting
• Grains: Wheat (4 stages)
• Vegetables: Carrot (3 stages), Potato (3 stages), Pumpkin
• Fruits: Strawberry, Pineapple, Coconut
• Berries: Raspberry Bush, Blueberry Bush

Underground Cavern Biome Blocks

• Crystal Caverns: Amethyst Cluster
• Mushroom Grotto: Giant Mushroom Cap, Giant Mushroom Stem, Bio Moss
• Lava Tubes: Obsidian Spike
• Underground Fortress: Fortress Wall, Pillar, Decor variants

⚒️

Gathering & Crafting

Resource Processing

• Furnace: Smelt ores into bars. Requires fuel (Coal, Wood).
• Anvil: Use bars to forge weapons, tools, and armor. Higher Forging level increases item quality.
• Cauldron: Brew potions using herbs and chemicals discovered in the world.

Survival Skills

Fishing and Cooking are essential for maintaining your health. Rare fish can be found in different biomes, providing unique buffs when cooked.

🎒

Items & Equipment

VoxelGame features 100+ unique items across multiple categories for combat, crafting, and utility.

Equipment Tiers

Gear comes in 6 tiers, each with progressively better stats:

Weapons & Tools

• Swords — 6 tiers (Stone through Runite)
• Pickaxes — 6 tiers for mining
• Axes — 6 tiers for woodcutting
• Shovels — 6 tiers for digging
• Bows & Arrows — Ranged combat
• Hammers — 7 forging quality tiers (Generic through Mythic)

Armor Sets

• Helmets — 5 tiers (Iron through Runite)
• Chestplates — 5 tiers
• Leggings — 5 tiers
• Boots — 5 tiers with special imbues
• Gloves — Regular and Thief Gloves (for pickpocketing)

Wands & Magic

• Magic Wand — Basic spell casting
• NPC Wand — NPC dialogue editing
• Weather Wand — Cycle weather in biome
• Tornado Wand — Spawn tornado at target
• Shop Wand — Edit shop chest prices
• Gem Wands — 4 tiers with gem sockets (1-4 sockets)

Gems (Imbue Reagents)

Herbs & Potions

• 8 Herb types: Ironcap, Snakeweed, Toadstool, Sunbloom, Frostleaf, Bloodmoss, Moonpetal, Venomspike
• 8 Brewed Potions: Strength, Speed, Poison, Antipoison, Fire, Regen, Ranged, Reflect

Consumables

• Health & Mana Potions — Restoration items
• Food: Cooked Meat, Cooked Fish, Carrot, Mushroom, Potato
• Enchantment Scroll — Item enchantment

Materials

• Ingots: Iron, Copper, Gold, Mithril, Adamantite, Runite
• Boss drops: Dragon Hide, Fossil Scale, Ancient Heartwood, Kraken Ink, Frost Crystal
• Coal Lump — Fuel and crafting

Tools & Utility

• Chisel — Block shaping
• Fishing Rod — Catch fish
• Hoe — Till soil for farming
• Paintbrush — Cycle block color variants
• Spyglass — Observe distant animals for XP
• Bucket / Water Bucket — Liquid transport
• Torch / Lantern — Light sources (lantern equipable in off-hand)
• Flute / Kazoo — Musical instruments
• Rubber Chicken — Right-click Guard for confused emote
• Storage Cartridge — Store ScriptVM programs
• Memory Capture Tool — Snapshot NPC positions for diorama
• Map Fragment / Treasure Map — 4 fragments combine to mark buried chest

Special Items

• Wings — Back slot equipment for flight
• Runner Hat — Sonic-style speed/featherfall/air-dash
• Power Hat — Kirby-style gem power copying
• Auto Surfboard — Battery-powered vehicle (WASD control, E to mount)

💰

Economy & Banking

The game features a robust economic system involving physical Gold Coins and digital BTC.

• Bank: Located in major hubs, the Bank allows you to store gold in a secure vault and exchange it for BTC.
• Shop Chests: Players can set up their own shops by placing a Shop Chest, setting prices, and stocking items.
• Grand Exchange: A global marketplace for trading items with other players for gold.

🏰

Guild System

Form or join guilds to collaborate with other players, share resources, and build colonies together.

Guild Features

• Guild Creation: Create your own guild with custom name and recruit members
• Guild HQ: Establish a headquarters with special guild furniture and decorations
• Guild Chest: Shared storage accessible by all guild members
• Colony Statistics: Track guild progress, member contributions, and achievements
• Guild Panel: Manage membership, view stats, coordinate activities

Co-op Features

• Shared Chest: Party-based shared storage for co-op play
• Display Case: Auto-filled by guild chest for showcasing items
• Guild Bank: Shared coin storage for guild expenses

⚡

Circuitry & Automation

Use Copper Wire to transmit signals between components. This allows for complex logic gates, automation, and security systems.

• Input: Buttons, Levers, and Trigger Blocks (pressure plates).
• Output: Copper Lamps, Alarms, and Mechanical Actuators.
• Logic: Computer Blocks can be programmed to handle complex logic via a terminal interface.
• Surveillance: Set up Camera Blocks and view their feeds through a Handycam or Computer Monitor.

🌤️

Weather & Seasons

Weather System

The game features a dynamic weather system with 7 weather types that affect gameplay and atmosphere:

• Clear — Sunny skies, no precipitation
• Cloudy — Overcast, reduced visibility
• Rainy — Rain particles, wet surfaces
• Stormy — Lightning, thunder, heavy rain (required for tornado spawning)
• Snowy — Snow particles, ground accumulation
• Blizzard — Heavy snow, reduced visibility, wind effects
• Sandstorm — Desert weather, reduced visibility

Weather can be controlled with the Weather Wand or changes naturally over time. Weather intensity is adjustable in Graphics Settings (Weather FX slider: 0-100%).

Season System

Four seasons cycle throughout the year, each with unique characteristics:

• Spring — Increased crop growth, flower spawning
• Summer — Faster movement speed, extended daylight
• Autumn/Fall — Leaf color changes, harvest bonuses
• Winter — Snow accumulation, frozen water, special winter mobs

Seasons affect mob spawning, crop growth rates, and ambient colors. Winter enables snow accumulation on blocks and frozen water surfaces.

🌍

World & Biomes

Explore a vast procedural world with 24 unique biomes, each with distinct terrain, resources, and challenges.

Surface Biomes

Underground Cavern Biomes

Deep underground features unique cavern systems:

• Crystal Caverns: Amethyst clusters, geodes, glowing crystals
• Mushroom Grotto: Giant mushrooms, bio moss, spore particles
• Lava Tubes: Obsidian spikes, flowing lava, fire mobs
• Underground Fortress: Ancient brick structures, dungeons, loot chests
• Catacombs: Dungeon brick corridors, traps, undead mobs

Navigation & Waypoints

Never get lost! The Navi system allows you to set custom waypoints in the world. Use the minimap in the top-right corner to see your coordinates and current biome. Waypoints will appear as icons on your HUD, guiding you back to base or important discoveries. See also the Navi Companion (Fairy) section for the interactive guide character.

World Generation

• Procedural terrain: Unique world every seed
• Custom seed input: Enter custom seeds for specific world types
• Parthenon spawn: Marble temple at world origin with 10 Human NPCs
• Structure spawning: Dungeons, fortresses, villages, temples
• Ore distribution: Realistic ore veins at appropriate depths
• Fluid dynamics: Water and lava flow physics

🐾

Companion Animals

Every Human NPC in the world spawns with its own companion animal — a tamed beast stored in the NPC's companionAnimalKind field. Your own companion (chosen at game start) is a special NPC with isCompanion = true.

Companion Stats

Pet Powers

🧚

Navi Companion (Fairy Guide)

Navi is your fairy guide — a small glowing companion that assists you throughout the world. She has four distinct wing lobes in an MSN butterfly style that flap continuously while she flies. Her body emits a gentle trail of white pixel dust particles in varied sizes.

Behavior

• Idle: When no target is nearby, Navi hovers in the top-right corner of the screen in a small bobbing loop.
• Engaging: When an NPC or point of interest comes into range, Navi flies out from her idle position with a bouncy, fluttery movement pattern to engage the target.
• Wing animation: Four lobes flap with an offset phase per lobe, giving a natural butterfly-like motion.
• Particle dust: White pixel particles of varied sizes drift downward and fade from her position at all times.

⚔️

Pet Battle System

Right-click any Human NPC and select BATTLE to initiate a pet battle. Your companion faces the NPC's companion in a turn-based arena. The battle screen replaces the main view while active.

Battle Screen Layout

• 3D Previews: Both companions are rendered as live 3D models that orbit slowly (g_battleOrbitAngle). Hovering over a preview shows a stat card with ATK, LVL, SPD, and BOND values.
• HP Bars: Player companion on the left, enemy companion on the right. Each bar shows current/max HP.
• Move Buttons: One button per known power. Click a move to execute the player's turn; the enemy AI selects its move simultaneously.
• XP & Level: After a battle victory, your companion gains XP. On level-up the companion's stats increase and may learn a new power.

Synthesized Battle NPCs

When a battle opens, the engine synthesizes two temporary NPC objects (g_battlePlayerAnimalNPC and g_battleEnemyAnimalNPC) from the companions' stat blocks. The flag g_battleUseAnimalNPCs tells the renderer to draw these instead of the regular world NPCs. This means the battle previews always show the correct species mesh at the correct level.

Battle Outcome

• Win: Enemy NPC loses its companion permanently for this session. Your companion gains XP.
• Lose: Your companion's tameness decreases slightly. No permanent stat loss.
• Flee: Either side can flee. Fleeing costs the fleeing side a small tameness penalty.

💎

Gem & Food Feeding

Right-click your companion animal (or any tamed NPC) and select FEED while holding a gem or food item to grant permanent upgrades.

Gem Effects (Feed to Companion)

Food Effects (Feed to Companion)

Gems are consumed on use. Food items are also consumed. Gems can also be socketed into Gem Wands at an Anvil for combat imbues — see the Gems reference.

🌾

Farming

VoxelGame features a full crop-farming system. Till dirt or grass blocks with a hoe to create FarmLand, then plant seeds nearby water to grow crops through multiple growth stages.

Crop Types

Farming Steps

• Equip a hoe and right-click a Dirt or Grass block to till it into FarmLand.
• Place seeds (wheat, carrot, or potato) on FarmLand. The FarmLand must be within 4 blocks of a water source.
• Crops grow through their stages automatically over time.
• Left-click a mature crop to harvest it. Harvesting replaces it with the initial growth stage so the plot can be replanted.

Other New Blocks

⚔️

Combat & Knockback

VoxelGame uses a real-time melee and ranged combat system with physics-based knockback.

Melee Hits

• Left-click an NPC with a weapon equipped to deal melee damage.
• On hit, the NPC receives a horizontal velocity impulse (velX/velZ) pushing it away from the player — this is knockback.
• Simultaneously, globals g_npcHitPushX and g_npcHitPushZ accumulate a reactive push applied to the player's camera position, simulating the impact recoil. This push decays each frame.

NPC Ranks

NPCs have a rank from Peasant (0) to Guardian (6). Higher ranks scale HP and damage via the rankStats() function. Rank is shown in the INSPECT menu.

Dragon Taming

Dragons spawn in the world in Wild state. Cage them with Dragon Cage blocks to transition to Caged. When freed, a Freed dragon follows the player and breathes fire at enemies automatically.

👥

NPCs & Mobs

The game features 66+ distinct mob species (MobKind enum, include/NPC.h) with genetic algorithm-driven AI. Right-click any NPC to open its context menu.

Mob Categories

NPC Features

• Combat Genetics: NPCs fight each other. Winners gain stat improvements stored in their CombatGenome — a blockchain-tracked record of lineage and wins.
• Dialogue System: Species-appropriate dialogue with 11 NPC roles (Herder, Hunter, Guild Builder, Mentor, Tourist, Spy, Guard, etc.).
• Rank System: Peasant → Guardian rank affects HP, damage, and trade prices.
• Companion Animals: Every Human NPC spawns with a companion animal (hasCompanionAnimal = true). Defeating it in battle removes it for the session.
• Schedules: NPCs have daily routines — working, resting, wandering.
• Quest Givers: Some NPCs offer quests with multi-step objectives.

Boss Mobs

Legendary bosses drop rare crafting materials:

• Sand Colossus → Fossil Scale
• Ancient Treant → Ancient Heartwood
• Kraken → Kraken Ink
• Frost Wyrm → Frost Crystal
• Dragon → Dragon Hide

🌀

Portals & Gateways

Portal A / Portal B

Place two Portal A blocks (or two Portal B blocks) anywhere in the world — they automatically pair. Walk through to teleport between them (2-second cooldown). Velocity is zeroed on exit.

Warp Portal A / Warp Portal B

Like regular portals but preserve your entry velocity — great for launch ramps. Pair two Warp Portal A blocks (or B blocks) together.

Gateway Block

Two-stage interaction: right-click to charge, then right-click again to enter. Each Gateway generates a unique pocket dimension on first entry. Eight biome themes are available. A Return Crystal spawns at the pocket gateway position to bring you back. Cooldown: 2.5 seconds.

⚡

Circuitry & Automation

Use Copper Wire to transmit signals between components. Right-click a Computer Block to open a terminal.

• Inputs: Buttons, Levers, Trigger Blocks (pressure plates).
• Outputs: Copper Lamps, Alarms.
• Zip Folder: Adjacent block file archive. Terminal commands: zip list|add|extract|rm
• Satellite Receiver: Wired to a computer, extends network BFS range to 5000 blocks.
• Handycam: Press E to pick up, again to throw. Records 10 FPS. Commands: handycam list|<ip> start|stop|status|clear|play
• Cinema Camera (CineCam): Left-click to break and launch a drone; ESC to land. Encodes an MP4 clip via ffmpeg and registers it in the linked computer's filesystem.
• Shop Chest: Owner fills 27 slots with prices; buyers purchase items with BTC. Commands: shop list|buy <slot>
• Blockchain / Wallet: Commands: wallet new|show|set|import|export|list, balance, send <addr> <amt>, startminer / stopminer, lottery create|list|buy
• Action Block: Runs a custom script when a player walks over or interacts with it.

🌐

Multiplayer

VoxelGame uses ENet for low-latency peer-to-peer networking. One player hosts, others join via IP.

Hosting a Server

1. From the main menu, choose Host.
2. The server listens on port 25565 by default.
3. Your world seed and config are sent automatically to joining clients.
4. As the host you have Owner role — access the admin console with F3.

Joining a Server

1. Choose Join, enter the server IP and port.
2. You will receive a WorldSync packet containing the server's seed — your client generates the exact same world.
3. Other players appear as rendered characters with a distinct skin tint.
4. Press F1 to open the player roster.

Admin Console Commands (F3)

Everyone Commands

Available to all players regardless of role.

Moderator+ Commands

Admin+ Commands

Debug / World Commands

Unrestricted in code today, but intended for admin/testing use.

Roles

Roles in ascending order: Banned < Player < Member < Moderator < Admin < Owner. Roles are persisted in saves/roles.json.

🔧

Modding

VoxelGame supports native C++ mods via a C ABI plugin system. Mods are .so (Linux) or .dll (Windows) files placed in ~/.config/VoxelGame/mods/ or ./mods/.

• Mods can register new block types starting at ID 505 (BlockType::COUNT).
• Implement extern "C" void mod_init(ModAPI*) to register blocks and event handlers.
• Event hooks: onBlockPlaced, onBlockBroken, onPlayerDamage, onUpdate, onItemUsed, onChatMessage.
• Custom computer terminal commands can be registered via api->registerCommand().
• Helper callbacks: getBlock, setBlock, spawnHologram, logMsg.

See the full Modding Guide for the complete C ABI reference.