External JSON files

(Redirected from External JSON file)

Certain aspects of Pixelmon, including special drops, NPCs, and structures, can be edited through JSON files. These files can be accessed by enabling the "useExternalJSONFiles" config setting and then starting Minecraft. The external JSON files will be created at the path, "<Minecraft directory>/pixelmon". JSON files can be edited with any plain text editor.

External JSON files should be edited carefully, and it is highly recommended to have knowledge of the JSON format before editing them. Incorrect editing of external JSON files can result in unexpected behavior when using Pixelmon features that rely on the external JSON files. However, deleting the external JSON folder will cause it to be regenerated with its default contents when Minecraft is started up again.

After editing external JSON files, they will need to be reloaded in order for the changes to take effect. Shopkeeper and NPC files can be reloaded in-game via the /pokereload command. All external JSON files are reloaded after restarting Minecraft.

When Pixelmon is updated, there may occasionally be changes to the external JSON files. These changes can be tracked in the external JSON file repository, and any customizations to the external JSON files can be merged with the default files as needed. Failure to update the external JSON files may cause problems if updates introduce new features that rely on changes to the external JSON files.

Examples of how to edit external JSON files can be found on this page.

Contents

Drops

Drops files are located at "<Minecraft directory>/pixelmon/drops". They allow modification of regular Pokémon drops, boss Pokémon drops, and special drops.

bossdrops.json

This file contains data about boss Pokémon drops and spawning data for Mega Evolved boss Pokémon.

  • "megaDrops": This array contains item IDs for the possible drops of uncommon and rare boss Pokémon.
  • "shinyMegaDrops": This array contains item IDs for the possible drops of legendary and ultimate boss Pokémon.
  • "bosses": This array contains spawning data for Mega Evolved boss Pokémon.
    • "name": The name of a Pokémon with a Mega Evolution.
    • "spawnlocation": The spawn location where the Mega Evolved boss Pokémon can spawn in.
    • "biomes": Unused.
    • "flying": This object contains data about the flying AI of an air or air persistent Mega Evolved boss Pokémon. These are the same flying parameters found in the Pixelmon database.
    • "swimming": This object contains data about the flying AI of a water Mega Evolved boss Pokémon. These are the same swimming parameters found in the Pixelmon database.

pokechestdrops.json

This file allows the special drop tables to be modified. The file contains three JSON arrays, "tier1", "tier2", and "tier3". Each array contains the item IDs of items that can be dropped in each special drop tier.

pokedrops.json

This file allows regular Pokémon drops to be edited. It is an array of JSON objects, one for each Pokémon. Pokémon that are not implemented in Pixelmon are also contained in this file, although these entries are currently unused by Pixelmon.

  • "pokemon": The name of the Pokémon whose drops are being defined in the object.

All other fields follow a similar format, but allow for multiple drops with different rarities and quantities to be defined. JSON keys are created by combining a drop type and a data type.

Drop types include:

  • "maindrop": The first item that the Pokémon can drop 100% of the time.
  • "optdrop1": The second item that the Pokémon can drop 100% of the time.
  • "optdrop2": The third item that the Pokémon can drop 100% of the time.
  • "raredrop": An item that the Pokémon can drop 10% of the time.

It is not necessary to include all four drop types in a drop entry; Pokémon can have up to four items to drop, but may also drop fewer than four items.

Data types include:

  • "data": The item ID of the item to drop.
  • "min": The minimum quantity of the item that the Pokémon can drop. This number can also be 0 for the item to not always be dropped (or to make the drop rarer for "raredrop") . If this field is omitted, its default value is 0.
  • "max": The maximum quantity of the item that the Pokémon can drop. If this field is omitted, its default value is 1.

Drop quantities are chosen uniformly randomly between "min" and "max", inclusive of both numbers.

Drop types and data types can be combined into the following JSON keys:

maindrop optdrop1 optdrop2 raredrop
data maindropdata optdrop1data optdrop2data raredropdata
min maindropmin optdrop1min optdrop2min raredropmin
max maindropmax optdrop1max optdrop2max raredropmax

NPCs

NPC JSON files are located at "<Minecraft directory>/pixelmon/npcs". It contains files used to define NPC data such as spawning details, dialogue, shopkeeper stock and sell prices, and NPC Trainer Pokémon.

NPC JSON files that contain dialogue must have file names suffixed by an underscore and the language code that correspond to the language that the dialogue is written in. For example, the American English version of the Blacksmith JSON file is named "blacksmith_en_us.json". Server-side information, such as the possible Pokémon an NPC Trainer can have, is always obtained from the American English version of the JSON file. Files in other languages are only used to obtain translation-specific data such as dialogue.

