Welcome to rpgmaker_mv_decoder’s documentation!

RPGMaker MV Decoder v1.4.0

This is a set of python scripts for decoding and encoding RPGMaker MV/MZ game assets.

Decoding has a handy feature, it will figure out (if possible) the key automatically. It will also can use the file data for creating the extension. If you know the key, you can pass it in.

If you want you can use the API instead

Features

• GUI for those who need that

• Fast

• No key needed if there’s any encoded png images

• Can put proper file extensions on the decoded files

Example usage

./decoder.py "<source path>" "<destination path>" ["<optional key>"]

./encoder.py "<source path>" "<destination path>" "<key>"

./gui.py

The GUI has a fairly simple main window:

Progress will be shown while finding the key, decoding the files or encoding the files:

Hitting the question mark will bring up the about box, which gives some handy links:

Help

You can use the standard --help option for full documentation:

Decoding

Usage: decode.py [OPTIONS] <Source> <Destination> [<Key>]

  Decodes RPGMaker files under <Source> directory to <Destination> directory.

Arguments:
  <Source>       The source directory. For best results this should be the
                 parent of the 'www' or 'img' directory.
  <Destination>  The parent destination directory. This script will create a
                 project directory under this path if it doesn't already
                 exist.
  <Key>          The decoding key to use. This argument is optional. If the
                 key is omitted it will be inferred (if possible) based on the
                 file contents.

Options:
  --detect_type  Detect the file type and use the associated file extension.
                 By default .rpgmvp becomes .png and .rpgmvo becomes .ogg
                 regardless of the file contents.
  --version      Prints the version number
  --overwrite    Overwrite files without prompting
  --help         Show this message and exit.

Encoding

Usage: encode.py [OPTIONS] <Source> <Destination> <Key>

  Encodes image and audio files under <Source> directory.

Arguments:
  <Source>       The source directory. For best results this should be the
                 parent of the 'www' or 'img' directory.
  <Destination>  The parent destination directory. This script will create a
                 project directory under this path if it doesn't already
                 exist.
  <Key>          The encoding key to use.

Options:
  --version    Prints the version number
  --overwrite  Overwrite files without prompting
  --help       Show this message and exit.

Installation

Stable release

To install rpgmaker_mv_decoder, run this command in your terminal:

$ pip install rpgmaker_mv_decoder

This is the preferred method to install rpgmaker_mv_decoder, as it will always install the most recent stable release.

If you don’t have pip installed, this Python installation guide can guide you through the process.

From sources

The sources for rpgmaker_mv_decoder can be downloaded from the Github repo.

You can either clone the public repository:

$ git clone git://github.com/kins-dev/rpgmaker_mv_decoder

Or download the tarball:

$ curl -OJL https://github.com/kins-dev/rpgmaker_mv_decoder/tarball/master

Once you have a copy of the source, you can install it with:

$ python setup.py install

Usage

Decoding

Usage: decode.py [OPTIONS] <Source> <Destination> [<Key>]

  Decodes RPGMaker files under <Source> directory to <Destination> directory.

Arguments:
  <Source>       The source directory. For best results this should be the
                 parent of the 'www' or 'img' directory.
  <Destination>  The parent destination directory. This script will create a
                 project directory under this path if it doesn't already
                 exist.
  <Key>          The decoding key to use. This argument is optional. If the
                 key is omitted it will be inferred (if possible) based on the
                 file contents.

Options:
  --detect_type  Detect the file type and use the associated file extension.
                 By default .rpgmvp becomes .png and .rpgmvo becomes .ogg
                 regardless of the file contents.
  --version      Prints the version number
  --overwrite    Overwrite files without prompting
  --help         Show this message and exit.

Encoding

Usage: encode.py [OPTIONS] <Source> <Destination> <Key>

  Encodes image and audio files under <Source> directory.

Arguments:
  <Source>       The source directory. For best results this should be the
                 parent of the 'www' or 'img' directory.
  <Destination>  The parent destination directory. This script will create a
                 project directory under this path if it doesn't already
                 exist.
  <Key>          The encoding key to use.

Options:
  --version    Prints the version number
  --overwrite  Overwrite files without prompting
  --help       Show this message and exit.

rpgmaker_mv_decoder

rpgmaker_mv_decoder package

Submodules

rpgmaker_mv_decoder.callbacks module

callback module

Used to handle callbacks in a single object rather than multiple parameters

rpgmaker_mv_decoder.callbacks.show_version(ctx: click.core.Context, _, value: bool)

