Port Fly, Dig, Teleport and the Escape Rope

FLY opens _FlyMap in the party menu: the region's Town Map with "Where?",
the visited flypoints in turn and the Fly user's icon, then FlyScript flies
the icon off along SpriteAnimFunc_FlyFrom's path, enters the spawn point and
lands it with SpriteAnimFunc_FlyTo. Teleport returns to the last Pokémon
Center's town through IsSpawnPoint. Dig and the Escape Rope lead out of a
cave to the warp EnterMapWarp's SaveDigWarp recorded, which saves now keep.

newloadmap stops its script as StopScript does and the world resumes it on
the new map, which the landing and return movements need. A destination
that is not ported yet gives a notice.

Closes #25

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/ARCHITECTURE.md

@@ -88,10 +88,18 @@ keeps the card on screen (`world.pokegear`) during the call's texts.
 `scripts/mom.ts` runs `BankOfMom` as a special; its amount box is a
 `mombank` effect answered with buttons in the same way, and so are the
 pages of `scripts/trainer-card.ts` and the screen of `scripts/options.ts`,
-whose option bytes live in the script state. The world refreshes the card's play
+whose option bytes live in the script state, and of `scripts/fly-map.ts`,
+which Fly opens before the world queues its script. The world refreshes the card's play
 time, colon and badge step every tick; `world/game-time.ts` is the play
 time (`wGameTime`), which the world advances two frames per tick.
 
+`newloadmap` stops a script as `StopScript` does: the `warp` effect carries
+the offset after it, and once the world has entered the new map it starts
+the rest of the script there with the same field-move context (Fly's
+landing, Teleport's and Dig's return movements). A `fly` effect hides every
+object while the party icon flies (`world.flyingIcon`, drawn by the
+renderer).
+
 `TilesetAnimator` translates the ROM animation command tables, advancing two
 video frames per overworld tick. It owns mutable graphics separately from the
 asset cache. The renderer records background color indices for grass sprite

docs/NATIVE_PORT.md

