# FireRed Creature RPG Architecture

A 24-week advanced course that teaches a complete Pokemon-style RPG as a stack of data tables and state machines, using Pokemon FireRed source files as the primary authority and Pokemon Showdown only as a secondary reference for battle modeling, Dex-style data access, and deterministic battle tests.

## Outcomes
- Decompose a complete creature-collector RPG into runtime shell, overworld maps, event scripting, creature data, battle, inventory, UI, save, and link systems.
- Trace FireRed gameplay from data records through globals, callbacks, tasks, scripts, structs, and concrete source functions.
- Identify the FireRed files, structs, functions, constants, data tables, and state variables that implement each major game system.
- Design minimal clone versions of map loading, script execution, party data, battle turns, item use, and save persistence.
- Use Pokemon Showdown as a secondary comparison for battle data hooks, Dex/mods, simulator turns, and regression testing without replacing FireRed as the main architecture source.

## Prerequisites
- Strong C reading ability, including structs, pointers, globals, macros, and function pointers.
- Basic TypeScript or JavaScript reading ability for Pokemon Showdown comparisons.
- Familiarity with game loops, state machines, event dispatch, and data-driven design.
- Comfort reading large codebases and decompiled or reverse-engineered projects.
- Basic Git, build systems, JSON, and command-line tooling experience.

## Weekly Plan
- Week 1: FireRed Callback Shell and Task Scheduler
  - Topics: AgbMain startup responsibilities, main callback slots and SetMainCallback2, task allocation and task IDs, RunTasks as per-frame dispatch, data table to callback to visible behavior tracing
  - Source focus: pokefirered/src/main.c chunk_b35676322b169f85 (AgbMain); pokefirered/src/main.c chunk_6cfd90f6d0136799 (SetMainCallback2); pokefirered/src/task.c chunk_cb0bb91a147bfb59 (CreateTask); pokefirered/src/task.c chunk_3ffebc0341225936 (RunTasks)
- Week 2: Headers, Generated Data, and Build-Time Pipelines
  - Topics: headers as cross-module contracts, generated data versus runtime JSON, toolchain stages for data and assets, bin2c binary embedding, jsonproc template-driven source generation
  - Source focus: pokefirered/include/battle.h chunk_4079f42fde2b4370 (battle action and battler contract); pokefirered/include/bag.h chunk_8f2c0bdfc3224a33 (bag UI interface); pokefirered/build_tools.sh chunk_1a4a3316f8593aaf (tool suite); pokefirered/Makefile chunk_30eb2e53e9597446 (generated data rules); pokefirered/tools/jsonproc/jsonproc.cpp chunk_dd905c2bfaba76d6 (JSON/template generation)
- Week 3: Map Records, Layouts, Warps, and Triggers
  - Topics: map header fields, layout registry references, object events, warp events and dynamic warps, coordinate triggers and background events
  - Source focus: pokefirered/data/layouts/layouts.json chunk_76c0c20446e9e415 (BattleColosseum_2P layout); pokefirered/data/layouts/layouts.json chunk_4a91aa64203b6d9a (BattleColosseum_4P layout); pokefirered/data/maps/BattleColosseum_2P/map.json chunk_919152bd3bfceb95 (map header, objects, warps); pokefirered/data/maps/BattleColosseum_2P/map.json chunk_237e353ea279eb27 (coordinate triggers); pokefirered/data/maps/map_groups.json chunk_f22eb0b9c9a5d2a4 (link map group)
- Week 4: Overworld Load Flow and Warp Resolution
  - Topics: CB2_Overworld as map runtime callback, map data load sequence, warp destination state, LoadMapFromWarp control flow, Pallet Town map data as a small reference case
  - Source focus: pokefirered/src/overworld.c chunk_7ca71901368c46f7 (CB2_Overworld); pokefirered/src/overworld.c chunk_f00e575dedd069ed (map data load); pokefirered/src/overworld.c chunk_9b2a7fa129935fc9 (warp destination); pokefirered/src/overworld.c chunk_7ea6afd1253d6817 (LoadMapFromWarp); pokefirered/data/maps/PalletTown/map.json chunk_05643f6bfaa3b9bf (Pallet Town map data)