show_version Click callback that displays the version number to the user

Args:

• ctx (click.Context): context for options parsing

• _ (_type_): ignored

• value (bool): if true, show the version number and exit

rpgmaker_mv_decoder.callbacks.default_message_callback(level: rpgmaker_mv_decoder.messagetypes.MessageType, text: str) → None

default_message_callback default handling of messages

Args:

• level (MessageType): What kind of message this is

• text (str): What to display

rpgmaker_mv_decoder.callbacks.default_prompt_callback(message_type: rpgmaker_mv_decoder.messagetypes.MessageType = MessageType.DEBUG, message: str = '', responses: rpgmaker_mv_decoder.promptresponse.PromptResponse = PromptResponse.OK) → bool

default_prompt_callback default prompt

Args:

• message_type (MessageType, optional): What type of message is this. Defaults to MessageType.DEBUG.

• message (str, optional): What to display to the user. Defaults to "".

• responses (PromptResponse, optional): What kind of repsones can the user give. Defaults to PromptResponse.OK.

Returns:

• bool: True if the operation should run the action, False if the action should be skipped and None if the operation should be canceled.

class rpgmaker_mv_decoder.callbacks.Callbacks(progressbar_callback: typing.Callable[[click._termui_impl.ProgressBar], bool] = <function _default_progressbar_callback>, prompt_callback: typing.Callable[[rpgmaker_mv_decoder.messagetypes.MessageType, str, rpgmaker_mv_decoder.promptresponse.PromptResponse, bool], bool] = <function default_prompt_callback>, message_callback: typing.Callable[[rpgmaker_mv_decoder.messagetypes.MessageType, str, bool], None] = <function default_message_callback>)

Bases: object

Callbacks encapsulates all the callbacks that might be used during execution

property progressbar

progressbar callback for updating the progress of the operation

Returns:

• Callable[[ProgressBar], bool]: Function to call. Progress data should be specified via the parameter. If the user cancels the operation, this should return True

property prompt: Callable[[rpgmaker_mv_decoder.messagetypes.MessageType, str, rpgmaker_mv_decoder.promptresponse.PromptResponse], bool]

prompt callback for asking the user a question

Returns:

• Callable[[MessageType, str, PromptResponse], bool]: Function to call. First argument is the type of message, second is the message, third is the responses a user can give.

property message: Callable[[rpgmaker_mv_decoder.messagetypes.MessageType, str], None]

message callback for displaying a message to the user

Returns:

• Callable[[MessageType, str], None]: Function to call. First argument is the type of message, second is the message

debug(text: str) → None

debug helper function for printing a debug message

Args:

• self (Callbacks): callbacks object

• text (str): text to display

info(text: str) → None

info helper function for printing a info message

Args:

• self (Callbacks): callbacks object

• text (str): text to display

warning(text: str) → None

warning helper function for printing a warning message

Args:

• self (Callbacks): callbacks object

• text (str): text to display

error(text: str) → None

error helper function for printing a error message

Args:

• self (Callbacks): callbacks object

• text (str): text to display

rpgmaker_mv_decoder.cli_help module

Command line interface help classes

class rpgmaker_mv_decoder.cli_help.DecodeHelp(name: Optional[str], context_settings: Optional[Dict[str, Any]] = None, callback: Optional[Callable[[...], Any]] = None, params: Optional[List[click.core.Parameter]] = None, help: Optional[str] = None, epilog: Optional[str] = None, short_help: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False)

Bases: click.core.Command

DecodeHelp help command override

Used to customize click help

format_help_text(ctx: click.core.Context, formatter: argparse.HelpFormatter)

format_help_text formats the help

Override that adds arguments to the help properly

Args:

• ctx (click.Context): context for click

• formatter (HelpFormatter): formatter to use

class rpgmaker_mv_decoder.cli_help.EncodeHelp(name: Optional[str], context_settings: Optional[Dict[str, Any]] = None, callback: Optional[Callable[[...], Any]] = None, params: Optional[List[click.core.Parameter]] = None, help: Optional[str] = None, epilog: Optional[str] = None, short_help: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False)

Bases: click.core.Command

EncodeHelp help command override

Used to customize click help

format_help_text(ctx: click.core.Context, formatter: argparse.HelpFormatter)

format_help_text formats the help

Override that adds arguments to the help properly

Args:

• ctx (click.Context): context for click

• formatter (HelpFormatter): formatter to use

rpgmaker_mv_decoder.clickdisplay module