npcs.json

This JSON file contains data about NPC spawning rarity and which NPC JSON files to read. If a new NPC JSON file is created, the NPC must be added to this file in order for it to be registered by Pixelmon.

rarities

This array contains the rarities of each type of naturally spawning NPC (NPC Trainers, move tutors, move relearners, traders, and spawn shopkeepers).

  • "type": The type of NPC to define the rarity of ("trainer", "tutor", "relearner", "trader", "shopkeeper").
  • "rarity": The relative spawning rarity of the NPC. Spawning rarities are relative between NPC types; if one type of NPC has a rarity of 200 and a second type has a rarity of 100, the first NPC type will spawn twice as often as the second type. An NPC with a rarity of 0 will not spawn naturally.

The default NPC Trainer entry is shown below.

   {
     "type": "trainer",
     "rarity": 200
   }

trainers

This array defines the spawn rarity and textures that an NPC Trainer will use.

  • "name": Corresponds to the "trainerType" field in the "data" of the NPC Trainer JSON file.
  • "rarity": The relative rarity of the NPC Trainer compared to other NPC Trainers. If this field is omitted, the NPC Trainer will not spawn naturally and can only be accessed using an NPC editor.
  • "textures": An array of skin textures that the NPC Trainer can use, excluding the ".png" extension. Textures are located at "assets/pixelmon/textures/steve" in the Pixelmon jar file or a resource pack.

The Bug Catcher's entry is shown below.

     {
       "name": "BugCatcher",
       "rarity": 20,
       "textures": [ "bugcatcher1", "bugcatcher2", "bugcatcher3", "bugcatcher4" ]
     }

Other arrays

All other arrays in the npcs.json file define the NPC files to register for each type of NPC. The NPC files for each type are found at "<Minecraft directory>/pixelmon/npcs/<NPC type>". The only field of each array object is a "name" field, which defines the name of the JSON file to register. This name field should not contain the language code or ".json".

Array NPC type NPC folder
villagers Chatting NPC villagers
list NPC Trainer trainers
shopKeepers Shopkeeper shopKeepers
gymnpcs Gym NPC gyms

shopItems.json

This is a list of item IDs for items that are possible to buy from or sell to shopkeepers, along with the base buying price and the selling price of the item.

Existing buy and sell prices for items can be modified or removed. If an item has no sell price, the item cannot be sold to a shopkeeper. Items can also be removed from the list, although removing an item with a buy price also necessitates the removal of the item from all shopkeepers who offer the item in question.

Additional items can be added to the list, including from vanilla Minecraft and from other mods. An item only needs to have a buy price if the item can be bought from a shopkeeper; otherwise, it is only necessary to define a sell price. A sample JSON entry for a typical item (a Poké Ball in this case) is shown below.

{
     "name": "pixelmon:item.Poke_Ball",
     "buy": 200,
     "sell": 100
}

Custom damage values or NBT tags may be appended to items using "itemData" and "nbtData" fields respectively. When using these extra fields, an "id" field is also required in order to refer to the custom item from the shopkeeper JSON files. The format for NBT tags is the same format that can be used in certain commands like /give, and is detailed on this page. Note that any '"' characters will need to be escaped with a '\'.

Below is a sample JSON entry that uses all of the fields that can be used in the JSON, creating spruce wood planks (damage value 1) that have the description, "Wooden planks".

{
    "id": "sprucePlanksLore",
    "name": "minecraft:planks",
    "itemData": 1,
    "nbtData": "{display:{Lore:[\"Wooden planks\"]}}",
    "buy": 5,
    "sell": 2
}

Chatting NPCs

Chatting NPC JSON files are located at "<Minecraft directory>/pixelmon/npcs/villagers".

  • "skins": An array of "filename" fields defining all skin textures that the chatting NPC can use. Textures are located at "assets/pixelmon/textures/steve" in the Pixelmon jar file or a resource pack. The ".png" extension should be included in the file name.
  • "names": An array of "name" fields defining the possible names that the chatting NPC can be named. The name is displayed when talking to the chatting NPC.
  • "chat": An array of "lines" objects defining the lines of dialogue that the chatting NPC will say when talked to. This is split into multiple "text" fields so that the chatting NPC will say each batch of text one at a time (i.e., the player clicks to continue the dialogue).

