Jump to content
  • entries
  • comments
  • views

About this blog

The open-source online script for VX Ace!

Entries in this blog


*Ring ring!*


Your wait is finally over!


I decided to release a early (and probably completely bugged) version of ASOE to the public. You can check out all the details in the official topic. As well as access the download, read the documentation and follow the discussion here:




(kinda short blog entry for something that I worked on quite a long time - don't ya think so?)





ASOE (Asynchronous Online Engine) is a collection of scripts that allow you to create, host and play asynchronous multiplayer online games in RPGMaker VX Ace. ASOE is perfectly suited for turn based games, but it can enrich the gameplay of any VXA game by adding online features to it.


[!] Note: If you use the demo project, there is no setup required - its all plug-and-play. But if you want to change the existing systems like the title screen or change the behavior of register, login and logout - understanding this chapter is crucial.






the glorious default login screen


Let's start at the Start

Welcome to another chapter in the ever growing ASOE documentation! Today we talk about some of the basics of the engine, the things each and every game based on ASOE requires: Registering Accounts, Logging in, Updating data to the server as well as Logging out.


The default title screen uses just a single auto run event that calls a common event. This common event (asoe_sys_login_register) handles all the basic stuff like registering a new account, logging in and deleting a existing account again. You can use it as it is - or you take a look at the common event itself and make use of its parts to build your own login system.


[!] Remember: To provide an entry point to your online game, all you have to do is to call the common event Nr. 1 (asoe_sys_login_register).



Keyboard Input translated to RGSS3 by Efeberk


1. Registering a new account

The second menu point is actually the first one a player will choose: Registering a Account. The player will be prompted to enter a name as well as a password for his character (this is done via keyboard input and not via Input Name). You can dissect the asoe_sys_login_register common event if you want to alter the process, but thats not mandatory. A few important things must be noted:


* Entered data is always case-insensitive.

* All account names are unique, there can be no duplicates.

* Both names and passwords are limited to 4 (min) and 15 characters (max) (this can be changed).


Next, the script contacts the server and creates the account. Its important to understand that account data is NOT actor data. An account can hold any number of characters (even 0). Accounts include lots of other data instead that is not directly tied to a single actor. The most important account parameters are (will be expanded in the future):


Accountname, Password, Guild, Gold, Score, Level, Rank, logDate, steps, items, weapons, armors, mapLocation, usergroup and code


Gold, steps, items, weapons, armors and mapLocation is obvious and included in the account data as they affect a players party at whole.


Guild holds the current guild ID of a player. While Score, Level and Rank will be used at a later stage to maintain a online highscore list like seen in many online games.


logDate is required to know when the account logged in the last time. usergroup is used to differentiate between players and admins (to be implemented later). Finally code is the current security code of a account, like explained in the previous chapter.



Selectable actors are limited by server configuration

Finally, the script calls the character selection scene that allows the player to choose the first actor for his adventuring party. The available actor IDs can be specified in the servers config file (explained later), so you can limit the selection to just a few of them. This is the default character selection, if a game designer wants something different or more fancy, it is required to dissect asoe_sys_login_register to point to another scene.


[!] Remember: Changing the character selection requires scripting and access to the scripts themselves. How to do this will be explained in a future blog post in detail.


When everything went right, the player is now teleported to the starting map as stated in the server config file. The chat as well as the hotkeys are activated and the update timer starts (to be explained later).


2. Login

This one is quite simple: The player just enters the name and matching password for an already existing account. The script then performs a few checks and loads both the account data as well as the data of all the players actors to the client. Finally the player is transferred to the last saved location of the party (this can be the default location for a new account).


Two important things to mention: First a version number check is done, please note that this version is NOT the version of the ASOE script itself. Its a version number game designers can add to both their server and their clients when updating their games. Should the version numbers match, the player can proceed and enter the game.


Second: When the versions do not match, the client requests a download link from the server and opens up the default browser (depends on system settings, the script has no influence on that). This download can be configured in the server settings and it is recommended to point it directly to a ZIP or RAR file. This file will be automatically downloaded (default behavior of any browser). Then the game prompts the player to update his project folder and quits.


The only thing left to the player is to unzip the archive and copy it over the previous game folder. This will also update the version number. After relaunching the game, login should be possible without any problems.


[!] Note: The standard version/patch system requires the user to locate, unzip and copy the new project to his project folder. There are patch scripts for VX Ace out there (like THIS ONE by the legendary Tsukihime)- but I did not include them because I want to keep the script to the very basics, without any 3rd party code installed. Game designers who want fully automated and optimized patch functionality, have to add this on their own.


[!] Note: Some games use both: A online mode as well as a offline mode. It is basically possible to do that using ASOE but this functionality is not fully supported. There is a switch that you can check in a conditional branch to see if the player is logged in or not. Its not recommended to use the same game content for both modes, there should be strict online maps as well as strict offline maps as well. Almost all of the core features require data to be transferred to or from the server in order to function. As the script was not concipied for dual use you will have to create NPCs (like vendors) for both modes in order to make your game work properly. I will see what I can do to improve this situation in the future.


3. Delete Account

Even more simple, a player can delete any account if both name and password are entered correctly. Players are encouraged to never share their account password.


4. Ingame Updates

As you can see in the picture below, the save button is greyed out. This means there is no way for a player to save the game manually. This is because its an online game: All data is saved on the server side instead, save files are obsolete when using ASOE. Even more important is to know that the game makes in game updates on a regular base.


Every minute, the current account and player data is transferred to the server. This includes switches and variables for this player as well. This periodic update is your first line of defense against data loss, but both players and game designers should never completely rely on this update. Many things can happen in just a minute and if the game crashes, the server disconnects or the player quits via X-out - vital data might be lost!


9vdopv.jpgCircle should be trice as big because this point is SO IMPORTANT


5. Logging out of the game

FInally, as you can see in the picture above there is a logout button that replaces the game end button. Whenever a player quits the game, this logout button must be used. I cannot stress this issue enough: players should not just be encouraged but enforced to make use of this button! When the player logs out, the current data is transferred to the server and all of his characters are saved (and therefore considered SAVE).


If you forget to logout properly and the last automatic update dates a few seconds back, the worst thing that can happen that a player loses that shiny new piece of equipment he or she just acquired!




Another wall of text finished and this ends this chapter about ASOE - the asynchronous online engine for RPGMaker VX Ace!





1.2 ASOE Security Layer

ASOE (Asynchronous Online Engine) is a collection of scripts that allow you to create, host and play asynchronous multiplayer online games in RPGMaker VX Ace. ASOE is perfectly suited for turn based games, but it can enrich the gameplay of any VXA game by adding online features to it.


[!] Note: This is a technical article that is not required in order to use the script. Its a recommended read to anyone who wants to build on top of the existing code base.


Why Security is Important

When Efeberk - the original author of this online script - published it, he did not put too much emphasis on security. There was a help file included that contained some information about XSS (Cross-Site-Scripting) and thats it. He left the real work to the users of the script. We'll, I don't blame him for that - in fact im thankful that Efeberk wrote an online script for VX Ace at all! But, as this is open software, one of my first tasks was to increase the security of the script:


A living state Machine

​First of all, online games are not sealed environments like offline games - online games are living breathing state machines. This adds to the joy of playing (and creating) such a game but also opens the door for hackers and cheaters alike. You have to imagine that literally every client (player) could be a hostile attacker that tries to corrupt your games database. And besides database corruption there are also the threats of XSS (Cross-Site-Scripting) and spam/fake data packets.


The ASOE security layer

So there are a few basic countermeasures that are included in the core system of ASOE to prevent malicious attacks on the server. Most important is the wrapping of the PHP $_GET command in order to filter the received data. This should negate script level attacks like XSS. Every single piece of information that is transferred to the server is first filtered by a PHP function that looks like this:

function asoe_get($parameter) {     $parameter = $_GET[$parameter];     if (ASOE_MODE_SECURE) {   	  $parameter = mysql_real_escape_string($parameter);         $parameter = htmlspecialchars($parameter, ENT_IGNORE, 'utf-8');         $parameter = strip_tags($parameter);   	  $parameter = stripslashes($parameter);     }     return $parameter;}

Next, there was a code added to each and every piece of data sent from the client to the server and vice-versa. This code could be referred to a "checksum", although it works a bit differently than usual. This code is generated when the client logs in and is re-generated every time doing so. The code is a simple 3-4 digit number that is randomly generated by the server. This number is transferred to the client during the log-in process. Now, every time the client transfers data to the server, it adds this code as well. The server compares the code to its own - locally stored - code-number. Only if the codes match, the client data is processed. Otherwise the data is dumped and the current process is terminated.


Finally a sequence number was added to the code as well. This means that the code - once generated - is not static, it changes with every request sent or received. Both the server as well as the client keep comparing their code-numbers to the numbers in the data packets they receive. As only the client and the server know how the sequence number is computed, it should be impossible for an intruder to smuggle a fake packet to the server.


The combination of a code-number and a sequence number creates a secret morse-code only the client and the server know about. And as both numbers are unique for each client and are always changing, a potential attacker must put tons of effort into the system in order to hack it. As ASOE is used for games only, I think this security layer offers more than enough protection to keep online environments save.



Console output showing data packets as well as security code-number


1.1 How ASOE works

ASOE (Asynchronous Online Engine) is a collection of scripts that allow you to create, host and play asynchronous multiplayer online games in RPGMaker VX Ace. ASOE is perfectly suited for turn based games, but it can enrich the gameplay of any VXA game by adding online features to it.


[!] Note: This is a technical article that is not required in order to use the script. Its a recommended read to anyone who wants to build on top of the existing code base.


Requests not Sockets

ASOE uses HTTP requests in order to communicate with the server. This process can be compared to what web-browsers do in order to communicate with a website host. The request procedure is somewhat slow, but access is guaranteed and there is no need for the programmer to provide a socket, port, connection or protocol. This makes it very easy to add new features to the code, as most of the technical details are covered by the HTTP protocol itself.


The Pro's of this approach:

  • Its easy to setup and maintain.
  • The communications is reliable.

The Con's of this approach:

  • It's slow compared to other solutions (thus no realtime action).
  • Features a decent overhead (but this won't have much impact on bandwidth usage).

How real MMOs do it

All currently available multiplayer games use a direct connection via Sockets and the TCP or UDP protocol. I assume this would be possible in RPGMaker VX Ace as well (there is a game actually that uses this approach, you can check it out HERE), but thats way beyond my skills and available time at the moment.


A direct connection does require a port number and protocol in addition to the servers IP address. It also requires the client to successfully connect to the server and a machine that is running 24/7. Furthermore, direct connection requires both client and server to be synchronous all the time - lag and transmission errors can screw up the whole game experience.


How ASOE does it

As explained above, ASOE uses HTTP requests as found in web-applications. It does therefore not require a direct connection, does not need a port or protocol (as the Win32API handles all of this already). This is how Efeberk built his code base and its exactly the way how I continued to expand the project. Its a system that is easy to maintain and that can be expanded on the fly.


You still require a server machine and a IP address for it. But direct connection via sockets is not required, this removes all synchronization and the errors that could arise from it. Its also not required to have a machine running 24/7. In fact, the same web-server that provides hosting for a website can be used to host a game using ASOE. This also means, you do not require a server executable (EXE) or any other program. Just a bunch of PHP files and a MySQL database are required.


The pair structure

So, if you like to add new functionality to the system, you have to understand that each request requires a pair of two functions in order to work:

  • A function inside your VXA project that makes the request
  • A PHP file on your server to receive the request

This requires you to write two functions every time you want to add a new online feature to your game.


1. The VXA project function

Lets say we want to add a new function to the game that allows us to receive a small piece of text from the web server. This text could be "News of the Day" or whatever. In order to do this, we first have to create the function inside our VXA project. This is easily done by creating a new method using RGSS in the script editor. More important is the "request" method and it's syntax. Lets have a look at it:

def getNews()     result = WEBKIT.req("my_functions/mygame_getNews", "")     return resultend

Really simple, isn't it? The detail is in the WEBKIT.req line. Thats a method that allows us to request data from the server. It has two arguments: The first one specifies the path and name of the servers PHP file we want to call, it is also used to GET stuff from the server. The second argument is used to POST stuff to the server (not used in our case).


So the method we have just defined is looking for a file named "mygame_getNews" inside a folder "my_functions" on our web server. Of course you could also place it in the topmost hierarchy of your server folder (but thats not recommended).


The function does not do anything by itself, it just returns what the server provides (if anything at all).


2. The server PHP file

This whole stuff begins to make sense when we add a new PHP file to our server that will receive the call from the RPGMaker client project. Please note that you have to add a new PHP file for every piece of functionality to your server, it is therefore recommended to maintain an organized folder structure to prevent utter chaos.


[!] Note: Yes, there are other systems to organize PHP requests. It would also have been possible to let the RPGMaker client access just a single PHP file on the server that branches up and decides which parameters to return internally. This approach was abandoned in favor of the current, much simpler solution. Because right now you can add pieces of code in form of tiny little PHP files to the project on the fly. This is easier to maintain and expand, it also allows multiple developers to work on the project without messing everything up.


Ok, now lets create a new folder inside our servers structure, lets call that folder "my_functions". Next we create a new text file, using the text editor of our choice (Notepad++ in my case), we name that file "mygame_getNews.php". Please note that the names are exact the same as used in the method we just created in the RPGMaker script editor.


Finally, lets add some basic functionality to the freshly created file - open it using the text editor and write:

<?php /* --------------------------------------------------------------------------------mygame_getNews.php by MalagarVersion 1.0-------------------------------------------------------------------------------- */include("../asoe_core/asoe_core_connection.php");if (asoe_security_check($connection, TRUE) == FALSE) { die(ASOE_CODE_ERROR); }echo "This is our news of the day";?>

This is now a bit more complicated, but its really easy once you understand:


The text within /* and */ is a comment that provides some basic information to make maintaining the code much easier. So these four lines do not have any effect and are just notes.


The next two lines (include and the if control structure) are staple and should be the first lines in any PHP file using ASOE. they provide some basic functionality and security features. I will explain them in a separate blog entry.


Finally, the only important line in our script is this one:

echo "This is our news of the day";

This line contains the text the client will receive when calling the method, so the text within the apostrophes will be transferred from the server to the client. Note that the echo statement is required, as it prints the text onto a blank PHP page so the client can pick it up. An echo statement like this is always required if you want to transfer data back to the client.


[!] Note: Any experienced PHP coder will scream in horror now as transferring data using echo is unsecured. But its the only way to get the system working using this approach. I have added a bunch of security counter measures that will be explained later. So calm down!



Finally, the client will receive that line of text and can do with it what you want. You can print the message out in a message box for example. Of course the real functionality begins just here, when we transfer player data back and forth between the client and the server (especially numbers). This was a very brief introduction to how the system works, the details follow later.


Thanks for reading this wall of text. Welcome to the world of ASOE!





1.0 Installing ASOE

ASOE (Asynchronous Online Engine) is a collection of scripts that allow you to create, host and play asynchronous multiplayer online games in RPGMaker VX Ace. ASOE is perfectly suited for turn based games, but it can enrich the gameplay of any VXA game by adding online features to it.


1. Requirements

Before we begin with the installation instructions, there are a few requirements that you must met in order to successfully setup ASOE. Please check the following points before you continue:

  • Full version of RPGMaker VX Ace available?
  • Text editor of your choice at hand? (e.g. Notepad++)
  • A FTP client is available? (e.g. Cyberduck)
  • Access to a webhosting service? (Alternatively you can host the game on your own machine)
  • Your webhost provides you with a domain or static IP?
  • Your webhost supports PHP (.php files) ?
  • Your webshot provides a MySQL database?

2. Download ASOE

First, download the most recent version of ASOE from the internet. For example you can use the mediafire link below:




3. How to install ASOE

Next, unpack the archive and take a look at it’s contents. ASOE is divided into three seperate folders.

  • ASOE _VXA_CLIENT folder – the actual RPGMaker VX Ace project
  • ASOE_MYSQL folder – contains the .sql file for database install
  • ASOE_PHP folder – contains all server side .php scripts

Set the main folder aside for now, you can add it to your VX Ace folder or your VX Ace projects folder. We get back to that later. What we will do now is setting up your online database and install the scripts to provide the server side functionality. Before we can do this, you have to get your webhost login credentials as well as setup a MySQL database.


4. Database setup

Login to your hosting package by using the credentials provided by your webhoster (username and password). Next, locate the option to create a new MySQL database within the configuration panel that your webhoster provides.


Now, create a new MySQL database and note the Username, Database Name, Password as well as the Database Host (usually a domain name or static IP address). Please note that this process differs depending on which provider you choose, so there is no general explanation to this process.




5. Populating the database

From within your webhost providers configuration panel, there is usually a option to launch PHPMyAdmin. This utility enables you to make changes to a existing MySQL database. After launch, you should be able to select your freshly created database.




After selecting that database, there is an option to import a .sql script. Select that option and click “choose fileâ€, a dialog comes up that lets you select a file from your harddrive. Now navigate to the ASOE_MYSQL folder and select the asoe.sql found within. Confirm and PHPMyAdmin will now populate your database with tables and some basic entries.




If everything went well, you should see the following tables in your database:




6. Configurate the PHP files

After you have created your database and taken notes of the credentials, switch back to your downloaded ASOE folder and locate the PHP folder within. Open it and locate the subfolder named "asoe_core" and locate the following configuration file found within:




Now open this file with the text editor of your choice. This can easily be done by right clicking on the file name and then choosing “open with > notepadâ€.


You will now see the various configuration options stated in the file. For now we just focus on the first four ones, right after the file header. Enter your database credentials that you have written down earlier, like in the example below:

define(“ASOE_DATABASE_HOSTâ€, “www.yourdomain.comâ€);define(“ASOE_DATABASE_USERNAMEâ€, “dbo1234567890″);define(“ASOE_DATABASE_PASSWORDâ€, “YourPasswordâ€);define(“ASOE_DATABASE_NAMEâ€, “db1234567890″);

Make sure that you have located the right lines within the configuration file and insert your data correctly in the rightmost part of each line (between the apostrophes). Also make sure that the apostrophes remain intact and do not delete any of the other characters (this includes the ); at the end).


If your scripts are running on a high-end system with both PHP 5.5 and MySQL 5 installed, there are no more changes. But some web hosts (especially free hosts) use much older configurations. In that case you have to disable some functions in order for the project to run properly. Locate the following line in the asoe_config file as well and change 1 to 0 like this:

define("ASOE_MODE_SECURE", 0);

Finally, save the file and close it again.


7. Server installation

Now that the database is in place, we have to upload the files in the ASOE_PHP folder to your domain. You will need a FTP Client to do this (a FTP client program allows you to upload files to a domain). Start the FTP client and enter your domains credentials (domain, username and password).


Next, upload the complete ASOE_PHP folder to your domain, depending on the FTP client you use this can usually be done via drag-and-drop. The ASOE_PHP folder contains various sub folders with a minimum of 72 separate .php files, make sure you upload them all. Also make sure that you not just drop them onto the highest level of your domain hierarchy but into a folder named ASOE_PHP as well. It is very important to keep the folder hierarchy intact. To check if everything went well, here is how the hierarchy looks on my web host (with the asoe_core folder expanded):



8. Client setup

Finally it’s time to setup your RPGMaker VX Ace project. Close the FTP client as well as your web-browser containing the PHPMyAdmin interface (if it is still open) and locate the ASOE_VXA_CLIENT project folder on your hard-drive. Open it and launch the project by double clicking the “Game†icon showing gear-wheels (that’s the VX Ace project, not the game application). Your trusted RPGMaker VX Ace will start and open the game in the usual editor.


Now open the script editor via Menu (or by pressing F11) and locate the following file in the lower part of the long list of scripts that shows up on the left side:




Select that script file by clicking it and it’s text content will show inside the right part of the script editor window. Now locate the following lines therein:

HOST = “www.yourdomain.comâ€PATH = “/ASOE_PHP/â€

And change those lines according to your domain (or static IP address) as well as the path where your .php files are located on the webserver. Remember to keep the apostrophes as well as the slashes intact.


[!] Note: Especially the PATH could be different according to your configuration. This depends into what sub-folders you copied the files on your web host. For example if you buried the files deeper into your web host, you have to adjust the PATH constant accordingly. Lets say you put the files into a "mygame" subfolder and another "game1" subfolder therein. In that case you have to adjust the path accordingly to:

PATH = "/mygame/game1/ASOE_PHP/"

Now save the file and close the script editor.

9. First Registration & Login

It’s almost done! Now launch your game and choose “Register†on the title screen. Enter a name and password for your new account and choose a first party member from the list of actors (those actors are pulled directly from the database of your project). Next you are auto-logged in and transported to the starting location of your party.


[!] Note: If you start the project without creating an account (because you alread have one) choose “Login†and enter your credentials (the accountname and password). If everything went well, you will be transported to the last memorized location of your party.

Congratulations, you have successfully setup both server and client side of ASOE – Asynchronous Online Engine!


Welcome to ASOE

Welcome to ASOE dear readers!

As some of my friends on here already know, I am working on an online script for VX Ace - codenamed ASOE (Asynchronous Online Engine). This script is based on the original ODS (online database) script by Efeberk (you can find that one HERE). I did my best fixing bugs, cleaning up things and adding features to that script over the course of the last 8-10 weeks. Many changes and tweaks have been applied under the hood, so you cannot compare it to the original script anymore. This is why I have decided to start another blog on this. Sooner or later ASOE will be released as open-source to the maker community, and as it is a rather complex script, this blog is intended to be a documentation in order to understand the scripts functionality.


I won't release the code before christmas, but I think its a good idea to start with the documentation as soon as possible. So, say hello to ASOE!





(Image courtesy of Efeberk, the original author of this script)


What is ASOE?

ASOE is nothing less than a online engine for RPGMaker VX ACE. It allows the project that uses it (referred to as client), to communicate with a MySQL database via a bunch of PHP scripts (referred to as server). This allows to add multiplayer online functionality to any RPGMaker VX Ace project.


So it's a real MMO script?

Yes and No. ASOE is Asynchronous (hence the name), and that means it's not suited for real-time online action games. You won't see the other players walking around or anything like that. Asynchronous means that the script is able to exchange data via the internet, but not in realtime. This may sound like a major drawback, but its built into the system (as the script uses HTTP requests instead of communication via sockets) - so there is no real way around. What it does, is that it provides all the features required to simulate an online game that is not relying on real-time action. So you can build turn based games with it, strategy games, online highscore lists and leader boards, you can have players trade and exchange items as well as send email. Most of the core functionality was written by Efeberk - so kudos goes to him. What I did was just some kind of spring-cleaning to the code in order to prepare it for the future.


What are the requirements?

First of all: ASOE is not a beginner script. You will need decent knowledge of RGSS, the maker itself as well as two other programming languages: PHP and MySQL. In addition you must know how to setup a MySQL database and of course you must have access to a web host that allows execution of PHP files. I say this once now and for all: Over the course of the future development, I won't help people setup the database or get the script to work. You have to do this by yourself. My support is only geared towards the script itself, as well as bug fixing and expanding it.


So you decorate yourself with the work someone else did?

Clearly: No. I have no interest in being cool. As said before, this script was written by Efeberk. I only continued his work for the better, as this is the spirit of open-source software as I see it. Im doing this to give the community something back in return for all the help I have received so far.


What changed compared to the original version?

Too many little things in order to list them all here. This is what this blog is here for: To explain all the details over the course of the upcoming weeks. But if you like to hear some hard facts, here are the three most important changes:


1. Bugfixes - Efeberks old script was not perfectly tested and the bazaar and some other parts where full of bugs.

2. Security & Cleanup - the old script was not really perfectly organized, it was also unsecured because you could corrupt the server.

3. Account & Party Functionality - the old script was limited to just 1 character per account and in fact characters and accounts where tied together. I changed that to support full party functionality and separated account data from actor data. This was done to make the system more open. The old script was focused towards 1-char games with a bit of MMO functionality added. The new version allows for any kind of game (one char per account as well as party based games).


ASOE Online Documentation Index

Thanks for reading this and I hope this project is helpful to others!