= easyrpg-player(6)
:manmanual: EasyRPG Manual
:mansource: EasyRPG Player {player_version}

== Name

easyrpg-player - Interpreter for RPG Maker 2000/2003 games


== Synopsis

*easyrpg-player* [<optional flags>...]


== Description

EasyRPG Player is an open source interpreter for RPG Maker 2000 and 2003 games.
It aims to support all features of unmodified games and also has some support
for some additional binary patches.

== Options

=== Engine options

*--autobattle-algo* _ALGO_::
  Which AutoBattle algorithm to use. Possible options:

  - 'RPG_RT'     - The default RPG_RT compatible algo, including RPG_RT bugs
  - 'RPG_RT+'    - The default RPG_RT compatible algo, with bug fixes
  - 'ATTACK'     - Like RPG_RT+, but only physical attacks, no skills

*-c*, *--config-path* _PATH_::
  Set a custom configuration path. When not specified, the configuration folder
  in the users home directory is used. The default configuration path is
  '$XDG_CONFIG_HOME/EasyRPG/Player'.

*--encoding* _ENCODING_::
  Instead of autodetecting the encoding or using the one in 'RPG_RT.ini', the
  specified encoding is used. 'ENCODING' is the number of the codepage used in
  Windows. Common encodings:
  - '932'  - Japanese (Shift-JIS)
  - '936'  - Simplified Chinese (GB2312)
  - '949'  - Korean (Unified Hangul)
  - '950'  - Traditional Chinese (Big5)
  - '1250' - Central European
  - '1251' - Cyrillic
  - '1252' - Western European (Latin 1)

NOTE: For games that only use ASCII (English games) use '1252'.

*--enemyai-algo* _ALGO_::
  Which EnemyAI algorithm to use. Possible options:
  - 'RPG_RT'      - The default RPG_RT compatible algo, including RPG_RT bugs
  - 'RPG_RT+'     - The default RPG_RT compatible algo, with bug fixes

*--engine* _ENGINE_::
  Disable autodetection of the simulated engine. Possible options:
   - 'rpg2k'       - RPG Maker 2000 (v1.00 - v1.10)
   - 'rpg2kv150'   - RPG Maker 2000 (v1.50 - v1.51)
   - 'rpg2ke'      - RPG Maker 2000 RPG Maker 2000 (English release, v1.61)
   - 'rpg2k3'      - RPG Maker 2003 (v1.00 - v1.04)
   - 'rpg2k3v105'  - RPG Maker 2003 (v1.05 - v1.09a)
   - 'rpg2k3e'     - RPG Maker 2003 RPG Maker 2003 (English release, v1.12)

*--font1* _FILE_::
  Path to a font to use for the first font. The system graphic of the game
  determines whether font 1 or 2 is used. When no font is selected or the
  selected font lacks certain glyphs the built-in pixel font is used.

*--font1-size* _PX_::
  Size of font 1 in pixels. The default value is 12.

*--font2* _FILE_::
  Path to a font to use for the second font. See font 1 for further information.

*--font2-size* _PX_::
  Size of font 2 in pixels. The default value is 12.

*--font-path* _PATH_::
  Configures the path where the settings scene looks for fonts. The user can
  choose from any font in the directory. This is more flexible than using
  *--font1* or *--font2* directly. The default path is 'config-path/Font'.

*--language* _LANG_::
  Loads the game translation in language/'LANG' folder.

*--load-game-id* _ID_::
  Skip the title scene and load Save__ID__.lsd ('ID' is padded to two digits).

*--log-file* _FILE_::
  Path to the logfile. The Player will write diagnostic messages to this file.
  The default logfile is '$XDG_STATE_HOME/EasyRPG-Player.log'.

*--new-game*::
  Skip the title scene and start a new game directly.

*--no-log-color*::
  Disable colors in terminal log.

*--no-rtp*::
  Disable support for the Runtime Package (RTP). Will lead to checkerboard
  graphics and silent music/sound effects in games depending on the RTP.

*--patch-antilag-switch* _SWITCH_::
  Disables event page refreshing when the switch 'SWITCH' is set to 'ON'.

*--patch-common-this*::
  Enable usage of __This Event__ in common events in any version of the engine.
  By default, this behaviour is only enabled for RPG Maker 2003 v1.12.

*--patch-direct-menu* _VAR_::
  Directly access subscreens of the default menu by setting VAR.
  See also: https://dev.makerpendium.de/docs/patch_db/main-en.htm?page=direct_menu

*--patch-dynrpg*::
  Enable limited support for the DynRPG patch from Cherry. The patches are not
  loaded from DLL files, but re-implemented by the engine. See also:
  https://rpg-maker.cherrytree.at/dynrpg/getting_started.html

*--patch-easyrpg*::
  Enable EasyRPG extensions such as support for 32 bit images and large charsets.

*--patch-key-patch*::
  Enable support for the Key Patch by Ineluki.

