Skip to content

QUICK_START.md

Latest commit

 

History

History
256 lines (208 loc) · 6.83 KB

QUICK_START.md

File metadata and controls

256 lines (208 loc) · 6.83 KB
Raw

Quick Start Guide - Metatopia Game Engine

Prerequisites

1. Install Rust

If you don't have Rust installed, get it from rustup.rs:

macOS/Linux:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Windows: Download and run the installer from rustup.rs

After installation, restart your terminal and verify:

rustc --version
cargo --version

2. Install Build Dependencies

macOS:

# Install Xcode Command Line Tools (if not already installed)
xcode-select --install

Linux (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install build-essential pkg-config libx11-dev libxi-dev libgl1-mesa-dev

Windows:

Running the Examples

1. Clone and Enter the Project

git clone https://github.com/Metatopia-Dev/metatopia-game-engine.git
cd metatopia-game-engine

2. Build the Project

First, build all dependencies and the engine:

cargo build --release

Note: The first build will take a few minutes as it downloads and compiles all dependencies.

3. Run the Examples

Option A: Quickstart Template (Easiest!)

Create and collect cubes — the simplest way to see the engine in action:

cargo run --example my_first_game --release

Controls:

  • WASD - Move
  • Mouse - Look around
  • Walk over cubes to collect them
  • ESC - Quit

Option B: Basic Non-Euclidean Demo

Experience portals and different geometries:

cargo run --example basic_game --release

Controls:

  • WASD - Move around
  • Mouse - Look around
  • Space - Move up
  • Shift - Move down
  • R - Reset to Euclidean origin
  • Walk through glowing portals to transition between Euclidean, Hyperbolic, and Spherical spaces
  • ESC - Quit

Option C: Pest Control Simulator

Play as an exterminator in Euclidean space:

cargo run --example pest_control_sim --release

Option D: Metatopia Studio (3D Editor & Rhai Scripting)

Build scenes and write live scripts directly in the engine:

cargo run --example metatopia_editor --release

Controls:

  • WASD + Mouse - Fly camera
  • Space - Toggle Play / Edit simulation modes
  • Tab - Cycle selected entity
  • 1..5 - Spawn Cube, Sphere, Cylinder, Torus, Capsule
  • G - Cycle Rhai script presets (Pulsing Glow, Hover & Bob, Color Shift, Orbit)
  • R - Recompile and live hot-reload all scripts
  • Arrow Keys / PgUp / PgDown - Move selected object
  • Q / E - Rotate selected object
  • X - Delete selected object

Controls:

  • WASD - Move
  • Mouse - Look/Aim
  • Left Click - Use tool (Spray Bottle / Vacuum Gun)
  • 1-2 - Switch tools (1: Spray Bottle, 2: Vacuum Gun)
  • R - Reload all tools
  • Space - Move up
  • Shift - Move down
  • ESC - Quit

Option D: CYBERSHOCK: Neon Grid Arena (3D Cyberpunk FPS)

Action-packed sci-fi arena shooter with 3 weapons, enemy waves, boss battles, powerups, dash boost, and synthwave audio:

cargo run --example cyber_arena_fps --release

Controls:

  • WASD - Move
  • Mouse - Aim & Look
  • Left Click - Fire active weapon
  • 1 / 2 / 3 or Q - Switch weapons (1: Plasma Rifle, 2: Scatter Cannon, 3: Heavy Railgun)
  • R - Reload
  • Shift - Cyber Dash / Boost
  • Space - Jump
  • Enter - Restart game after Game Over / Victory
  • ESC - Quit

Option E: VR Netflix in Hyperbolic Space

Infinite movie theaters without overlap:

cargo run --example vr_netflix_hyperbolic --release

Controls:

  • WASD - Move
  • Mouse - Look around
  • 1-5 - Switch theater space:
    • 1: Hyperbolic Lobby (Poincaré disk floor)
    • 2: Spherical Dome (Starfield dome)
    • 3: Escher Theater (Staircase screens)
    • 4: Personal Pocket (Cozy curved room)
    • 5: Social Hub (Shared space)
  • Tab - Cycle selected screen
  • Left Click - Play/Pause selected screen
  • Space - Move up
  • Shift - Move down
  • R - Reset view
  • +/- - Ambient brightness
  • ESC - Quit

Option F: Mandelbulb Fractal Explorer

Real-time 3D fractal rendered via GPU ray marching:

cargo run --example fractal_explorer --release

Controls:

  • Mouse Drag - Orbit camera
  • Scroll / +/- - Zoom in/out / Change iterations
  • 1-5 - Color palette (1: Fire, 2: Ocean, 3: Nebula, 4: Earth, 5: Monochrome)
  • P / O - Increase / Decrease fractal power
  • A - Toggle audio-reactive mode
  • R - Reset view
  • ESC - Quit

Option G: Basic Graphics

Minimal WGPU rendering setup demonstrating the engine's shader pipeline:

cargo run --example basic_graphics --release

Option H: Simple Demo

Console-based demonstration of the manifold, ECS, and portal systems without GPU rendering:

cargo run --example simple_demo --release

Troubleshooting

If you get "command not found: cargo"

Make sure Rust is in your PATH:

source $HOME/.cargo/env

If you get graphics/GPU errors

The engine requires a GPU with Vulkan, Metal (macOS), or DirectX 12 (Windows) support. Update your graphics drivers:

If the build fails with "package not found"

Update your Cargo index:

cargo update

If you get linking errors on Linux

Install additional libraries:

sudo apt-get install libudev-dev libwayland-dev libxkbcommon-dev

Performance Issues

If the examples run slowly:

  1. Make sure you're using --release flag (optimized build)
  2. Close other GPU-intensive applications
  3. Reduce window size in the EngineConfig

Development Mode

For faster compilation during development (but slower runtime):

cargo run --example basic_game

To see detailed logging:

RUST_LOG=debug cargo run --example basic_game

Next Steps

  1. New to game dev? Read the Game Developer's Guide for a step-by-step tutorial
  2. Start with my_first_game.rs — it's ~130 lines and uses the zero-boilerplate quickstart module
  3. Explore the code: Check out the examples in examples/ directory
  4. Read the docs: See README.md for architecture details
  5. Create your own: Copy my_first_game.rs, rename it, and start building!

System Requirements

  • OS: Windows 10+, macOS 10.15+, or Linux (Ubuntu 20.04+)
  • CPU: Dual-core 2.5GHz or better
  • RAM: 4GB minimum, 8GB recommended
  • GPU: Vulkan 1.2, Metal, or DirectX 12 compatible
  • Disk: 2GB free space for build artifacts

Quick Test

To quickly verify everything works, run the engine's test suite:

cargo test

This runs 80+ unit, integration, and doc-tests without launching graphics.

Need help? Check the README.md for more details or create an issue on GitHub!