Corescripts setup

This guide explains how scripts can be set up to be modified, and configured to be served by the Site. If a Client is from 2011 or later, it will require corescripts to be set up in order to function correctly.

Terminology

The term "corescripts" can sometimes be ambiguous or refer to multiple things. In Mercury Core, the following definitions apply.

• Builtins: These are scripts, models, or other assets that are distributed with the Client (therefore not loaded from the Site), and provide core functionality such as animations, character scripts (health regeneration, humanoid state), fonts, and some basic meshes.
• Hardcoded assets: These are assets with IDs that are hardcoded into the Client which cannot easily be changed, though they are still loaded from the Site. This includes things like the Health model (the bar at the bottom of the screen, showing health and managing the red damage flash effect in some Clients).
• Loadscripts: These are some of the first scripts that run when a place is loaded, for example the Host script, loaded by Studio when running the command to host a place, or the Join script, loaded by the Client when a user joins a place.
• Corescripts: These are scripts that run on the Client. They provide functionality such as GUI elements, chat, and user interface. Corescripts are loaded from the Site, and each has a unique asset ID.
  The Join script loads the Starter script (default ID 37801172), and the Starter script loads the rest of the corescripts. These scripts can be modified to change the IDs, so the IDs can be easily changed, as long as they are compatible with the Client (this means they usually have to be numeric and below 2147483647).
• Dependencies: These are assets (usually images) loaded by Corescripts, Builtins, or Hardcoded assets. They have their own unique IDs which, again, can be modified if needed, and are loaded from the Site.
• Libraries: These are scripts that may include any functionality, commonly generic or reusable, loaded by Corescripts and any user-created scripts. Libraries are loaded by calling LoadLibrary() function with the Library's name (every library name begins with 'Rbx'), and each has an ID similarly to corescripts.
  Libraries were removed from the Client in 2020 after years of deprecation. Depending on the Client version, they may be used heavily, rarely, or not at all.
• Plugins: These are scripts distributed alongside Studio to provide extra functionality.
• Client scripts: The combination of Builtin scripts, Loadscripts, Corescripts, and Libraries.
• Privileged assets: The combination of all Hardcoded assets, Corescripts, Libraries, and Dependencies.

Under the usual vague definitions, "corescripts" could refer to any of the above.

Loadscripts are loaded from the Site, each from their own specific URL paths.
Privileged assets are all loaded as if they were normal assets from the Site. However, they are instead loaded from a separate directory from the other assets to improve ease of setup, updating, and management. It would theoretically be possible to set up Mercury Core normally, and upload all these assets to the Site like normal assets, but this would be an inconvenient and tedious process, especially in development where Database resets may be common.

Example scripts

An example repository, holding most Loadscripts, Plugins, and Privileged assets for the 11 December 2013 Client (release 132) used in Mercury 2 can be found at tp-link-extender/2013.

Omissions

Some of the less useful or untestable Corescripts, such as those for handling badges and gamepass/product purchases, have been deliberately removed from the example repository. This is because the functionality for these features is not implemented in Mercury Core, mainly due to the trust required between the Site and gameservers to handle communications securely. As such, they can't be implemented in a revival platform that allows users to host their own gameservers.
Once we are able to test with dedicated servers, we may re-add these scripts to the example repository.

Instructions

The set of scripts includes a compiler to move and bundle scripts into the format and directory structure expected by Mercury Core. These instructions also include how to run the compiler and set up the output to be used by Mercury Core.

1. Clone the tp-link-extender/2013 repository to a directory of your choice on your local machine, and navigate to the root directory of the cloned repository.

   git clone https://github.com/tp-link-extender/2013
   cd 2013

2. Install the necessary tools. This can be done in a few ways:

   • Install Aftman, and run aftman install to install the necessary tools.
   • Install Rokit, and run rokit install to install the necessary tools.
   • Manually install Darklua and add it to your PATH so it is accessible from the command line as darklua. This is the main dependency for the compiler, though we're planning to remove its requirement in the future.

