PokeMMO Mod Documentation

[Desu]

PokeMMO Mods are a custom format used by the PokeMMO Client to load override resources.

The following types of resources are available to modify:

• Music (mp3/ogg/wav)
• Item Icons
• Monster Icons
• Front/Back Monster Battle Sprites (PNG/GIF)
• Front/Back Monster Battle Sprite scale (Table for overwriting render scale. Default is 3x. Only supported for GIFs)
• Front Battle Monster Sprite positioning (Table for overwriting the rendered Y coordinate/altitude)

Basic Mod Structure:

 

Every mod is a simple zip file. It can be edited with any zip editor, including window's build in zip archive support.

 

 

A mod file should contain the following required elements:

1. An info.xml file with basic information about the mod and it's author.

2. An icon.png file with an icon for the mod.

3. The resources you wish to modify.

 

info.xml

 

The basic structure is as follows:

 

<?xml version="1.0" encoding="UTF-8"?>
<resource name="PokeMMO Example Mod" version="1.0" description="Barebones mod with no actual content changes." author="Desu" weblink="https://forums.pokemmo.eu/index.php?/user/2-desu/">
</resource>

Note: The weblink must link to the "pokemmo.eu" domain.

 

icon.png

 

This is simply a PNG file which is displayed in the Mod Management panel. Suggested size is 48x48.

 

 

Music:

 

All files in the /sounds/ folder will be loaded as music files. They should be named '0/123.mp3' where 0 is region id and 123 is the sound id. 

Use "/bgm" command ingame to print out the current playing sound id.

 

Item Icons:

 

All files in the /sprites/itemicons/ folder will be loaded as item icons. They should be named '123.png' where 123 is the item id. You may use the 'Dump Moddable Resources' utility in settings to see what items correspond with what ids. Suggested size is 24x24.

 

 

Monster Icons:

 

All files in the /sprites/monstericons/ folder will be loaded as monster icons. They should be named 'ID-FRAME.png' You may use the 'Dump Moddable Resources' utility in settings to see what monsters correspond with what ids. Suggested size is 32x32.

 

 

Monster Battle Sprites:

 

Certain files in the /sprites/battlesprites/ folder will be loaded as monster icons. The naming format is 'ID-front-n.png'. ID is the ID of the monster, followed by either 'front' or 'back' to indicate which type of sprite this is, finally followed by either 'n' (normal) or 's' (shiny).

 

 

PNG Notes:

PNG files are required to be 64x64.

Front sprites are modified by the 'table-front-y.txt' and 'table-front-altitude.txt' tables.

PNG files are NOT modified by the 'table-front-scale.txt' and 'table-back-scale.txt' tables.

 

GIF Notes:

GIF files support arbitrary image sizes. 

GIF sprites are NOT modified by the 'table-front-y.txt' and 'table-front-altitude.txt' tables. Sprites will be automatically positioned to what the 'center' of the sprite.

GIF files are modified by the 'table-front-scale.txt' and 'table-back-scale.txt' tables. For example, You can use this to render front sprites at 2x scale while back sprites are 3x.

GIF files currently use a static time between frames of 50ms. I only remembered this when writing this documentation, it will be fixed Soon™

 

Table Notes:

There are several table files in the /sprites/battlesprites/ folder which modify the way sprites are rendered. I recommend you use the 'Dump Moddable Resources' utility to see how this table functions.

It is editable with a standard text editor.

• table-front-y.txt - Modifies the rendered Y position for front sprites. (PNG Only)
• table-front-altitide.txt - Modifies the rendered Y position for front sprites. Would control shadow rendering, if we supported it. (PNG Only)
• table-front-scale.txt - Modifies the render scale of front sprites. (GIF Only)
• table-back-scale.txt - Modifies the render scale of back sprites. (GIF Only)
• table-summary-scale.txt - Modifies the render scale of sprites in the summary window.

[Desu]

Follower Sprite Mods:

Certain files in the /sprites/followsprites/ folder will be loaded as overworld follower sprites. The naming format is 'ID-Gender-Shiny(-FormId).png'.

ID is the ID of the monster

Gender is 'b' for both, 'f' for female, 'm' for male

Shiny is either 'n' for normal or 's' for shiny

FormID is the form id for monsters that have multiple forms. If a form id is not specified it will be treated as form '0'.

These sprites are expected to be a single atlas image containing all frames for the follower gender/shiny combination.