A chat entry for the Artist chatting NPC is shown below.

       {
           "lines": [
               {
                   "text": "Ah, this town is so inspiring."
               },
               {
                   "text": "If only I had my easel with me; my mind is buzzing with artsy thoughts!"
               }
           ]
       }

NPC Trainers

NPC Trainer JSON files are located at "<Minecraft directory>/pixelmon/npcs/trainers". If a new NPC Trainer JSON is added, it will initially only be available through the NPC editor. By editing the Pixelmon database (specifically, the TRAINERTYPES and TRAINERSPAWNBIOMES tables), it is possible to make user-made NPC Trainers spawn naturally.

  • "data"
    • "trainerType": The ID of the NPC Trainer class, used by the "trainers" array in npcs.json to find this NPC Trainer's data.
    • "minLevel": The minimum average level of the NPC Trainer's Pokémon.
    • "maxLevel": The maximum average level of the NPC Trainer's Pokémon.
    • "minPartyPokemon": The minimum number of Pokémon that the NPC Trainer can have.
    • "maxPartyPokemon": The minimum number of Pokémon that the NPC Trainer can have.
    • "winnings": The base amount of PokéDollars that the NPC Trainer will award to the player upon defeat. This base amount is multiplied by the average level of Pokémon in the NPC Trainer's partty (rounded down) to produce a final PokéDollar amount.

The Blacksmith's data is shown below.

   "data": {
       "trainerType": "Blacksmith",
       "minLevel": 20,
       "maxLevel": 40,
       "minPartyPokemon": 1,
       "maxPartyPokemon": 6,
       "winnings": 32
   }
  • "pokemon": A list of "name" fields defining which Pokémon species the NPC Trainer can use.
  • "names": A list of "name" fields defining what the NPC Trainer's names can be. This name is used to refer to the NPC Trainer during battle.
  • "chat"
    • "opening": The NPC Trainer's dialogue at the start of the battle.
    • "win": The NPC Trainer's dialogue when the NPC Trainer defeats a player.
    • "lose": The NPC Trainer's dialogue when the NPC Trainer is defeated by a player.

The Blacksmith's chat data is shown below.

       {
           "opening": "My Pokémon are trained hard over the fires of endurance. They are invincible!",
           "win": "I did warn you! Nice try.",
           "lose": "Not as invincible as I thought.."
       }

Shopkeepers

Shopkeeper JSON files are located at "<Minecraft directory>/pixelmon/npcs/shopKeepers".

  • "data": This defines the spawning type of the shopkeepers; this can be either "PokemartMain", "PokemartSecond", or "Spawn".
  • "biomes": If the shopkeeper is a spawn shopkeeper, this list defines the biomes where the shopkeeper can spawn.
  • "textures": All possible skins for the shopkeeper are defined in this list. Any existing textures from assets/pixelmon/textures/steve can be used here, and a resource pack may also place skins at this location for custom skins to be used.
  • "names": This is a list of possible names for the shopkeeper. These names are displayed when talking to the shopkeeper.
  • "chat": This is a list of possible greetings and parting phrases for the shopkeeper. The messages should be paired together in a single object.
  • "items": This is a list of the items that can be sold by the shopkeeper.
    • The "name" field contains the item ID of the item to sell and is the only required field. If an item in shopItems.json has an "id" field defined, this ID is used to refer to that item here; otherwise, the item's "name" field (the item's internal Minecraft ID) is used.
    • The "multi" field is a multiplier that allows the particular shopkeeper type to offer an item for more or less than its base price as defined in the "shopItems.json" file.
    • The "rarity" field defines the chance (from 0 to 1) of the item appearing in the shopkeeper's stock each day. Leaving out this field causes the item to always appear in the shopkeeper's stock.
    • The "variation" field determines whether the item may randomly be priced at 10% above or below its usual price. By default, this is enabled.

A sample shopkeeper item is shown below. It causes the shopkeeper to have a 70% chance of selling Ultra Balls that are 10% above the normal price (as defined in shopItems.json) and do not vary in price.

{
     "name": "pixelmon:item.Ultra_Ball",
     "multi": 1.1,
     "rarity": 0.7,
     "variation": false
}

Another sample shopkeeper item is shown below. It causes the shopkeeper to always sell the custom spruce wood planks item defined above with its default base price, sometimes varying at 10% above or below this base price.

{
    "name": "sprucePlanksLore"
}

Gym NPCs