clickdisplay.py Simple helper class for the click progress bar

class rpgmaker_mv_decoder.clickdisplay.ClickDisplay(items: Iterable[pathlib.Path])

Bases: object

ClickDisplay class for handling item display in click progress bar

setup(items: Iterable[pathlib.Path]) → None

setup figures out the width of the display needed for filenames

Args:

• items (Iterable[Path]): Items being passed to the click progress bar

show_item(item: pathlib.Path) → str

show_item Pads the item name so it is shown correctly

This is used as a callback in the click progress bar

Args:

• item (Path): Item to display

Returns:

• str: String to append to progress info. Trailing spaces will be removed.

rpgmaker_mv_decoder.constants module

constants.py Constants for use by modules

rpgmaker_mv_decoder.exceptions module

Custom Exception Types

exception rpgmaker_mv_decoder.exceptions.Error(message: str)

Bases: Exception

Base class for exceptions in this module.

Attributes:

• message: Explanation of the error

exception rpgmaker_mv_decoder.exceptions.NoValidFilesFound(message: str)

Bases: rpgmaker_mv_decoder.exceptions.Error

Exception raised when no files are found. Based on Error class

Attributes:

• message: Explanation of the error

exception rpgmaker_mv_decoder.exceptions.FileFormatError(expression: str, message: str)

Bases: rpgmaker_mv_decoder.exceptions.Error

Exception raised for errors in the input. Based on Error class

Attributes:

• expression: Input expression in which the error occurred

• message: Explanation of the error

exception rpgmaker_mv_decoder.exceptions.PNGHeaderError(expression: str, message: str)

Bases: rpgmaker_mv_decoder.exceptions.FileFormatError

Exception raised for PNG images that when the IHDR section doesn’t checksum correctly.

Attributes:

• expression – Input expression in which the error occurred

• message – Explanation of the error

exception rpgmaker_mv_decoder.exceptions.RPGMakerHeaderError(expression: str, message: str)

Bases: rpgmaker_mv_decoder.exceptions.FileFormatError

Exception raised for files missing the RPGMaker MV header.

Attributes:

• expression – Input expression in which the error occurred

• message – Explanation of the error

rpgmaker_mv_decoder.messagetypes module

messagetypes.py Types of messages for the UI

class rpgmaker_mv_decoder.messagetypes.MessageType(value)

Bases: enum.Enum

MessageType Is a message debug, informational, warning or error

DEBUG = 1

INFO = 2

WARNING = 3

ERROR = 4

get_message_header() → str

get_message_header Header for this message type

Returns:

• str: Header to prepend to the message

get_icon() → str

get_icon Returns the TK icon for this message type

Returns:

• str: The TK icon for this message type

rpgmaker_mv_decoder.project module

project.py

Module for dealing with RPGMaker projects

class rpgmaker_mv_decoder.project.Project(source_path: typing.Optional[pathlib.PurePath] = None, destination_path: typing.Optional[pathlib.PurePath] = None, key: typing.Optional[str] = None, callbacks: rpgmaker_mv_decoder.callbacks.Callbacks = <rpgmaker_mv_decoder.callbacks.Callbacks object>)

Bases: abc.ABC

Handles a project and runs operations

property overwrite: bool

if files should be overwritten. None will cause the system to prompt the user.

property key: str

Gets the key or returns None if the key is not valid

rpgmaker_mv_decoder.projectdecoder module

Class for decoding a project

class rpgmaker_mv_decoder.projectdecoder.ProjectDecoder(source: pathlib.PurePath, destination: pathlib.PurePath, key: str, callbacks: rpgmaker_mv_decoder.callbacks.Callbacks = <rpgmaker_mv_decoder.callbacks.Callbacks object>)

Bases: rpgmaker_mv_decoder.project.Project

Handles a project and runs operations

decode_header(file_header: bytes) → bytes

decode_header take a RPGMaker header and return the key or the actual file header

Check’s the first 16 bytes for the standard RPGMaker header, then drops them. Takes the next 16 bytes and either calculates the key based on a PNG image, or uses the specify key to decode. If png_ihdr_data is provided, checks that the IHDR section checksums correctly.

Args:

• file_header (bytes): First 32 bytes from the file, 16 bytes are the RPGMaker header, followed by 16 bytes of the file header

Raises:

• RPGMakerHeaderError: The header doesn’t match RPGMaker’s header

Returns:

• bytes: If key was None, the key needed for a PNG image header, otherwise the decoded file header.

decode_file(input_file: pathlib.PurePath, detect_type: bool) → bool

