This guide has the goal to help you to Setup/Play RoBrowser. If there's any trouble during the process, please open an issue with all your concerns and points to improve.
- Getting started
- 1. Important notes before starting
- 2. Local Installation
- 3. Setup Instructions
- 4. Serving and Running roBrowser
- 5. Add game assets
- 6. Adding Custom Plugins
- 7. ROBrowser Settings Overview
- 9. Troubleshooting
In case of any error start by opening developer mode and check the browser Console (F12 or CTRL+Shift+I in most browsers). Don't forget to adjust the level filters if you don't see everything. Also worth checking the Network tab.
For public servers using secure web protocols
httpsandwssis a de-facto must, since most browsers don't allow non-secure websocket calls on the internet anymore.
This guide section will help you running robrowser locally.
Here's a list of things that you will need to have for a sucessfull installation and gameplay of your favorite server.
| Item | Description |
|---|---|
| RoBrowserLegacy | Client to Run Ragnarok Online on browser |
| NodeJS 20+ | NodeJS to compile RoBrowser assets |
| wsproxy | A Websocket Proxy to interligate Login + Server + Map into one endpoint |
| Game Server | Your Emulator that usually is rAthena or Hercules |
| Game Files | A kRO or any RO installation files to use as your base for the server |
| Remote Client | If you don't want to use local files you will need a Remote Client to serve the game assets to roBrowser hia http. Default version: PHP Other versions: JS |
| Browser | Any browser that is compatible with OpenGL ES 2.0 (Requirement for RoBrowser) |
| Embed Server | Any programming language that has embed servers to use. Example: NodeJS, PHP or Ruby. It's totally up to you. |
Currently tested browsers:
- Chrome: (Desktop & Mobile)
- FireFox: (Desktop & Mobile)
- Safari: (Desktop & Mobile)
- Edge: (Desktop)
Others will probably work as well especially if Chromium based, but there might be slight differences.
Note
If you already have NodeJS LTS installed, skip this step.
Make sure you're running NodeJS LTS or 18 above. Validate your version using the command:
node --version
# v20.10.0 (example output)If your version is minor than 18 you can
To install NVM you can use the command below:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bashAfter you install NVM, reopen your terminal and check if the installation was successful:
nvm --version
# 0.39.0Now you need to switch to the appropriate version to run roBrowser by using the command:
nvm install --lts
# Downloading and installing node latest version
# Now using node v20.10.0 (npm v10.2.3)Just to make sure, check if the node changed to the specified version after installation:
node --version
# v20.10.0
npm --version
# v10.2.3Now you're good to go and compile the needed files to your Ro-Browser application!
To run roBrowserLegacy it will be necessary a proxy layer between your browser and the map_server, login_server, and char_server. Instead connect into 3 instances, you will only connect to the main proxy.
To install wsproxy, use the command below:
npm install wsproxy -gFor more info read the wsProxy Readme.
All client/packet versions are supported, but the number of missing features increases with higher dates, since we need time to get everything implemented. We advise you to use versions older than 2015 for the best experience, but this is not a restriction, only a suggestion.
The game files needs to match the version/episode that you will play. Due that, we recommend to always start with kRO Client or you can choose a different Client dowloading from one of Hercules assets on Nemo website.
You need a game server that is compatible with the original game. There are many implementations/versions/forks that are compatible, you can use any of them, but we suggest using one of the following two, because we test using these emulators:
Warning
- Disable packet_obfuscation on the game server. (Not supported yet, causes invalid packets)
First, you will need the project in your machine. You can fork your own version or just clone the repository by typing:
git clone https://github.com/MrAntares/roBrowserLegacy.git
Or you can just download our latest release here.
Having the project extracted in your machine, you will need to install the node dependencies by running:
npm installNow we have everything to make our game run as expected. Before start, we have to start a web-server to host all our roBrowserLegacy. By default, our project already have one installed on the node dependencies, which is called live-server, configured under the project's package.json pre-configured commands.
Running the live server (browserless):
npm run live
# [email protected] live
# > live-server . --no-browser
# Serving "." at http://127.0.0.1:8000Or if you're using PHP or Ruby you can type any of these commands:
php -S 0.0.0.0:8000
# or
ruby -run -ehttpd . -p8000With any of them, you will be able to access http://localhost:8000 with a proper web-server running locally.
There's two builds available today: Development and Production.
This step/section is only recommended for a "Live" server. It will only pack all the resource files into one file to speed up loading.
First, we have to access the roBrowserLegacy project root:
cd path/to/robrowserlegacyThen you can simply run:
npm run build -- -O -T -HIt will generate 3 files inside dist/Web, which are Online.js, ThreadEventHandler.js and index.html that you have to move/copy into your project root.
cp dist/Web/* .
Now you're good to open your browser at https://127.0.0.1:8000 and see your roBrowser base client running!
Tip
In case you want to minify your roBrowser, go on the instance config and turn the development flag into false.
If you want to contribute directly on RoBrowserLegacy source, you should focus on /src path.
First, go to your roBrowserLegacy Folder:
cd path/to/robrowserlegacyYou can start the development build by typing:
npm run serve
# > [email protected] serve
# > live-server ./dist/Web
#
# Serving "./dist/Web" at http://127.0.0.1:8080Since we're under development purposes (modifying the source/testing) change in the roBrowser config inside the dist/Web/index.html with: development: true.
This step/section is only recommended for a "Live" server. It will only pack all the resource files into one file to speed up loading. Requires to set in the roBrowser config: development: false,.
For development purposes (modifying the source/testing) skip this section and set in the roBrowser config: development: true,. In development mode roBrowser will use the files directly from src/.
- Access
http://localhost:8000/tools/build/index.htmlwith your browser
- Click on "Online", compilation should take around 10~30secs. If it runs longer than 2 minutes there might be an issue.
- Click on "Thread"
- Copy/move the generated files into your web folder (
Online.jsandThreadEventHandler.js)
TODO: improve this flow (important!)
- Enable Intro screen in the configs by setting
skipIntro: false - Drag your game assets into the box on your Intro sceen
-
Install a Remote Client to your web server.
-
copy your
.grfunderresourcesdirectory (only unencripted, 0x200 version is supported) -
alternatively, if you don't want to use GRFs directly, then you can extract your GRFs into the
datadirectory (not recommended, but it works fine) -
copy your
DATA.INI(GRF loading order) underresourcesdirectory -
copy your BGM
.mp3underBGMdirectory -
copy your data directory under
datadirectory -
copy your System files under
Systemdirectory -
copy your
clientinfo.xml(client-server information) underdatadirectory -
copy your AI files under
AIdirectory -
check the
configs.phpif it is configured properly for your use and make sureDEBUGis set to false -
check the
.htaccessfile if the ErrorDocument option points to theindex.phpvia the correct url. If you don't run roBrowser from the www root and you use remote client then you need to adjust this url (see examples in the file)
In all AI/*.lua files :
- Replace all
require "AI\\Const"withrequire "AI/Const" - Replace all
require "AI\\Util"withrequire "AI/Util"
- copy your custom plugins into
src\Plugins
Some examples: https://github.com/MrAntares/roBrowserLegacy-plugins
Here you have a list with all of init variables on ROBrowser. Let's take a look:
function initialize() {
var ROConfig = {
// GLOBAL VARIABLES
type: ROBrowser.TYPE.FRAME, // Possible: .FRAME (instert into current document), .POPUP (open new window)
target: document.getElementById("robrowser"), // When using TYPE.FRAME this is the id of the target iframe in the current document
application: ROBrowser.APP.ONLINE, // Possible: .ONLINE (game), .MAPVIEWER, .GRFVIEWER, .MODELVIEWER, .STRVIEWER, .GRANNYMODELVIEWER (not implemented)
width: 800, // Only affects TYPE.POPUP
height: 600, // Only affects TYPE.POPUP
// SERVER CONFIG
servers: [{ // Game server info. You must configure this! You can have multiple servers like: servers: [{..}, {..}, {..}], you can also use clientinfo to set the server list (servers: "data/clientinfo.xml",)
display: "Demo Server", // Display name, can be anything
desc: "roBrowser's demo server", // Description, can be anything
address: "127.0.0.1", // Must match your game server's
port: 6900, // Must match your game server's
langtype: 12, // Must match your game server's
packetver: 20191223, // Must match your game server's
grfList: "DATA.INI", // By default uses DATA.INI to get grf list, but you can define an array (grfList: ['custom.grf', 'palette.grf', 'data.grf'],) or a regex (grfList: /\.grf$/i,)
remoteClient: "http://127.0.0.1/client", // Your remote client address. Defaults to http://grf.robrowser.com/
renewal: true, // Must match your game server's type (true/false). When using clientinfo.xml you can add the <renewal>true</renewal> custom tag.
packetKeys: false, // Packet encryption keys ( not implemented?? )
socketProxy: "ws://127.0.0.1:5999/", // The websocket proxy's address you set up previously for robrowser (wsproxy)
adminList: [2000000] // List admins' account IDs here like: [2000000, 2000001, 2000002 .... etc]
}],
// OTHER CONFIG - These can be part of the server config as well, thus making them adjustable per server
development: false, // When false needs a compiled Online.js in the root (faster load). When true, the client will directly use the javascript files from src/ (slower load, for debugging/development only). Additionally, the console output is enabled when set to true to help debugging.
enableConsole: false, // Enables the console output in a non-development environment (development: false)
disableConsole: false, // Force disables console output in any environment (regardless or the development config option)
packetDump: false, // Dump packet as hex to the console?
skipServerList: false, // Skip server selection?
skipIntro: false, // Skip intro page?
version: 20230927.0959, // Update this value every time you update your robrowser, to trigger a source refresh on every browser. Recommended to use a decimal timestamp (YYYYMMDD.hhmm), but can be anything
forceUseAddress: false, // Some times when connect to server, the server return 127.0.0.1 as IP to connect. This key force robrowse to ignore and use IP set at 'address'
worldMapSettings: { // Settings for world map.
episode: 98, // Episode content to show (0-98, eg:14.2, default:98 = latest)
add:[], // Optional, Array of maps to custom show (eg: ['rachel', 'ra_fild01'])
remove:[] // Optional, Array of maps to custom remove (eg: ['alberta', 'pay_fild03'])
},
enableCashShop: false, // Enable Cash Shop UI?
enableBank: false, // Enable Bank UI? (Requires PACKETVER 20130724 above)
enableMapName: false, // Enable Map Name Banner? (Requires client data (GRF) newer than 2019.06.19)
enableRefineUI: false, // Enable Renewal Refine UI? (Requires client data (GRF) newer than 2016.10.12) (Should also enable in server side)
enableDmgSuffix: false, // Enable Damage Suffix (>1M = K, >100M = M) - Requires client data (GRF) newer or equals to 2019.05.08
enableCheckAttendance: false, // Enable Check Attendance? (Requires PACKETVER 20180307 above)
loadLua: false, // Enable this option to load LUA tables (currently only item table) from client/System/...
//clientHash: '113e195e6c051bb1cfb12a644bb084c5', // Set fixed client hash value here (less secure, for development only)
calculateHash: false, // When true, the client will calculate it's own hash and send that value (slower, more secure, only when development is false). Must provide the list of files in hashFiles!
hashFiles: ["api.html", "api.js", "Online.js", "ThreadEventHandler.js"], // List of files to calculate the Hash based on. Add all files your robrowser uses, including your "main page/index.html" where you set up the RoBrowser Config. Only used when calculateHash is true.
/* Plugins */
plugins: {
/* Syntax */
// Simple (no parameters):
// PluginName: 'Plugin_JS_Path_In_PluginsFolder_Without_Extension',
// Complex (with configurable parameters):
// PluginName: { path:'Plugin_JS_Path_In_PluginsFolder_Without_Extension', pars: { param1: <val1>, param2: <val2>, param3: <val3>... } }
/* Example: */
// KeyToMove: 'KeyToMove/KeyToMove'
// IntroMessage: { path:'IntroMessage/IntroMessage', pars: { newsUrl: 'https://yourserver.com/news/news.html' } }
},
/* Custom, "for fun" camera modes */
ThirdPersonCamera: false, // When true you can zoom in more and rotate camera around player more freely with mouse
FirstPersonCamera: false, // When true you can look from the player's head, like an FPS game and rotate camera without limit
CameraMaxZoomOut: 5, // How far can you zoom out the camera, default:5. Note: Extreme values can break camera and/or mouse.
};
var RO = new ROBrowser(ROConfig);
RO.start();
}
window.addEventListener("load", initialize, false); // When the webpage loads this will start roBrowserIn case of the langtype option, we added support for some custom types:
Normal
- 160: Central European
- 161: Greek
- 162: Turkish
- 163: Hebrew
- 164: Estonian, Latvian, Lithuaninan
Unicode
- 240: UTF-8
- 241: UTF-16LE
- 242: UTF-16BE
Using these custom types makes roBrowser incompatible with other clients without modifying them as well! Only use them if you know what you are doing!
You can set up your own index.html / integrate roBrowser into your website as well based on the .examples/ and this example above.
- Access to
http://localhost:8000/after moving all the files from yourro-browser/dist/Webtoro-browser(project root).
9.1 Troubleshooting: The screen is weird and/or the developer console (F12) says it can't load game assets
Your remote client is not configured properly.
- Check the
client/configs.phpand make sureDEBUGis set to false. - Check the
client/.htaccessfile if the ErrorDocument option points to theclient/index.phpvia the correct url. If you don't run roBrowser from the www root and you use remote client then you need to adjust this url (see examples in the file).
If it is still not working you can try setting DEBUG to true and open the http://localhost:8000/client/index.php in your browser to see the debug trace. You can also call files directly from your game data to see if they load properly, eg: http://localhost:8000/client/data/texture/black.bmp. After debugging set DEBUG to false.
Check that you don't have an extension using postMessage, it will conflict with code in api.html which listen for message.
You probably forgot the step about AI require replacement in Add game assets section
You probably have a server security issue if your server is public. Check your certificates and make sure you configured everything to run securely, you provided the required configuration values in https/wss and that the main page of roBrowser is also opened with https. Redirecting every http call to https on the webserver is also probably a good idea.
I personally had to disable metamask extension.