Skip to content

Commit aa253e3

Browse files
fpscanfpscan
authored
Merge pull request #1082 from white-axe/mkxp-z
Add mkxp-z documentation
2 parents c1eb934 + fa9bd64 commit aa253e3

File tree

7 files changed

+271
-2
lines changed

7 files changed

+271
-2
lines changed

‎docs/development/licenses.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,7 @@ See below for a summary of the licenses behind RetroArch and its cores:
159159
| [Meteor](../library/meteor.md) | [GPLv3](https://github.com/libretro/meteor-libretro/blob/master/COPYING) | |
160160
| [mGBA](../library/mgba.md) | [MPLv2.0](https://github.com/libretro/mgba/blob/master/LICENSE) | |
161161
| [MicroW8](../library/microw8.md) | [Unlicense](https://github.com/libretro/uw8-libretro/blob/main/UNLICENSE) | |
162+
| [mkxp-z](../library/mkxp-z.md) | [GPLv2](https://github.com/mkxp-z/mkxp-z/blob/dev/COPYING) | |
162163
| mpv | [GPLv3](https://github.com/libretro/libretro-mpv/blob/master/LICENSE) | |
163164
| [Mr.Boom](../library/mr_boom.md) | [MIT](https://github.com/libretro/mrboom-libretro/blob/master/LICENSE) | |
164165
| Mupen64Plus | [GPLv3](https://github.com/libretro/mupen64plus-libretro/blob/master/LICENSE) | |

‎docs/guides/core-list.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,7 @@
137137
| [mGBA](../library/mgba.md) | Game Boy Advance | |
138138
| Microw8 | Game engine | A port of a WebAssembly based fantasy console to libretro |
139139
| [Minivmac](../library/minivmac.md) | Mac II | MacII variant of minivmac emulator |
140+
| [mkxp-z](../library/mkxp-z.md) | RPG Maker XP/VX/VX Ace | |
140141
| mpv | Media player | An port of MPV media player to libretro |
141142
| Mr.Boom | Game | A clone of the classic Bomberman series |
142143
| Mu | Palm OS | An emulator for the Palm m515 OS ported to libretro |

‎docs/library/bios.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,8 @@ PlayStation | Beetle PSX HW | [BIOS information](beetle_p
9090
PlayStation | PCSX ReARMed | [BIOS information](pcsx_rearmed.md#bios)
9191
Pokémon Mini | PokeMini | [BIOS information](pokemini.md#bios)
9292
PSP | PPSSPP | [BIOS information](ppsspp.md#bios)
93+
RPG Maker 2000/2003 | EasyRPG | [BIOS information](easyrpg.md#rtp-files)
94+
RPG Maker XP/VX/VX Ace | mkxp-z | [BIOS information](mkxp-z.md#bios)
9395
Saturn | Beetle Saturn | [BIOS information](beetle_saturn.md#bios)
9496
Saturn | Kronos | [BIOS information](kronos.md#bios)
9597
Saturn | Yabause | [BIOS information](yabause.md#bios)

‎docs/library/easyrpg.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ You must download the RTP2000 and RTP2003 from [here](https://www.rpgmakerweb.co
4141

4242
RetroArch database(s) that are associated with the EasyRPG core:
4343

44-
- [RPG Maker](https://github.com/libretro/libretro-database/blob/master/rdb/RPG%20Maker.rdb) (only covers 2000 and 2003 games, not the other versions)
44+
- [RPG Maker](https://github.com/libretro/libretro-database/blob/master/rdb/RPG%20Maker.rdb)
4545
- [RPG Maker thumbnails](https://github.com/libretro-thumbnails/RPG_Maker)
4646

4747
## Features
@@ -150,3 +150,7 @@ The EasyRPG core supports the following device type(s) in the controls menu, bol
150150
- [Libretro EasyRPG Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/easyrpg_libretro.info)
151151
- [Libretro EasyRPG Github Repository](https://github.com/libretro/easyrpg-libretro)
152152
- [Report Libretro EasyRPG Core Issues Here](https://github.com/libretro/easyrpg-libretro/issues)
153+
154+
## (Related cores)
155+
156+
- [RPG Maker XP/VX/VX Ace (mkxp-z)](mkxp-z.md)

‎docs/library/mkxp-z.md‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
# RPG Maker XP/VX/VX Ace (mkxp-z)
2+
3+
## Background
4+
5+
Open-source cross-platform player for (some) RPG Maker XP / VX / VX Ace games. A very heavily modified fork of mkxp. RGSS on steroids with a stupid name.
6+
7+
### Author/License
8+
9+
The mkxp-z core has been authored by:
10+
11+
- mkxp-z
12+
13+
The mkxp-z core is licensed under:
14+
15+
- [GPLv2](https://github.com/mkxp-z/mkxp-z/blob/dev/COPYING)
16+
17+
A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md).
18+
19+
## Requirements
20+
21+
Currently, the mkxp-z core requires hardware that supports OpenGL 2.0 or later or OpenGL ES 2.0 or later.
22+
23+
## BIOS
24+
25+
Some RPG Maker games require RTPs (Run Time Packages), which are stock assets intended to be shared between games.
26+
27+
There is one standard RTP for each RPG Maker version supported by the mkxp-z core (XP, VX, VX Ace), which can be downloaded from [https://www.rpgmakerweb.com/run-time-package](https://www.rpgmakerweb.com/run-time-package).
28+
29+
The RTPs are distributed as Windows installers and need to be extracted before they can be used by the mkxp-z core. They can be extracted on many different operating systems using [innoextract](https://constexpr.org/innoextract/). The installers are also runnable in Wine, although innoextract is more convenient.
30+
31+
Once extracted, the RTP files should consist of a directory which contains two subdirectories named "Audio" and "Graphics" and possibly other files and subdirectories. The directory that contains the "Audio" and "Graphics" subdirectories should be renamed to "Standard" (for RPG Maker XP), "RPGVX" (for RPG Maker VX) or "RPGVXAce" (for RPG Maker VX Ace) and placed into the "mkxp-z/RTP" subdirectory of the frontend's system directory. If done correctly, the directory structure should look like this:
32+
33+
```
34+
[system directory]
35+
└── mkxp-z
36+
└── RTP
37+
├── RPGVX
38+
│   ├── Audio
39+
│   ├── Fonts
40+
│   ├── Game.ico
41+
│   ├── Graphics
42+
│   ├── RGSS200J.dll
43+
│   ├── RGSS202E.dll
44+
│   └── RGSS202J.dll
45+
├── RPGVXAce
46+
│   ├── Audio
47+
│   ├── Fonts
48+
│   ├── Game.ico
49+
│   └── Graphics
50+
└── Standard
51+
├── Audio
52+
├── Game.ico
53+
└── Graphics
54+
```
55+
56+
The three files named Game.ico and the .dll files listed in the above directory tree are not required by the mkxp-z core. Feel free to delete them if you want.
57+
58+
## Extensions
59+
60+
Content that can be loaded by the mkxp-z core have the following file extensions (see the [Usage](#usage) section for instructions on how to load games):
61+
62+
- .ini
63+
- .json
64+
- .rxproj
65+
- .rvproj
66+
- .rvproj2
67+
- .mkxp
68+
- .mkxpz
69+
- .zip
70+
- .7z
71+
72+
RetroArch database(s) that are associated with the mkxp-z core:
73+
74+
- [RPG Maker](https://github.com/libretro/libretro-database/blob/master/rdb/RPG%20Maker.rdb)
75+
- [RPG Maker thumbnails](https://github.com/libretro-thumbnails/RPG_Maker)
76+
77+
## Features
78+
79+
Frontend-level settings or features that the mkxp-z core respects:
80+
81+
| Feature | Supported |
82+
|-------------------|:---------:|
83+
| Restart | ✔ |
84+
| Saves | ✔ |
85+
| States | ✔ |
86+
| Rewind | ✔ * |
87+
| Netplay | ✔ * |
88+
| Core Options | ✔ |
89+
| RetroAchievements | ✕ |
90+
| RetroArch Cheats | ✕ |
91+
| Native Cheats | ✕ |
92+
| Controls | ✔ |
93+
| Remapping | ✔ |
94+
| Multi-Mouse | ✕ |
95+
| Rumble | ✕ |
96+
| Sensors | ✕ |
97+
| Camera | ✕ |
98+
| Location | ✕ |
99+
| Subsystem | ✕ |
100+
| [Softpatching](../guides/softpatching.md) | ✕ |
101+
| Disk Control | ✕ |
102+
| Username | ✔ |
103+
| Language | ✔ |
104+
| Crop Overscan | ✕ |
105+
| LEDs | ✕ |
106+
107+
\* Because RetroArch does not currently support rewind or netplay with cores that use threaded audio, rewind and netplay currently require disabling the ["Threaded Audio" core option](#core-options). This core option is enabled by default for better performance and for closer similarity to the original RPG Maker runtimes, which also use threaded audio.
108+
109+
## Directories
110+
111+
The mkxp-z core's library name is 'mkxp-z'
112+
113+
The mkxp-z core saves/loads to/from these directories.
114+
115+
**Frontend's Save directory**
116+
117+
| Directory | Description |
118+
|:------------:|:-----------:|
119+
| mkxp-z/Saves/[game title] | This is the directory where the game's save files are saved to. The exact contents of the directory vary depending on the specific game being played. |
120+
121+
**Frontend's System directory**
122+
123+
| Directory | Description |
124+
|:------------:|:-----------:|
125+
| mkxp-z/Fonts | Any fonts that the game uses that are not found in the game files will be loaded from here as a fallback. Supported file extensions for fonts are .otf and .ttf. The names of the font files do not matter since the mkxp-z core matches fonts based on the font family name stored in the file. |
126+
| mkxp-z/RTP | This is where RTPs are loaded from. See the [BIOS](#bios) section for more details. |
127+
128+
## Geometry and timing
129+
130+
- The mkxp-z core's core provided FPS is 40 (RPG Maker XP) or 60 (RPG Maker VX, RPG Maker VX Ace).
131+
- The mkxp-z core's core provided sample rate is 44100 hertz.
132+
- The mkxp-z core's base width is 640 (RPG Maker XP) or 544 (RPG Maker VX, RPG Maker VX Ace).
133+
- The mkxp-z core's base height is 480 (RPG Maker XP) or 416 (RPG Maker VX, RPG Maker VX Ace).
134+
- The mkxp-z core's max width is 640 (RPG Maker XP) or 544 (RPG Maker VX, RPG Maker VX Ace).
135+
- The mkxp-z core's max height is 480 (RPG Maker XP) or 416 (RPG Maker VX, RPG Maker VX Ace).
136+
- The mkxp-z core's core provided aspect ratio is 4:3 (RPG Maker XP) or 17:13 (RPG Maker VX, RPG Maker VX Ace).
137+
138+
## Usage
139+
140+
There are three ways to load games using the mkxp-z core:
141+
142+
- Load the Game.ini or mkxp.json.
143+
- Create an empty file with the file extension .mkxp in the same directory as Game.ini and/or mkxp.json, and load that. This is intended to make it easier to deal with save states in RetroArch, since RetroArch's save states are named after the file you load as the game, so if you load Game.ini or mkxp.json, all the save states for every game will be named "Game" or "mkxp", which is really inconvenient.
144+
- Put the game into a zip or 7z archive with file extension .mkxpz, .zip or .7z and load that. Please note that the files inside the zip or 7z archive should be uncompressed if possible, especially .rgssad/.rgss2a/.rgss3a and .otf/.ttf files inside the archive, or the game will lag quite a bit from trying to seek compressed files. The game will still run, though, just very slowly.
145+
146+
There is currently no way to load preload scripts or postload scripts. Support for preload/postload scripts will be added in the future.
147+
148+
## Core options
149+
150+
The mkxp-z core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded.
151+
152+
Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch.
153+
154+
- **Runtime: RGSS Version** (Restart) [mkxp-z_rgssVersion] (**inherit**|default|1|2|3)
155+
156+
Specify the RGSS version to run under.
157+
By default, mkxp will try to guess the required version
158+
based on the game files.
159+
If this fails, the version defaults to 1.
160+
Changes will take effect after the core is reset.
161+
162+
- **Runtime: Save State Size** (Restart) [mkxp-z_saveStateSize] (64|66|68|70|72|74|76|78|80|82|84|86|88|90|92|94|96|98|**100**|102|104|106|108|110|112|114|116|118|120|122|124|126|128|132|136|140|144|148|152|156|160|164|168|172|176|180|184|188|192|196|200|204|208|212|216|220|224|228|232|236|240|244|248|252|256|264|272|280|288|296|304|312|320|328|336|344|352|360|368|376|384|392|400|408|416|424|432|440|448|456|464|472|480|488|496|504|512|528|544|560|576|592|608|624|640|656|672|688|704|720|736|752|768|784|800|816|832|848|864|880|896|912|928|944|960|976|992)
163+
164+
Maximum size of each save state, in mebibytes.
165+
If the game uses more than this much memory, save state creation will fail.
166+
Changes to this setting will not take effect until the core is unloaded.
167+
168+
- **Video: Subimage Fix** [mkxp-z_subImageFix] (inherit|**default**|enabled|disabled)
169+
170+
Work around buggy graphics drivers which don't
171+
properly synchronize texture access, most
172+
apparent when text doesn't show up or the map
173+
tileset doesn't render at all.
174+
(default: enabled for systems using OpenGL ES, disabled on other systems)
175+
176+
- **Video: Framebuffer Blitting** [mkxp-z_enableBlitting] (inherit|**default**|enabled|disabled)
177+
178+
Enable framebuffer blitting if the driver is
179+
capable of it. Some drivers carry buggy
180+
implementations of this functionality, so
181+
disabling it can be used as a workaround.
182+
(default: disabled on Windows, enabled on other systems)
183+
184+
- **Audio: Threaded Audio** (Restart) [mkxp-z_threadedAudio] (**enabled**|disabled)
185+
186+
Use a worker thread for rendering the audio instead of
187+
rendering in the main thread, if possible. Reduces audio
188+
crackling, especially on systems with slow file system
189+
access speed. Changes to this setting will not take effect
190+
until the game is closed.
191+
192+
- **Audio: MIDI Chorus** [mkxp-z_midiChorus] (**inherit**|enabled|disabled)
193+
194+
Activate "chorus" effect for midi playback.
195+
196+
- **Audio: MIDI Reverb** [mkxp-z_midiReverb] (**inherit**|enabled|disabled)
197+
198+
Activate "reverb" effect for midi playback.
199+
200+
- **Audio: SE Source Count** (Restart) [mkxp-z_SESourceCount] (**6**|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59|60|61|62|63|64)
201+
202+
Number of OpenAL sources to allocate for SE playback.
203+
If there are a lot of sounds playing at the same time
204+
and audibly cutting each other off, try increasing
205+
this number.
206+
Changes will take effect after the core is reset.
207+
(if this value is also set in the game's mkxp.json,
208+
the maximum of the value set here and the value in
209+
mkxp.json will be used)
210+
211+
## Joypad
212+
213+
| RetroPad Inputs | RGSS Inputs |
214+
|------------------------------------------------|--------------------------|
215+
| ![](../image/retropad/retro_a.png) | Input::C |
216+
| ![](../image/retropad/retro_b.png) | Input::B |
217+
| ![](../image/retropad/retro_x.png) | Input::A |
218+
| ![](../image/retropad/retro_y.png) | Input::X |
219+
| ![](../image/retropad/retro_dpad_up.png) | Input::UP |
220+
| ![](../image/retropad/retro_dpad_down.png) | Input::DOWN |
221+
| ![](../image/retropad/retro_dpad_left.png) | Input::LEFT |
222+
| ![](../image/retropad/retro_dpad_right.png) | Input::RIGHT |
223+
| ![](../image/retropad/retro_l1.png) | Input::L |
224+
| ![](../image/retropad/retro_r1.png) | Input::R |
225+
| ![](../image/retropad/retro_l2.png) | Input::SHIFT |
226+
| ![](../image/retropad/retro_r2.png) | Input::CTRL |
227+
| ![](../image/retropad/retro_l3.png) | Input::Y |
228+
| ![](../image/retropad/retro_r3.png) | Input::Z |
229+
| ![](../image/retropad/retro_select.png) | Input::ALT |
230+
| ![](../image/retropad/retro_left_stick.png) X | Input::LEFT and Input::RIGHT |
231+
| ![](../image/retropad/retro_left_stick.png) Y | Input::UP and Input::DOWN |
232+
233+
## Mouse
234+
235+
| RetroMouse Inputs | RGSS Inputs |
236+
|-------------------------------------------------------|---------------------------|
237+
| ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Input.mouse_x and Input.mouse_y |
238+
| ![](../image/retromouse/retro_left.png) Mouse 1 | Input::MOUSELEFT |
239+
| ![](../image/retromouse/retro_right.png) Mouse 2 | Input::MOUSERIGHT |
240+
| ![](../image/retromouse/retro_middle.png) Mouse 3 | Input::MOUSEMIDDLE |
241+
| Mouse 4 | Input::MOUSEX1 |
242+
| Mouse 5 | Input::MOUSEX2 |
243+
| Wheel Up | Input.scroll_v |
244+
| Wheel Down | Input.scroll_v |
245+
246+
## External Links
247+
248+
- [mkxp-z GitHub Repository](https://github.com/mkxp-z/mkxp-z)
249+
- [Libretro mkxp-z Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mkxp-z_libretro.info)
250+
- [Report Libretro mkxp-z Core Issues Here](https://github.com/mkxp-z/mkxp-z/issues)
251+
252+
## (Related cores)
253+
254+
- [RPG Maker 2000/2003 (EasyRPG)](easyrpg.md)

‎docs/meta/see-also.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,11 @@ This is a list of cores that are related to each other in some way.
122122
- [Nintendo - NES / Famicom (Nestopia)](../library/nestopia.md)
123123
- [Nintendo - NES / Famicom (QuickNES)](../library/quicknes.md)
124124

125+
## RPG Maker
126+
127+
- [RPG Maker 2000/2003 (EasyRPG)](../library/easyrpg.md)
128+
- [RPG Maker XP/VX/VX Ace (mkxp-z)](../library/mkxp-z.md)
129+
125130
## id Software
126131

127132
- [Doom (PrBoom)](../library/prboom.md)

‎mkdocs.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -303,7 +303,9 @@ nav:
303303
- 'Mr.Boom (Bomberman)': 'library/mr_boom.md'
304304
- 'Quake 1 (TyrQuake)': 'library/tyrquake.md'
305305
- 'Rick Dangerous (XRick)': 'library/xrick.md'
306-
- 'RPG Maker 2000/2003 (EasyRPG)': 'library/easyrpg.md'
306+
- 'RPG Maker Emulation':
307+
- 'RPG Maker 2000/2003 (EasyRPG)': 'library/easyrpg.md'
308+
- 'RPG Maker XP/VX/VX Ace (mkxp-z)': 'library/mkxp-z.md'
307309
- 'ScummVM': 'library/scummvm.md'
308310
- 'The Powder Toy': 'library/the_powder_toy.md'
309311
- 'TIC-80': 'library/tic80.md'

0 commit comments

Comments
 (0)