- Week 5: Fieldmap Tiles, Collision, Camera, and Objects
  - Topics: metatile data and block access, tile behavior queries, collision checks, camera-relative map drawing, object-event movement boundaries
  - Source focus: pokefirered/src/fieldmap.c chunk_642df7a31e75f54c (fieldmap runtime support); pokefirered/src/fieldmap.c chunk_eeb0180842f7ece9 (map block and tile behavior flow); pokefirered/src/fieldmap.c chunk_77ef7f3f8bff9777 (fieldmap helper flow); pokefirered/src/event_object_movement.c (source-use note: high-signal object-event movement source named in research packet; use with runtime movement claims after chunk review)
- Week 6: Player Input and Avatar Field Control
  - Topics: field input polling, avatar movement attempt flow, interaction checks, A-button event lookup, movement state gating
  - Source focus: pokefirered/src/field_control_avatar.c chunk_636f753078bf545a (avatar field control); pokefirered/src/field_control_avatar.c chunk_79332c416dfb6ac9 (player interaction handling); pokefirered/src/field_control_avatar.c chunk_4488cb84aee4d6dd (field-control branching); pokefirered/src/fieldmap.c chunk_eeb0180842f7ece9 (tile behavior support)
- Week 7: Object Events, NPC Movement, and Map Triggers
  - Topics: object-event records, NPC local IDs and script labels, trigger variables, coordinate event dispatch, object events versus background events
  - Source focus: pokefirered/data/maps/BattleColosseum_2P/map.json chunk_919152bd3bfceb95 (receptionist object event); pokefirered/data/maps/BattleColosseum_2P/map.json chunk_237e353ea279eb27 (two player spot triggers); pokefirered/data/maps/BattleColosseum_4P/map.json chunk_30cd3fd6e624b8c6 (four coordinate triggers); pokefirered/src/event_object_movement.c (source-use note: high-signal object-event movement source from packet)
- Week 8: Script VM, Flags, Variables, and Progression State
  - Topics: script pointer execution, script command handlers, flag and variable storage, branching and blockers, story progression as state mutation
  - Source focus: pokefirered/src/script.c chunk_1be14bbdaf5c3400 (script engine); pokefirered/src/script.c chunk_03258f0288d89251 (script control flow); pokefirered/src/script.c chunk_d424688149aa3bcb (script execution support); pokefirered/src/scrcmd.c chunk_c2a54fb6031b5886 (script command implementation); pokefirered/src/event_data.c chunk_a13cdbcb283dbf3b (flags and variables)
- Week 9: Pokemon Structs, Species Tables, and Accessors
  - Topics: Pokemon and BoxPokemon representation, species info records, data access through GetMonData-style APIs, party slots and stored state, encrypted or packed creature data boundaries
  - Source focus: pokefirered/include/pokemon.h chunk_55fc8220f5b93cdc (Pokemon data declarations); pokefirered/include/pokemon.h chunk_8e98575ccadc6d51 (Pokemon struct contract); pokefirered/include/pokemon.h chunk_2cc1cd9d6bfc7136 (mon data constants and access patterns); pokefirered/src/data/pokemon/species_info.h chunk_99a58307a160a13c (species data table); pokefirered/src/pokemon.c chunk_af8613c6e25be253 (Pokemon data implementation)
- Week 10: Stats, Moves, Evolutions, and Learnsets
  - Topics: stat calculation inputs, move slots and PP, level-up move data, TM/HM learnset bitsets, evolution and species transitions
  - Source focus: pokefirered/src/pokemon.c chunk_4573760bdda53819 (Pokemon runtime calculations); pokefirered/src/pokemon.c chunk_f56e3a6588d98715 (Pokemon data mutation and lookup); pokefirered/src/pokemon.c chunk_c089f03b70501fda (creature state helpers); pokefirered/src/data/pokemon/species_info.h chunk_2e759c52d0f4129a (species table continuation); pokefirered/src/data/pokemon/tmhm_learnsets.h (source-use note: high-signal FireRed TM/HM learnset table named in research packet); pokemon-showdown/data/learnsets.ts (secondary source-use note: high-signal modern learnset modeling file named in packet; do not treat as FireRed mechanics)
