Documentation
Reference notes for creating and injecting custom Pokemon cleanly.
Game Download
Full offline gamePortable ZIP. Extract it and run the game without installing.
Offline installerInstaller build for offline play that can also access the official online PokeRogue version.
Patch locationApply custom patch bundles to the same offline game folder you actually run.
After patchingClose the game, reopen it, then hard reload or clear cache if the custom Pokemon does not appear.
How It Works
Create bundleThe web form validates your Pokemon, converts sprites, and generates a ZIP patch bundle.
Local installExtract the ZIP near your PokeRogue folder and run INSTALL.bat or node apply-patch.js.
Local filesThe online web app cannot read your local game files; local checks run inside the installer.
ID conflictIf the local installer finds the same custom ID, it asks whether to replace it, choose another ID, or cancel.
Game restartClear cache and restart PokeRogue after applying a patch. Test with a new save slot first.
Sprite Requirements
RequiredFront sprite PNG is required. JSON is optional.
Supported JSONTexturePacker, Aseprite, raw dict, and raw list atlas formats are supported.
PNG onlyWithout JSON, Auto can detect grid sheets, separated sprites, or one static frame.
OffsetsDefault PokeRogue atlas offsets are preserved to avoid jitter and cropped sprites.
FallbacksMissing back or shiny sprites fall back to the available regular sprite. Icon is auto-generated if omitted.
File limitsMain sprite PNG max 5MB, atlas JSON max 1MB, icon max 512KB, Pokemon sound max 2MB.
IconIcons are resized with nearest-neighbor pixel scaling for the PokeRogue icon atlas. Use transparent PNG for best results.
Sprite Size and Battle Scale
Size profilesTiny: target 40px, max 44px; Small: target 56px, max 64px; Medium: target 76px, max 84px; Large: target 96px, max 104px; Titan: target 120px, max 128px; Colossal: target 150px, max 150px
Sizing basisTiny through Colossal are based on the visible Pokemon body, not the transparent canvas around it.
Auto sizeAuto keeps the detected visible body scale safely. Pick a manual size when the character looks too small or too large.
ColossalColossal is capped at 150px. Use it only for extremely large characters, not just high detail artwork.
PaddingKeep Original preserves uploaded frame padding. 0px crops to the visible body. Auto crops and adds a safe shared edge.
Battle PresenceNormal: 1x; Hero: 1.1x; Boss: 1.25x; Giant: 1.35x; Cinematic: 1.5x
Important differenceSprite Size changes exported PNG frame/body size. Battle Presence changes in-battle render scale only.
Giga defaultCustom Gigantamax forms stay Normal battle presence by default, so they do not automatically become 1.5x.
PreviewThe web battle preview shows Battle Presence as a visual guide, but it does not rewrite the source PNG.
Moves and Abilities
Move groupsStarter, level-up, egg, and TM moves are separate lists and are all written into the generated patch.
Starter movesUse 0-4 starter moves. These are the moves available when the Pokemon starts a run.
Level movesUse up to 29 level-up rows. Levels should be 1-100 and can include evolution-style moves.
Egg movesUse up to 4 egg moves. Unlocking egg moves is controlled from Advanced starter options.
TM movesUse up to 40 TM compatibility moves from the official TM list.
Quick movesQuick/Random fills starter, level, egg, and TM moves with type-aware choices and avoids duplicate move entries.
Ability slotsEach Pokemon can have Ability 1, Ability 2, Hidden Ability, and one Passive Ability. Ability 2 can be NONE.
Changing abilityThe active regular ability is chosen on the starter select screen when multiple abilities are unlocked. It is not freely changed during battle.
PassivePassive must be unlocked and enabled before it applies. Advanced starter options can seed passive unlock and enabled state.
Wonder GuardWhen Wonder Guard is active, PokeRogue forces max HP to 1. For that stage or form, keep HP, Def, and Sp. Def low; earlier evolutions without Wonder Guard can still use normal bulk.
Evolution and Forms
Evolution 1Evolution 1 can evolve from Basic or another selected valid source depending on the target setting.
Evolution 2Evolution 2 can continue the chain or be used as another branch when configured that way.
Moves on evolutionEvolution stages can copy Basic moves once, then be edited independently. Later Basic edits do not overwrite them unless copied again.
Mega and GigaMega and Gigantamax are battle forms attached to Basic/Evolution species, not separate new Dex IDs.
Applies ToIf Basic has no evolution, Mega/Giga can attach to Basic. If evolutions are enabled, choose which stage the form applies to.
Random Mega/GigaWorld settings can use Random Mega/Giga for boss or trainer encounters when the same species has both enabled forms. PokeRogue seeded randomness picks one when the encounter is created.
Dynamic formDynamic Battle Form uses an engine-backed trigger such as HP below half. The selected Pokemon must have the required engine ability.
ID Rules and Safety
Allowed rangeDex ID must be 2000-99999. The 9000+ range is recommended for custom Pokemon.
Reserved IDsDefault PokeRogue IDs are blocked before the ZIP is generated.
BackupsThe local installer creates .bak files for the main JS bundles before patching.
Spawn placementWorld tab separates normal wild, wild boss, and trainer-pool placement so boss rarity no longer mixes with normal wild rarity.
Trainer Pokemon rarityTrainer Type chooses who may own the Pokemon. Trainer Pokemon Rarity chooses how rare that Pokemon is inside the eligible trainer party; Champion does not automatically mean Ultra Rare.
Trainer safetyUse low appearance chance and max 1 per trainer party for powerful custom cameos, especially Champion, Rival, and Evil Boss placements.
Random biomeUse Random Biome when you want Forge to choose one valid wild biome during export.
Form indexNormal form is index 0. Enabled forms on the same species become 1, 2, 3 in order, so users should choose normal/mega/giga/random mega-giga instead of typing an index.
Replace safetyIf multiple custom patches collide on IDs, the installer asks for safe replacement or new IDs before applying.
RollbackIf a critical patch step fails, the installer restores the backed-up game files instead of leaving a half patch.
Save Data Location
Windows pathPokeRogue offline saves are stored under %APPDATA%\PokeRogue, not inside the copied game folder.
Main save storageThe most important folder is %APPDATA%\PokeRogue\Local Storage\leveldb. It contains the Chromium local storage used by the Electron app.
Cleaner resetIf leveldb is not enough, close PokeRogue and remove %APPDATA%\PokeRogue\Local Storage to reset the whole Chromium local storage area.
Extra browser dataIf old data still appears after that, also remove %APPDATA%\PokeRogue\IndexedDB. This is usually not needed, but it is safe to reset after backing up.
Why copies share savesAll copied PokeRogue folders use the same Electron app profile name, so they read the same save data from AppData. Copying D:\PokeRogue does not create a separate save.
Open quicklyIn Windows CMD or Run, use: explorer "%APPDATA%\PokeRogue"
Backup firstClose every PokeRogue window before copying, deleting, or restoring this folder. Back it up before testing heavy custom patches.
What gets deletedDeleting this storage removes runs, Pokédex progress, candies, vouchers, ability/passive unlocks, cost reduction, egg move unlocks, and other local progress.
Custom progressThis reset also removes custom Pokemon unlock progress such as custom ability, passive, candy, cost, and egg move unlocks stored in the save data.
Custom files stayResetting save data does not remove patched custom Pokemon files from the game folder. To remove the custom Pokemon itself, restore a clean game backup or replace it with a new patch.
Custom starter unlocksA patched custom starter can appear again after storage deletion because the patched game code can seed it back into starter data when the game initializes.
Stats, Cost, and PvP
Single statsEach stat HP, Atk, Def, Sp. Atk, Sp. Def, and Speed must stay between 1-255.
Forge freedomThe main Forge and marketplace allow any total BST inside the per-stat limit. This keeps custom assets creative.
Starter costStarter Cost uses 1-10. Use higher cost for stronger or legendary-tier custom Pokemon.
Ability impactCost is not only BST. Very strong abilities, passives, immunities, or battle forms may deserve a higher cost even when the raw stats look fair.
PvP balanceOnline PvP is stricter than Forge. A Pokemon must fit its Cost vs BST limit before queueing.
PvP limitsCost 1: max BST 320; Cost 2: max BST 380; Cost 3: max BST 440; Cost 4: max BST 500; Cost 5: max BST 560; Cost 6: max BST 620; Cost 7: max BST 680; Cost 8: max BST 740; Cost 9: max BST 820; Cost 10: max BST 900
Old importsIf an older PvP import has no cost snapshot, PvP reads the original config cost when available, otherwise it falls back to Cost 3.
Online PvP Setup
StatusOpen /pvp and check the engine status card. PvP is usable only when it says PokeRogue source adapter: playable.
Start serverRun RUN_PVP_SERVER.bat from the web folder before using Quick Match or Test vs Bot. The health URL is http://localhost:8787/health by default.
Prepare clientIf the arena page cannot launch, run PREPARE_PVP_CLIENT.bat once to copy the patched PokeRogue client into public/pokerogue-pvp-client.
Supabase dataApply supabase/migrations/007_pvp_core.sql before using Team Builder. PvP teams and imported characters are stored in Supabase under the logged-in user.
Team BuilderImport a Forge JSON, patch ZIP, or marketplace asset, then choose exactly 3 active Pokemon with 4 PvP-known moves each.
Practice firstUse Test vs Bot before Quick Match. It uses the same server and PokeRogue worker path, so it catches most setup issues early.
Smoke testRun npm.cmd run pvp:websocket:smoke to start a temporary local PvP server and verify auth, practice start, ready state, move action, and turn resolution.
Server refreshThe /pvp page refreshes engine health automatically every few seconds. Use Refresh Status if you started the server after opening the page.
Art, Shiny, and Sound
Transparent artUse transparent PNG. White or solid backgrounds will appear in-game unless removed before upload.
Pixel styleHD modern pixel art works best when resized with crisp pixel edges and a clean transparent frame.
Front and backFront faces the player as the enemy view. Back faces the opponent as the player-side view.
ShinyShiny does not use a separate Dex ID. Shiny front/back sprites share the same species ID and variant handling.
Missing shinyIf shiny files are omitted, the patch uses the normal sprite as the shiny fallback.
Pokemon soundUse short M4A cries when possible. The web accepts limited sound files and copies them into the local patch bundle.
Marketplace Setup
Supabase keysSet NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY only. Never use a service role key in the web app.
Auth modeUse email and password auth, then turn off email confirmation in Supabase if you want no-verification login.
DatabaseApply supabase/migrations/001_marketplace.sql first, then 002_marketplace_hardening.sql, 003_marketplace_performance_events.sql, 004_marketplace_price_gallery_limit.sql, and 005_marketplace_favorites_sorting.sql.
Selling flowCreators publish listings and send buyers to their own Ko-fi link. The web app tracks views and Ko-fi clicks, not payments.