Gym NPC JSON files are located at "<Minecraft directory>/pixelmon/npcs/gyms". These files are used for editing flavor aspects of NPCs such as dialogue and skins. Data about the Pokémon used by Gym NPC Trainers is found in the structure JSON files.

  • "npctype": Either "trainer" or "chat" for an NPC Trainer or a chatting NPC.
  • "winnings": The base amount of PokéDollars that an NPC Trainer will award to the player upon defeat. This base amount is multiplied by the NPC Trainer's level to produce a final PokéDollar amount.
  • "skins": An array of "filename" fields defining all skin textures that the NPC can use. Textures are located at "assets/pixelmon/textures/steve" in the Pixelmon jar file or a resource pack. The ".png" extension should be included in the file name.
  • "names": This is a list of possible names for the NPC. The NPC's name is displayed when interacting with the NPC.
  • "chat": Depending on the NPC's type, the NPC's dialogue is formatted the same as either an NPC Trainer or a chatting NPC.

Structures

Structure JSON files are located at <Minecraft directory>/pixelmon/structures. This folder contains files that define Pixelmon structure aspects such as block composition, spawning details, and NPCs found inside the structures.

structures.json

This JSON file contains spawning data for all Pixelmon structures. It is split into three different arrays:

  • "towns" contains structures that spawn in towns.
  • "gyms" contains Gyms.
  • "standalone" contains all other structures that are not Gyms and do not spawn in towns.

Each array consists of structures of that array's type. The three different types of structures each have different fields that can be specified.

towns

  • "id": The ID of the structure when spawned via the /struc command
  • "filename": The block snapshot file that defines the structure's block data, relative to "pixelmon/structures/towns".
  • "weighting": Used to determine the relative rarity of spawning the structure. A higher weighting makes the structure spawn more commonly.
  • "depth": How far into the ground the structure will spawn at.
  • "maxnum": The maximum amount of structures of this type that can spawn in a town.
  • "npcs": Data about NPCs that spawn in the structure.
    • "type": The type of NPC to spawn.
    • "data": Additional arguments modifying the NPC, such as "Main" or "Secondary" for shopkeepers.
    • "x": The x component of the coordinate where the NPC spawns, relative to the origin of the structure.
    • "y": The y component of the coordinate where the NPC spawns, relative to the origin of the structure.
    • "z": The z component of the coordinate where the NPC spawns, relative to the origin of the structure.

The town Pokémon Center JSON data is shown below as an example.

   {
     "id": "towncenter1",
     "filename": "pokecenter1.snapshot",
     "weighting": 20,
     "depth": 2,
     "maxnum": 1,
     "npcs": [
       {
         "type": "NurseJoy",
         "x": 9,
         "y": 3,
         "z": 7
       }
     ]
   }

gyms

  • "id": The ID of the structure when spawned via the /struc command
  • "filename": The block snapshot file that defines the Gym's block data, relative to "pixelmon/structures/gyms".
  • "npcdata": The JSON file that defines the Gym's NPC spawning data, relative to "pixelmon/structures/gyms".
  • "depth": How far into the ground the Gym will spawn at.

The Grass Gym JSON data is shown below as an example.

   {
     "id": "grassgym",
     "filename": "grassgym.snapshot",
     "npcdata": "grassgym.json",
     "depth": 8
   }

standalone

  • "id": The ID of the structure when spawned via the /struc command
  • "filename": The block snapshot file that defines the Gym's block data, relative to "pixelmon/structures/standalone".
  • "biomes": The names of biomes that the structure can spawn in.
  • "rarity": Used to determine the relative rarity of spawning the structure. A higher rarity makes the structure spawn more commonly.
  • "depth": How far into the ground the Gym will spawn at.

The frozen shrine JSON data is shown below as an example.

   {
     "id": "iceshrine",
     "filename": "shrine1.snapshot",
     "biomes": [ "Ice Plains Spikes", "Ice Plains", "Ice Mountains", "Cold Taiga M" ],
     "rarity": 20,
     "depth": 0
   }

Block snapshots

Block snapshot (.snapshot files) are used to define the blocks that make up a structure. They can be created and modified using the /psnapshot command.