- Week 11: Party Lifecycle, Summary UI, and Move Learning
  - Topics: party slot ownership, summary screen data reads, move relearner menu state machine, move replacement flow, party data mutation from UI
  - Source focus: pokefirered/src/pokemon_summary_screen.c chunk_e8e17a42bbf17d46 (summary screen and Pokemon menu evidence); pokefirered/src/learn_move.c chunk_af3598df6f092723 (Move Relearner state machine start); pokefirered/src/learn_move.c chunk_e820ee15ae8caa6d (move teaching and replacement states); pokefirered/include/pokemon.h chunk_9b5ff7d0cd9f4c67 (Pokemon interface continuation); pokefirered/src/pokemon.c chunk_9c96aedd5b8237e6 (Pokemon helper flow)
- Week 12: Battle Interface Contract and Encounter Setup
  - Topics: battle.h as subsystem map, battler positions and actions, trainer party structs, wild and trainer battle setup, transition from overworld to battle
  - Source focus: pokefirered/include/battle.h chunk_4079f42fde2b4370 (battler identity and action constants); pokefirered/include/battle.h chunk_4e3097f639b05787 (trainer party structs); pokefirered/include/battle.h chunk_403d30271e2270d6 (trainer table contract); pokefirered/src/battle_setup.c chunk_0e0ab33ad5402d71 (battle setup); pokefirered/src/battle_setup.c chunk_db24b720e895b599 (setup flow); pokefirered/src/battle_setup.c chunk_a8e4b22a367933e7 (battle start handoff)
- Week 13: Battle Main Loop, Turn Order, and Battler State
  - Topics: battle main callback, chosen actions by battler, turn-order arrays, battle resources and shared globals, controller and sprite-facing state
  - Source focus: pokefirered/src/battle_main.c chunk_2017de6d7013d2b7 (battle main flow); pokefirered/src/battle_main.c chunk_568e3366056a9ce4 (battle state progression); pokefirered/src/battle_main.c chunk_a15739d3170f73c1 (turn/action flow); pokefirered/include/battle.h chunk_825c6c75270bc90c (BattleResources and BattleResults); pokefirered/include/battle.h chunk_8367bbcb71bfc88d (BattleScripting and globals)
- Week 14: Move Execution, Damage, Status, and Battle Scripts
  - Topics: battle script command dispatch, current move data, damage and hit effects, status and side timers, animation and message hooks
  - Source focus: pokefirered/src/battle_script_commands.c chunk_9779e386ddb42cb0 (battle script commands); pokefirered/src/battle_script_commands.c chunk_c405e26d69cb40ac (script command effects); pokefirered/src/battle_script_commands.c chunk_98989865d85f275c (battle script flow); pokefirered/src/battle_util.c chunk_9335e5727aa0657d (battle utility and move support); pokefirered/include/battle.h chunk_a08e84ff1272f826 (disable/protect/special status structures)
- Week 15: Trainer Data, Wild Encounters, and Battle Results
  - Topics: trainer table structure, wild encounter table inputs, battle result storage, win/loss routing, overworld return after battle
  - Source focus: pokefirered/src/data/trainers.h (source-use note: high-signal trainer table named in packet); pokefirered/src/data/wild_encounters.json (source-use note: high-signal wild encounter JSON named in packet); pokefirered/src/battle_setup.c chunk_494d132a59422c85 (battle transition/load/event representative chunk); pokefirered/src/battle_main.c chunk_1c5a1226d8d9afb7 (battle main result flow); pokefirered/src/battle_main.c chunk_46361bdbd92dae37 (battle main cleanup/result continuation); pokefirered/include/battle.h chunk_f5cd027bf13ab47d (BattleStruct and result-related state)
- Week 16: Battle AI Scripts and Ability Hook Comparison
  - Topics: AI script pointer control, party-aware AI predicates, status checks across party slots, Showdown ability hooks as secondary contrast, data hook modeling versus C command flow
  - Source focus: pokefirered/src/battle_ai_script_commands.c chunk_0a05fcecbd58029f (battle AI command source); pokefirered/src/battle_ai_script_commands.c chunk_34a415cc38858fdc (party scanning, status predicates, sAIScriptPtr branching); pokemon-showdown/data/abilities.ts chunk_d5bdb17c16d6f1a4 (secondary ability hooks such as onDamagingHit/onModifyMove); pokemon-showdown/data/abilities.ts chunk_b4a38d21b0114ee8 (secondary residual/base-power hook examples); pokemon-showdown/data/abilities.ts chunk_6372bce3e311c10b (secondary data/engine split note)
