v21.1 Common Developer Issues N/A

I've noticed a few issues tend to come up more often for new devs, and I figured it'd be nice to have one place to stash them all rather than always linking back to threads.

These are written for v20 Essentials, and I will be trying to keep it current for any future Essentials updates. Depending on the topic, though, some solutions may still be applicable for prior versions. (Stuff not directly affected by Essentials like tiles and image editing will remain the same)

The wiki has a similar guide here. There'll be a bit of overlap, but I'm trying to keep this from being too redundant.

These instructions say to compile my game - how do I do that?​

Compiling can be triggered automatically (if the game detects changes like new maps added or recent changes to the PBS files), or manually by starting the game in debug mode and holding Ctrl with the game window active. (If you just want to compile plugin scripts, hold the Shift key) You can also force compile by deleting PluginScripts.rxdata from the Data folder.

When you compile, your console will show a message saying that it compiled.

I’m getting an error message saying that I’m missing a .dat file!​

.dat files are created when the game compiles the PBS files. As part of the compiling process, the game deletes the original .dat files. This means that if you close while the game is in the middle of compiling, there will be some .dat files that it deleted but it didn't remake yet. Luckily, the solution is the same as the cause - just compile the game again, but let it finish compiling this time.

The game isn't recognizing that I've added/changed/removed a plugin!​

Recompile your plugins.

I’m walking through tiles I shouldn’t be able to/I can’t walk through tiles I should be able to!​

The most common cause of this is using an invisible tile to erase instead of using the actual eraser tiles.

Passability is typically determined by the tile that’s on top. You put a bridge tile over a water tile, you want the player to be able to walk on it, even if they can’t walk on water. You put a box on top of a floor tile, you don’t want the player to be able to walk on it, even if they can usually walk on the floor.

The game can't look at a tile and understand how it's supposed to function. If a tile is transparent, it doesn't think "there's no tile here" - it thinks "there's a tile here, but its graphic is totally transparent". That can lead to something looking right, but actually having a passable tile on top of a non-passable one, or vice versa.

When you erase a tile, you need to use the top left tile in your editor, the one next to all the autotiles.

This tells the game “There is not a tile here”, not just “there’s a tile here with a transparent graphic”.

To prevent this problem happening again, it's a good idea to fill all empty space in your tileset with placeholder graphics, like the red Xs in Essentials' tilesets.

If you've checked for invisible tiles (and you've actually checked by filling in blank spaces on your tileset - don't just assume "Well, I don't remember using an invisible tile, so that can't be the problem"), then it's possible the player has Through set on because of a move route. Check to see if they can pass through events as well, and if they can, use another move route to set Through back to off.

My water tiles disappear when I playtest!​

Reflective tiles are drawn underneath all other tiles in Essentials. If you have still water or a puddle, it's reflective, and shouldn't be on top of any solid tiles like grass.

I’m running in tall grass, but I’m not encountering any Pokémon!​

• Make sure you have Pokémon in your party.
• Make sure you set the terrain tag for your grass. (Should be terrain tag 2)
• Make sure you’re not holding Ctrl.
• Make sure you have encounters defined for the map.
• Make sure you’ve set the the right encounter version. Your PBS should start with just [MapID], not [MapID,1] - that’s creating encounters for encounter version 1 instead of encounter version 0. For more information, see https://essentialsengine.miraheze.org/wiki/Wild_encounters#Encounter_versions

Every time I encounter a Pokémon from Gen 6+, there’s just a ? instead of their sprite!​

Essentials only comes with the canon sprites for Pokémon up to Gen 5 - you’ll need to add the sprites for later Pokémon yourself. The most popular resource for this is the Gen 8 Project.

My encounters for regional Pokémon are just their normal forms!​

This is actually the same problem as the one above. If a Pokémon doesn't have a sprite for its alternate form, it'll default to its base sprite. Since regional forms were added in the 3D model games, there's no canon sprites for them, but you can find them in the Gen 8 Project as well.

How can I set a trainer to have a Pokémon with a specific form? I tried SPECIES_FORM...​

In v20, form is set as a property of a Pokémon, like name or shininess.

So rather than doing this:
You'll do this:

I added a new evolution to a Pokémon, but I'm getting an error about "undefined value in GameData::Evolution"!​

This can be a broad issue - any time you add an evolution where the method is not defined in the scripts, you'll get this error. But the most common cause is misaligning values, especially when adding evolutions to existing Pokémon.

Evolutions are always formatted as SPECIES,Method,parameter. If you have a method with no parameter (like most friendship-based evos), you still have to add another comma, because without it, the game will mistake your next species for its parameter.

This happens with Eeveelutions a lot - people will have something like this:
The game reads this as “evolves into Espeon with the method HappinessDay and parameter UMBREON”, “evolves into HappinessNight with method NEWSPECIES”, and then returns an error because there’s no evolution method named NEWSPECIES.

It should look like this:

My Pokémon changed level when it evolved!​

Evolved Pokémon need to have the same growth rate as their pre-evolution.

My game crashes when I heal with Nurse Joy! It says something about "undefined method `pattern=' for nil:NilClass"?​

The healing animation in PMCs involves both the nurse and the healing machine. This means that the nurse event has to refer to the healing machine event, and events refer to each other using their ID number.


