Introduction

RPatchur is a customizable, cross-platform patcher for Ragnarok Online clients.

Features

How to Build

Rust version 1.49.0 or later is required to build the project.

$ git clone https://github.com/L1nkZ/rpatchur.git
$ cd rpatchur
$ cargo build --release

Cross Compilation

It is recommended to build the project on the platform that you target. However, a Dockerfile is available here for those of you who’d like to compile from Linux and distribute to Windows. This Dockerfile builds a Docker image that can be used to easily cross-compile the project from Linux to Windows.

Note: The executable’s icon and description will be missing for cross compiled builds.

Musl

A Dockerfile is also available for those who’d like to build with musl to reduce the list of dependencies needed to deploy rpatchur on Linux. You can find this Dockerfile here.

How to Use

Using rpatchur is pretty simple, you just need to copy the patcher into your game client’s directory and create a configuration file with the same name as the patcher. For example, if you name your patcher mypatcher.exe, you must name the configuration file mypatcher.yml.

You will also need to have an HTTP server that serves your patches and a web page to use as the patcher’s UI.

Command-line options

$ ./rpatchur --help
rpatchur 0.3.0
LinkZ <wanthost@gmail.com>
A customizable patcher for Ragnarok Online

USAGE:
    rpatchur [OPTIONS]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -w, --working-directory <GAME_DIRECTORY>    Sets a custom working directory

Configuration File

rpatchur uses a YAML configuration file to store configurable parameters. You can find an example of a configuration file here.

Fields

Here’s a description of each field used in the configuration file.

User Interface

rpatchur uses a web view to implement its UI, this makes it completely customizable and also easily updatable. An important thing to note however, is that rpatchur uses the system’s web renderer (i.e. Internet Explorer on Windows). Nowadays, most Windows systems have Internet Explorer 11 installed, so you have to make your web application compatible with this browser, at least.

You can find an example of a bootstrap-based patcher UI (compatible with Internet Explorer >= 10) here.

You can find an example of a bootstrap-based launcher UI (compatible with Internet Explorer >= 10) here.

JavaScript Bindings

The web view interacts with the patcher through two-way JavaScript bindings. There are a few JavaScript functions that can be called during execution.

Functions without arguments

These functions do not take any argument and have to be invoked through a particular external.invoke function. For example, to invoke the setup function, you should call external.invoke('setup') from your JavaScript code. These functions do not return anything.

Functions with arguments

This function takes two arguments and can be invoked with a call to external.invoke as well. This function doesn’t return anything. For example you can call it like so:

external.invoke(JSON.stringify({
    function: 'login',
    parameters: {
        'login': login, 'password': password
    }
}));

Callbacks

The patcher also invokes some callbacks during execution:

You can define these callbacks to receive useful information to display to the user.

mkpatch

mkpatch is a cross-platform utility for generating THOR patch archives with a command-line interface.

Command-line options

$ ./mkpatch --help
mkpatch 0.1.1
LinkZ <wanthost@gmail.com>
Patch generation utility for THOR patchers

USAGE:
    mkpatch [FLAGS] [OPTIONS] <patch-definition-file>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information
    -v, --verbose    Enable verbose logging

OPTIONS:
    -o, --output-file <output-file>
            Path to the output archive (default: <patch_definition_file_name>.thor)

    -p, --patch-data-directory <patch-data-directory>
            Path to the directory that contains patch data (default: current working directory)


ARGS:
    <patch-definition-file>    Path to a patch definition file

Usage

Example:

$ ./mkpatch examples/patch.yml -p ~/myclient_files/
2021-03-10 16:50:45,236 INFO  [mkpatch] Processing 'patch.yml'
2021-03-10 16:50:45,237 INFO  [mkpatch] GRF merging: true
2021-03-10 16:50:45,237 INFO  [mkpatch] Checksums included: true
2021-03-10 16:50:45,237 INFO  [mkpatch] Target GRF: 'data.grf'
2021-03-10 16:50:45,268 INFO  [mkpatch] Patch generated at 'patch.thor'

The executable returns 0 in case of success and a non-zero value in case of failure.

The --patch-data-directory argument must point to a directory that contains the files declared in the patch definition file (e.g., data/texture/.../image.bmp). For example, if you specify --patch-data-directory /tmp/mydata, /tmp/mydata/data/texture/.../image.bmp will be added to the archive as data\texture\...\image.bmp.