decode_file Takes a path and decodes a file

Args:

• input_file (PurePath): File to read and modify

• detect_type (bool): True means generate file extensions based on file contents

Returns:

• bool: True if the operation should continue

decode(detect_type: bool) → None

decode Decodes a project

Args:

• detect_type (bool): True means generate file extensions based on file contents

rpgmaker_mv_decoder.projectencoder module

Class for encoding a project

class rpgmaker_mv_decoder.projectencoder.ProjectEncoder(encoding_source: pathlib.PurePath, destination: pathlib.PurePath, key: str, encoding_callbacks: rpgmaker_mv_decoder.callbacks.Callbacks = <rpgmaker_mv_decoder.callbacks.Callbacks object>)

Bases: rpgmaker_mv_decoder.project.Project

Class for encoding a project

encode_header(file_header: bytes) → bytes

encode_header Encode a file with a key

Takes first 16 bytes and encodes per RPGMaker MV standard

Args:

• file_header (bytes): 16 bytes

• key (str): Key to encode with

Returns:

• bytes: First 32 bytes of the encoded file

encode_file(input_file: pathlib.PurePath) → bool

encode_file Takes a path and encodes a file

Args:

• input_file (PurePath): File to read and modify

Returns:

• bool: True if the operation should continue

encode()

encode Encodes the project

rpgmaker_mv_decoder.projectkeyfinder module

Class for decoding a project

class rpgmaker_mv_decoder.projectkeyfinder.ProjectKeyFinder(source: pathlib.PurePath, callbacks: rpgmaker_mv_decoder.callbacks.Callbacks = <rpgmaker_mv_decoder.callbacks.Callbacks object>)

Bases: rpgmaker_mv_decoder.project.Project

Handles finding a project key

property keys: Dict[str, int]

keys sorted dictionary of possible keys for this project

find_key() → str

find_key Check the path for PNG images and return the decoding key

Finds image files under the specified path and looks for a key to decode all the files. This can fail if only a small number (less than 3) of the .rpgmvp files are .png images.

Raises:

• NoValidFilesFound: If no valid PNG images are found

Returns:

• str: Decoding key

rpgmaker_mv_decoder.projectpaths module

project.py

Module for dealing with RPGMaker projects

class rpgmaker_mv_decoder.projectpaths.ProjectPaths(source: Optional[pathlib.PurePath] = None, destination: Optional[pathlib.PurePath] = None)

Bases: object

Object that holds/validates project paths

property destination: pathlib.PurePath

Gets the destination path to use or returns None if the destination path is not valid

property source: pathlib.PurePath

Gets the source path to use or returns None if the source path is not valid

property output_directory: pathlib.PurePath

output_directory returns the name of the output directory including the project name

property encoded_images: List[pathlib.Path]

encoded_images list of encoded images under the source path

Creates a sorted list of Path objects ending with “.rpgmvp” under the source path, or None if the source path is unset

property encoded_files: List[pathlib.Path]

encoded_files list of encoded files under the source path

Creates a sorted list of Path objects ending with “.rpgmvp” or “.rpgmvo under the source path, or None if the source path is unset

property all_files: List[pathlib.Path]

all_files list of all files under the source path

Creates a sorted list of Path objects that are files under the source path, or None if the source path is unset

rpgmaker_mv_decoder.promptresponse module

promptresponse.py How the user can respond to a prompt

class rpgmaker_mv_decoder.promptresponse.PromptResponse(value)

Bases: enum.Flag

PromptResponse types of responses the user can give

Show OK unless NO is also specified, which then OK should be YES

NONE = 0

OK = 1

YES = 1

NO = 2

SKIP = 4

YES_NO = 3

YES_SKIP = 5

CANCEL = 8

OK_CANCEL = 9

YES_NO_CANCEL = 11

YES_SKIP_CANCEL = 13

get_responses() → List[str]

get_responses List of response that this enum represents

Returns:

• List[str]: Possible user response to this message

get_messagebox_response() → str

get_messagebox_response gets the TK messagebox button set for this response

Returns:

• str: The TK messagebox button set for this response. None if nothing matches

rpgmaker_mv_decoder.utils module

Utility functions

rpgmaker_mv_decoder.utils.int_xor(var: bytes, key: bytes) → bytes

int_xor integer xor

Runs XOR on 2 bytes streams (must be less than 64 bytes)

Args:

• var (bytes): Input 1

• key (bytes): Input 2

Returns:

• bytes: XOR of input 1 and input 2

