Skip to content

Commit ef3a61a

Browse files
fpscanfpscan
authored
Merge pull request #1122 from white-axe/mkxp-z
Update mkxp-z documentation
2 parents c3675f6 + 6370606 commit ef3a61a

2 files changed

Lines changed: 126 additions & 15 deletions

File tree

‎docs/guides/memorymonitoring.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -238,6 +238,13 @@ To be clear: the cores listed on this page support libretro's memory monitoring
238238
|-------------------------------------------------------------|:---------:|:------|
239239
| [Beetle VB](https://github.com/libretro/beetle-vb-libretro) | ✔ | |
240240

241+
### RPG Maker
242+
243+
| Core | Supported | Notes |
244+
|------------------------------------------------|:---------:|:------|
245+
| [EasyRPG](https://github.com/libretro/easyrpg-libretro) | ✕ | |
246+
| [mkxp-z](https://github.com/mkxp-z/mkxp-z) | ✔ | Only supported on little-endian devices. |
247+
241248
### Sega
242249

243250
#### Dreamcast/Naomi

‎docs/library/mkxp-z.md‎

Lines changed: 119 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,28 @@ Open-source cross-platform player for (some) RPG Maker XP / VX / VX Ace games. A
88

99
The mkxp-z core has been authored by:
1010

11-
- mkxp-z
11+
- [Aeodyn](https://github.com/Aeodyn) <Aeodyn0@gmail.com>
12+
- [Alex Folland](https://github.com/AlexFolland) <lexlexlex@gmail.com>
13+
- [Amaryllis Kulla](https://github.com/Ancurio) <ancurio@mapleshrine.eu>
14+
- [Thomas Schneider](https://github.com/BlackLotus)
15+
- [Carsten Teibes](https://github.com/carstene1ns) <dev@f4ke.de>
16+
- [cremno](https://github.com/cremno) <cremno@mail.ru>
17+
- [David Salvisberg](https://github.com/Daverball) <dave@daverball.com>
18+
- [Eblo](https://github.com/Eblo)
19+
- [Eliza Velasquez](https://github.com/elizagamedev)
20+
- [Jáchym Toušek](https://github.com/enumag) <enumag@gmail.com>
21+
- [ijuintekka](https://github.com/ijuintekka) <ijuintekka@hotmail.com>
22+
- [Joni Savolainen](https://github.com/jonisavo) <joni@savolainen.io>
23+
- [Luis Cáceres](https://github.com/lacc97) <lacc97@protonmail.ch>
24+
- [mook](https://github.com/mook)
25+
- [Nathan de Medeiros Vieira](https://github.com/Nathan-MV) <nathanmvieira@outlook.com>
26+
- [Riley Pierce](https://github.com/rainefall) <rileyraine01@gmail.com>
27+
- [Rodrigo Locatti](https://github.com/ReinUsesLisp) <rodrigo.locatti@gmail.com>
28+
- [Splendide Imaginarius](https://github.com/Splendide-Imaginarius)
29+
- Struma <strumajen@icloud.com>
30+
- [Edward Rudd](https://github.com/urkle) <urkle@outoforder.cc>
31+
- [Wayward Heart](https://github.com/WaywardHeart)
32+
- [Hao Liu (刘皓)](https://github.com/white-axe) <whiteaxe@tuta.io>
1233

1334
The mkxp-z core is licensed under:
1435

@@ -64,7 +85,6 @@ Content that can be loaded by the mkxp-z core have the following file extensions
6485
- .rxproj
6586
- .rvproj
6687
- .rvproj2
67-
- .mkxp
6888
- .mkxpz
6989
- .zip
7090
- .7z
@@ -83,12 +103,12 @@ Frontend-level settings or features that the mkxp-z core respects:
83103
| Restart | ✔ |
84104
| Saves | ✔ |
85105
| States | ✔ |
86-
| Rewind | ✔ * |
87-
| Netplay | ✔ * |
106+
| Rewind | ✔ [^1] |
107+
| Netplay | ✔ [^1] |
88108
| Core Options | ✔ |
89-
| [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ |
90-
| RetroArch Cheats | ✕ |
91-
| Native Cheats | ✕ |
109+
| [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ [^2] |
110+
| RetroArch Cheats | ✔ [^2] |
111+
| Native Cheats | ✔ |
92112
| Controls | ✔ |
93113
| Remapping | ✔ |
94114
| Multi-Mouse | ✕ |
@@ -104,8 +124,6 @@ Frontend-level settings or features that the mkxp-z core respects:
104124
| Crop Overscan | ✕ |
105125
| LEDs | ✕ |
106126

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-
109127
## Directories
110128

111129
The mkxp-z core's library name is 'mkxp-z'
@@ -124,6 +142,8 @@ The mkxp-z core saves/loads to/from these directories.
124142
|:------------:|:-----------:|
125143
| 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. |
126144
| mkxp-z/RTP | This is where RTPs are loaded from. See the [BIOS](#bios) section for more details. |
145+
| mkxp-z/Scripts/Preload | Any preload scripts added to this directory can be toggled in the "Preload Scripts" section of the core options. Enabled preload scripts will be loaded in lexicographic order of the bytes in their file names prior to loading the game's scripts. |
146+
| mkxp-z/Scripts/Postload | Any postload scripts added to this directory can be toggled in the "Postload Scripts" section of the core options. In RPG Maker VX Ace games, enabled postload scripts will be loaded in lexicographic order of the bytes in their file names after the game's scripts are loaded but before the game starts running. Enabled postload scripts have no effect in RPG Maker XP and RPG Maker VX games. |
127147

128148
## Geometry and timing
129149

@@ -140,17 +160,23 @@ The mkxp-z core saves/loads to/from these directories.
140160
There are three ways to load games using the mkxp-z core:
141161

142162
- 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.
163+
- Create an empty file with the file extension .rxproj, .rvproj or .rvproj2 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.
144164
- 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.
145165

146-
There is currently no way to load preload scripts or postload scripts. Support for preload/postload scripts will be added in the future.
166+
Preload scripts and postload scripts may be added to the mkxp-z/Scripts/Preload and mkxp-z/Scripts/Postload subdirectories of the libretro system directory. Each preload script and postload script added to these directories has its own core option for toggling it. If more than one preload script or postload script is enabled via the core options at the same time, they will be loaded in lexicographic order of the bytes in the file names, which is the same as the order in which they appear in the core options menu.
167+
168+
The default set of preload scripts provided with mkxp-z is embedded in the core and available by default to remove the need to manually copy them into the preload script directory.
169+
170+
Native cheats are run as Ruby scripts. They can be used, for example, to change the contents of `$game_switches`.
147171

148172
## Core options
149173

150174
The mkxp-z core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded.
151175

152176
Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch.
153177

178+
In addition to the core options shown below, there are also core options for changing the key bindings and the currently enabled preload scripts and postload scripts.
179+
154180
- **Runtime: RGSS Version** (Restart) [mkxp-z_rgssVersion] (**inherit**|default|1|2|3)
155181

156182
Specify the RGSS version to run under.
@@ -159,12 +185,26 @@ Settings with (Restart) means that core has to be closed for the new setting to
159185
If this fails, the version defaults to 1.
160186
Changes will take effect after the core is reset.
161187

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)
188+
- **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|544|576|608|640|672|704|736|768|800|832|864|896|928|960|992|1024|1152|1280|1408|1536|1664|1792|1920|2048|2560|3072|3584|4096)
163189

164190
Maximum size of each save state, in mebibytes.
165191
If the game uses more than this much memory, save state creation will fail.
166192
Changes to this setting will not take effect until the core is unloaded.
167193

194+
- **Runtime: Debug** (Restart) [mkxp-z_debug] (enabled|**disabled**)
195+
196+
Launch the game in debug mode.
197+
Changes will take effect after the core is reset.
198+
199+
- **Runtime: Battle Test** (Restart) [mkxp-z_battleTest] (enabled|**disabled**)
200+
201+
Launch the game in battle test mode.
202+
Changes will take effect after the core is reset.
203+
204+
- **Video: Frame Skip** [mkxp-z_frameSkip] (inherit|enabled|**disabled**)
205+
206+
Skip (don't draw) frames when behind.
207+
168208
- **Video: Subimage Fix** [mkxp-z_subImageFix] (inherit|**default**|enabled|disabled)
169209

170210
Work around buggy graphics drivers which don't
@@ -181,6 +221,16 @@ Settings with (Restart) means that core has to be closed for the new setting to
181221
disabling it can be used as a workaround.
182222
(default: disabled on Windows, enabled on other systems)
183223

224+
- **Video: Texture Synchronization** [mkxp-z_textureSync] (**default**|eager|lazy)
225+
226+
Controls how often GPU textures are copied to CPU memory.
227+
Eager synchronization is less likely to cause graphical issues but may cause performance problems in some games.
228+
Lazy synchronization is faster but may or may not,
229+
depending on which libretro frontend you're using and what version of it you're using,
230+
cause graphical artifacts when performing certain operations,
231+
such as toggling fullscreen or, on Android, opening the app switcher.
232+
(default: lazy)
233+
184234
- **Audio: Threaded Audio** (Restart) [mkxp-z_threadedAudio] (**enabled**|disabled)
185235

186236
Use a worker thread for rendering the audio instead of
@@ -208,8 +258,56 @@ Settings with (Restart) means that core has to be closed for the new setting to
208258
the maximum of the value set here and the value in
209259
mkxp.json will be used)
210260

261+
- **Text: Font Scale** [mkxp-z_fontScale] (0.2|0.25|0.3|0.35|0.4|0.45|0.5|0.55|0.6|0.65|0.7|0.75|0.8|0.85|0.9|0.95|**1.0**|1.05|1.1|1.15|1.2|1.25|1.3|1.35|1.4|1.45|1.5|1.55|1.6|1.65|1.7|1.75|1.8|1.85|1.9|1.95|2.0|2.05|2.1|2.15|2.2|2.25|2.3|2.35|2.4|2.45|2.5|2.55|2.6|2.65|2.7|2.75|2.8|2.85|2.9|2.95|3.0|3.05|3.1|3.15|3.2|3.25|3.3|3.35|3.4|3.45|3.5|3.55|3.6|3.65|3.7|3.75|3.8|3.85|3.9|3.95|4.0|4.05|4.1|4.15|4.2|4.25|4.3|4.35|4.4|4.45|4.5|4.55|4.6|4.65|4.7|4.75|4.8|4.85|4.9|4.95|5.0)
262+
263+
Scales the sizes of all fonts.
264+
If you think text tends to be too large or too small,
265+
try fiddling with this.
266+
(if this value is also set in the game's mkxp.json,
267+
the product of the value set here and the value in
268+
mkxp.json will be used)
269+
270+
- **Text: Kerning** [mkxp-z_fontKerning] (**inherit**|default|enabled|disabled)
271+
272+
Kerning adjusts the spacing between individual letters or characters.
273+
Enabling it generally looks nicer, but RGSS doesn't use it,
274+
so disabling it should make text appearance more accurate.
275+
(default: enabled)
276+
277+
- **Text: Font Hinting** [mkxp-z_fontHinting] (**inherit**|default|0|1|2|3)
278+
279+
Hinting adjusts the rendering of individual letters or characters.
280+
Enabling it may look nicer (especially on low-resolution displays), but
281+
RGSS doesn't use it, so disabling it should make text appearance more
282+
accurate. Documentation can be found at:
283+
https://pysdl2.readthedocs.io/en/latest/modules/sdl2_sdlttf.html#sdl2.sdlttf.TTF_HINTING_NORMAL
284+
(default: 3)
285+
286+
- **Text: Font Height Reporting** [mkxp-z_fontHeightReporting] (**inherit**|default|0|1)
287+
288+
Controls the algorithm for reporting the height of rendered text.
289+
0: Nominal (TTF_FontHeight); matches RGSS behavior; may cut off bottoms of some characters.
290+
1: Rendered (TTF_SizeUTF8); deviates from RGSS; may look better.
291+
(default: 0)
292+
293+
- **Text: Outline Crop** [mkxp-z_fontOutlineCrop] (**inherit**|default|enabled|disabled)
294+
295+
Crops top row and left column of text that has an outline.
296+
Disabling it generally looks nicer, but RGSS enables it, so enabling it
297+
should make text appearance more accurate.
298+
(default: enabled)
299+
300+
- **Text: Load Fonts Into Memory** [mkxp-z_loadFontsIntoMemory] (**default**|enabled|disabled)
301+
302+
When loading a font, load the entire font file into memory instead of using a file handle.
303+
This improves text rendering performance on systems with extremely slow file system access speed
304+
at the cost of higher memory usage.
305+
(default: enabled on Emscripten, disabled on other platforms)
306+
211307
## Joypad
212308

309+
These are the default bindings. They can be changed in the "Button Bindings" section of the core options if needed.
310+
213311
| RetroPad Inputs | RGSS Inputs |
214312
|------------------------------------------------|--------------------------|
215313
| ![](../image/retropad/retro_a.png) | Input::C |
@@ -222,16 +320,18 @@ Settings with (Restart) means that core has to be closed for the new setting to
222320
| ![](../image/retropad/retro_dpad_right.png) | Input::RIGHT |
223321
| ![](../image/retropad/retro_l1.png) | Input::L |
224322
| ![](../image/retropad/retro_r1.png) | Input::R |
225-
| ![](../image/retropad/retro_l2.png) | Input::SHIFT |
226-
| ![](../image/retropad/retro_r2.png) | Input::CTRL |
323+
| ![](../image/retropad/retro_l2.png) | Input::CTRL |
324+
| ![](../image/retropad/retro_r2.png) | Input::SHIFT |
227325
| ![](../image/retropad/retro_l3.png) | Input::Y |
228326
| ![](../image/retropad/retro_r3.png) | Input::Z |
229-
| ![](../image/retropad/retro_select.png) | Input::ALT |
327+
| ![](../image/retropad/retro_start.png) | Input::ALT |
230328
| ![](../image/retropad/retro_left_stick.png) X | Input::LEFT and Input::RIGHT |
231329
| ![](../image/retropad/retro_left_stick.png) Y | Input::UP and Input::DOWN |
232330

233331
## Mouse
234332

333+
These are the default bindings. They can be changed in the "Button Bindings" section of the core options if needed.
334+
235335
| RetroMouse Inputs | RGSS Inputs |
236336
|-------------------------------------------------------|---------------------------|
237337
| ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Input.mouse_x and Input.mouse_y |
@@ -252,3 +352,7 @@ Settings with (Restart) means that core has to be closed for the new setting to
252352
## (Related cores)
253353

254354
- [RPG Maker 2000/2003 (EasyRPG)](easyrpg.md)
355+
356+
[^1]: 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.
357+
358+
[^2]: Only supported on little-endian devices.

0 commit comments

Comments
 (0)