@@ -36,6 +36,7 @@ These paths refer to the pinned [PRET source](https://github.com/pret/pokecrysta
 | `game/scripts/pokegear.ts`       | `engine/pokegear/pokegear.asm`, `engine/phone/phone.asm`, `engine/phone/scripts/mom.asm`, `elm.asm`, `engine/rtc/print_hours_mins.asm` | `PokeGear` with each card's joypad handling: the clock (`Pokegear_UpdateClock`, `PrintHoursMins`), the map card's landmark cursor (`TownMap_InitCursorAndPlayerIconPositions`, `TownMap_GetKantoLandmarkLimits`), the phone list (`PokegearPhone_UpdateDisplayList`, `GetCallerClassAndName`, `PokegearPhoneContactSubmenu`, `CheckCanDeletePhoneNumber`) and calls (`MakePhoneCallFromPokegear`, `CheckPhoneContactTimeOfDay`, `GetMapPhoneService`, `HangUp`). Callee scripts run in the event interpreter on the start menu's draft. Screens are native; the radio's stations are not ported. |
 | `game/scripts/trainer-card.ts`   | `engine/menus/trainer_card.asm`, `engine/gfx/player_gfx.asm` (`GetCardPic`), `engine/gfx/cgb_layouts.asm` (`_CGB_TrainerCard`), `home/game_time.asm` | `TrainerCard`'s two reachable pages with their joypad rules, strings from `.Name_Money`, `.Dex_PlayTime` and `.Badges`, the caught count, and the badges from `TrainerCard_JohtoBadgesOAM` with their eight-frame steps. `rendering/trainer-card.ts` draws the card picture, leader faces and badges from the ROM with the card's palettes and attribute map. `world/game-time.ts` is `GameTimer` (capped at 999:59:59). Text is native; the blinking colon's and badges' phase start at the page load. |
 | `game/scripts/options.ts`        | `engine/menus/options_menu.asm`, `data/default_options.asm`, `engine/battle/core.asm` (`CheckWhetherToAskSwitch`), `engine/menus/start_menu.asm` | `_Option` with `OptionsControl` and each option's routine on the four option bytes, `DefaultOptions`, and the two settings consumed so far: `BATTLE_SHIFT` and `MENU_ACCOUNT`. Strings come from the ROM; the screen is native. |
+| `game/scripts/fly-map.ts`        | `engine/pokegear/pokegear.asm` (`_FlyMap`, `FlyMap`, `TownMapBubble`, `CheckIfVisitedFlypoint`), `data/maps/flypoints.asm`, `engine/events/field_moves.asm` (`FlyFromAnim`, `FlyToAnim`), `engine/sprite_anims/functions.asm` | The Fly map's region choice (Kanto only after Indigo Plateau, without the player's icon otherwise), the default flypoint and up/down scrolling over visited flypoints (`wVisitedSpawns` through the ROM's `EngineFlags`). The flights follow `SpriteAnimFunc_FlyFrom` and `SpriteAnimFunc_FlyTo` frame by frame with the party icon. The Town Map, bubble and icons are drawn natively; the leaves are not presented. |
 | `game/scripts/evolution.ts`      | `engine/pokemon/evolve.asm`, `engine/pokemon/learn.asm`, `engine/movie/evolution_animation.asm`, `engine/pokemon/party_menu.asm` | `EvolveAfterBattle`/`EvolvePokemon` over the raw evolution bytes, the evolution texts and a timed, B-stoppable picture sequence, `UpdateSpeciesNameIfNotNicknamed`, `CalcMonStats` and the HP rise, `LearnLevelMoves`, `LearnMove`/`ForgetMove` outside battle and `PlacePartyMonEvoStoneCompatibility`. |
 | `game/rom/pokemon.ts`            | `data/pokemon/base_stats`, `evos_attacks.asm`, `data/moves/moves.asm`, `data/items/attributes.asm`, `engine/gfx/load_pics.asm` | Species, move and item names, base data, evolution lists, learnsets, move PP, item pockets, growth-rate exp and front pictures (`FixPicBank`, `PadFrontpic`). Starter pictures match rebuilt bytes; all 251 evolution lists match the pinned source. |
 | `game/party`                     | `engine/pokemon/move_mon.asm`, `engine/pokemon/caught_data.asm`, `engine/items/items.asm`                                      | `GeneratePartyMonStats` for script gifts: DVs, `FillMoves`, PP, exp, `CalcMonStatC`, happiness and caught data. `PutItemInPocket`, key items and `TossItem`. `SendMonIntoBox`, `SendGetMonIntoFromBox` (deposit and withdraw), `RestorePPOfDepositedPokemon` and `CalcLevel` for the PC's boxes and item storage. TMs and HMs are refused.                                         |
@@ -400,8 +401,11 @@ Badge, forced cycling, already surfing, water permission, `CheckDirection`
 and `CheckFacingObject`), `StrengthFunction`, `FlashFunction`
 (`SpecialAerodactylChamber` by map attributes, which sets
 `EVENT_WALL_OPENED_IN_AERODACTYL_CHAMBER`, or `DARKNESS_PALSET`),
-`TryWhirlpoolMenu`, `CheckMapCanWaterfall`, and the checks of Fly, Dig,
-Teleport, Headbutt and Rock Smash. A success queues `Script_CutFromMenu`,
+`TryWhirlpoolMenu`, `CheckMapCanWaterfall`, `FlyFunction` (the Storm
+Badge, an outdoor map, then the Fly map), `EscapeRopeOrDig` (a cave or
+dungeon with a `wDigWarpNumber`) and `TeleportFunction` (an outdoor map and
+`IsSpawnPoint` on `wLastSpawnMapGroup`), and the checks of Headbutt and Rock
+Smash. A success queues `Script_CutFromMenu`,
 `SurfFromMenuScript`, `Script_StrengthFromMenu`, `Script_UseFlash`,
 `Script_WhirlpoolFromMenu`, `Script_WaterfallFromMenu` or
 `SweetScentFromMenu.SweetScent` with the field-move context the interpreter
