Project 4: Scrolling Playground

Build smooth scrolling with bounds and map updates.

Quick Reference

Attribute	Value
Difficulty	Level 3
Time Estimate	1-2 weeks
Main Programming Language	Game Boy Assembly (SM83/LR35902)
Alternative Programming Languages	C (GBDK-2020), C++ (GBDK-2020)
Coolness Level	Level 4
Business Potential	Level 1
Prerequisites	DMG memory map, VBlank timing, basic assembly concepts
Key Topics	tiles, tile maps, LCDC, VRAM timing

1. Learning Objectives

By completing this project, you will:

Build and verify a working scrolling playground system.
Apply DMG hardware constraints (timing, memory, and I/O rules).
Create repeatable validation steps using emulator tooling.
Document decisions and trade-offs for future projects.

2. All Theory Needed (Per-Concept Breakdown)

2bpp Tile Rendering and Background Maps

Fundamentals DMG backgrounds are composed of 8x8 tiles stored in VRAM. Each tile uses a 2bpp format, meaning two bitplanes encode four shades per pixel. A background map is a 32x32 grid of tile indices that selects which tiles appear on screen. Mastering this pipeline is the foundation of all DMG rendering.

Deep Dive into the concept The DMG PPU renders a 160x144 display by fetching tile indices from a background map and then reading tile data from VRAM. Each tile row uses two bytes: one for the low bitplane and one for the high bitplane. The combination of those bits yields a color index 0-3, which is then mapped through a palette to a grayscale shade. Because the PPU continuously fetches data, VRAM updates must be synchronized to safe windows. The LCDC register determines which tile data region is used and whether the background is enabled. A practical renderer stores tiles in ROM, copies them to VRAM during VBlank, and then writes tile indices into the background map. Scrolling is achieved by modifying SCX/SCY registers, but the map itself remains 32x32. This means you must update map edges as the camera moves, a task that ties rendering directly to world logic. Correct tile encoding is critical: a single misplaced bit flips pixels across a row. The best practice is to use a tile editor that exports DMG 2bpp data and verify results in a VRAM viewer.

How this fit on projects This concept is central to Scrolling Playground. It informs the build pipeline, timing discipline, and verification steps used throughout the project.

Definitions & key terms

Tile: An 8x8 pixel graphic stored in VRAM.
Tile map: A grid of tile indices that forms the background.
2bpp: Two bits per pixel; four colors.

Mental model diagram

ROM Tiles -> VRAM Tile Data -> Background Map -> PPU -> LCD

How it works (step-by-step)

Copy tiles from ROM to VRAM during VBlank.
Write tile indices into the background map.
Enable background in LCDC.
Optionally update SCX/SCY for scrolling.

Minimal concrete example (pseudocode)

load_tiles_to_vram()
write_tile_map(indices)
enable_background()

Common misconceptions

“Tile maps store pixels” -> they store indices.
“Any time is safe to write VRAM” -> only safe windows.

Check-your-understanding questions

Why does 2bpp encode four colors?
What does LCDC control for tile data?
Predict what happens if VRAM writes occur mid-frame.

Check-your-understanding answers

Two bits yield four combinations.
LCDC selects tile data region and enables the background.
You see corruption or flicker.

Real-world applications

Title screens and HUD backgrounds
Scrolling levels

Where you’ll apply it You’ll apply it in Section 3.1, Section 4.1, and Section 5.2. Also used in: P04 Scrolling Playground.

References

Pan Docs: LCDC
Pan Docs: Memory Map

Key insights Tiles are data, maps are structure.

Summary Rendering is a pipeline of tile data plus tile maps under strict timing.

Homework/Exercises to practice the concept

Encode a simple 8x8 pattern in 2bpp by hand.
Explain the difference between tile data and tile maps.

Solutions to the homework/exercises

Two bitplanes per row create four color indices.
Tile data is pixel art; tile maps reference tiles by index.

3. Project Specification

3.1 What You Will Build

You will build a DMG project component focused on Scrolling Playground. It will be functional, repeatable, and verifiable in strict emulators. It will include clear output signals (visual or logged) and a documented validation process. It will exclude advanced extras beyond scope, such as CGB-only features.

3.2 Functional Requirements

Core functionality: Implement the primary system described in Scrolling Playground.
Deterministic output: Provide a repeatable visible or logged result.
Hardware constraints: Respect VRAM/OAM timing and memory map rules.

3.3 Non-Functional Requirements

Performance: Must stay within a safe per-frame budget.
Reliability: Must behave consistently across two emulators.
Usability: Clear on-screen or logged indicators for success.

3.4 Example Usage / Output

Build:
$ rgbasm -o build/main.o src/main.asm
$ rgblink -o build/game.gb build/main.o
$ rgbfix -v -p 0 build/game.gb

Run:
$ sameboy build/game.gb

Expected:
- No header warnings
- Stable on-screen indicator or log output

Exit Codes:
- 0 = success
- 1 = build failure
- 2 = header validation failure