*--patch-maniac* _[N]_::
  Enable support for the Maniac Patch by BingShan.
  Values for N:
   - 1: Enable the patch (default)
   - 2: Enable the patch but do not adjust variable ranges to 32-bit.

  Not adjusting the variable ranges is useful if you are adding the patch to an
  existing game, as this reduces the likelihood that the game will stop working.

*--patch-pic-unlock*::
  Picture movement is not interrupted by messages in any version of the engine.
  By default, this behaviour is only enabled for RPG Maker 2003 v1.12.

*--patch-rpg2k3-cmds*::
  Support all RPG Maker 2003 event commands in any version of the engine.

*--no-patch*::
  Disable all engine patches.

NOTE: Providing any patch option disables the patch autodetection of the engine.
To disable a single patch, prefix any of the patch options with *--no-*.

*--project-path* _PATH_::
  Instead of using the working directory, the game in 'PATH' is used.

*--record-input* _FILE_::
  Record all button inputs to 'FILE'.

*--replay-input* _FILE_::
  Replays button input from 'FILE', as generated by *--record-input*. If the
  RNG seed (*--seed*) and the state of the save file directory are the same as
  it was when the log was recorded, this should reproduce an identical run to
  the one recorded.

*--rtp-path* _PATH_::
  Adds 'PATH' to the RTP directory list and use this one with highest
  precedence.

*--save-path* _PATH_::
  Instead of storing save files in the game directory they are stored in
  'PATH'. The directory must exist.

NOTE: When using the game browser all games will share the same save directory!

*--seed* _SEED_::
  Seeds the random number generator.


=== Video options

*--fps-limit*::
  In combination with *--no-vsync* sets a custom frames per second limit. If
  unspecified, the default is 60 fps. Set to 0 or use *--no-fps-limit* to
  disable the frame limiter. This option may not be supported on all platforms.

*--fps-render-window*::
  Render the frames per second counter in both fullscreen and windowed mode.
  Can be disabled with *--no-fps-render-window*.

*--fullscreen*::
  Start in fullscreen mode.

*--game-resolution* _RESOLUTION_::
  Force a different game resolution. RPG Maker games are designed for 320x240.
  This option fakes certain metrics to make games run at higher resolutions.
  Rendering in a different resolution can cause graphical glitches or break
  games entirely. Possible options:
   - 'original'    - 320x240 (4:3), the default resolution
   - 'widescreen'  - 416x240 (16:9)
   - 'ultrawide'   - 560x240 (21:9)

*--pause-focus-lost*::
  Pause the game when the window has no focus. Can be disabled with
  *--no-pause-focus-lost*.

*--scaling* _MODE_::
  How the video output is scaled. Possible options:
   - 'nearest'    - Scale to screen size using nearest neighbour algorithm.
                    This is fast, but causes scaling artifacts.
   - 'integer'    - Like 'nearest' but scales to a multiple of the game
                    resolution to avoid artifacts.
   - 'bilinear'   - Like 'nearest' but apply a bilinear filter to avoid the
                    artifacts.
*--show-fps*::
  Enable display of the frames per second counter. When in windowed mode it is
  shown inside the window. When in fullscreen mode it is shown in the titlebar.
  Use *--fps-render-window* to always show the counter inside the window. Can be
  disabled with *--no-show-fps*.

*--stretch*::
  Ignore the aspect ratio and stretch video output to the entire width of the
  screen. Can be disabled with *--no-stretch*.

*--vsync*::
  Enables vertical sync. Vsync may or may not be supported on all platforms.
  Check the engine log to verify whether or not vsync actually is being used.
  Can be disabled with *--no-vsync*.

*--window*::
  Start in windowed mode.


=== Audio options

*--disable-audio*::
  Disable audio (in case you prefer your own music).

*--music-volume* _VOLUME_::
  Set the volume of background music to a value from 0 to 100.

*--sound-volume* _VOLUME_::
  Set the volume of sound effects to a value from 0 to 100.

*--soundfont* _FILE_::
  Adds 'FILE' to the list of soundfonts used for playing MIDI files and use
  this one with highest precedence. The soundfont must be in SF2 format.

*--soundfont-path* _P_::
  Configures the path where the settings scene looks for soundfonts. The user
  can choose from any soundfont in the directory. This is more flexible than
  using *--soundfont* directly. The default path is 'config-path/Soundfont'.

=== Debug options

*--battle-test* _MONSTERPARTY_::
  Starts a battle test with the specified monster party. This is for starting
  battle tests in RPG Maker 2000.

*--battle-test* _MONSTERPARTY_ _FORMATION_ _CONDITION_ _TERRAIN_::
  Starts a battle test with the specified monster party, formation, start
  condition and terrain. This is for starting battle tests in RPG Maker 2003.

*--hide-title*::
  Hide the title background image and center the command menu.

*--start-map-id* _ID_::
  Overwrite the map used for new games and use Map__ID__.lmu instead ('ID' is
  padded to four digits).

NOTE: Incompatible with *--load-game-id*.

*--start-position* _X_ _Y_::
  Overwrite the party start position and move the party to position ('X', 'Y').

