oracle-of-secrets/Docs/NPCs.md

# NPCs Analysis

This document provides an analysis of the Non-Player Character (NPC) sprites found in the `Sprites/NPCs/` directory.

## File Overview

| Filename | Sprite ID(s) | Description |
|---|---|---|
| `bean_vendor.asm` | `Sprite_BeanVendor` | Handles the logic for the bean vendor who sells Magic Beans to the player. |
| `bottle_vendor.asm` | (Vanilla Hook) | Modifies the vanilla bottle vendor to handle selling milk. |
| `bug_net_kid.asm` | (Vanilla Hook) | Modifies the Sick Kid to grant the Pegasus Boots after playing the Song of Healing. |
| `deku_scrub.asm` | `Sprite_DekuScrubNPCs` | Manages various Deku Scrub NPCs, including one who gives the Deku Mask. |
| `eon_owl.asm` | `Sprite_EonOwl` | The owl that guides Link. Includes logic for both the Eon Owl and Kaepora Gaebora. |
| `eon_zora.asm` | (Part of `zora.asm`) | A friendly Zora NPC found in the Eon Abyss. |
| `eon_zora_elder.asm`| (Part of `zora.asm`) | The elder Zora in the Eon Abyss. |
| `farore.asm` | `Sprite_Farore` | The Oracle Farore, who appears in cutscenes and guides the player. |
| `followers.asm` | (Vanilla Hooks) | Contains logic for various follower characters like the Zora Baby and the Old Man. |
| `fortune_teller.asm`| (Vanilla Hook) | Modifies the fortune teller's dialogue to provide hints relevant to the hack's progression. |
| `goron.asm` | `Sprite_Goron` | Handles both the Kalyxo Goron who opens the mines and the Eon Gorons. |
| `hyrule_dream.asm` | (Part of `farore.asm`) | Logic for NPCs appearing in Link's dream sequences (Zelda, King, Soldier). |
| `impa.asm` | (Vanilla Hook) | Modifies Impa's behavior, particularly in setting spawn points. |
| `korok.asm` | `Sprite_Korok` | A friendly Korok NPC. |
| `maku_tree.asm` | `Sprite_MakuTree` | The Maku Tree, a key story NPC who provides a Heart Container. |
| `maple.asm` | (Part of `mermaid.asm`)| Maple the witch, who can send Link to dream worlds. |
| `mask_salesman.asm` | `Sprite_MaskSalesman` | The Happy Mask Salesman, who sells the Bunny Hood and Stone Mask. |
| `mermaid.asm` | `Sprite_Mermaid` | A friendly mermaid NPC. Also contains logic for Maple and the Librarian. |
| `piratian.asm` | `$0E` | A friendly pirate-like NPC that becomes aggressive if attacked. |
| `ranch_girl.asm` | (Vanilla Hook) | Modifies the chicken lady at the ranch to give the Ocarina. |
| `tingle.asm` | `$22` | Tingle, who sells dungeon maps to the player. |
| `vasu.asm` | `Sprite_Vasu` | Vasu, the jeweler who appraises magic rings. Also includes logic for Error. |
| `village_dog.asm` | `Sprite_VillageDog` | A friendly dog that interacts with the player. Includes logic for the Eon Dog. |
| `village_elder.asm` | (Part of `bean_vendor.asm`)| The village elder NPC. |
| `zora_princess.asm` | `Sprite_ZoraPrincess` | The Zora Princess, who grants the Zora Mask. |
| `zora.asm` | `Sprite_Zora` | A friendly Zora NPC. Also contains logic for the Zora Princess and Eon Zoras. |

## Detailed NPC Analysis

### `bean_vendor.asm` / `village_elder.asm`
- **Sprite ID:** `Sprite_BeanVendor`
- **Summary:** This file contains the logic for two NPCs. The primary is the Bean Vendor, who sells Magic Beans for 100 rupees. The second is the Village Elder.
- **Key Logic:**
    - **BeanVendor:** Initiates a dialogue on contact. If the player agrees to buy, it checks for sufficient rupees, deducts the cost, and spawns a collectible Magic Bean sprite.
    - **VillageElder:** Engages in dialogue and sets a progress flag (`OOSPROG`) after the first interaction.

### `bug_net_kid.asm`
- **Sprite ID:** (Hooks `SpritePrep_SickKid`)
- **Summary:** This modifies the vanilla "Sick Kid" NPC. Instead of giving the Bug Net, he gives the player the Pegasus Boots.
- **Key Logic:** The `SickKid_CheckForSongOfHealing` routine checks if the `SongFlag` is set. If it is, the `BugNetKid_GrantBugNet` routine is called, which uses `Link_ReceiveItem` to give the boots (`ITEMGET` ID `$4B`).

### `deku_scrub.asm`
- **Sprite ID:** `Sprite_DekuScrubNPCs`
- **Summary:** Manages several Deku Scrub NPCs, including the Deku Butler and Deku Princess. A key interaction involves a withered Deku Scrub who, after being healed with the Song of Healing, gives the player the Deku Mask.
- **Key Logic:**
    - The main state machine checks for the `SongFlag`.
    - If the song is played, it transitions through a dialogue sequence (`QuiereCuracion`, `DarMascara`).
    - Finally, in the `Regalo` state, it calls `Link_ReceiveItem` with item ID `$11` (Deku Mask) and sets a progress flag (`$7EF301`).

### `eon_owl.asm`
- **Sprite ID:** `Sprite_EonOwl`
- **Summary:** This is the guide owl, appearing in both the overworld (as Eon Owl) and the Hall of Secrets (as Kaepora Gaebora).
- **Key Logic:**
    - **Eon Owl:** In the overworld, it triggers introductory dialogue when the player gets close and then flies away.
    - **Kaepora Gaebora:** In the Hall of Secrets, it appears only after all 7 crystals are collected and before the player has the Song of Soaring. It offers to teach the player the song.

### `farore.asm` / `hyrule_dream.asm`
- **Sprite ID:** `Sprite_Farore`
- **Summary:** Handles the Oracle Farore and NPCs that appear in dream sequences.
- **Key Logic:**
    - **Farore:** Manages the introductory cutscene where she follows Link, sets the main story state (`$B6`), and changes the game state to post-pendants (`$7EF3C5 = 2`).
    - **Dream NPCs:** Contains simple display logic for Zelda, the King, and a soldier during the `MakuTree_HasMetLink` dream sequence.

### `followers.asm`
- **Sprite ID:** (Hooks vanilla follower system)
- **Summary:** Contains significant custom logic for follower characters, most notably the Zora Baby (Locksmith) and the Old Man.
- **Key Logic:**
    - **Zora Baby:**
        - Replaces the Locksmith sprite (`$39`).
        - Can be picked up and carried by Link.
        - When placed on a water gate switch, it triggers the switch.
        - Transitions from a follower to a standard sprite when on a star tile in a dungeon.
    - **Old Man:** Logic is modified to grant the Goldstar (Hookshot Lv2 upgrade) instead of the Magic Mirror.

### `vasu.asm`
- **Sprite ID:** `Sprite_Vasu`
- **Summary:** This is the ring jeweler, Vasu. He can appraise rings the player has found. The file also contains logic for the "I am Error" NPC.
- **Key Logic:**
    - Vasu's main loop presents a choice: "Appraise" or "Explain".
    - If "Appraise" is chosen, it checks if the player has any unappraised rings (`FOUNDRINGS`).
    - It charges 20 rupees (the first one is free) and transfers the bits from `FOUNDRINGS` to `MAGICRINGS`, making them usable.
    - The Error NPC appears as a subtype and gives the player a random ring when spoken to.