Project 10: Banked Asset Loader
Stream assets from banked ROM into VRAM.
Quick Reference
| Attribute | Value |
|---|---|
| Difficulty | Level 4 |
| Time Estimate | 2-3 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 | MBC, bank switching, save RAM |
1. Learning Objectives
By completing this project, you will:
- Build and verify a working banked asset loader 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)
Cartridge Banking and Save RAM
Fundamentals Most DMG games exceed 32KB and rely on memory bank controllers (MBCs). Banking lets you swap ROM and RAM banks into a fixed window, and it enables save RAM on cartridges with batteries.
Deep Dive into the concept The DMG CPU can only address 64KB, so larger games use MBCs to page different 16KB banks into the 4000-7FFF range. MBC1 is common on DMG, and it supports both ROM banking and RAM banking modes. This means your code must explicitly select which bank is visible before reading data or calling code in that bank. Save RAM is accessed via A000-BFFF and must be enabled before writing; disabling it afterward reduces accidental corruption. Banking is a global state change, so call wrappers should save and restore the current bank to avoid confusion. A clean banking strategy groups related assets together to minimize switches and prevent latency spikes. For streaming systems, you may load data in small chunks across multiple frames. For save systems, you must define a stable data layout with integrity checks. Banking discipline is a defining skill in DMG development.
How this fit on projects This concept is central to Banked Asset Loader. It informs the build pipeline, timing discipline, and verification steps used throughout the project.
Definitions & key terms
- MBC: Memory Bank Controller that swaps ROM/RAM banks.
- ROM bank: A 16KB chunk of ROM mapped into the switchable window.
- RAM bank: A bank of external RAM used for saves or data.
Mental model diagram
Fixed ROM (0000-3FFF) | Switchable ROM (4000-7FFF)
Ext RAM (A000-BFFF) <- MBC selects bank
How it works (step-by-step)
- Read header to determine MBC type and ROM/RAM sizes.
- Select a ROM bank before reading banked data.
- Enable RAM, read/write saves, then disable RAM.
- Restore previous bank after banked calls or reads.
Minimal concrete example (pseudocode)
save_bank = current_bank()
select_bank(target)
read_data()
restore_bank(save_bank)
Common misconceptions
- “Bank switches are free” -> they change global state and can break calls.
- “RAM is always enabled” -> it must be enabled per MBC rules.
Check-your-understanding questions
- Why keep interrupt handlers in bank 0?
- What happens if you forget to restore a bank?
- Predict a failure from writing RAM while disabled.
Check-your-understanding answers
- Interrupts must always be reachable, which bank 0 guarantees.
- You execute the wrong code or read wrong data.
- Writes are ignored or corrupt data unpredictably.
Real-world applications
- Large levels and asset streaming
- Save systems with multiple slots
Where you’ll apply it You’ll apply it in Section 3.1, Section 4.2, and Section 5.10. Also used in: P10 Banked Asset Loader.
References
- Pan Docs: MBC1
- Pan Docs: Cartridge Header
Key insights Banking is architecture, not a trick.
Summary MBCs turn a tiny address space into a large world, but require strict discipline.
Homework/Exercises to practice the concept
- Design a bank plan for a 256KB game.
- Define a minimal save data layout with checksum.
Solutions to the homework/exercises
- Group assets by level and keep core code in bank 0.
- Use a signature + checksum to validate saves.
3. Project Specification
3.1 What You Will Build
You will build a DMG project component focused on Banked Asset Loader. 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 Banked Asset Loader.
- 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 banked asset loader that behaves correctly under DMG hardware constraints?”
5.4 Concepts You Must Understand First
Stop and research these before coding:
- Cartridge Banking and Save RAM
- 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 Banked Asset Loader
- 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
9.2 Related Open Source Projects
- 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
10.4 Related Projects in This Series
- Previous Project: HUD + Window Layer
- Next Project: Banked Code Loader
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