3. Copy your PrivateKey.pem file (the private key corresponding to the public key patched into the Client) into the compile directory.

4. Run go run . in the compile directory to compile all scripts.

5. Navigate to the out directory in the root of the repository.

6. There should be two directories: server and plugins. Move the entire server directory into the data directory of your Mercury Core repository.

The output structure of the compiler is as follows:

• out
  • server: Assets and scripts to be served from the Site. This entire directory must be moved into the data directory of the Mercury Core repository.
    • assets: All Privileged assets. Each has an ID matching that expected by the Client, and are served normally as assets from the Site. When serving any asset, this directory is checked first. Privileged assets are pre-signed with the private key if required (if they are Corescripts or Libraries).
    • loadscripts: Loadscripts. These are not pre-signed as they need to be modified by the Site before they are served.
    • render: Render scripts, used to send to RCCService to render thumbnails and icons for assets.
  • plugins: Studio plugins. These are bundled alongside the Client itself, so this directory is not needed by Mercury Core.

Modification

This section details how to modify Client scripts.

The first thing to set straight is that Client scripts don't need to be modified. If a repository of scripts equal to that distributed at the time of the Client being used is available, it can sometimes be used as-is if using URL-rewriting methods in, for example, a DLL or other dynamic library hook.

Usually, minor modifications are required. This sometimes includes changing asset IDs to match those uploaded to the Site, or changing URLs in Loadscripts and Corescripts to match the Site's URL structure. Client script modification can result in incredible benefits, though most of these can be attained with little more than these minor changes.

Sometimes, major corescript modification is required. This can be if a new feature needs to be added or an existing one needs to be changed/removed, if performance issues need to be fixed (these are very common in older Clients), or if a feature needs to be rewritten to work with the new API implementation.

In-depth modification

Heavy Client script modification

Heavy Client script modification is rarely undertaken by revival platform developers. As one may expect from the process of optimising and rewriting ancient code for decades-old deprecated systems, this is a daunting and very time-consuming task, requiring a deep understanding of the Client's internal workings, as well as the ability to reverse-engineer and debug complex issues with little feedback.

Documentation for newer Client scripts is generally a little easier to find, and documentation for older ones is extremely sparse. If you want to find the only available resources on modifying old Client scripts, uh... you're looking at it.

We strongly suggest turning back now.

To effectively modify Client scripts, you'll need at least passing familiarity with the, depending on your Client, 30 000 to 300 000 lines of Lua code that make them up. A complete or clean rewrite of all Client scripts is an option, though would require an astounding level of work and understanding of the Client's internal workings. Starting from a copy of the original scripts is less than ideal but at least provides a working base to start from.

Most of the time, the only debugging system available is the Client's log output files, unless you're lucky enough to have a Client with a debug window corescript (2014 or later). As such, it's probably a good idea to build a logger script and debug console to forward log messages to an in-game GUI. The Mercury debug console is available in the example repository, which also includes some extra utilities and other fun features.

The best available crutches for understanding the API available in Client scripts is the Community Roblox API reference. This also includes addition and removal dates for functions, as well as a timeline showing when features began to become usable, which can be useful when working with older Clients.

To improve the ability to modify the older Client scripts in the example repository, they were rewritten in a language that compiles to Lua. Options previously used included MoonScript and YueScript. We ended up using Luau, as it's used for development of later official Client scripts, and the presence of type checking allows us to create a set of type definitions for the older Client's API. This also improves the experience for anyone developing games for the platform.
A custom script compiler is provided in the example repository, which can be used to compile and minify the Luau files into Lua, as well as correctly structuring and moving other Privileged assets into the correct directories to be served by the Site. The compiler also bundles scripts in a way that reusable parts can be extracted out into the Modules directory, improving maintainability and reducing duplication.