3.5 Data Formats / Schemas / Protocols

StateRecord (pseudocode shape):

frame_counter: u16
input_mask: u8
flags: u8

AssetIndex (pseudocode shape):

bank_id: u8
offset: u16
length: u16

UpdateQueue item:

target: VRAM/OAM
dest: address
size: bytes

3.6 Edge Cases

VRAM/OAM access outside safe windows
Bank switch not restored
Input sampled multiple times per frame

3.7 Real World Outcome

A stable, reproducible DMG component that can be verified visually or via emulator logs, with no flicker or corruption.

3.7.1 How to Run (Copy/Paste)

$ rgbasm -o build/main.o src/main.asm
$ rgblink -o build/game.gb build/main.o
$ rgbfix -v -p 0 build/game.gb
$ sameboy build/game.gb

Exit Codes:

0 = success
1 = build failure
2 = header validation failure

3.7.2 Golden Path Demo (Deterministic)

Load ROM
Observe the expected on-screen state or log output
Confirm stability for 30 seconds

3.7.3 Failure Demo (Deterministic)

Force a known invalid state (e.g., wrong bank selected)
Observe expected failure behavior (visual corruption or emulator warning)

4. Solution Architecture

4.1 High-Level Design

Input/Timer -> Core Logic -> Render/Sound Updates -> Validation

4.2 Key Components

Component	Responsibility	Key Decisions
Input/Timing	Stable cadence	VBlank-driven loop
Data/Assets	Storage & layout	Fixed bank + banked assets
Renderer	Safe updates	VBlank/STAT windows

4.4 Data Structures (No Full Code)

State: counters, flags, and last-input snapshot
Asset tables: offsets + bank IDs
Update queue: list of VRAM/OAM updates

4.4 Algorithm Overview

Key Algorithm: Frame Update

Wait for VBlank
Read input and update state
Apply safe VRAM/OAM updates
Render or log output

Complexity Analysis:

Time: O(n) over visible entities or updates
Space: O(n) for entity/state tables

5. Implementation Guide

5.1 Development Environment Setup

Install RGBDS
Install DMG-accurate emulator
Set up project folder

5.2 Project Structure

project-root/
|---- src/
|   |---- main.asm
|   |---- hardware.asm
|   `---- assets.asm
|---- build/
|---- tools/
`---- README.md

5.3 The Core Question You’re Answering

“How do I build scrolling playground that behaves correctly under DMG hardware constraints?”

5.4 Concepts You Must Understand First

Stop and research these before coding:

2bpp Tile Rendering and Background Maps
- What parts are most timing-sensitive?
- Why does DMG hardware enforce this?
- Book Reference: “Game Boy Coding Adventure” - relevant chapters

5.5 Questions to Guide Your Design

Timing and Safety
- Where are the safe update windows?
- How will you ensure you only write during those windows?
Validation
- What will you see or log when it works?
- How will you reproduce the result exactly?

5.6 Thinking Exercise

Draw the Timing Window

Sketch a frame timeline and mark exactly where your updates will occur.

5.7 The Interview Questions They’ll Ask

Prepare to answer these:

“What hardware constraints drive your design?”
“How do you validate correctness on DMG?”
“What makes your updates deterministic?”
“How do you avoid timing glitches?”
“How do you debug errors when you have no OS?”

5.8 Hints in Layers

Hint 1: Start with a stable VBlank loop Build the simplest loop that waits for VBlank and updates a single state.

Hint 2: Add one subsystem at a time Layer in input, rendering, or audio only after the base loop is stable.

Hint 3: Validate with emulator tools Use VRAM/OAM viewers and breakpoints to confirm data correctness.

Hint 4: Stress test timing Intentionally add workload and watch for corruption or flicker.

5.9 Books That Will Help

Topic	Book	Chapter
DMG fundamentals	“Game Boy Coding Adventure”	Ch. 1-5
Low-level systems	“The Art of Assembly Language”	Ch. 1-6

5.10 Implementation Phases

Phase 1: Foundation (2-4 days)

Goals:

Build a bootable ROM and stable loop
Create a minimal visible output

Tasks:

Set up toolchain and build pipeline
Display a simple on-screen indicator

Checkpoint: Emulator shows stable output without warnings

Phase 2: Core Functionality (1 week)

Goals:

Implement the core system for Scrolling Playground
Add validation logs or overlays

Tasks:

Build the main subsystem
Verify correctness with emulator tools

Checkpoint: System behaves correctly for 30 seconds

Phase 3: Polish & Edge Cases (3-5 days)

Goals:

Handle edge cases and timing failures
Document limitations and fixes

Tasks:

Add edge case handling
Stress test and refine

Checkpoint: No flicker/corruption under stress test

5.11 Key Implementation Decisions

Decision	Options	Recommendation	Rationale
Update timing	VBlank only / HBlank	VBlank only	Safest for DMG
Data layout	Dense / Aligned	Aligned	Easier debugging