@@ -409,8 +413,24 @@ already reads (`GetPartyNickname`, the replacement block, the surfing
 state). New interpreter support: `callasm BlindingFlash` (sets the Flash
 flag), `callasm SweetScentEncounter` (the encounter the world drew with
 `CanEncounterWildMon`, `GetMapEncounterRate` and `ChooseWildEncounter`, no
-rate roll) and `UseFlashTextScript`'s sound-only `text_asm`. Fly's map, Dig
-and Teleport's warps, `TreeMonEncounter` and `RockMonEncounter` are not
+rate roll) and `UseFlashTextScript`'s sound-only `text_asm`.
+`FlyFunction.FlyScript`, `TeleportFunction.TeleportScript` and
+`EscapeRopeOrDig.UsedDigScript` run with the chosen `wDefaultSpawnpoint` or
+the dig warp's position. `newloadmap` handles `MAPSETUP_WARP`,
+`MAPSETUP_TELEPORT` and `MAPSETUP_FLY` (`EnterMapSpawnPoint` from
+`SpawnPoints`) and `MAPSETUP_DOOR` (`EnterMapWarp` to the warp Dig copies
+into `wNextWarp`; the player keeps facing unless `CheckWarpFacingDown`),
+then stops the script, which resumes on the new map. `EnterMapWarp`'s
+`SaveDigWarp` records any warp from an outdoor map into an indoor one
+(`CheckIndoorMap`), except from Mount Moon Square and Tin Tower's roof; saves
+keep it as `digWarp`. `FlyFromAnim`, `FlyToAnim`, `HideSprites`,
+`SkipUpdateMapSprites`, `.ReturnFromFly` and `WaitSFX` are accepted, the Fly
+animations as timed `fly` effects (65 and 33 ticks). The Escape Rope
+(`EscapeRopeEffect`) runs `EscapeRopeOrDig` from the pack, opening the Kabuto
+chamber's wall there (`SpecialKabutoChamber`) and using up one rope; a
+failure prints nothing before Oak's warning. `JumpRoamMons` (no roaming
+Pokémon yet) and the fades are not modelled. A destination map that is not
+ported gives a notice. `TreeMonEncounter` and `RockMonEncounter` are not
 ported and give a notice after their checks.
 `Softboiled_MilkDrinkFunction` runs in the menu with `GetOneFifthMaxHP`,
 `RemoveHP` and `RestoreHealth`, refusing the user itself and Pokémon that

docs/PLAN.md

@@ -169,7 +169,7 @@ The numbered sections below keep their full scope. Each one opens with a checkli
 - PACK: the Items, Balls, Key and TM pockets (left and right change pockets; there are no TMs or HMs yet), and each item's submenu chosen by its permissions and field menu (`USE`, `GIVE`, `TOSS`, `SEL`, `QUIT`). TOSS asks how many and confirms. USE follows `UseItem`: Oak's warning without a field use, "You don't have a POKéMON!" for party items without one, and `_DoItemEffect` by the item's `ItemEffects` address: Potions and the other `HealingHPAmounts` items, status healers, Full Restore, Revive and Max Revive, the bitter Energypowder, Energy Root, Heal Powder and Revival Herb, Ethers, Elixers, the MysteryBerry and PP Up. The Bicycle closes the menu and runs `Script_GetOnBike` or `Script_GetOffBike` outdoors; elsewhere Oak objects, because `wFieldMoveSucceeded` shares `wItemEffectSucceeded`'s byte.
 - PP Up keeps a quirk: `wUsePPUp` shares `wTempPP`'s byte, so `ComputeMaxPP` adds one step (a fifth of the base PP, at most 7) to the current PP as well as the maximum. Sketch and moves with three PP Ups are "maxed out".
 - The menu runs on a script draft, like the PC. Changes commit when it closes; a save made while it is open keeps the state from before it. The start menu cursor, the party menu cursor and the last pocket stay in memory between openings and are cleared after a battle, as `CleanUpBattleRAM` does. The party cursor reaches the next battle's `ChangeHappiness`.
-- Not ported: MAIL, moving a Pokémon's moves to another party member with left and right, item reordering with Select and the remaining field items such as Repel and Escape Rope (each gives a notice and changes nothing). Rare Candy, evolution stones and vitamins run since the evolution section below; field moves, SEL and Select since the section after it.
+- Not ported: MAIL, moving a Pokémon's moves to another party member with left and right, item reordering with Select and the remaining field items such as Repel (each gives a notice and changes nothing; the Escape Rope runs since the Fly section below). Rare Candy, evolution stones and vitamins run since the evolution section below; field moves, SEL and Select since the section after it.
 
 ## Implemented: evolution
 
