Official Gameplay Guide

⌨️

Controls

🎨

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: Press F2 for a quick save. Use ESC → Save As to create a named save. Worlds are stored in the saves/ folder.

🔊

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.

⚔️

Skills & Stats

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

⚒️

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.

💰

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.

⚡

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.

🌍

World & Biomes

Explore a vast world with unique environmental challenges and resources:

• Magic Forest: Home to glowing trees and rare magical essences.
• Volcanic: Dangerous lava flows and valuable obsidian/basalt.
• Skylands: Floating islands accessible only by advanced traversal or flight.
• Tundra / Desert: Harsh climates requiring specific gear to survive comfortably.

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.

🐾

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.

You may have up to 5 active companions at a time. When you reach the cap and tame a new animal, it is automatically stored in your 3D Disk (see below).

3D Disk — Capture & Recall

The 3D Disk is a special item that lets you capture any NPC — animal or human — and store them in your party.

• Capture: Hold a 3D Disk and right-click any non-dead NPC. The NPC becomes your companion and is stored (inDisk = true) immediately.
• Companion HUD bars (top-right) show all companions in a column. Companions stored in a Disk appear greyed-out with a [DISK] prefix.
• Deploy / Recall: Click a companion's HUD bar to toggle between deployed (active in the world) and stored (in-Disk). Only deployed companions fight and level up.
• Human companions fight alongside you when you are attacked — they automatically chase and engage your attacker.

Companion Stats

Pet Powers

World-Space Combat Moves

When companions (and hostile mobs) fight in the open world they select moves dynamically from their CombatGenome. Each move has its own body animation and particle effect:

Action Particles

• Hit sparks — 8 coloured sparks scatter from the target on each player strike, tinted to the animal's body colour.
• Attack swoosh — 5 white/amber flecks arc outward from the attacker's strike direction.
• Death burst — 16 colour-matched particles explode outward on death.
• Howl rings — 3 expanding circles rise from the howling animal.
• Foot dust — small beige puffs kick up when a mob runs fast or is Howl-buffed.
• Lunge trail — 3 amber sparks trail behind the NPC's back during a Lunge or Pounce.

🧚

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 40 distinct mob species (MobKind values 0–39). Right-click any NPC to open its context menu.

• Humanoids (Humans, Goblins, Skeletons, etc.): Options include TALK, TRADE, ATTACK, INSPECT, and BATTLE. Shops offer infinite stock — buy with coins. Each humanoid carries its own companion animal.
• Animals (passive): Options include TALK, FEED, and ATTACK. Feeding raises tameness. Tamed animals can be challenged to a battle.
• Capturing with 3D Disk: Hold a 3D Disk and right-click any NPC to capture them as a companion. Humans and animals alike can be captured. Captured NPCs are stored in the party HUD and can be deployed or recalled at any time.
• Velociraptors: Fast, hostile, spawn in jungle/tropical biomes. Raptor Hunters (rare NPCs) will pursue them.
• NPC Combat & Genetics: NPCs fight using a dynamic CombatGenome that selects from 11 distinct moves including Pounce, Spin, Howl, Bite, and Retreat. Each move has unique body animations and particle effects. Winners evolve stronger genomes over time.
• Emotes: NPCs display floating emote icons (heart, happy, angry, sleep, etc.) that bounce above their heads to communicate emotional state.
• Dialogue: NPCs have species-appropriate dialogue. Rank (Peasant–Guardian) 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.

Taming Animals

Feed an animal repeatedly to raise its tamedness toward 100. At 100 it becomes your companion (isCompanion = true) and appears in the party HUD. If your party is already at 5 active companions the new companion is automatically stored in a 3D Disk slot.

🛤️

Rail Transport

Rail blocks let you build track networks across the world. Each rail renders as a flat textured quad at ground level, showing its direction or curve.

Rail Types

Rendering

Rail blocks are non-full-cube blocks rendered as a single flat quad 1/16th of a block above the surface. The quad uses the rail's top-face atlas texture, so each direction and curve variant looks correct. Rails do not block movement — they sit on top of the block below them.

Crafting (see Recipes page)

• Rail (×6): 3×3 grid — Iron Ore / Wood / Iron Ore in each row.
• Powered Rail: Copper Wire / Wood / Copper Wire rows with Gold Ore in centre.
• Rail Bend variants: Combine 3 Rail blocks in the appropriate L-shape.

🌀

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 9 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.

🌍

World & Biomes

Worlds are procedurally generated from a seed. In multiplayer, all clients receive the server's seed via the WorldSync packet and generate the identical world.

• Magic Forest: Glowing trees, rare magical essences.
• Volcanic: Lava flows, obsidian, VolcanicRock.
• Skylands: Floating islands — requires wings or portals to reach.
• Tundra / Desert: Harsh climates with unique ores and plants.
• Jungle / Tropical: Dense vegetation, Velociraptors, coconuts, pineapples.
• Ocean: Coral, clownfish, ocean mud, underwater caves.
• Deep Caves: Large chambers carved by 3D noise at Y 8–65. Walls line with Marble Slab or Alabaster Slab.
• Ore Distribution: Ores are distributed through solid rock using 3D scatter veins. They no longer cluster exclusively on cavern walls — expect to find ore embedded throughout the rock mass at appropriate depth ranges.

World Config Sliders (Create World menu)

• Terrain Scale (0.003–0.15): Frequency of height variation.
• Height (20–200): Maximum terrain height multiplier.
• Water Level: Ocean depth.
• Erosion: Gates erosion pass intensity and cavern size.
• Ridge / Terracing / Foothills / Biome Size: Fine-tune terrain shape.

🖥️

Chunk Rendering & LOD

The world is divided into 16 × 256 × 16 block chunks. Each chunk stores up to three separate mesh objects:

• Render Distance: Default 8 chunks. The inner ring (full mesh) uses a smaller radius; the outer ring uses LOD meshes.
• Instant Block Updates: When you place or break a block, the visual update is applied immediately on the client for a responsive feel. The server then confirms the change.
• Chunk Dimensions: 16 wide × 256 tall × 16 deep. Height limit 256 is hard-coded; terrain generation respects the World Config height slider.

🖥️

Graphics & Performance

Open the Pause Menu (ESC) and click GRAPHICS to open the Graphics & Performance settings overlay.

Sliders

Quality Presets

Three preset buttons instantly configure all sliders to recommended values:

• LOW — minimum render distance, no grass, reduced fog, 0% weather FX. Best for low-end hardware.
• MEDIUM — balanced defaults suitable for most systems.
• HIGH — maximum render distance, full grass and fog, 100% weather FX.

Water Detail

Three buttons control the quality of the water surface simulation:

🌐

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)

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 342 (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.