Welcome to the Pokémon Roguelike/Extraction Hybrid project! This repository contains the code and data modifications for a unique take on Pokémon Essentials, combining roguelike dungeon crawling, extraction shooter loot mechanics, and Nuzlocke permadeath rules.
The game leverages Pokémon Essentials' built-in Overworld_RandomDungeons module. Dungeons are generated procedurally, and players must navigate through floors, battling encounters and gathering loot.
After a dungeon floor generates, the game dynamically spawns "VIP Trainers" (bosses or teleporters) and Loot Chests. Loot chests are populated using custom item/TM randomizer plugins, ensuring a varied experience every run.
At key points, players can choose to Continue deeper into the dungeon or Extract to return to the Hub.
- Snapshotting: The player's Bag is snapshotted at the start of a raid.
- Blackout: If the player blackouts (loses all Pokémon), their Bag reverts to the snapshot, losing any non-Key Items found during the run.
- Extracting: Successful extraction secures the loot, allowing the player to deposit it in the standard Pokémon PC, which serves as both an "Item PC" and "Stash".
Any Pokémon in the player's party that hits 0 HP is considered permanently dead. At the end of every battle, fainted Pokémon are automatically moved to the "Graveyard" PC box. Whenever the player accesses the PC, the Graveyard box is automatically purged (Pokémon are released) to prevent overflow.
To maintain the integrity of the permadeath rules, revival items (e.g., Revive, Max Revive) are blacklisted and dynamically prevented from spawning in loot chests by scanning the item PBS data for revival effects.
- Version Lock: Strictly built on Pokémon Essentials v21.1. All Ruby (RGSS) scripts adhere to v21.1 syntax.
- Asset Management: This repository strictly contains code, scripts, and PBS files. Visual and audio implementation is handled manually in RPG Maker XP. Reference PBS files directly when calling specific Pokémon, Item, or Move names.
We have implemented a system to easily spawn dynamic trainers on randomly generated maps, consolidating randomization, graphics updates, and battle logic using the pbDynamicTrainer alias (which resolves RPG Maker script box syntax crashes).
- Setup: Place the script call (e.g.,
pbDynamicTrainer("A")) on Page 1 as a Parallel Process. Calling it this way automatically pulls from the entire available pool of standard trainers. It updates the overworld graphic instantly on map load and then automatically turns ON Self SwitchD. - Interaction: On Page 2 (Condition: Self Switch
Dis ON, Trigger: Action Button), add the exact same script call. Because the script detects the trainer is already set up, it safely skips the graphic generation phase and initiates the pre-battle message and combat. If the player wins, it turns ON your specified victory switch (defaultA) to transition to the defeated NPC page. - VIP Bosses: The setup is exactly the same! Simply name your event "VIP" in the top-left of the editor, and
pbDynamicTrainerwill natively detect it and assign a boss fromDYNAMIC_VIPS. On Page 3 (Condition: Self SwitchA), add thepbDefeatedVIPscript call so the player can extract.
Dungeon floors use the core Essentials Overworld_RandomDungeons generator (Dungeon = true). Because standard static RPG Maker events would spawn in walls or the void on procedurally drawn maps, a custom Ruby hook intercepts the map generation.
- Mobile-Optimized Detection: Instead of a heavy full-map scan that strains mobile CPUs, the system uses a random coordinate sampler. It validates tiles by performing dual checks: it ensures the tile is passable (walkable) and checks that it matches a valid Terrain Tag.
- Event Teleportation: The spawner identifies predefined dynamic entities (e.g., VIPs, standard Trainers, and Loot Chests) strictly by their Event Name in RPG Maker. These events are then safely teleported (
.moveto) onto the valid coordinates before the player gains control.
The system completely replaces traditional RPG Maker Variable tracking with a custom Ruby module. It stores the current_raid_floor inside $PokemonGlobal (so it persists across saves) and dictates automated map transfers. NPCs like the Challenge Guide (Steven) only need to call pbStartRaid (which maps to RoguelikeExtraction.resume_or_start_raid) to intelligently route the player to the next correct floor based on their progress.
The RaidTracker module also fully manages the player's inventory during a raid:
- Start: When a raid begins, it generates a hash of
$PokemonBagtracking all non-Key items and their quantities. - Extract: When calling
pbExtractRaid, the raid ends successfully. The floor resets to 0, the snapshot is cleared, and the player retains all their gathered loot. - Blackout: When calling
pbBlackoutRaid, the player fails the raid. The floor resets to 0, and the script purges the player's inventory, completely restoring the original snapshot state (meaning all unextracted non-Key loot is permanently lost).
- Hardcore Mode: Triggered by a configurable game switch. When active, blacking out results in a total loss of the player's Bag (minus Key Items), rather than just reverting to the start-of-floor snapshot. It also triggers a "Soft Reset" on the player's party: surviving Pokémon are sent to the Graveyard, and a random Pokémon from the PC is drafted to save the run. If the PC is empty, the
RAID_BLACKOUT_SWITCHturns ON, forcing the player to start over entirely with a new starter. - Secure Pouch: A functional Key Item that completely bypasses both Standard and Hardcore blackout mechanics. The pouch contains its own array (
$PokemonGlobal.secure_pouch_items) and capacity limit. Players can manually interact with theSECUREPOUCHfrom their bag to deposit or withdraw stacks of items they want to guarantee they extract with.
- To enforce extraction game mechanics and prevent a known tile-generation glitch with
Overworld_RandomDungeons, saving the game via the start menu is completely disabled while the player is inside an active raid floor. Players must find an extraction point and return to the Hub if they wish to save.