Skip to main content
Mars-RS is built with Rust and compiled to WebAssembly for browser-based execution. This guide will walk you through setting up your development environment.

​
System Requirements

Operating System

Linux, macOS, or Windows with WSL2

Memory

Minimum 4GB RAM (8GB recommended)

Storage

At least 2GB free disk space

Browser

Modern browser with WebAssembly support

​
Installing Rust

1

Install rustup

The Rust toolchain manager rustup is the recommended way to install Rust.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
After installation, restart your terminal or run:
source $HOME/.cargo/env
2

Verify installation

Check that Rust is properly installed:
rustc --version
cargo --version
You should see version 1.56 or later.
3

Add WebAssembly target

Mars-RS compiles to WebAssembly, so you need to add the WASM target:
rustup target add wasm32-unknown-unknown
The wasm32-unknown-unknown target compiles Rust to WebAssembly without any platform-specific bindings.

​
Project Dependencies

Mars-RS relies on three primary dependencies defined in Cargo.toml: 
[package]
name = "mars-rs"
version = "0.1.0"
edition = "2021"

[dependencies]
macroquad = "0.3"
rapier2d = { version = "0.17.2", features = ["simd-stable"] }
nalgebra = { version = "0.32.3", features = ["convert-glam015"] }

​
Core Dependencies

A simple and easy-to-use game library for graphics rendering and input handling.Key Features:
  • Cross-platform graphics rendering
  • WebAssembly support out of the box
  • Built-in UI system for buttons and controls
  • Input handling for keyboard and mouse
Used in Mars-RS for:
  • Rendering the VEX field and game objects
  • Drawing the robot and triballs
  • Handling user input in Driver mode
  • Creating the UI for mode switching
A 2D physics engine for Rust with WebAssembly support.Configuration:
features = ["simd-stable"]
The simd-stable feature enables SIMD optimizations for better performance while maintaining stability across platforms.
While rapier2d is included in dependencies, physics simulation is currently in development. The physics.rs file is empty in the current implementation.
A linear algebra library for graphics and physics computations.Configuration:
features = ["convert-glam015"]
This feature enables conversion between nalgebra and glam math types, which is necessary for interoperability with macroquad.Used in Mars-RS for:
  • Vector and matrix transformations
  • Rotation calculations
  • Position and velocity computations

​
Building the Project

1

Clone the repository

git clone https://github.com/your-org/mars-rs.git
cd mars-rs
2

Install dependencies

Cargo will automatically download and compile all dependencies:
cargo build
This may take several minutes on the first build as Cargo compiles all dependencies.
3

Build for WebAssembly

Compile the project to WebAssembly:
cargo build --target wasm32-unknown-unknown --release
The --release flag enables optimizations for better performance.
The output file will be at target/wasm32-unknown-unknown/release/mars-rs.wasm
4

Copy WASM file

Copy the compiled WASM file to your project root (or wherever index.html is located):
cp target/wasm32-unknown-unknown/release/mars-rs.wasm .

​
Project Structure

Understanding the codebase organization: 
mars-rs/
├── src/
│   ├── main.rs          # Entry point and main game loop
│   ├── robot.rs         # Robot struct and rendering
│   ├── field.rs         # VEX field and triball rendering
│   ├── movement.rs      # Autonomous movement algorithms
│   ├── driver.rs        # Manual control logic
│   ├── ui.rs            # User interface and mode switching
│   ├── util.rs          # PID controllers and helper functions
│   ├── paths.rs         # Path definition and manipulation
│   └── physics.rs       # Physics simulation (in development)
├── Cargo.toml           # Project dependencies
├── index.html           # Web page for WASM loading
└── mars-rs.wasm         # Compiled WebAssembly binary

​
Key Modules

main.rs

Contains the main game loop using macroquad’s #[macroquad::main] attribute

robot.rs

Defines the Robot struct with position, heading, and differential drive kinematics

field.rs

Renders the VEX field with checkerboard tiles, goals, barriers, and triballs

movement.rs

Implements PID control, Pure Pursuit, and Boomerang path following

​
Development Workflow

​
Fast Iteration

For quick development iterations, use cargo’s watch mode: 
cargo install cargo-watch
cargo watch -x 'build --target wasm32-unknown-unknown'
This automatically rebuilds when you save changes to source files.

​
Debugging

cargo check

​
Web Server Setup

Mars-RS requires a web server to load the WASM module due to browser security restrictions.
If you have Python installed:
python -m http.server 8000
Navigate to http://localhost:8000
Install and run with npx:
npx http-server -p 8000
Or install globally:
npm install -g http-server
http-server -p 8000
Install a Rust-based server:
cargo install basic-http-server
basic-http-server .
Defaults to port 4000

​
HTML Setup

The index.html file loads the WebAssembly module: 
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>mars-rs</title>
    <style>
        html, body, canvas {
            margin: 0px;
            padding: 0px;
            width: 100%;
            height: 100%;
            overflow: hidden;
            position: absolute;
            background: white;
            z-index: 0;
        }
    </style>
</head>
<body>
    <canvas id="glcanvas" tabindex='1'></canvas>
    <script src="https://not-fl3.github.io/miniquad-samples/mq_js_bundle.js"></script>
    <script>load("mars-rs.wasm");</script>
</body>
</html>
The macroquad JavaScript bundle (mq_js_bundle.js) is loaded from a CDN. Make sure you have an internet connection when running the simulation.

​
Troubleshooting

If rustup is not in your PATH after installation:
# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.cargo/bin:$PATH"
Then restart your terminal or run:
source ~/.bashrc
Make sure you’ve added the WebAssembly target:
rustup target add wasm32-unknown-unknown
rustup target list --installed
Try updating the Rust toolchain and cleaning the build:
rustup update
cargo clean
cargo build --target wasm32-unknown-unknown --release
Check the browser console for errors. Common issues:
  • CORS errors: Use a proper web server, not file:// URLs
  • Wrong path: Verify index.html references the correct WASM filename
  • Missing JavaScript: Ensure the macroquad bundle loads before your WASM

​
Next Steps

Now that you have Mars-RS installed and building:

Quickstart

Run your first simulation and try the controls

Robot API

Learn about the Robot struct and movement functions

Movement Algorithms

Explore PID tuning and path following

Field Rendering

Understand the VEX field layout and game objects

Build docs developers (and LLMs) love

Get started for freeTalk to us