JoiPlay

Introduction

JoiPlay is a player for Ren'Py, RPG Maker XP/VX/VXAce/MV, TyranoBuilder and HTML games. JoiPlay consists of main app and plugins. This approach makes JoiPlay extendable and easy to maintain. Main app (JoiPlay) acts as a game launcher and lets you add and organize games, change settings, play HTML based games (RPG Maker MV, TyranoBuilder and others) and more. Plugins add support for other game engines (Ren'Py, RPG Maker XP/VX/VXACE) to JoiPlay.

JoiPlay uses Storage and Internet permissions. These permissions are required and JoiPlay won't work without these permissions. Storage permissions (READ_EXTERNAL_STORAGE and WRITE_EXTERNAL_STORAGE) are needed to read/write game data from/to internal and external storages. Internet permission is used to check updates, get compatibility list, send http requests from games and get responses from game servers.

1.Launcher

When a user opens JoiPlay, launcher will welcome the user. Launcher lets you add, organize and start games.

Image 1.1 - Launcher

Launcher screen contains options button (1), search bar (2), game icons (3) and add game button (4).

1- Options button opens options menu which contains Import, Compatibility List, Settings, Backup/Restore, Invalidate Missing Games, Help and About items.

Image 1.2 - Options Menu

2- Search bar let you search games in game list.

3- Game icons let you start games and open game menu. Single tap to game icon starts games and long tap opens game menu. Also game icons can be arranged by long tapping and moving.

4- Add game button opens add game dialog.

Image 1.3 - Add Game Dialog

1.1 Adding Games

Users can add games by tapping add game button or opening a exe, sh, py or html file.

1.1.1 Adding games by using add game button

Adding games by using add game button is the safe way to add games. Adding a game is pretty easy and doesn't require any technical knowledge. You can follow these steps to add a game.

1- Tap add game button to show add game dialog (Image 1.3).

2- Fill game name and version (Optional).

3- Tap CHOOSE button under Executable File to show file chooser, go to game folder and choose executable file (Image 1.4).

Image 1.4 - File Chooser Dialog

4- Tap CHOOSE button under Icon to show file chooser and choose an image file (Optional).

5- Tap ADD button to add game to launcher (Image 1.5).

Image 1.5 - Filled Add Game Dialog

1.1.2 Adding games by opening with JoiPlay

Using open with dialog is the fastest way to add a game to JoiPlay. When an executable file is opened with JoiPlay, JoiPlay tries to find game name and a suitable icon and shows add game dialog with game name, executable file and icon. You can follow these steps to add a game using open with dialog.

1- Open game folder and tap executable file (Image 1.6).

Image 1.6 - Open With Dialog

2- Choose JoiPlay to show add game dialog (Image 1.7). Game name and icon will be filled if suitable information is found.

Image 1.7 - Add Game Dialog After JoiPlay Selected

3- Tap ADD button.

1.2 Options Menu

Options menu contains Import, Compatibility List, Settings, Backup/Restore, Invalidate Missing Games, Help and About items.

Import option lets you add games by importing RGA files. Importing will extract game files to /storage/emulated/0/Android/data/com.joiplay.joiplay/files folder and this folder will be used as game folder.

Compatibility List option opens Compatibility List activity where users can rate compatibility of games and see rated games.

Settings option opens Settings where users can change app, gamepad and plugin settings.

Backup/Restore option lets you backup/restore app data. This option backups/restores game list, settings, imported games and save files for games located in sdcard.

Invalidate Missing Games checks game folders for each game and removes the game if game folder is missing.

Help option shows help dialog.

About option shows about dialog where users can see app version and connect/disconnect to Patreon.

1.2 Game Menu

Game menu contains game information and options to modify game and start game specific actions.

Image 1.8 - Game Menu

Patch, Export, Edit and Delete options are independent from game type and will be shown for every game. Decrypt Files, Unpack/Repack Scripts, Optimize Maps and Edit Plugin options are only shown for RPG Maker games

Patch option applies patches to games. Patch files must be zip archives with rga extension. This option extracts files to {gamefolder}/patch folder for RPG Maker XP/VX/VXAce and {gamefolder}/ folder for other game types. JoiPlay updates game information according to game.cfg file if it exists in patch file.