- Week 17: Item Tables, Bag State, and Inventory UI
  - Topics: item data records, bag pockets and quantities, bag window API, money and menu helpers, inventory mutation rules
  - Source focus: pokefirered/src/item.c chunk_1b104a09a7f41ad7 (item system); pokefirered/src/item.c chunk_296b886a4f0b7cc8 (item lookup and mutation flow); pokefirered/src/item.c chunk_352eff45b08b4413 (item support continuation); pokefirered/include/bag.h chunk_8f2c0bdfc3224a33 (bag text/windows/yes-no/money interface)
- Week 18: Item Use, Field Effects, and Progression Unlocks
  - Topics: item-use dispatch, field-use versus battle-use items, healing and key item behavior, script variables and flags as blockers, unlock checks from inventory state
  - Source focus: pokefirered/src/item_use.c chunk_7e88bbaddbab5bb9 (item-use flow); pokefirered/src/item_use.c chunk_8f5c0eba4013eb8a (field item-use continuation); pokefirered/src/item_use.c chunk_ce2671932ba5ff71 (item-use support continuation); pokefirered/src/event_data.c chunk_bff5bbc2efc3008f (event flags/vars support); pokefirered/src/scrcmd.c chunk_7609d397203c8536 (script commands for progression flow)
- Week 19: Menu State Machines for Party, Summary, and Moves
  - Topics: menu callbacks and task states, summary screen reads, move relearner states, confirm/cancel branches, UI-driven Pokemon data writes
  - Source focus: pokefirered/src/learn_move.c chunk_af3598df6f092723 (Move Relearner state machine overview); pokefirered/src/learn_move.c chunk_e820ee15ae8caa6d (teach move confirmation and replacement flow); pokefirered/src/pokemon_summary_screen.c chunk_e8e17a42bbf17d46 (summary/menu source evidence); pokefirered/src/task.c chunk_cb0bb91a147bfb59 (CreateTask); pokefirered/src/task.c chunk_3ffebc0341225936 (RunTasks)
- Week 20: Save Blocks, Load Validation, and Flash Persistence
  - Topics: save block ownership, load-save initialization, sector validation, flash write/read boundaries, restoring world, party, bag, and flags
  - Source focus: pokefirered/src/load_save.c chunk_0755fbe98f753bb7 (load/save entry flow); pokefirered/src/load_save.c chunk_3efebaad2e0f31e0 (load/save validation support); pokefirered/src/load_save.c chunk_d615017937c86ab6 (load/save continuation); pokefirered/src/save.c chunk_ab80cd8f4fa87d77 (save system); pokefirered/src/save.c chunk_852fbc242f85cc74 (save sector flow); pokefirered/src/agb_flash.c (source-use note: flash persistence file named in packet; chunk IDs not promoted in synthesis)
- Week 21: RFU Link State, Cable Club Maps, and Multiplayer Handoff
  - Topics: RFU mode constants, link manager callback messages, VBlank timers and link state, Cable Club map group data, link battle/trade handoff boundaries
  - Source focus: pokefirered/include/AgbRfu_LinkManager.h chunk_8df030184c481b3b (RFU mode constants); pokefirered/include/AgbRfu_LinkManager.h chunk_b75d95e146826302 (callback message taxonomy); pokefirered/include/AgbRfu_LinkManager.h chunk_fc7074757ec1be96 (link state constants and init parameters); pokefirered/include/AgbRfu_LinkManager.h chunk_f549b5be90786ef0 (LINK_MANAGER state); pokefirered/data/maps/map_groups.json chunk_f22eb0b9c9a5d2a4 (link map group); pokefirered/data/maps/BattleColosseum_4P/map.json chunk_f18829d873bc1246 (4-player Colosseum map header and warps)
- Week 22: Showdown Dex, Mods, Learnsets, and Legality Boundaries
  - Topics: Dex as battle data facade, generation mods, move/species/ability/item lookup, nonstandard filtering, learnsets as secondary modeling reference
  - Source focus: pokemon-showdown/sim/DEX.md chunk_922688d7428150d1 (Dex purpose and move lookup); pokemon-showdown/sim/DEX.md chunk_5fbe60392b5eedf9 (Dex.mod generation-specific data); pokemon-showdown/sim/DEX.md chunk_74ee605430e5596f (moves/species/abilities/items APIs); pokemon-showdown/sim/NONSTANDARD.md chunk_800f1eafbea0ed7c (all data requires filtering); pokemon-showdown/data/moves.ts chunk_012eada95ff7aa5f (secondary move data); pokemon-showdown/data/mods/gen9dlc1/learnsets.ts (secondary source-use note: high-signal modern learnset file named in packet; not FireRed behavior)
