Homecoming Launcher Technical Deep Dive

[Number Six]

This is a technical deep dive of the new Homecoming Launcher. For download instructions, please visit the public beta thread.

 

Terminology
The launcher uses some terminology that, while it’s not necessary to know for normal use, can be helpful when reading log files or discussing features.

• Package: A package is a collection of files that lives under a particular root (which may be a subdirectory). Packages are versioned and stateful - a cancelled download will not leave a package partially installed or updated for example. Only once the entire transaction is staged and verified is a package committed. Packages can have dependencies on other packages. Packages are not directly visible through the user interface and are mostly an implementation detail.
• Profile: A profile, or launch profile, is what you see in the UI as the buttons on the left. A profile contains information about which packages it requires, as well as instructions on how to launch a program, and what configuration options can be set. News feeds and server status are also provided on a per-profile basis.

Since there is a layer of separation, multiple profiles can (and in fact, do) share packages of common files. The launcher handles the details of figuring out which packages need to be installed or removed based on the profiles the user has indicated they want installed.

 

Security Features
The HC Launcher has multiple layers of security.

 

The first layer of security is the cryptographic integrity protections. All launcher assets, scripts, code, profiles, and packages are signed using X.509 certificates. We are currently using 2048 RSA keys for the production infrastructure, and 384-bit elliptic curve (secp384r1) for our test/dev infrastructure. The exact algorithms used may change in the future once there is wider library support for ed25519.

 

The launcher does not allow any code to run that is not signed, whether from a package or as part of a self-update. The signing keys are not accessible from the deployment infrastructure, so even a compromised download server could not cause users to run untrusted code.

 

By running the launcher, you’re still trusting the HC Team, but you can at least know that’s who the files are actually coming from.

 

There are some additional but less effective layers. One example is that each package has its own VFS with the package root as /, and processes all file access within it, so the package files themselves can’t reference absolute paths or escape out of the VFS. This doesn’t matter that much when we’re talking about downloading program code anyway, and is more useful for preventing accidents rather than trying to block something malicious.

 

Finally, the launcher has the ability to log in to our account system and retrieve an OAuth token. While there is not currently much use to doing this, we have near-term plans to use this functionality to log into the game itself. This allows us to address a common feature request and create a secure method to “remember password” that doesn’t actually save the password.

File Structure
The new file layout is designed to make the game client cleaner and more organized, as well as reduce the chance of potential problems with name collision. Some of it will look familiar and has not changed from the traditional structure, while some of it will not.

 

From the top level, here’s a breakdown of what is inside the HC: CoH install folder:

• accounts - Each account you log into will get a subfolder in here (moved from the top-level). The per-account subfolder contains chat logs if you have that option turned on, visited maps / fog of war data, playerslot.txt, and settings.json, which contains certain account-wide UI settings such as cooldown timers and chat timestamps.
• architect - Contains all AE-related data. Depending on what you have saved, it may contain subfolders for missions, storyarcs, and critters.
• assets - All of the packed game assets are contained in subfolders. Renamed and reorganized as while the assets are currently packed using the pigg format, that may or may not change in the future.
• bin - The game executables. It contains one subdirectory per platform -- currently win32 and win64. Inside you will find the launcher itself, as well as a subdirectory for each profile (live/beta/pre) with the game executables.
• cache - Temporary data that may be deleted with no ill effect. The shader cache, which was previously in LocalAppData\NCSoft has been moved here.
• costumes - Saved costumes. No change from the traditional location.
• crash - Any saved crash reports or memory dumps end up here.
• data - May be used for file overrides for addons. While we will be adding an official addon architecture in the future, placing files under data is still the best current way to apply client modifications.
• logs - Contains system-wide log files. Inside is a subfolder for the launcher logs, as well as a folder for each profile.
• powercust - Saved power customization themes. No changes here.
• screenshots - Exactly what it says.
• settings - Contains subfolders for the launcher itself as well as each game profile. Inside the game profile folders, you will find json files with the graphics and client settings that were previously stored in the registry. The per-profile settings folder is also used by the various in-game commands for saving and loading settings, keybinds, etc.

 

Interesting Technical Details
The core of the launcher is written in C. It uses a cross-platform support library developed internally that the game itself has used for a little over a year -- it started life as part of the project to port the client & mapserver to 64-bit. That library in turn uses jemalloc, mbedtls, and zlib. The launcher adds IUP, libjpeg, libpng, and libcurl.

 

The launcher also embeds a Lua interpreter, and the UI is written in Lua. This is partly to make minor updates to the launcher’s UI strictly a “data” change that doesn’t cause antivirus products to freak out, and partly a proof of concept and testbed for future projects involving the game client. The lua scripts are digitally signed and the launcher will not run unsigned code. The GUI is built using IUP, specifically IUP’s lua bindings.

 

Enterprising users will discover a ‘launchercli’ binary inside of the bin directory. This is exactly what it sounds like. While slightly barebones, it allows for installing, updating, and launching the game from the command line.

[DoctorDitko]

Wow.

I have no suggestions to offer, no nits to pick.

That is an amazingly well-thought-out design, and the implementation seems solid from this end.

/em praise