Module contents

Package for decoding RPGMaker MV/MZ encoded files

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/kins-dev/rpgmaker_mv_decoder/issues.

If you are reporting a bug, please include:

• Your operating system name and version.

• Any details about your local setup that might be helpful in troubleshooting.

• Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation

rpgmaker_mv_decoder could always use more documentation, whether as part of the official rpgmaker_mv_decoder docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/kins-dev/rpgmaker_mv_decoder/issues.

If you are proposing a feature:

• Explain in detail how it would work.

• Keep the scope as narrow as possible, to make it easier to implement.

• Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up rpgmaker_mv_decoder for local development.

1. Fork the rpgmaker_mv_decoder repo on GitHub.

2. Clone your fork locally:

   $ git clone git@github.com:your_name_here/rpgmaker_mv_decoder.git
   

3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

   $ mkvirtualenv rpgmaker_mv_decoder
   $ cd rpgmaker_mv_decoder/
   $ python setup.py develop
   $ pip install -r requirements_dev.txt
   

4. Create a branch for local development:

   $ git checkout -b name-of-your-bugfix-or-feature
   

   Now you can make your changes locally.

5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

   $ flake8 rpgmaker_mv_decoder tests
   $ python setup.py test or pytest
   $ tox
   

   To get flake8 and tox, just pip install them into your virtualenv.

6. Commit your changes and push your branch to GitHub:

   $ git add .
   $ git commit -m "Your detailed description of your changes."
   $ git push origin name-of-your-bugfix-or-feature
   

7. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

1. The pull request should include tests.

2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.

3. The pull request should work for Python 3.6, 3.7, 3.8, 3.9 and 3.10, and for PyPy. Check https://travis-ci.com/kins-dev/rpgmaker_mv_decoder/pull_requests and make sure that the tests pass for all supported Python versions.

Tips

To run a subset of tests:

$ python -m unittest tests.test_rpgmaker_mv_decoder

Deploying

A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in HISTORY.rst). Then run:

$ bump2version patch # possible: major / minor / patch
$ git push
$ git push --tags

Alternatively you can use something like:

$ bump2version patch
$ git push --atomic origin <branch> <tag>

GitHub will then deploy to PyPI if tests pass.

Credits

Development Lead

• Scott Atkins <scott@kins.dev>

Contributors

None yet. Why not be the first?

History

1.4.0 (2022-05-10)

• Fixed minor API bugs

• Fixed documentation

• Added cli overwrite prompt

• New messaging system

• New prompt system

• Updates to the progress UI

• Renamed callback module to callbacks

• Refactored messaging to user

• Better package information

• Added –overwrite and –version to options for CLI tools

1.3.0 (2022-05-04)

• Added project class

• Updated messages for skipped files

• Fixed same key calculation

• Code cleanup

• Refactored CLI - Removed duplicated code

1.2.1 (2022-04-26)

• Fixed history

• Callback class to make life easier internally

1.2.0 (2022-04-21)

• Added overwrite handling in the GUI

1.1.1 (2022-04-18)

• Fixing tag issue

• Fixing release build

1.1.0 (2022-04-18)

• Documentation changes

• GUI changes

1.0.3 (2022-04-18)

• Bumping version to fix out of order upload to pypi

1.0.2 (2022-04-15)

• Fixed history file

• Fixed documentation link

1.0.0 (2022-04-15)

• Added about dialog

• Production ready

0.3.4 (2022-04-14)

• Updating actions to publish properly

• Documentation updates

0.3.3 (2022-04-14)

• Fix to GitHub actions

0.3.2 (2022-04-14)

• Automate the release process

0.3.1 (2022-04-13)

• Fixes to documentation

0.3.0 (2022-04-13)

• Added icons

• Added encoding

• Changed exe name

• UPX packing on Windows

• Documentation updates

0.2.4 (2022-04-06)

• More testing

• Bump2Version configuration fixes

• Fixing up tox.ini

0.2.3 (2022-04-01)

• Added tests

0.2.2 (2022-04-01)

• Fixed documentation

• Fixed exceptions

0.2.1 (2022-03-31)

• Bug fixes

0.2.0 (2022-03-30)

• Added GUI

0.1.1 (2022-03-23)

• Faster key detection

• Python typing

• Added documentation

• Keeping files compatible with RPGMaker MV/MZ * Using .png or .ogg instead of real extension

0.1.0 (2021-04-18)

• First release on PyPI.

Indices and tables

• Index

• Module Index

• Search Page