- Week 23: Showdown Simulator Turns, Action Queue, and Server Boundary
  - Topics: Battle request state, player choices and commit flow, action queue resolution, runMove responsibilities, BattleStream and server runtime contrast
  - Source focus: pokemon-showdown/sim/battle.ts chunk_3b063b1b44a6d638 (Battle class and request-state model); pokemon-showdown/sim/battle.ts chunk_889e310105810281 (choose and commitChoices flow); pokemon-showdown/sim/battle-queue.ts chunk_f572d84e556bce5e (battle action queue); pokemon-showdown/sim/battle-actions.ts chunk_95a7524b39636e24 (runMove responsibilities); pokemon-showdown/sim/battle-stream.ts chunk_ced1577d9e2d59ac (BattleStream API); pokemon-showdown/server/README.md chunk_1ba53f1706d86463 (server run command and localhost behavior)
- Week 24: Deterministic Tests and Full FireRed System Trace
  - Topics: battle tests as executable specifications, seeded battle setup, assertion vocabulary for combat state, debug logs and replay output, end-to-end source map from data to behavior
  - Source focus: pokemon-showdown/test/TESTS.md chunk_134ac9f75b9d6477 (createBattle, seeds, forceRandomChance); pokemon-showdown/test/TESTS.md chunk_e8da8b9a442469fd (makeChoices and RNG-independent assertions); pokemon-showdown/test/common.js chunk_979fde4c3177ea4f (createBattle options and deterministic seed); pokemon-showdown/test/assert.js chunk_26026d44764fa919 (species, fainted, fullHP assertions); pokemon-showdown/test/assert.js chunk_f2ab14d37f397660 (statStage and HP-change assertions); pokefirered/src/overworld.c chunk_7ea6afd1253d6817 (LoadMapFromWarp); pokefirered/src/save.c chunk_9900b8674c89af66 (save continuation)

## Assessment Plan
- homework_w01 (homework) due week 1
- homework_w02 (homework) due week 2
- quiz_w02 (quiz) due week 2
- homework_w03 (homework) due week 3
- homework_w04 (homework) due week 4
- quiz_w04 (quiz) due week 4
- homework_w05 (homework) due week 5
- homework_w06 (homework) due week 6
- quiz_w06 (quiz) due week 6
- homework_w07 (homework) due week 7
- homework_w08 (homework) due week 8
- quiz_w08 (quiz) due week 8
- homework_w09 (homework) due week 9
- homework_w10 (homework) due week 10
- quiz_w10 (quiz) due week 10
- homework_w11 (homework) due week 11
- homework_w12 (homework) due week 12
- quiz_w12 (quiz) due week 12
- homework_w13 (homework) due week 13
- homework_w14 (homework) due week 14
- quiz_w14 (quiz) due week 14
- homework_w15 (homework) due week 15
- homework_w16 (homework) due week 16
- quiz_w16 (quiz) due week 16
- homework_w17 (homework) due week 17
- homework_w18 (homework) due week 18
- quiz_w18 (quiz) due week 18
- homework_w19 (homework) due week 19
- homework_w20 (homework) due week 20
- quiz_w20 (quiz) due week 20
- homework_w21 (homework) due week 21
- homework_w22 (homework) due week 22
- quiz_w22 (quiz) due week 22
- homework_w23 (homework) due week 23
- homework_w24 (homework) due week 24
- quiz_w24 (quiz) due week 24
- midterm (midterm) due week 12
- final (final) due week 24

## Lab Policy
auto

## Source and Feedback Usage
- Use context_research.md as the compact source-memory packet for every stage.
- Teach concrete findings from the research notes; do not merely promise to inspect sources later.
- Cite source paths and chunk IDs from weekly source focus entries when making source-backed claims.
- Context research reviewed 50348 chunk(s) across 2198 source file(s).
- Curriculum source module: pokemon-showdown/data
- Curriculum source module: pokefirered/src
- Curriculum source module: pokemon-showdown/server
- Curriculum source module: pokemon-showdown/test
- Curriculum source module: pokefirered/data
- Curriculum source module: pokefirered/include
- Curriculum source module: pokemon-showdown/sim
- Curriculum source module: pokefirered/tools