Export option creates a RGA file using game information. This option copies all game assets to RGA file and created RGA file can be used to add the game by importing it. RGA files makes games easier to share and can be used to backup games.

Edit option lets users to edit game name, version and icon.

Delete option deletes the game and it's data from JoiPlay. This option will show a confirmation dialog which has a option to delete game folder. Deleting game folder with this option might also delete parent folder on some rare cases.

Decrypt Files option is available for RPG Maker games and used to decrypt encrypted files and archives. Encrypted archives won't be deleted after decryption so users should remove them manually if decryption is successful. Reading files from encrypted archives is slower than reading decrypted files so this option can be used to get some performance gains (recommended for Pokémon Essentials).

Unpack/Repack Scripts option is available for RPG Maker XP/VX/VXAce games. This option unpacks Scripts.{rx|rv}data{2} and repacks loose scripts. Unpacked scripts can be edited with a text editor to fix error or modify game. Repacking scripts might cause some unintended behaviour so original Scripts.{rx|rv}data{2} file should be backed up.

Optimize Maps option is available for RPG Maker XP games. This option recreates maps and tilesets to reduce hight of tilesets. It's a workaround for OpenGL maximum texture size limit but might cause some issues because it changes tile ids. This option should be used only when a game has tilesets bigger than ~8192px and has tile rendering issues.

Edit Plugins option is available for RPG Maker MV games. This option let users enable/disable game plugins.

2.Settings

Settings contains options related to app, gamepad and plugins. Each settings category has a separate card. Cards are collapsed by default and can be expanded/collapsed by tapping card title.

Image 2.1 - Settings

2.1 App Settings

App Settings contains global options which affect app and plugins.

Language : This option changes language of app and plugins.

Default Game Folder : This option changes default starting folder for files chooser dialog.

Follow System Theme : When this option is enabled, JoiPlay changes background color according to system theme.

Background Color : Changes background color of JoiPlay. Available colors are white, grey and black.

Accent Color : Changes accent color of JoiPlay. Accent color is used for text, icons and widgets. Avaible colors are variants of white/grey, green, purple, blue, yellow and red.

Enable Cheats : When it's enabled, JoiPlay will add a cheat button to virtual gamepad.

2.2 Gamepad Settings

Gamepad Settings contains options to change button size, opacity and key codes.

Button Opacity : Changes opacity of gamepad buttons. Lower values than 20 might make buttons hard to see so they aren't recommended.

Button Size : Changes size of gamepad buttons. Low or high values might make buttons too small or big.

First...Sixth Button : Virtual gamepad has six remappable buttons and key codes of these buttons can be changed for each button separately. These will be used as default settings for all games.

2.3 Ren'Py Settings

Ren'Py Settings are used to change default parameters for Ren'Py games.

HW Video : Sets config.hw_video to True/False when it's enabled/disabled. When it's enabled, hardware video decoding is used which is faster than software decoding. Note : Game will throw an exception if video format isn't supported by device.

Auto Save : Sets config.autosave_on_choice to True/False when it's enabled/disabled. When it's enabled, game will be saved upon encountering an in-game choice.

Use Phone/Small Variant : When it's disabled, Ren'Py won't use phone/small screen variant and window elements will fit better to screen (usually).

2.4 HTML Settings

HTML Settings are used to change default parameters for HTML based games.

Use HTTP Server : When It's enabled, JoiPlay will use a HTTP server to serve files instead of using file urls. Enabling HTTP server will decrease read speed a bit but it might fix some bugs.

Use Crosswalk Plugin : When it's enabled, JoiPlay will use Crosswalk instead of Android System Webview. This option should be enabled only when a RPG Maker MV game uses images larger than WebGL's maximum texture size. Note : This option requires Crosswalk Plugin which crashes on some devices.

Local Saves for HTML : When it's enabled, JoiPlay injects a js file to every html file which overrides localStorage and implements some commonly used Node.js methods to write data to internal storage instead of webview's cache. Note : Also modifies plugins.js on RPG Maker MV games and might cause bugs.

WebGL : Overrides preferableRendererType method to return"webgl"/"canvas" when it's enabled/disabled. Enabling WebGL usually improves performance on modern devices.

2.5 RPGM Plugin Settings

RPGM Plugin Settings are used to change default parameters for RPG Maker Plugin.