NOTE: Incompatible with *--load-game-id*.

*--start-party* _A_ [_B_ _..._]::
  Overwrite the starting party members with the actors with IDs 'A', 'B', '...'

NOTE: Incompatible with *--load-game-id*.

*--test-play*::
  Enable TestPlay (Debug) mode.


=== Other options

*-v*, *--version*::
  Display program version and exit.

*-h*, *--help*::
  Display help and exit.

For compatibility with the original RPG Maker runtime the following legacy
arguments are supported:

*BattleTest* _ID_::
  Same as *--battle-test*. The argument list starts at the 4th argument.

*HideTitle*::
  Same as *--hide-title*.

*TestPlay*::
  Same as *--test-play*.

*Window*::
  Same as *--window*.


== Environment

'RPG2K_RTP_PATH'::
  Full path to a directory containing an extracted RPG Maker 2000
  Runtime Package (RTP).

'RPG2K3_RTP_PATH'::
  Full path to a directory containing an extracted RPG Maker 2003 RTP.

'RPG_RTP_PATH'::
  Full path to a directory containing a combined RTP.

NOTE: All '*_RTP_PATH' variables support directory lists, using colon (':') or
semicolon (';') as separator. Useful when you have multiple translated RTP
versions or directories with extra files. The '--rtp-path' command line
option supports directory lists as well.

'SDL_SOUNDFONTS'::
  List of soundfonts in sf2 format to use when playing MIDI files. The first
  existing soundfont is used.

NOTE: Use colon (':') or semicolon (';') as separator. Use '--soundfont'
to specify a soundfont on the command line.


== Files

=== EasyRPG.ini
Sets game-specific settings to alter the engine behaviour. It follows a simple
*Key*=_Value_ syntax in multiple sections.

Options in section 'Game':

*NewGame*=_1_::
  Same as *--new-game*.

*FakeResolution*=_1_::
  When 'WinW'/'WinH' in 'RPG_RT.ini' are used, enable the metric faking
  algorithm used by *--game-resolution*.

*Engine*=_ENGINE_::
  Same as *--engine*.

Options in section 'Patch' (see also options starting with *--patch*):

*AntiLagSwitch*=_SWITCH_::
  Same as *--patch-anti-lag-switch* 'SWITCH'.

*CommonThisEvent*=_1_::
  Same as *--patch-common-this*.

*DynRPG*=_1_::
  Same as *--patch-dynrpg*.

*KeyPatch*=_1_::
  Same as *--patch-key-patch*.

*Maniac*=_1_::
  Same as *--patch-maniac*.

*PicUnlock*=_1_::
  Same as *--patch-pic-unlock*.

*RPG2k3Commands*=_1_::
  Same as *--patch-rpg2k3-commands*.

NOTE: Providing any patch option disables the patch autodetection of the engine.

Example:

----
[Game]
NewGame=1
Engine=rpg2k

[Patch]
CommonThisEvent=1
Maniac=1
----

NOTE: Values in the configuration file will overwrite auto-detected ones,
however, command line parameters will take precedence.

=== RPG_RT.ini
The game configuration file. It follows a simple *Key*=_Value_ syntax in
multiple sections.

Options in section 'RPG_RT':

*GameTitle*=_TITLE_::

  Title shown in the titlebar. The string must have the same encoding as the
  game (see also *--encoding*).

*FullPackageFlag*=_1_::

  Indicates that the game does not use assets from the Runtime Package (RTP).

*WinW*=_WIDTH_::

  Set a custom screen width in pixels. Use this in combination with *WinH*. The
  x and y coordinates are at the top-left corner. This behaviour can be
  altered with *FakeResolution*.

*WinH*=_HEIGHT_::

  Set a custom screen height.

NOTE: These resolution options were invented by the Maniac Patch but they are
processed even when the patch is disabled. Using a custom resolution disables
*--game-resolution*.

Options in section 'EasyRPG':

*Encoding*=_ENCODING_::
  Same as *--encoding*.

Example:

----
[RPG_RT]
GameTitle=My Game
FullPackageFlag=1
WinW=640
WinH=480

[EasyRPG]
Encoding=1252
----

'Encoding=1252' sets the correct encoding for most English games.

NOTE: Values in the configuration file will overwrite auto-detected ones,
however, command line parameters will take precedence.

== Reporting Bugs

Bugs should be reported at the issue tracker:
https://github.com/EasyRPG/Player/issues


== Copyright / Authors

EasyRPG Player is Copyright (C) 2007-2025 the EasyRPG authors, see file
AUTHORS.md for details.

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU GPL version 3.
See the file COPYING or http://gnu.org/licenses/gpl.html for details.


== See Also

mkxp - An open source RGSS (Ruby Game Scripting System) interface
implementation that aims to support games created by "RPG Maker XP",
"RPG Maker VX" and "RPG Maker VX Ace".

For additional information about EasyRPG software and related projects there
is a wiki: https://wiki.easyrpg.org
