Mods: the complete guide

Configure the mods required by a server and understand how the launcher installs them. For trust and review rules, see Server-required mods; for Lua packages, see Server resources.

Three layers of mods#

A player's game folder is managed by the launcher as three layers. Knowing which layer a file belongs to answers most questions before they are asked.

The launcher keeps a journal of every file it placed, tagged with its layer (%LOCALAPPDATA%\Open77\modstore\state\projection.json, one entry per file with layer: stack or layer: world). Two rules follow from it:

• A world projection keeps every stack file exactly as it is and only removes the previous world's files. Joining another world swaps world files; it never touches Open//77.
• The stack projection at launcher start-up owns the whole folder and removes world files, so a world's archives never leak into another world or into the player's own game.

World mods are therefore re-laid on every Connect. They are not re-downloaded: blobs are content-addressed and stay in the player's store (modstore\blobs\<sha>), so a returning player only pays the projection.

Life of a world mod#

The path from your disk to the player's, with the file or log line to look at for each step.

1. The server declares it. Either a resource carries preload_mod "dist/package.zip" or an operator committed a hosted package from Warden. At start-up the server inspects each archive, stages it under server/.open77/mods/ by hash and announces the set:

   [INF] Required mods: 5 declared, digest=eccac11f…, enabled=True, unsecured=True.
   [INF] [resource:aventador_svj] started generation=1

   Every resource-owned package becomes a required mod named <resource>-assets; the digest covers the whole set and changes whenever a package does.

2. The server hosts the bytes beside its resource endpoint, immutable and content-addressed:

   GET http://<host>:<resource-port>/mods/v1/blobs/<sha256>

   The port is the one the server announces in its heartbeat (11779 on the development server, next to game port 11778). A server whose HTTP listener is down shows up in the launcher as This world's mods could not be downloaded.

3. The master relays the list. The catalogue row carries requiredMods (id, version, sha256, sizeBytes, url), the digest and the unsecured flag. The launcher and the in-game browser read the same row.

