The Super Mango manual
23 pages, written next to the code and checked against it. Here to learn? Start with Sandbox School. Looking for something specific? Everything is listed below, or filter the page list.
Start Here
Where to begin: the lessons, the controls, how the code is organised and how to test a change.
- OverviewProject map, quick start, product facts, and first routes through the manual.
- Sandbox SchoolEight guided experiments from first frame to reproducible replay.
- Mechanics MuseumSix focused levels and the simulation inspector.
- Developer GuideCoding conventions, safe extension patterns, entity workflow, and contribution rules.
- Controls & InputKeyboard, gamepad, browser, replay, smoke, and runtime flag reference.
- Testing & Smoke MatrixWhich native, smoke, docs, WebAssembly, and release checks to run for each change.
- ArchitectureInit, loop, cleanup, GameState ownership, render order, and runtime flow.
Engine & Code
How the game works inside: every source file, the player, the numbers that tune it.
- Source FilesModule-by-module reference for every core C and header file in the codebase.
- Entity WalkthroughTrace a collectible through parser, runtime, editor, undo and tests.
- Player ModuleSampled input, physics, animation, collisions, and lifecycle across src/player/.
- Constants ReferenceNamed limits, dimensions, scores, timings, and gameplay constants.
World Builder
Make your own levels: the TOML format, the editor, and what every enemy and surface does.
- Level DesignTOML schema, minimum level template, and authoring rules for worlds.
- Level EditorVisual editor canvas, palette, properties, undo, validation, and play-test flow.
- Entities & HazardsEnemy and hazard behaviours, TOML placement, and gameplay effects.
- Collectibles & SurfacesCoins, stars, bouncepads, rails, float platforms, ropes, ladders, and vines.
Assets & Builds
Art, sound, the generated catalogs, and how builds and releases are made.
- AssetsSprite sheets, tilesets, fonts, folder rules, and visual resource notes.
- Asset InventoryGenerated playable asset sizes and bundle budget.
- Asset ProvenanceSources, third-party notices and media license records.
- SoundsAudio files, categories, naming rules, and game sound reference.
- Level CatalogGenerated campaign inventory: screens, content counts, and progression links.
- Overlay SnapshotsText snapshots for pause, game-over, completion, and terminal overlay states.
- Build SystemMake targets, compiler flags, platform prerequisites, and WebAssembly build flow.
- Release ChecklistPre-release source, docs, WebAssembly, archive, CI, and Pages verification gates.
Super Mango Editor
Play a C11/raylib platformer, build TOML worlds, and learn how the engine works.
Super Mango is a 2D platformer built in C11 with raylib, designed as an educational project for learning game development. The game features dynamic multi-screen TOML worlds with parallax backgrounds, enemies, hazards, collectibles, and fixed-time-step physics, building natively on macOS/Linux/Windows and as WebAssembly for browser play.
Quick Links
Learn by Doing
| Page | Description |
|---|---|
| Sandbox School | Eight guided labs, from first frame to reproducible experiments |
| Mechanics Museum | Six standalone levels for focused inspection |
| Entity Walkthrough | Trace a collectible through file format, runtime and editor |
Engine & Code
| Page | Description |
|---|---|
| Architecture | Game loop, init/loop/cleanup pattern, GameState container, 32-layer render order |
| Controls & Input | Keyboard, gamepad, browser/WASM, replay, smoke, and runtime flag reference |
| Testing & Smoke Matrix | Which local/CI checks to run for runtime, editor, docs, WASM, and release changes |
| Source Files | Module-by-module reference for every .c / .h file |
| Player Module | Input, physics, animation and lifecycle across src/player/ |
| Constants Reference | Curated gameplay constants and runtime-width distinctions |
Content & Assets
| Page | Description |
|---|---|
| Entities & Hazards | All 6 enemy types and 7 hazard types: behaviour, constants, TOML placement |
| Collectibles & Surfaces | Coins, stars, bouncepads, rails, float platforms, climbable surfaces |
| Assets | All sprite sheets, tilesets, and generated sounds in assets/; text uses raylib’s built-in font |
| Sounds | The 12 generated WAVs in assets/sounds/ and how the game plays them |
| Asset Inventory | Generated raw asset sizes and budget |
| Asset Provenance | Code, artwork, audio and font license records |
| Level Catalog | Generated inventory of every stage selected by the v1 campaign manifest, its progression link, and content count |
| Overlay Snapshots | Generated text snapshots for pause and terminal overlays |
Building & Contributing
| Page | Description |
|---|---|
| Build System | Makefile, compiler flags, build targets, prerequisites for all platforms |
| Level Design — TOML Reference | Full TOML schema for every entity type; minimum level template |
| Level Editor | Visual editor: canvas, palette, properties, undo, play-test, file I/O |
| Developer Guide | Coding conventions, adding new entities, sound effects workflow |
| Release Checklist | Source, docs, WebAssembly, archive, CI, and Pages gates before shipping |
Key Features
- 2D side-scrolling platformer with dynamic multi-screen worlds (configurable via
screen_count) - 32 render layers drawn back-to-front with per-level configurable parallax backgrounds
- Fixed-time-step physics (1/60 s steps fed by an accumulator);
make timing-labshows why variable steps made results depend on the frame rate - Six enemy types (spider, jumping spider, bird, faster bird, fish, faster fish)
- Seven hazard types (spike, spike block, spike platform, circular saw, axe trap, blue flame, fire flame)
- Five collectible types (coin, star yellow/green/red, last star)
- Climbable vines, ladders, ropes; three bouncepad tiers (small/medium/high); crumble bridges; float platforms (static/crumble/rail-riding)
- TOML-only level workflow:
levels/campaigns/main.tomlorders the sandbox and two volcanic stages;--level <path>also opens the separate learning labs - Authored
[[checkpoints]]supply explicit respawns; levels without records retain automatic screen-boundary respawns - Pause, game-over, and level-completion overlays: terminal menus support Next Level, Replay, Level Select, Exit, or Retry as applicable; Up/Down or D-pad selects, Enter/Space/Start confirms (A also confirms), Esc/Back exits (B also exits)
- Standalone visual level editor with undo, copy/paste, validation blocking, recent files, autosave, and play-test integration
- Start menu, HUD, lives, F1 settings, saved preferences and per-level best results
- Opt-in debug inspector: freeze/step, slow motion, live tuning and experiment capture/replay
- Keyboard, hot-plug gamepad and browser touch controls
- Builds natively on macOS, Linux, Windows; WebAssembly via Emscripten
Project at a Glance
| Item | Detail |
|---|---|
| Language | C11 |
| Compiler | clang recommended for CI/local parity; gcc compatible |
| Window size | 800 × 600 px OS window by default (native settings scale the canvas 1×–4×) |
| Logical canvas | 400 × 300 px (2× pixel scale) |
| Target FPS | 60 |
| Audio | raylib/miniaudio-negotiated device format; decoded effects and streamed WAV music |
| Libraries | raylib 6.0 (bundled GLFW on desktop), tomlc17 (TOML parser) |
| Level format | TOML (.toml files in levels/) |
Quick Start
# macOS — install dependencies
brew install cmake python
# Build and run the game
make run CC=clang
# Build and run the level editor
make run-editor CC=clang
# Run a specific level file
make run-level CC=clang LEVEL=levels/labs/01_collision.toml
# Optional local WebAssembly preflight (CI is authoritative for WASM releases)
make webSee Build System for Linux and Windows instructions.