6. Testing Strategy

6.1 Test Categories

Category	Purpose	Examples
Unit Tests	Validate small routines	Input decoding, counters
Integration Tests	Subsystem behavior	Loop + rendering
Edge Case Tests	Timing stress	Max sprites, heavy updates

6.2 Critical Test Cases

Baseline run: ROM boots and shows stable output.
Stress test: Maximum updates without flicker.
Regression test: Repeat run after changes and compare results.

6.3 Test Data

Input sequence: Up, Up, A, Start
Expected: deterministic state changes and stable display

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

Pitfall	Symptom	Solution
Wrong update timing	Flicker or corruption	Move writes to VBlank
Bank not restored	Random crashes	Save/restore bank state
Incorrect register setup	Blank screen	Verify I/O writes

7.2 Debugging Strategies

Use emulator VRAM/OAM viewers: confirm data and timing.
Log state changes: compare expected vs actual frames.

7.3 Performance Traps

Overloading a frame with too many updates causes missed safe windows. Cap work per frame.

8. Extensions & Challenges

8.1 Beginner Extensions

Add a visual status indicator for success
Add a simple on-screen counter

8.2 Intermediate Extensions

Add a debug toggle for extra metrics
Add a second validation scenario

8.3 Advanced Extensions

Run the ROM on real hardware via flash cart
Add a small automated test harness

9. Real-World Connections

9.1 Industry Applications

Embedded firmware: fixed timing loops and I/O constraints
Retro toolchains: reproducible builds for constrained devices

RGBDS: https://rgbds.gbdev.io/ - DMG assembler/linker
SameBoy: https://sameboy.github.io/ - Accurate DMG emulator

9.3 Interview Relevance

Hardware timing questions
Memory map and register-level reasoning

10. Resources

10.1 Essential Reading

Game Boy Coding Adventure by Maximilien Dagois - DMG fundamentals
The Art of Assembly Language by Randall Hyde - registers and timing

10.2 Video Resources

DMG dev walkthroughs (YouTube) - focus on timing and VRAM rules

10.3 Tools & Documentation

Pan Docs: https://gbdev.io/pandocs/ - hardware reference
RGBDS: https://rgbds.gbdev.io/ - toolchain docs

Previous Project: Tile Renderer + Background Test
Next Project: Sprite Pipeline + DMA

11. Self-Assessment Checklist

11.1 Understanding

I can explain the core hardware constraints behind this project
I can describe why the chosen timing model works
I can explain one trade-off I made

11.2 Implementation

All functional requirements are met
All test cases pass in two emulators
The output is stable and deterministic

11.3 Growth

I can explain this project in an interview
I documented what I would do differently next time

12. Submission / Completion Criteria

Minimum Viable Completion:

Core functionality works and is visible
ROM builds without warnings
Behavior is reproducible

Full Completion:

All edge cases handled
Performance budget respected

Excellence (Going Above & Beyond):

Verified on real hardware
Includes automated validation steps

Project 4: Scrolling Playground

Quick Reference

1. Learning Objectives

2. All Theory Needed (Per-Concept Breakdown)

2bpp Tile Rendering and Background Maps

3. Project Specification

3.1 What You Will Build

3.2 Functional Requirements

3.3 Non-Functional Requirements

3.4 Example Usage / Output

3.5 Data Formats / Schemas / Protocols

3.6 Edge Cases

3.7 Real World Outcome

3.7.1 How to Run (Copy/Paste)

3.7.2 Golden Path Demo (Deterministic)

3.7.3 Failure Demo (Deterministic)

4. Solution Architecture

4.1 High-Level Design

4.2 Key Components

4.4 Data Structures (No Full Code)

4.4 Algorithm Overview

5. Implementation Guide

5.1 Development Environment Setup

5.2 Project Structure

5.3 The Core Question You’re Answering

5.4 Concepts You Must Understand First

5.5 Questions to Guide Your Design

5.6 Thinking Exercise

Draw the Timing Window

5.7 The Interview Questions They’ll Ask

5.8 Hints in Layers

5.9 Books That Will Help

5.10 Implementation Phases

Phase 1: Foundation (2-4 days)

Phase 2: Core Functionality (1 week)

Phase 3: Polish & Edge Cases (3-5 days)

5.11 Key Implementation Decisions

6. Testing Strategy

6.1 Test Categories

6.2 Critical Test Cases

6.3 Test Data

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

7.2 Debugging Strategies

7.3 Performance Traps

8. Extensions & Challenges

8.1 Beginner Extensions

8.2 Intermediate Extensions

8.3 Advanced Extensions

9. Real-World Connections

9.1 Industry Applications

9.2 Related Open Source Projects

9.3 Interview Relevance

10. Resources

10.1 Essential Reading

10.2 Video Resources

10.3 Tools & Documentation

10.4 Related Projects in This Series

11. Self-Assessment Checklist

11.1 Understanding

11.2 Implementation

11.3 Growth

12. Submission / Completion Criteria