Use Ruby 1.8 : When It's enabled, RPG Maker XP and VX games will be runned using Ruby 1.8 instead of 1.9. Disabling this option will cause errors on some games.

Smooth Scaling : When it's enabled, game will be scaled using linear interpolation.

VSync : When It's enabled, frame rate of game and refresh rate of screen will be synchronised to prevent screen tearing.

FrameSkip : When It's enabled, plugin will not draw lagged frames. Usually causes unintended behaviours so it should be disabled on most cases.

Solid Fonts : When It's enabled, plugin doesn't use alpha blending for text. It increases text rendering speed but decreases quality.

Path Cache : When It's enabled, plugin will cache all file paths with lowercase characters to allow case insensitivity. Caching file paths mostly takes some time up to a minute but prevents missing file errors.

Window Size : Changes window size of the game. Default value is 640x480. This option doesn't affect visible area on screen because game will be scaled to fill screen.

Font Scale : Changes scaling factor for game font. Default value is 0.75 and can be used to change text size.

2.6 Pokemon Essentials Settings

Pokemon Essentials Settings contains several options to enable/disable fixes for Pokémon Essentials based games.

Pokémon Essentials Fixes : When It's enabled, some methods will be overridden to fix several bugs.

Pokémon Input Overrides : When It's enabled, Input module will be overridden to support external controllers. It only supports keys supported by RPG Maker XP.

Tilemap Fix by inori-z : When It's enabled, a workaround, written by inori-z (Rosa), will be used to blit tiles from tilesets larger than OpenGL's maximum texture size.

Disable Autotile Animation : When It's enabled, autotiles won't be refreshed on every frame. It reduces movement lags.

3.In-game Buttons

In-game buttons include buttons for showing/hiding buttons, closing game, changing orientation, showing soft keyboard, showing gamepad settings and opening cheat menu.

Image 3.1 - In-game Buttons

1- Show/Hide top button bar

2- Show/Hide gamepad buttons

3- Close game

4- Change orientation

5- Show soft keyboard

6- Show gamepad settings

7- Show cheat menu

4.Troubleshooting

This section only contains some common issues and might not help on all cases. Please contact us via Discord or e-mail if you can't fix the issue.

4.1 Game doesn't save

Save issues are mostly related to storage problems or unsupported functions. If the game is a RPG Maker MV game, disabling "Local Saves for HTML" option in HTML settings usually fixes the issue. If disabling this option doesn't fix the issue, disabling plugins related to save function will fix. Fixing save issues on other game types involves editing game scripts and usually a complicated task. If you can't fix the issue, you should contact us via Discord or e-mail.

4.2 Missing File/Loading Errors

This error is usually shown when a file is missing but it might be a false alarm too. Most games are developed for Windows which uses a case-insensitive filesystem but Android uses case-sensitive filesystems. JoiPlay and RPG Maker Plugin use a path cache to emulate case-insensitivity. If "Path Cache" option is disabled, path cache won't be used and you will see false error sometimes. First step should be checking if file exists or not. If file exists, enabling "Path Cache" should fix the error. If it doesn't exist, please try downloading and extracting files again.

4.3 Black or Transparent Graphics/Background

This issue usually occurs on RPG Maker games. On RPG Maker MV games, this mostly caused when game tries to render a image larger than WebGL's maximum texture size limit and can be fixed only by using Crosswalk Plugin by installing it and enabling "Use Crosswalk Plugin" option. On other RPG Maker games, it's caused by wrong/corrupted RTP installation and can be fixed by clearing app data of RPG Maker Plugin and selecting "Default" after starting the game. If these don't fix the issue, it means a plugin or dll file causes it. Khas Advanced Lighting plugin for RPG Maker MV prevents text rendering and disabling it usually fixes the issue. KGL2.klib, tktk_bitmap.dll and TRGSSX.dll provide extra bitmap features but don't work on JoiPlay so games which depends on these libraries might not work.

4.4 Missing Font Errors

This errors are shown on some RPG Maker VX games and can be fixed by copying need font files to "Fonts" folder.

4.5 Script/Reference Error

This issue occurs on RPG Maker MV games and usually doesn't provide any additional information. Disabling "Local Saves for HTML" option or enabling "Use HTTP Server" option might help.

4.6 Stack Size/Level Errors

This issue usually caused by cheats and can be fixed by disabling "Enable Cheats" option in settings.