4. The launcher decides. On Connect it asks the master for a verdict on every hash, applies the capability cap (executable content needs a verified verdict, or the player's consent on an unsecured world), shows the consent gate, then fetches whatever the store lacks, hashing every byte against the announced value. Each archive is inspected — stored or freshly downloaded — and the package is laid over the stack:

   unsecured world: accepting unreviewed executable content in 'tweakxl assets' ('red4ext/plugins/TweakXL/TweakXL.dll')
   modstack: world layer keeps 291 stack file(s) in place
   world 'Open77 Development': projected 54 file(s), removed 0, kept 291 in place.

5. The game starts with a contract. The launcher passes the target and the digest it installed for this boot:

   Variable	Meaning
   OP77_CONNECT	host:port to auto-connect to
   OP77_CONNECT_MASTER	The directory source the ticket came from (alpha, development); the in-game shell enrols the identity with that master
   OP77_WORLD_SERVER	The world's server id
   OP77_WORLD_MODS_DIGEST	The required-mod digest this boot was prepared for

   REDengine mounts archive/pc/mod at boot, RED4ext loads the plugins, redscript compiles r6/scripts, TweakXL applies r6/tweaks. Nothing in this layer can be added mid-session.

6. The shell checks the contract. When a player picks a world from the in-game browser, the shell compares the world's digest with Open77.session.launcherContext().modsDigest. A match connects; a mismatch shows the Restart required prompt, which hands off to the launcher through open77://connect?server=…&endpoint=…&relaunch=<pid> and quits the game. See Joining from the in-game server browser.

Declaring mods on a server#

A resource that owns its package#

The recommended shape for anything a world needs: the package lives with the resource that needs it, the manifest states the loaders it depends on, and selecting the resource declares everything.

-- resources/assets/maps/kujira_world/open77.lua
resource "kujira_world"
version "1.0.0"
auto_start true
dependency "archivexl >=1.27.1"
dependency "tweakxl >=1.11.4"
preload_mod "dist/kujira.zip"
server_script "server/main.lua"

• Third-party packages live under resources/assets/ (loaders/, maps/, vehicles/, mods/); everything but loaders/ is ignored by git, so a checkout never carries someone else's archive. See Layout of the resources folder.
• The archive is a .zip or .7z whose entries are game-root relative paths (archive/pc/mod/…, r6/tweaks/…, r6/scripts/…). Nexus archives usually are already; a wrapping folder (MyMod/archive/pc/mod/…) must be stripped.
• Up to eight packages per resource, 1 byte to 64 MiB each; every declared path must exist.
• A dependency must itself be in resources.load. The loaders ship as resources (resources/assets/loaders/archivexl, resources/assets/loaders/tweakxl) that wrap the upstream release zip, so several worlds share one copy and the server starts them first.
• requiredMods.enabled must be true. Executable content (a .dll, a .reds, CET Lua, .asi) in a preload is refused unless the server is unsecured or the hash is verified.
• Changing a package needs a server restart and a fresh launcher boot of the game. ensure reloads the Lua, not the depot.

The load list in server.jsonc selects it:

"resources": {
  "load": ["freeroam", "archivexl", "tweakxl", "kujira_world"]
}

A hosted package from Warden#

For an operator without access to the resource tree: Warden → Mods → upload, read the plan (file, root, inert/executable, adds/replaces), commit, restart. Warden writes the requiredMods entry for you. Full walkthrough in Add a mod from the Warden panel.

An indexed package#

A package the platform distributes from its signed index is pinned by id and minVersion and costs the operator nothing. The index carries what Open//77 is licensed to redistribute; a package missing from it makes the world unjoinable, so check the index before pointing at it.

What a package may contain#

The launcher confines every file to a known root and classifies the package by its most privileged file.

Anything outside these roots, a path-traversal entry, or bytes that do not hash to the announced value refuses the package.

Worked example: a Nexus vehicle on the freeroam server#

Adding Lamborghini Aventador SVJ (Nexus 11176) to the development world, spawnable with /car. The mod requires ArchiveXL, TweakXL, RED4ext, redscript and the author's Vehicle manufacturer fix (Nexus 28744); CET is listed only for its spawn command and is not needed here.

1. Download the archives from the author's page (the launcher never rehosts what the author did not license; keep the licence in mind before making it a public requirement). Inspect them:

   KRNLNIK Lamborghini Aventador SVJ-11176-1-4.zip
     archive/pc/mod/aventador_svj.xl
     archive/pc/mod/KRNLNIK_Lamborghini_Aventador_SVJ.archive
     r6/tweaks/krnlnik/lamborghini_aventador_svj.tweak
     r6/tweaks/krnlnik/lamborghini_aventador_svj_ICONS.tweak
   VMF-28744-1-0.zip
     r6/scripts/VehicleManufacturerFix.reds

   Both are game-root relative. Repack without directory entries if you want the package minimal; the layout is what matters.

2. Create one resource per package. The fix first, because the car depends on it:

   -- resources/assets/mods/vehicle_manufacturer_fix/open77.lua
   resource "vehicle_manufacturer_fix"
   version "1.0.0"
   auto_start true
   preload_mod "dist/vmf.zip"
   server_script "server/main.lua"

   -- resources/assets/vehicles/aventador_svj/open77.lua
   resource "aventador_svj"
   version "1.4.0"
   auto_start true
   dependency "archivexl >=1.27.1"
   dependency "tweakxl >=1.11.4"
   dependency "vehicle_manufacturer_fix >=1.0.0"
   preload_mod "dist/aventador_svj.zip"
   server_script "server/main.lua"

   A server/main.lua that prints on onResourceStart is enough; the package does the work.

3. Select them and restart. Add "vehicle_manufacturer_fix", "aventador_svj" to resources.load. The .reds file is executable content, so this only boots on an unsecured server. Restart and read the boot log: Required mods: 5 declared with a new digest, one started line per resource.

4. Keep third-party bytes out of git. The repository ignores resources/assets/maps/kujira_world/, resources/assets/mods/vehicle_manufacturer_fix/ and resources/assets/vehicles/aventador_svj/ for that reason; the manifests are tiny, the archives are someone else's work.

5. Connect through the launcher. The consent gate reads 5 packages, 3 executable; accept, and the log shows projected 54 file(s), removed 0, kept 291 in place. The game boots with the archive mounted and the tweak records registered.

6. Spawn it. The freeroam /car command accepts any Vehicle.* record when Config.vehicles.allowCustomModels is true (resources/gamemodes/freeroam/shared/config.lua):

   /car Vehicle.aventador_svj_01

   The record name comes from the mod's tweak file. unknown_model means the record did not match ^Vehicle%.[%w_]+$ or the flag is off; an invisible or wrong vehicle means TweakXL did not load the record — check its log (below).

What the launcher does with the files#

• Store. %LOCALAPPDATA%\Open77\modstore\: blobs\<2 hex>\<sha256> (archives and every file inside them), pkg\<id>\<version>\modpkg.json (stack package manifests), state\projection.json (the journal). Nothing here is ever served to anyone.
• Projection. Files are hardlinked from the store into the game folder when the volume allows it, copied otherwise (--force-copy forces copies). Overwriting a hardlinked file in place — a local build deployed by hand — mutates the store's blob; the launcher notices at the next verification (not in the store yet) and re-fetches it. A placed file that no longer hashes as recorded counts as an unmanaged copy: an exclusive file is replaced by the stack's version (the log says so), a contested one is reported and left alone.
• Journal and commit. A projection writes projection.pending.json, moves files, then commits. An interrupted run is recovered on the next plan (a pending journal was found).
• Removal. Only files the launcher placed and that still hash as recorded are removed. A package that replaces a shipped file restores it on removal; prove that round trip on a test client before requiring such a package.
• The Solo profile projects the player's own set and takes Open//77's out; browse servers puts it back. World files never appear in Solo.

Developer builds and the local directory source#

The launcher's Directory source menu offers the official master and Local development (http://127.0.0.1:8090). On the local preset the launcher skips the stack update and the launcher self-update (a release launcher only trusts the production signing key), refuses the browser sign-in (it goes through the production website) in favour of the e-mail/password form, and still fetches and lays world mods. A dotnet build launcher never self-updates either; it reports version 1.0.0, which every release would otherwise out-rank.

Because the stack is not managed on that preset, branch builds deployed into the game folder stay in place. If the stack ever needs rebuilding, the headless CLI does it without the GUI:

$env:OP77_LAUNCHER_MASTER_URL = "https://master.open2077.net/"
Open77Launcher.exe --mods-apply --commit --game-dir "<game folder>"

Verifying that a mod loaded#

In order of cost, stop at the first that fails.

1. Launcher log (%LOCALAPPDATA%\Open77\launcher.log) at the Connect: world '<name>': projected N file(s), removed M, kept K in place. No such line means nothing was laid; a world mod fetch failed: <id> <reason> line names why.
2. Files on disk in the game folder, at the paths the archive declared (archive\pc\mod\<name>.archive, r6\tweaks\…, r6\scripts\…, red4ext\plugins\<loader>).
3. Loader logs after the game booted: red4ext\logs\red4ext-*.log lists the plugins it loaded (ArchiveXL, TweakXL, Open77); red4ext\plugins\ArchiveXL\ArchiveXL.log lists every .xl extension and archive it registered; red4ext\plugins\TweakXL\TweakXL.log lists the tweak files it applied and any record error. A redscript compile error shows a dialog at boot naming the script.
4. In game. A world mod: go where the geometry is. A vehicle: /car <record>. A tweak: the record exists (Game.GetVehicleSystem via CET, or a server-side Open77.vehicles.create with the record).
5. Server side. Required mods: N declared at boot, and each GET /mods/v1/blobs/<sha> answering 200 with the archive's size.

Troubleshooting#

Reference#