@@ -185,7 +185,7 @@ The numbered sections below keep their full scope. Each one opens with a checkli
 - Field moves in the Pokémon submenu run their menu functions: the world checks the badge (`CheckBadge`: "Sorry! A new BADGE is required."), the facing tile, water or object, then the menu closes and the ROM's `…FromMenu` script runs for the chosen Pokémon (no "Want to …?" question): Cut (`CheckMapForSomethingToCut`), Surf (including "already surfing" and forced cycling), Strength, Flash (a `PALETTE_DARK` map or the Aerodactyl chamber; `BlindingFlash` sets the Flash flag), Whirlpool and Waterfall. Failures print the ROM's messages and return to the party menu.
 - Sweet Scent runs `SweetScentFromMenu`: where wild Pokémon can appear and the map has a rate, `ChooseWildEncounter` picks one without the rate roll and a battle starts; elsewhere "Looks like there's nothing here…".
 - Softboiled and Milk Drink give a fifth of the user's maximum HP to another Pokémon that has not fainted and is not at full HP; the user needs more than that fifth.
-- Fly (outdoors with the Storm Badge), Dig (in caves), Teleport (outdoors with a spawn point), Headbutt (facing a tree) and Rock Smash (facing a rock) run their checks and messages, then give a notice: the Fly map, dungeon and spawn warps, tree encounters and rock encounters are not ported.
+- Headbutt (facing a tree) and Rock Smash (facing a rock) run their checks and messages, then give a notice: tree and rock encounters are not ported. Fly, Dig and Teleport run since the section below.
 - SEL registers an item that `CANT_SELECT` allows (in practice key items) in `wWhichRegisteredItem` and `wRegisteredItem`, which saves keep. Select runs `SelectMenu`: `CheckRegisteredItem` (a slot that no longer holds the item clears the registration; a registered ball is never found, as in the original) and `UseRegisteredItem` by field menu. The Bicycle uses `Script_GetOnBike_Register` and `Script_GetOffBike_Register`, without a message; elsewhere Oak objects. Without a registration Select explains SEL. This replaces the earlier Key Items shortcut.
 - Bill's PC's MOVE PKMN W/O MAIL: refused while a party Pokémon holds MAIL, then "Each time you move a POKéMON, data will be saved. OK?". Choose the party or a box, a Pokémon (MOVE, STATS, CANCEL), then a box and the position to insert before. The party keeps its last Pokémon and its last healthy one, a different full box or party has "no room", a Pokémon moved down its own list lands one place earlier (`.CheckTrivialMove`), a boxed Pokémon joining the party gets its stats with full HP and no status (`CalcBufferMonStats`), and one entering a box gets its PP restored. The original's left/right box switching is presented as a list of boxes; after "no room" the box is chosen again rather than the position.
 - Save format 3 gained `registeredItem`, migrated by absence to none.