Note: Command syntax is displayed in the standard Minecraft command format. An explanation of this format can be found here.

  • /psnapshot read <file name>: Loads a set of blocks previously saved to a file by /snapshot save.
  • /psnapshot set: Sets a corner of the area to save at the player's location. If there are already two corners set when this command is used, the corner that was set first will be overwritten by the new corner.
  • /psnapshot save: Saves the blocks in the area defined by the two previously set corners. Two corners must already be set in order for this command to work. If a set of blocks was already previously saved, it will be overwritten by the newly saved set of blocks.
    • /psnapshot save <file name>: Saves the blocks in the area like in /snapshot save. Also saves the blocks to a file (with the given name) in a "snapshots" folder inside the Minecraft folder. This file can be read back into Minecraft with the "load" argument.
  • /psnapshot place: Copies the previously saved blocks and places them where the player is located.
  • /psnapshot convert <file name>: Converts a snapshot created in Minecraft 1.8.9 and below into a snapshot compatible with Minecraft 1.10.2. This creates a new snapshot file with "-converted" appended to the original file name.

Gym NPC data

NPCs inside Gyms are defined in a JSON file separate from the structures.json file. This JSON file is split into two arrays:

  • "npcs" for data about NPCs themselves.
  • "pokemon" for data about possible Pokémon that NPC Trainers within the Gym can use.

npcs

  • "name": The ID of the NPC. This leads to the corresponding file at "pixelmon/npcs/gyms", which defines most of the data about the NPC such as dialogue and skins.
  • "type": The type of NPC to spawn.
  • "rotation": The rotation (yaw) of the NPC relative to the Gym's rotation.
  • "x": The x component of the coordinate where the NPC spawns, relative to the origin of the Gym structure.
  • "y": The y component of the coordinate where the NPC spawns, relative to the origin of the Gym structure.
  • "z": The z component of the coordinate where the NPC spawns, relative to the origin of the Gym structure.
  • "drops": If defined on an NPC Trainer, a random item from this array is awarded to the player after defeating the NPC Trainer in battle. This array uses item IDs from the shopItems.json file.

An entry for one of the Grass Gym's NPC Trainers is shown below.

   {
     "name": "grassgymbase",
     "type": "trainer",
     "tier": 3, 
     "rotation": 90,
     "x": 13,
     "y": 3,
     "z": 25
   }

pokemon

  • "name": The Pokémon's species.
  • "minLevel": The minimum level that the NPC Trainer can be in order to potentially use this Pokémon.
  • "maxLevel": The maximum level that the NPC Trainer can be in order to potentially use this Pokémon.
  • "sets": Defines data about the Pokémon moves, Abilities, held items, Natures, and EVs. It is possible to have multiple sets for a Pokémon.
    • "move<number>": A move that the Pokémon can have in a certain moveslot. It is possible to define multiple moves for a moveslot; one will be randomly chosen when the Pokémon is used. Omitting a moveslot causes the Pokémon to have no move in the omitted slot. Hidden Power can be defined to have a specific type (e.g., "Hidden Power Ice), and IVs will automatically be set accordingly if they are not manually defined.
    • "heldItem": Defines possible held items that the Pokémon can hold. Omitting this field causes the Pokémon to not hold an item.
    • "nature": Defines possible Natures that the Pokémon can have. Only used by Gym Leaders. Regular Gym Trainers or the omission of the field cause the Pokémon to randomly have any of the 24 Natures.
    • "ev<stat>": Defines the number of EVs that the Pokémon will have for a certain stat. Only used by Gym Leaders. Regular Gym Trainers always have 0 EVs.
    • "iv<stat>": Defines the number of IVs that the Pokémon will have for a certain stat. Defaults to 31 for Gym Leaders, and random between 0-31 for regular Gym Trainers.

An entry for one of the Pokémon inside the Grass Gym is shown below.

   {
     "name": "Servine",
     "minLevel": 17,
     "maxLevel": 35,
     "sets": [
       {
         "move1": [ "Giga Drain" ],
         "move2": [ "Reflect" ],
         "move3": [ "Light Screen" ],
         "move4": [ "Glare", "Leech Seed", "Synthesis", "Toxic" ],
         "heldItem": [ "pixelmon:light_clay" ],
         "nature": [ "Bold" ],
         "evHP": 252,
         "evDef": 252,
         "evSpDef": 4
       },
       {
         "minLevel": 31,
         "move1": [ "Leaf Blade" ],
         "move2": [ "Coil", "Swords Dance" ],
         "move3": [ "Aqua Tail", "Iron Tail", "Return" ],
         "move4": [ "Aqua Tail", "Iron Tail", "Return" ],
         "ability": [ "Overgrow" ],
         "heldItem": [ "pixelmon:muscle_band", "pixelmon:miracle_seed" ],
         "nature": [ "Adamant", "Jolly" ],
         "evAtk": 252,
         "evSpDef": 4,
         "evSpeed": 252
       }
     ]
   }