User Tools

Site Tools



This is an old revision of the document!

EasyRPG Player for the Web

EasyRPG supports running games directly inside your web browser.

If you want to test it you can play with a Demo of our TestGame. Try also a working game: Ib

How does it work

Web request are asynchronous. This means that all assets like pictures and music must be fetched asynchronously. When the Player wants to display a new graphic it will appear on the desktop versions (Windows, Linux, Android, …) immediately but on the web it will be invisible while the file is downloaded. Once the downloaded finishes it is replaced with the real image.

In contrast to images and music some files are important to continue execution. When a map file is pending the Player will halt until the file is downloaded. The first halt is while the Logo is displayed on startup, it downloads the database and the maptree here. Download of map files is blocking, too. But this is usually not noticeable because the download is executed while the fade out animation plays (it will stay black when the map downloading takes longer then this).

Hosting your own games

Hosting your own games is quite simple. Just follow these three steps.

Deploying the Player on your server

Download this archive and extract it on your server.

Your server needs support for PHP (most servers support this).

You will get the following files:

  • index.html
  • index.js
  • index.html.mem
  • games/index.php

Preprocessing steps for games

Because of current player for the web is not supporting MP3 playback properly in browser yet (there are resampling and buffering issues in SDL_mixer) you should convert MP3 audio files to Ogg Vorbis.

MP3 to Ogg Vorbis conversion

GNU/Linux command line option
  • First, install lame and decode all MP3 to WAV:
for song in *.mp3; do lame --decode "$song"; done
  • Then, install vorbis-tools and encode all WAV (including any other existing game WAV files in Music and Sound folders) to Ogg Vorbis. EasyRPG Player supports WAV files but Ogg is a lot smaller and worth for the web.
oggenc -q-1 *.wav
Windows drag and drop tools option
  • Open the LameDropXPd app (it is a square window), select all MP3 files from the folder, then drag and drop them over the square app window. They will be converted to WAV.
  • Then, download oggdropXPd (aoTuV version is preferred).
  • Open the oggdropXPd app (it is a square window), select all WAV files from the music folder, then drag and drop them over the square oggdropXPd window. They will be converted to Ogg Vorbis. If you want to make smaller Ogg Vorbis files, do secondary mouse button click over the square window to select options and adjust the compression quality option to -1 (~48 kbps) or -2 (~32 kbps).

Deploying a game on your server

The following only apply when you use our index.php.

Your games are expected in subdirectories of the games directory. The default game executed is the one in games/default. You can create further games by just putting them in subdirectories of the games directory. Because of security considerations (directory traversal) your directory name may not contain ., \ or cache.

If your games directory is not writable for PHP create a cache folder in games and give it write permissions. You can skip this step if games is writable. You can revoke read permission on this folder for world/others.

Run games/?update once. You have to run this each time you change files of the game. For other games then default use games/?update&game=folder_name.

Now open the index.html file and your default game should start. To play a different game pass ?game=folder_name to your index file.

Technical details about the server side

The index.php works as a file finder which allows case-insensitive lookup of files.

Depending on the requested file it either returns 404 or a Location-header to the file on the server.

This is required because Windows is case-insensitive (and original RPG2k was for Windows) and because the file extensions are not stored. Charset/Hero1 could be Hero1.png, hero1.bmp or, depending on which file exists.


The file System/System1 is requested. The server returns Location: games/default/System/System1.png. The same result is expected for file SyStEm/systEM1.


Our file finder is stored under src/platform/easyrpg-filefinder.php. In case you want to replace the file finder you only have to fulfill a very simple API.

The directory struture of the games folder is not part of the API contract. The player only expects that accessing games/ invokes the file finder.

The only GET arguments that must be supported are game and file.

game is the name of the game that is executed.

file is the name of the file the game requests.

When a file is requested it must return a downloadable representation of the file. How doesn't matter, it can be an octet-stream or a redirect via Location-header. If the file is not found 404 must be returned.

development/player/web.1452260408.txt.gz · Last modified: 2016/01/08 13:40 (external edit)