GB Studio Guide

How to Build a Super Mario-Inspired Game in GB Studio and Serve It on gb.spqw.net

This guide is for making a side-scrolling, jump-driven Game Boy platformer that captures the feel of early Mario games without copying Nintendo art, names, characters, music, or level layouts. It covers design constraints, asset prep, scene setup, event logic, level structure, performance limits, web export, and the simplest deployment shape for gb.spqw.net.

1. What GB Studio Is Good At

GB Studio is strongest when you design around Game Boy rules instead of fighting them. A Mario-inspired game works best if you keep movement readable, level chunks compact, enemy patterns simple, and collectible logic event-driven rather than physics-heavy.

• Use short, handcrafted stages split into multiple scenes.
• Build a small move set: run, jump, stomp, collect, checkpoint, exit.
• Design with clean silhouettes and repeated tiles.
• Prefer tight set-pieces over sprawling exploratory maps.

2. Current Technical Constraints You Need to Design Around

The official GB Studio docs remain the source of truth for hard limits. The most important ones for a platformer are these:

3. The Recommended Project Shape

Start with one world, three stages, and one repeatable gameplay loop.

1. Stage 1 teaches movement, jump timing, and basic enemy avoidance.
2. Stage 2 introduces moving risk: pits, narrow jumps, faster enemies.
3. Stage 3 tests mastery and ends with a clear goal actor or exit trigger.

Keep your first version small. A tight vertical slice is better than a half-finished world map.

Core systems to implement first

• Player spawn and respawn.
• Horizontal movement and tuned jump feel.
• Enemy patrol and player damage.
• Stomp detection or alternate attack rule.
• Coins or cores as collectibles.
• Checkpoint flag.
• Goal pole, door, or beacon exit.

4. Make It Mario-Inspired Without Copying Mario

The safest way to reference Mario is through design grammar, not direct imitation. Think in terms of verbs and cadence.

5. Asset Pipeline

Background art

• Draw on an 8x8 grid from the beginning.
• Build a tile kit first: ground edge, fill, ladder, hazard, platform, decor, exit.
• Audit unique tiles early so you stay well under the 192-tile ceiling.
• Use repeated motifs for clouds, hills, and underground walls.

Sprites

• Player: start with a 96x16 animated actor sheet.
• Enemy A: one walker with 2-frame animation.
• Enemy B: one hopper or stationary hazard.
• Pickup: static 16x16 sprite if possible.

UI

• Customize assets/ui/ascii.png for your score and dialog font.
• Customize assets/ui/frame.png for menus and checkpoint messages.
• Keep text short; platformers should not stall the player often.

6. Scene Construction for Platformers

Treat each GB Studio scene as one gameplay chunk. If a level is long, split it into scenes connected by edge transitions, doors, or checkpoint warps.

• Use scene 1 for the intro chunk and teaching space.
• Use scene 2 for the middle challenge and checkpoint.
• Use scene 3 for the final run and exit.

This reduces script complexity, lowers per-scene asset pressure, and keeps collision editing manageable.

Collision approach

• Mark solid floors and walls first.
• Leave decorative background tiles non-solid.
• Use separate visual language for hazards like spikes, acid, void, or crushers.
• Test jump clearance constantly. One-tile mistakes feel much worse in GB-scale games.

7. Event Logic You Will Actually Need

A good GB Studio platformer stays understandable by making most logic reusable. Build these as Custom Events early.

Variables to define on day one

• v_lives
• v_score
• v_pickups
• v_checkpoint_scene
• v_checkpoint_x
• v_checkpoint_y
• v_stage_unlocked

8. Enemy Design That Fits GB Studio

Do not start with ten enemy types. Start with three behaviors.

1. Walker: patrol left and right, reverse on wall or ledge trigger.
2. Hopper: idle, jump, land, repeat.
3. Hazard: static spike, fire bar substitute, crusher, or projectile lane.

These three patterns are enough to build many levels if you vary spacing, platforms, and timing windows.

9. Movement Feel Checklist

A Mario-inspired game lives or dies on feel. In GB Studio, that means repeated playtesting more than elaborate scripting.

• Jump arc should clear your standard two-tile obstacle reliably.
• Short taps and full jumps should feel distinct if your control scheme allows it.
• Landing should not slide unpredictably.
• Enemy contact should be readable and fair.
• Camera shifts between scenes should not disorient the player.

10. Content Order for the First Milestone

1. Build a graybox test scene with placeholder tiles.
2. Tune movement and camera behavior.
3. Add one pickup and one enemy.
4. Add death and respawn.
5. Add checkpoint.
6. Add level exit.
7. Only then replace placeholders with final art.

11. Audio

Use short jump, pickup, damage, and finish sounds. Keep music loops concise and readable. If you only have time for one music track, make a strong world-1 theme and vary the stage geometry around it.

• Jump sound must be immediate and recognizable.
• Pickup sound should communicate reward without becoming tiring.
• Damage sound should be sharper and higher priority than ambiance.

12. Performance and Scope Discipline

• Limit animated actors per scene.
• Reuse background tiles aggressively.
• Keep decoration secondary to gameplay readability.
• Prefer repeated enemy logic over bespoke one-off scripts.
• Split long levels into scenes instead of forcing one giant map.

13. Exporting the Game for the Web

1. In GB Studio, use Export Web.
2. Find the generated files in build/web.
3. Verify the exported folder contains an index.html entry file and assets.
4. Test locally in a browser before deployment.

Official docs state that the web build is a static HTML5 export, so deployment is just static file hosting. Mobile browsers get touch controls automatically in the exported build.

14. Serving the Game on gb.spqw.net

Your current gb.spqw.net setup is already a static nginx site, which is a good fit for GB Studio web exports. The practical options are:

Recommended deployment shape for this repo

1. Keep a landing page at the domain root with description, controls, and credits.
2. Place each playable export inside a versioned folder such as /play/v1/.
3. Point the homepage “Play” button to the latest stable export.
4. Commit the static files to the repo that backs the Coolify app.
5. Redeploy the Coolify app after each release.

What that means in practice

For this repo, once your GB Studio project exports to build/web, you would copy that folder into the site repository, for example as play/v1/, then update index.html to link to /play/v1/. Because the site is served by nginx as static files, no app code changes are needed beyond placing the exported files in the published directory tree.

15. A Sensible Development Stack Around GB Studio

• GB Studio for scene editing, scripting, and export.
• Aseprite for player, enemy, tile, and UI PNGs.
• Tiled or another grid editor for planning backgrounds.
• A git repo for the deployment site.
• Coolify for pull-and-redeploy workflow on gb.spqw.net.

16. First 7-Day Build Plan

1. Day 1: define theme, hero, enemy shapes, tile kit, and naming.
2. Day 2: graybox one movement test scene and tune jump feel.
3. Day 3: add one enemy, pickups, death, and respawn.
4. Day 4: add checkpoint plus level goal, then playtest difficulty.
5. Day 5: swap in final art and UI.
6. Day 6: add music, SFX, and polish scripts.
7. Day 7: export web build, stage it into the site repo, deploy, and test on mobile.

17. Final Checklist Before You Call It Done

• The hero, enemies, UI, music, and item names are original.
• The player always understands where to go next.
• Every pit, enemy, and jump is fair on first contact.
• Checkpoint logic survives scene transitions.
• The web build loads on desktop and mobile.
• The landing page explains controls and links to the playable build.