THE PIZZA
CONNECTION

selectedCharacter    Character?
customPlayerName     String?         // Overrides archetype name
currentFamilyBoss    Character?      // Nonna at start
stats                PlayerStats     // All numeric state
currentStoryId       String          // Active story node
completedStories     List<String>
inventory            List<GameItem>
equippedItems        List<GameItem>
crewMembers          List<CrewMember>
flags                Map<String,dyn> // Named state
archEnemy            String?         // Character ID
archEnemyState       ArchEnemyState? // Full rivalry
characterAge         double          // 14–80+
lifePhase            String          // young|prime|veteran|elderly
generation           int             // 1=original, 2+=successors
currentLocation      String?         // e.g. 'new_york'
locationReputations  Map             // Per-city memory

money         int    // WADD — use addMoney() / subtractMoney()
guts          int    // 1–18 — improveGuts() / setGuts()
heart         int    // 1–18 — improveHeart() / setHeart()
brains        int    // 1–18 — improveBrains() / setBrains()
fists         int    // 1–18 — improveFists() / setFists()
respect       int    // 0–100 — changeRespect()
heat          int    // 0–100 — changeHeat()
               //   floor = respect/5 (HEAT FLOOR RULE)
               //   You cannot cool off once you are feared.
madeManCeremonyDone  bool // Story gate, not auto-set
capoCeremonyDone     bool // Story gate
donCeremonyDone      bool // Story gate

// Via story choice effects:
ChoiceEffects(setArchEnemy: 'RANDOM')
// Or specific character:
ChoiceEffects(setArchEnemy: 'tano_garofalo')

// Always resolves through CharacterDatabase.
// Never store character data on GameState directly.

// CORRECT
gameProvider.addEventToQueue(event);
gameProviderQueueDynamicEvent(
  provider, event, allowAutoLaunch: true);

// NEVER inline — bypasses everything
navigator.push(MaterialPageRoute(
  builder:(_) => MyEventScreen()));

95+  Mandatory. Bypasses anti-spam pacing.
     Ceremonies, Final Fate.
85–94 Auto-launch candidate. High urgency.
      Arch Enemy confrontations.
<85  Queued normally. Subject to 3-story
     cooldown between random events.

final c = CharacterDatabase.getCharacterById('nonna');
final portrait = ImageUtils.safeAsset(c.imagePath);
// Path: assets/images/characters/{id}.png
// Victory: victory_defeat/{Name}_Victory.png
// Defeat:  victory_defeat/{Name}_Defeat.png

// For atmospheric reveals — always:
ImageUtils.arcadePortraitStage(character)
// bleed bg + foreground + accent glow

id               String  // snake_case, stable across saves
name             String
nickname         String  // 'The Bear', 'The Volcano'
gender           String  // 'male' | 'female'
startingLocation String
backstory        String  // Multi-paragraph
bonuses          CharacterBonuses
voicePattern     String  // 'enforcer_professional'
generation       int     // 1=original, 2+=successors
dialogue         CharacterDialogue
  greeting, success, failure, threat, family
storyModifiers   StoryModifiers
  businessDeals, violence, family, law

// Always serialize through the model
final json = gameState.toJson();
await saveService.saveSlot(idx, json);

// After any model field change:
flutter pub run build_runner build \
  --delete-conflicting-outputs

// The [STORY SELECT] AppLogger line in
// story_screen.dart is intentional.
// It logs which story loaded and why.
// Do NOT remove it.

GameProvider (root ChangeNotifier)
├── game_provider_economy     WADD, market, lay low
├── game_provider_crew        Crew, mutiny check
├── game_provider_event_queue Events, pacing, auto-launch
├── game_provider_story_prog  Story selection by phase
├── game_provider_persistence Save/load, migration
├── game_provider_legendary   Legendary moments
├── game_provider_territory   Territory, location travel
└── game_provider_empire      Empire pressure, bosses

// STATE IS THE ENEMY
// Logic lives in services. UI only renders state.
// No business logic in build() methods.

// ~3,470 lines. Navigate with ═══ dividers.
// Cmd+F on section number to jump.

Section 1   State variables
Section 2   Immersion hooks (music, typewriter)
Section 3   Input handling (keyboard, save/load)
Section 4   Build + leave dialog
Section 5   RPG dialog popup
Section 6   Location label resolution
Section 7   Choice dispatch (5 typed handlers)
Section 8   Dice engine + ceremony maps
Section 9   Consequence + arcade moments
Section 10  _buildContestedRoll
Section 11  Vendetta reveal

// Wrappers at bottom:
// _QuickEncounterWrapper
// _BossTakeoverWrapper
// _ArchEnemyRevealDialog