@@ -223,6 +223,15 @@ The numbered sections below keep their full scope. Each one opens with a checkli
 - The four bytes (`wOptions`, `wTextboxFrame`, `wGBPrinterBrightness`, `wOptions2`) are kept in the script state, so they change on the start menu's draft and commit when it closes. Save format 3 gained `options`, migrated by absence to `DefaultOptions`.
 - In effect: the battle style (`CheckWhetherToAskSwitch`: SET makes no offer when a trainer sends out its next Pokémon) and the menu account (`StartMenu`'s descriptions). Not yet: text speed (native text appears at once), the battle scene (no move animations), sound (no audio), printing and the textbox frame. The catching tutorial's temporary medium text speed has nothing to change.
 
+## Implemented: Fly, Dig, Teleport and the Escape Rope
+
+- Fly needs the Storm Badge and an outdoor map, then opens `_FlyMap`: the Johto map (Kanto's only once Indigo Plateau's flypoint is visited; before that the Johto map shows no player icon), "Where?" with the flypoint's name, the player's place and the Fly user's party icon on the selected flypoint. New Bark Town (or Indigo Plateau in Kanto) is the default, visited or not; up and down move to the next or previous visited flypoint with wrapping, A flies there, B returns to the party menu. Flypoints are read from `Flypoints` and visits from `wVisitedSpawns`, the `ENGINE_FLYPOINT_*` flags that town callbacks set.
+- `FlyScript`: `FlyFromAnim` hides every object while the party icon waits 64 frames and rises off the screen, swaying (`SpriteAnimFunc_FlyFrom`), the player arrives at the flypoint's `SpawnPoints` entry facing down (`MAPSETUP_FLY`), and `FlyToAnim` brings the icon down onto the player (`SpriteAnimFunc_FlyTo`). The icon flaps its wings with `SPRITE_ANIM_OBJ_RED_WALK`'s frames. The leaves and the sound are not presented.
+- Teleport works outdoors when `wLastSpawnMapGroup/Number` is a spawn point (`IsSpawnPoint`): "Return to the last POKéMON CENTER.", `teleport_from`, the spawn point facing down, then `teleport_to`. Otherwise "Can't use that here.".
+- Dig and the Escape Rope work in caves and dungeons once `wDigWarpNumber` is set: `EnterMapWarp`'s `SaveDigWarp` records the warp of any step from an outdoor map into an indoor one (houses included, as in the original; not from Mount Moon Square or Tin Tower's roof). The ROM's `UsedDigScript` or `UsedEscapeRopeScript` digs out (`step_dig`, hidden), arrives on that warp through `MAPSETUP_DOOR` and returns (`return_dig`); a cave entrance then walks the player out. Dig elsewhere says "Can't use that here."; the Escape Rope fails silently, then Oak warns, and is used up only on success. In the Kabuto chamber the rope opens the wall (`SpecialKabutoChamber`).
+- `newloadmap` now stops its script and resumes it on the new map, which these scripts need for their landing movements. Save format 3 gained `digWarp`, migrated by absence to none.
+- Unreachable in normal play so far: the Storm Badge, caves (Dark Cave is beyond Route 31) and flypoints beyond Cherrygrove. A destination that is not ported gives a notice. `JumpRoamMons` waits for roaming Pokémon.
+
 ## Native battles: current state
 
 The battle core, ROM tables, encounter hooks, battle UI and whiteout hooks are present. Unit tests cover wins, escape, loss, experience, move learning and capture; reference tests compare damage, type effectiveness, stat calculation and experience curves. Browser tests drive a test-only wild encounter through the real UI: victory with level-up and move learning, escape, whiteout, catching with a nickname, keyboard and on-screen D-pad menu navigation, mid-battle backup restore, rollback of unsupported effects, switching through the party menu and a Potion from the Items pocket. Real Route 29 encounters now use the ROM's encounter tables. Only the special Kurt and Park balls remain unported among battle items.
@@ -305,7 +314,7 @@ Introduce native player, party, Pokémon, inventory, money and quest models. Rea
 
 Expand script calls, choices, scene state, inventory commands and native special handlers. Translate routines reached through assembly calls into explicit native services; never fall back to emulator execution in the shipping game.
 
-Meeting Mom, Elm's introduction, the starter, the aide's Potion, Route 29, Cherrygrove, Route 30's trainers, Mr. Pokémon's house, the Cherrygrove rival battle, the return to Elm, capture, the catching tutorial, the PC, the introduction's naming and clock screens, and switching and healing items in battle run now. The opening milestone is complete within the recorded acceptance boundaries. The start menu, party menu and pack now run outside battle, and Pokémon evolve. Field moves from the menu, SEL/Select and MOVE PKMN W/O MAIL run too, and the Pokégear's clock, map and phone cards, with calls to Mom and Elm, Mom's bank at home and her purchases, the trainer card with the play time, and the options. Next: the Fly map and Teleport/Dig warps.
+Meeting Mom, Elm's introduction, the starter, the aide's Potion, Route 29, Cherrygrove, Route 30's trainers, Mr. Pokémon's house, the Cherrygrove rival battle, the return to Elm, capture, the catching tutorial, the PC, the introduction's naming and clock screens, and switching and healing items in battle run now. The opening milestone is complete within the recorded acceptance boundaries. The start menu, party menu and pack now run outside battle, and Pokémon evolve. Field moves from the menu, SEL/Select and MOVE PKMN W/O MAIL run too, and the Pokégear's clock, map and phone cards, with calls to Mom and Elm, Mom's bank at home and her purchases, the trainer card with the play time, the options, and Fly, Dig, Teleport and the Escape Rope. Next: Headbutt and Rock Smash encounters.
 
 Complete and validate the native battle engine: deterministic randomness, stats, move selection, accuracy/critical checks, damage, status, turn order, switching, fainting, experience, capture and rewards. Compare controlled seeds and states with the original, including integer rounding and overflow behavior.
 