If you just copy+paste events from one map to another, you'll likely be copying them out of order. (Which usually isn't an issue, except for when you have events that refer to other events like this) Some event commands will just adapt to this without providing an error message. (For example, if you had a Set Move Route command moving Event 4, and there was no longer an Event 4 on the map, then it would just skip over that command when it got there.) Script commands like .pattern tend to return errors because you can't really build a failsafe for every possible error in a script.

Remember, too, that this can cause problems beyond just an error message! If I had an NPC as event 4, my game wouldn't crash, but it would be affecting the NPC when it should be affecting the healing balls!

To solve this on one specific map, just find your healing balls event and check its ID, then change the 4 in get_character(4).pattern = 0 to the correct ID.

To prevent this issue in the future, if you want to copy a map and its events, just copy+paste the map from the map list.

This will copy both events and tiles to the new map.

When I transfer to a certain map, the game freezes!​

You probably have an autorun event someone on the map that's not closing. Autorun events loop until you tell them to stop by moving to another page, and they don't let anything else process while they're running.

The solution will depend on what your autorun event is supposed to be for - maybe you just need to turn on a self switch and move it to another page, maybe you can use another trigger, etc.

I tried to upscale some graphics, but they're blurry!​

This is just a matter of messing with the settings on your image-editing program of choice. (I only use PaintDotNet, so I'm grabbing screencaps from other guides, apologies if they're out-of-date)

PaintDotNet - Set Resampling to Nearest Neighbor.

GIMP - Set interpolation to none.

Photoshop - Set interpolation to Nearest Neighbor.


Make sure you're keeping proportions the same, too. (Scale to 200%, not 150% or anything in-between.)

You may also be interested in this Bulk Sprite Resizer.

This music I added won't play!​

• Does your file have any special characters in it, like é?
• Is your file a .ogg? (Other filetypes like .mp3 sometimes work, but .ogg seems to have the most success)
• Is your PokéGear's radio overriding it?
• Is BGM volume set to 0 in your options?
• Is the volume set to 0 in the command starting the music?
• Is your game muted in your system's volume mixer?

When I look at a Pokémon's area in the PokéDex, I get an error about "Message: undefined method `[]' for nil:NilClass", "282:UI_Pokedex_Entry:312:in `block in pbGetEncounterPoints'"​

You need to add the region map position for one of your maps in Metadata. (This is the MapPosition value)

No, that's not the PokéDex error I'm getting... it's "Message: undefined method `[]' for nil:NilClass", "UI_Pokedex_Entry:26:in `pbStartScene'"​

You're missing town map data for the whole region. (Remember that if you have regional dexes, the game assumes each is for a different region, so Regional Dex 2 will need to have town map data for Region 2)

I'm getting an error about "Message: undefined method `width' for nil:NilClass"?​

You've got a missing graphic somewhere. This can appear anywhere in your game, it just depends on what graphic is missing. Try to think about what graphics would be needed when you're getting the error message, or follow the backtrace. (Check out my Anatomy of an Error Message guide for more information on backtraces)

The most common ones I see with this are a missing trainer backsprite (the backtrace will mention ballTracksHand) or a missing player overworld (the error happens when naming the player).

I can't load my save! I get a message about an undefined class/module, SaveData:28:in `load'​

The class/module mentioned varies - I've seen "Quest", "Badgecase", "Game_PokeEvent", "SecretBase", "Adventure", and "DynamaxAdventure". But the cause and solution in all of these is the same: You added a plugin that stores something in save files, saved your game, and then removed it. Now when the game looks at your save, it has some information it doesn't know what to do with. You can fix this by adding the plugin back in or deleting your save. (If you don't know where that is, see here.)

These instructions say to put the code in a new script section above Main - where the heck is that?​

Main is the bottom script section in the script editor. You can create a new script section by right clicking and hitting Enter. (or hitting the Ins key on your keyboard, if you have one)

Every time I go to a new map, I get an error message saying Unknown ID 22, or some other number!​

In v21, you need to create map metadata for each new map you create.

I gave the player a PokéDex, but it isn't showing up in the pause menu!​

The PokéDex only appears if there's at least one species seen in the current regional dex. Make sure you've given the player a Pokémon, and, if you have, make sure you've got your regional dex set up correctly.

The enemy trainer won't Mega Evolve!​

• Is the No Mega Evolution switch turned on?
• Did you give them a Key Stone?

See also:

I can't figure out how to make TMs infinite use!​

Starting in v20, TMs in the default Essentials items.txt have their FieldUse property set to TR, meaning they'll be consumed after use. Just change the FieldUse to TM instead. (You can do a find-and-replace with Ctrl+H, replacing FieldUse = TR with FieldUse = TM)
For more information, see:

I can't figure out how to make this item untossable!​

An item is only tossable if it doesn't have the KeyItem flag (regardless of what pocket it's in), and if its field use isn't set to TM or HM. If this is true for your item, remember that you can still toss items in Debug mode regardless of their properties.

I can use field moves even though I don't have the right badge/don't have a Pokémon with the move!​

Debug mode lets you use field moves regardless of these factors, to make it easier to move around. Check out the wiki article on Debug mode to see what else Debug mode allows you to do that wouldn't normally be possible in-game.

I'm getting an error message about "permission denied"?​

Something is blocking access to your files. This could be an antivirus, or it could be because the file's been set to admin only.

I'm getting an error message that says "No game scripts specified" (Missing game.ini?)"​

• Is Game.ini in your game folder?
• Does your filepath have any special characters in it?
• Is your filepath especially long?