Please use sprites that are represented with a 1-1 pixel ratio. PNG files that have sprites at 2x normal scale will lead to scaling/artifact issues. (Batch resize applications exist so please do not do this manually.)

 

/sprites/followersprites/atlasdata.txt is required to supply the atlas layout and structure. An example of a functioning atlasdata.txt is as follows:

Spoiler

;Table which determines sheet settings for follow sprites
;This is a global setting for all the sheets contained within the mod package.
;Meaning your sheets need to be uniform in size and placements
;Lines starting with ; will be ignored

;Amount of columns and rows
rows=4
columns=4

;Frame data
;Which frames it should use for each direction
;Format: id,id
;Max of 4 animation frames, min of 2
;Example for 4x2 sheet
;[0][1]
;[2][3]
;[4][5]
;[6][7]
;Example for 4x4
;[00][01][02][03]
;[04][05][06][07]
;[08][09][10][11]
;[12][13][14][15]

north=0,1,2,3
south=12,13,14,15
west=4,5,6,7
east=8,9,10,11

;Sprite scale/x/y/z modifications
;Default values: 1.0,0,0,0
;For larger sprites try starting from value 0.75,0,10,0
;Increasing X will put the sprite more on right
;Increasing Y will put the sprite higher
;Increasing Z will put the sprite down ( depth axis only 3d )
123=0.75,0,10,0
234=0.75,0,10,0
345=0.75,0,5,0
456=0.75,0,10,0

 

 

[Vukooo]

Theme Mods:

Mods can provide custom themes. Themes need to be defined in the "info.xml" file:

  <themes theme_revision="3">
    <theme path="path/to/theme" name="themename" is_mobile="false" sprite_atlas="path/to/sprite/main.atlas"/>
  </themes>

theme_revision: Theme mods need to define a client theme revision they are compatible with. The client theme revision will be increased on major updates. Themes with a revision that are not equal to the current client theme revision will refuse to load.
path: The path needs to be relative to the zip root directory.
is_mobile: Whether the theme is intended for mobile platforms. Mobile themes can be used on non-mobile platforms but not vice versa.
sprite_atlas: An optional attribute that points to an atlas file relative to the zip root, that should be used when the theme is applied. For development purposes, the path can point to a directory containing the raw images. However, distributed mods are required to compile a texture atlas.

 

Current Theme Revision: 3

 

The current official themes and a history of theme changes can be found here: https://github.com/PokeMMO/PokeMMO_Mods/tree/master/theme_history
The changes in the latest update can be viewed in git diff format at: https://github.com/PokeMMO/PokeMMO_Mods/commit/ef853ef67d2dda6bba529e09b1edb983dea19d06

 

String Mods:

Mods can provide custom strings. Themes need to be defined in the "info.xml" file:

  <strings string_revision="1">
      <string path="path/to/string.xml"/>
  </strings>

string_revision: String mods need to define a client string revision they are compatible with. The client string revision will be increased on major changes to strings. Strings with a revision that are not equal to the current client string revision will refuse to load.
path: The path needs to be relative to the zip root directory.

 

Current String Revision: 1

 

Overlay Mods:

Mods can overlay certain internal PokeMMO asset paths with their own files. If a file from an overlayable directory gets loaded, the file will be first tried to be loaded from a mod and then from the internal storage.  
The overlay order is determined by the order of the mods in the Mod GUI. For every file the overlaying is resolved independently, therefore multiple overlay mods may be incompatible with each other.  

 

A mod needs to request permission to overlay a directory in the "info.xml":

  <overlays>
      <overlay path="path/to/overlay/"/>
  </overlays>

path: The path needs to be relative to the zip root directory.

 

The following paths can be overlayed:

• data/sprites/atlas/
• data/themes/
• data/sprites/textures/

 

Mods that want to overlay the same directory cannot be applied at the same time.

 

It is discouraged to overlay the "data/themes/ " path for non-trivial themes, see Theme Mods instead.

 

Example Mods:

A small collection of example mods can be found here: https://github.com/PokeMMO/PokeMMO_Mods/tree/master/examples

 

Theme History:

- XMas 2024: https://github.com/PokeMMO/PokeMMO_Mods/commit/aebf89b20984724432d8fa20550fd5ca8f86ddf0

- LNY 2025: https://github.com/PokeMMO/PokeMMO_Mods/commit/ef853ef67d2dda6bba529e09b1edb983dea19d06