docs/SESSION_HANDOFF.md

@@ -966,3 +966,54 @@ No emulator comparison; no CI or physical-device run.
 
 Next: the Fly map and Teleport/Dig/Escape Rope warps (board #25), which
 need script commands after a warp; then Headbutt and Rock Smash (#26).
+
+The options increment was committed as `c4cc0e7` (`Closes #24`). Not pushed.
+
+## Fly, Dig, Teleport and the Escape Rope: 2026-10-02
+
+Resumed with "continue" on a clean tree after `c4cc0e7`, taking board card
+#25.
+
+- `src/game/scripts/fly-map.ts` (`flyMap`): `_FlyMap`/`FlyMap` inside the
+  start menu run, before the world queues `FlyFunction.FlyScript`. Region
+  by the current landmark (Kanto only with Indigo Plateau's flypoint, else
+  Johto without the player icon), default New Bark/Indigo, up/down over
+  visited flypoints with wrapping (refused if none is visited, where the
+  original hangs), A returns the spawn, B goes back to the party menu.
+  `flymap` effect answered with buttons (`FLY_MAP_BUTTONS`).
+- Visits: `assets.spawnEngineFlag` inverts the ROM's `EngineFlags` over
+  `wVisitedSpawns` (Union Cave and the Fast Ship have no flag).
+  `assets.spawnPoint`/`spawnIndex` read `SpawnPoints` (`IsSpawnPoint`).
+- Interpreter: `newloadmap` handles `MAPSETUP_WARP`/`TELEPORT`/`FLY`
+  (spawn from `fieldMove.spawn` or `GetWhiteoutSpawn`) and `MAPSETUP_DOOR`
+  (`fieldMove.warp`, resolved by the world), then stops; the `warp` effect
+  carries `resume` unless only `end`/`endall` follows, and refuses inside a
+  call. The world's `finishScript` starts the rest of the script right after
+  entering the map, with the same field-move context (`ActiveScript.fieldMove`).
+  `door` warps keep the facing unless `FACE_DOWN_ON_WARP`.
+  `FieldMoveContext` is now one exported type.
+- `fly` effect (`FlyFromAnim` 65 ticks, `FlyToAnim` 33): `poses()` is empty,
+  `world.flyingIcon` replays `SpriteAnimFunc_FlyFrom`/`FlyTo` with the
+  ROM sine table, and the renderer draws `assets.monIcon` with
+  `RED_WALK`'s nine-frame flaps in object palette 0. Leaves not drawn.
+- World: `SaveDigWarp` in `prepareWarp` (outdoor to `CheckIndoorMap`, not
+  from 15:10/15:12); `digWarpMove` for Dig and the Escape Rope (with
+  `SpecialKabutoChamber`); Teleport through `IsSpawnPoint`; an unported
+  destination gives a notice. Saves gained `digWarp` (absent → null).
+- Start menu: `{ flyMap: true }` verdict, `host.flyTo`, `host.escapeRope`
+  (`MENU.EscapeRopeEffect`: `UseDisposableItem` only on success; failure
+  falls to Oak's warning), `host.visitedSpawn`.
+- UI: `#fly-map` with the bubble and the Town Map (`drawTownMap` takes an
+  optional `player` and a `species` icon). Checked visually at desktop and
+  390px widths, including the flight and landing.
+
+Checks: 423 unit tests with the local ROM (134 passed, 289 skipped without
+it; new `tests/fly-dig-teleport.test.ts`); 121 Chromium/WebKit browser tests
+passed, 19 skipped intentionally (a new Fly flow in both browsers, with a
+"fly" fixture room); native and reference builds; reference, vendor and
+release checks; `git diff --check`. No emulator comparison of the flight
+paths or warps; no CI or physical-device run. None of it is reachable in
+normal play yet (no Storm Badge, caves or further flypoints); Teleport
+works after a Pokémon Center visit for a Pokémon that knows it.
+
+Next: Headbutt and Rock Smash encounters (board #26).