This wiki is connected to the GTFO modding discord.

Overview

This page is for people who want to get started with modding GTFO but don't know anything about it. If you're a programmer and you want to write actual mods, check out the introduction to plugins.

Always remember that the official discord server is not the place to discuss anything modding related. Talk about it in the modding discord instead.

Prerequisites/Recommendations

Datablocks are all stored in JSON, you need to get familiar with this text format. Basically it's a way to have data as text stored in a way that can be read by both humans and computers. There's an infinite number of guides and ways to learn JSON. One place to start is w3schools.

The text files can be edited even with notepad, but for your sanity I recommend using something more advanced. The most common option here is vscode. It allows you to easily manage entire folders of files at once, provides syntax checking, highlighting, easy searching, replacing, and lots of other good stuff. You can also add some vscode extensions for yourself such as indent-rainbow to further make your life easier. Either way you'll be looking at massive amounts of JSON so best be prepared.

Knowledge of C# or programming in general can definitely help but is not required for modding using datablocks.

RegEx is very helpful for quickly finding and replacing data.

Introduction

Datablocks (also referred to as blocks or db) are GTFO's way of storing various information about the game. While I'm positive they don't directly edit the files ever, them choosing JSON is a convenient way for modders to read and change that information. What is stored in datablocks is completely in devs' control. Sometimes it may seem arbitrary what is stored there and what isn't, so some modders make plugins that allow even more control over the game.

Some examples of what we can find in datablocks:

• The stats of weapons, enemies, and players (HP, speed, damage etc);

• Terminal logs and passwords;

• Enemy population in levels;

• The objectives of levels;

• Level layouts themselves;

• Entire rundowns.

Everything that is stored in datablocks can be edited. As previously stated, the developers control what is stored in datablocks, making them limited in some aspects. Some things have set rules that you cannot see in datablocks. Some things may be very hard to get to work as expected. Some things cannot be done using only datablocks. Learning to use them can take a lot of effort, and you will have questions, so don't hesitate to ask in the datablock development channel.

MTFO Installation/Setup

For a quick, hassle-free setup it's recommended that you use R2Modman, a mod manager built to work with Thunderstore.

Installation with R2Modman/Thunderstore mod manager

1. Install the latest version of the mod manager

2. Launch the mod manager and select GTFO

3. Create a new profile and name it

4. Select "Online" and install MTFO

5. Open Settings -> Locations -> Change GTFO directory. Locate and select the install location of GTFO. By default this is C:\Program Files (x86)\Steam\steamapps\common\GTFO

6. Hit the "Play Modded" button

Best practice is to create one profile per rundown so you can switch between them easily.

You can find the profile folder by going through the mod manager to Settings -> All -> Browse Profile Folder

Manual Installation

1. Download Bepinex and MTFO, then follow their installation instructions (they should just require you to extract the packages in certain folders)

2. Run the game normally. To play vanilla again, you'd have to manually delete the mods (or remove/rename some specific files)

Getting the datablocks

Now that MTFO is ready, there are still a few things left to do to get datablocks

1. After installing the mods, launch the game once for MTFO config to generate

2. Move to BepInEx\config and open MTFO.cfg

3. Set "Dump GameData" to true, save the file

4. Launch and close the game

5. You should now see a folder like BepInEx\GameData-Dump\31829 (version might be changed), this is your datablocks folder

6. Copy the folder to BepInEx\plugins so you'll for example have BepInEx\plugins\31829 (folder name doesn't matter)

7. You can now edit the blocks in plugins and they'll be loaded by MTFO

A few things to note:

• You can always regenerate the datablocks by just deleting them from gamedata-dump and launching the game again

• Disabling the dump setting is optional

• Only keep one folder of datablocks to load, otherwise you have no control over what's loaded

• You don't need to keep all datablocks to have them load. In fact, it's recommended to only keep the ones you're going to edit

Get started

To get some familiarity with editing datablocks, we're going to do 3 things in this section:

1. Change a weapon's stats;

2. Enable a weapon from a previous rundown;

3. Switch the stats of an enemy to those of another.

You can test either after every step or all at once. A few tips before we get started:

• Datablock reference can be used to get a lot of information about blocks.

• LocalizedText is a special type that can both point to a text block and be read as a plain string.

• All enums can be passed as numbers or strings. I personally recommend using strings since they often give more information than plain numbers, but both work equally fine.

Remember, after initial generation, all datablocks should be located in GTFO\BepInEx\plugins\GameData_XXXXX\

Changing a weapon's stats

Let's keep this one simple. We're going to find the pistol's stats and change its damage to 100 and firemode to automatic. Weapon stats are kept in Archetype datablock. There are multiple ways to determine which block belongs to the pistol, but for now let's "assume" that the correct block is the one with the name "GEAR_Pistol_Semi_v2".

• Note: lines under 3155 and 3184 are collapsed in vscode editor to reduce clutter. You'll see this used a lot.

Among the fields we can see the ones named "Damage" and "FireMode" (the latter is an enum and will appear as a number if you're not using enums as strings). Change the damage to 100 and firemode to auto. Additionally, let's change the public name to "Balanced pistol" so we can see the custom blocks were loaded without having to drop into a level.

After saving, you can launch the game and test, or you can test after all the changes.

Enabling a weapon from a previous rundown

All datablocks share some fields. One of these fields is called "internalEnabled" and basically determines whether that block exists for the game or not. To enable a previous weapon, the only thing we need to do (assuming the old blocks have not been broken by game updates) is set this field to true in the correct places. For now we are going to enable the combat shotgun. Open PlayerOfflineGear datablock and find the block named "ShotgunAuto". Set "internalEnabled" to true on that block.

When you save this and launch the game, the combat shotgun should be available under special weapons.

Switching the stats of an enemy with those of another

Aside from "internalEnabled" there are 2 other fields that are shared by all blocks. One of them is "name" which you don't see used in-game, but it does help identify the block you're looking at. The last shared field is "persistentID". This is the field used by blocks to reference other blocks. Note that "persistentID" and "name" cannot repeat in the same file.

Let's change a striker's stats to those of a big striker's using these references. The main block of an enemy is Enemy datablock and the stats we're looking for are stored in EnemyBalancing datablock. The reference field is named "BalancingDataId".

To change the stats we just need to find the big striker's balancing data, get its persistentID (in this case it's 16), and set it on the striker data.

And that's it, wave strikers now have the balancing stats of a big striker. If you want, you can also change the balancing data of "Striker_Hibernate" as well for easier testing and more suffering.

• If you want to undo all your changes, you can delete the edited files and let them regenerate.

• If you're wondering what fields do what, you can either interpret the name or check out the datablock reference.

• Most fields that hold references to other blocks are of the type "uint" aka "UInt32".

Introduction to errors

If you edit datablocks enough, you're bound to run into errors, also called exceptions. There's an infinite number of causes so it's impossible to know all of them, but it's important to know where to start looking for information, at the very least so you can pass on more when looking for help. If you do run into something you can't fix yourself, you can ask in the tech support channel in the modding discord.

When launching the game with mods enabled, you'll see the BepInEx console as a separate window. This console is useful for many things, but most importantly for users, it shows errors in red text. All logged messages have the type and source as a prefix. E.g. [Error: MTFO] error message shows that there was an error caused by the mod MTFO. Most of the time errors are caused by the game itself, in which case you will see [Error: Unity] as the prefix. In this case I would always recommend to look for the error in the game logs instead of BepInEx logs. These are located in %userprofile%\AppData\LocalLow\10 Chambers Collective\GTFO If you closed the game already, their name will be of the following format: GTFO.[Date].[Time]_[PlayerNick]_[NetworkStatus]. If the game is still open, it'll instead be GTFO.[Date].[Time]_NICKNAME_NETSTATUS. For the most part you will be looking for the most recent file created. While in bepinex console the error message is one line, the game logs provide the stack trace, which is the full source of the error and often provides much more information than just the error message.

Let's take a look at an example. BepInEx console shows this error message:

NullReferenceException: Object reference not set to an instance of an object.

While the game logs show this:

18:17:44.732 - NullReferenceException: Object reference not set to an instance of an object.
Gear.MeleeWeaponFirstPerson.UpdateInput () (at <00000000000000000000000000000000>:0)
Gear.MeleeWeaponFirstPerson.UpdateLocal () (at <00000000000000000000000000000000>:0)

NullReferenceException is one of the most common errors that says next to nothing about the cause. All we know from BepInEx console is that an error happened. But the game logs show that the source is from melee weapons. Even if this error doesn't give enough information to you, it will allow other people to find the cause if you ask for help.

Also note that some errors can cause even more errors. When debugging, check the oldest errors first.

Remarks

• GameDataBlockBase, trying to save x without being setup error is most likely caused by errors in your JSON. Check your syntax and if you pass incorrect types, such as string instead of int.

• You can use git to track changes. This allows you to easily see everything you changed at any time, which is useful for many purposes and especially debugging.

• If something doesn't work correctly, check if your mods are up to date. Rundown updates often break them.

• Game logs are useful for more than just finding exceptions, they provide information about what's going on in the game. You can make a desktop shortcut to the logs folder to access them faster.

• Remember, game updates can break existing datablocks, so be careful when using old blocks as reference (and especially careful when enabling disabled blocks).

Recommended content

Check out the Datablocks reference main page for general information about datablocks. Learn to use datablocks reference to get information about specific datablocks.

Once you have some experience, you can check out the Newbie Level Guide if you're interested in making levels/rundowns.

Overview

Not all fields have functional use in-game. Some are used just to display something, like level descriptions for example. Now that we have isolated one level in our rundown, let's change some fields to distinguish it from R6B2.

Naming the blocks

First let's change the "name" fields of both rundown and level layout. As we know, this is one of the fields shared by all datablocks and must be unique in the file. It is never visible in-game without mods, but having good names helps with readability and lets us describe the block. This is especially relevant here since JSON has no comments (although there are ways).

The exact names are up to you. I can only try to give a few tips, whether to follow them is up to you:

• Keep a consistent style of naming.

• Describe what the block is concisely. A longer name is better than a shorter one that has no meaning.

• Don't use abbreviations you might not remember.

• Use practical names; no jokes.

• You can mark unfinished blocks by adding TODO (and even what exactly is unfinished) in the name if you need to remind yourself.

• If you're working on a block that has many entries and you're modifying only a few (e.g. archetype), you can think of a prefix to attach to all names so you know which ones you changed.

Here are the names I chose.

This is the only field we're changing that's usually invisible to the players.

Changing data displayed to the player

Remember a lot of text fields are of the LocalizedText type, these can be both numbers and strings. If you want localization in your custom rundown you can use the LocalizedText type, in this guide we'll only use strings. You can always check the original text you're changing by looking for the ID in TextDataBlock.

Let's mark the fields we'll focus on:

• In rundown datablock:

  • "Title" - the displayed title of the rundown;

  • "SurfaceDescription" - displayed when clicking the "intel" button (nobody reads this though);

  • "Prefix" - Mission prefix, in base game always used to specify tier. In old times the devs asked us to distinguish from base game rundowns (e.g. "act-1") but nowadays it doesn't matter;

  • "PublicName" - the name of the mission;

  • "ExpeditionDepth" - Drop cage target depth in expedition details;

  • "ExpeditionDescription" - text displayed under "://Intel_" in expedition details;

  • "RoleplayedWardenIntel" - text displayed under ":://Interrupted_Communications_" in expedition details and when dropping in.

• In level layout:

  • "ZoneAliasStart" - used to calculate zone alias unless overriden. By default a zone's alias is this number + localindex offset.

There are more but this is enough for now.

Since this all has no impact on gameplay (except ZoneAliasStart but that has minimal impact), the values are up to you. Here's what I used:

"Title": "Newbie guide rundown"
"SurfaceDescription": "<b>This</b> is a rundown.\nDear God...\nThere's more.\nNo!"
"Prefix": "F"
"PublicName": "Pollutant"
"ExpeditionDepth": 527
"ExpeditionDescription": "This is an example level created for the newbie guide"
"RoleplayedWardenIntel": ">.. Have we been here before?\r\n<size=20%>Yes</size>\r\n<color=red>>..No, you must be going insane..</color>"
"ZoneAliasStart": 100

The results:

There are more fields related to visual data in rundown and level layout but with this we have enough to make unique vanilla-style rundown & level information. We can move on to the 3rd step in the guide.

Overview

This step isn't necessary (and in some ways it's better not to do this at all), but for learning purposes it's good to understand exactly what we'll be working with.

For this step we're going to trim the main datablocks that we'll be working with (specifically Rundown and LevelLayout) so that they only contain one level.

This also doubles as an exercise in using VS Code.

Isolating blocks

Setup

To start, we'll grab a copy of the unedited Rundown, LevelLayout and GameSetup datablocks. You can follow along with how to generate them using MTFO from The Complete Newbie Guide or grab them from the archived versions at OriginalDataBlocks . You can also view the final version of our edited datablocks here: Final datablocks version page. Put these inside a folder in the GameData directory of BepInEx. You'll have something like this:

Open your GameData folder with VS Code.

Deleting rundown blocks

Open the Rundown datablock and delete the headers.

Now we'll delete all but one rundown from the "Blocks" part of the datablock.

First, find the "Tutorial Holder" rundown's block. This contains the game's tutorial, and its presence is hardcoded so we can't delete it.

Go to the start of the block, collapse it, and copy it. (Or, if using VS Code, you can use Control + Shift + [ to collapse the block your cursor is in).

Paste it at the bottom of the blocks.

Find the rundown that contains whichever level you'd like to use as a foundation. In this case, we'll use Rundown 6.

Collapse it, copy it and paste it at the bottom of the blocks.

Delete all the other blocks, aside from our two at the bottom (it's easiest to do this by collapsing them all). Once we're down to just our two blocks you might need to fix some formatting. There should be a comma between our two blocks, but not one at the end.

Deleting all but one level from the rundown

We only have one rundown and we want to keep only one level in it. Let's go with B2.

Collapse all the tier blocks.

Delete everything but B tier.

Confirm that the 2nd object in B tier is B2 "Contaminant" and collapse the tier blocks

Delete all but the 2nd block.

B2 has now become B1 and is the only level in the rundown.

Deleting secondary layer

Contaminant is the only level in our rundown, but it still has a secondary layer. Let's thoroughly remove the secondary layer from the Rundown datablock. We'll have to remove quite a few sections, see the image below for what we have to remove. We need to remove the bulkhead information from the main layer, and also a bunch of stuff from the secondary layer. After we're done, the secondary layer should look the same as the third layer.

Deleting level layout blocks

Now we have to do the same to the LevelLayout datablock. We'll find the correct level layout ID and delete the rest.

In the picture above from our rundown block, you can see that LevelLayoutData is set to 162. That's our main layer level layout.

Open the LevelLayout datablock and find the block with this ID.

Repeat the same process as for our rundown blocks: collapse it, copy it, collapse all blocks, delete them, paste the copied block, delete the comma.

Remember VS Code has to process over 200k lines here so don't be too harsh if it lags a bit. Deleting at least a part of the blocks does have practical use here as VS Code and its plugins won't take time to load when editing huge files like this one.

There should only be a few thousand lines left in this file.

Modifying game setup datablock

Most of the work is now done, and we only have to do a minor tweak to the GameSetup datablock. Open it up and change the "RundownIdsToLoad" to only contain the rundown ID for your rundown. The rundown's ID is the "PersistentID" number at the bottom of the rundown's block.

Regarding changing IDs

We talked briefly about changing the ID of our rundown block earlier. While this is not a necessary step anymore thanks to GTFO API, it was originally agreed with devs to change all custom rundowns' ID to 1. If you did do this, you'll obviously have to change the "RundownIdsToLoad" to match.

You're also allowed to change the LevelLayout block IDs. If you do so, then you'll have to change the "LevelLayoutData" from the rundown's block to match.

Verifying

Remember to save everything.

Launch the game. You should now see only B1 in the rundown menu.

Drop into the level. You should now have only the one rundown, and the level itself should load just fine. If you have freecam or some other mods, you can use them to check what the level looks like more easily. See if anything has changed.

You should see some marker (all sorts of objects placed in the level, a whole different topic) placement differences, also the lack of the secondary layer.

Oh and we deleted the bulkhead key, controller, and the bulkhead door (which is now just a security door) from the main layer. If you want to restore that, you can do so by restoring these 3 fields from the original datablock we kept as a backup (you did keep some as a backup, right?):

• ZonesWithBulkheadEntrance - zones in same layer (main) that have bulkhead entrances.

• BulkheadDoorControllerPlacements - where to place bulkhead door controllers. If a zone with a bulkhead entrance does not have a door controller, the entrance will not require a bulkhead key.

• BulkheadKeyPlacements - where to place bulkhead keys in the layer.

Make sure you restore the ones under MainLayerData and not secondary. You can also just copy the whole MainLayerData block.

Later sections of the guide will assume you restored these (or didn't delete them to begin with).

If you did actually restore and verify again, the terminal near the bulkhead might be near the zone door in front of the door controller now.

The Rundown, LevelLayout and GameSetup blocks are now cleaned up and we can move onto the 2nd step in the guide.

Since R6 is gone now and so are the source blocks, some things have changed and the guide may be hard to follow. You may want to see what blocks were used when originally developing the guide, or perhaps you just want to check/copy a specific block. Either way, the guide blocks are now stored on git:

You can also check out the commits to see any changes made since initial release. I will also cover some changes here as well.

R7 update

Since MTFO now supports loading only specific blocks (also to fix some crap broken by R7 like players' shoes, shooters with pouncer stance and so on), the blocks have been minimized.

Additionally, the exit zone size has been changed so the max size isn't reached before exit geomorph is generated.

Here's the new map:

R1 ALT update

Now that devs have confirmed they're officially killing the game (and keeping old rundowns), code-wise it shouldn't change much, which means less maintenance work for rundown developers.

With this update, there's only 2 things to do to get old levels to work:

2. Add the tutorial rundown (its reference is hardcoded so we can't get rid of it)

That's it. The layout doesn't even reroll. Unless you were using some mods that are now broken (this guide only uses MTFO), the level should be fully functional.

R2 ALT update

It seems no changes are required.

Since this is likely to continue, the notes will only be updated if there are relevant changes.

R8 update

The start of the guide has been reworked to include the R1 ALT update required changes. Additionally some ID numbers have been changed to avoid collisions.

Overview

This is the meat of the guide. We're going to add a zone, add sleepers, alarms, blood doors, spitters, respawns, resources, a generator puzzle, a pitch black zone, fog.. there's tons of stuff we can do here.

However, as always, we can't explore everything or we'll be here all week (and this part is already really long). I'll try not to go into too much detail on the meaning of fields this time either, since you can check the relevant blocks' reference to see what all the fields do.

In practice I would just use the more readable blocks from the (or some people opt to make levels using the ), but we started with MTFO generated blocks so let's continue with them.

Before we start

There's a block we can change once for the whole rundown to make level editing life a bit easier in the long run.

The datablock in question is ExpeditionBalance. We won't cover all of it, only the relevant parts.

Yes, we're about to screw up the balance of the current level, but when making your own levels you shouldn't start with preset resources and sleeper spawns.

Resources

The fields in question:

These are the base multipliers for resources. Say, with Health being 1.0, setting "HealthMulti" in a zone to 0.8 will result in 4 uses of health, or 80% health for a player. This basically requires no calculation.

The values we don't like - the ones that complicate the math - are weapon and tool ammo.

Set both of those fields to 1 so you don't have to think about how many uses of ammo/tool you'll spawn.

Artifacts

Artifact progress is not saved when using mods, so unless you have special mods that make use of it, it's just an annoyance. What's more, they can even cause your layout to reroll if there's not enough space to place all of them, affecting not only one zone, but the rest of the layout generated afterwards.

Set these 2 fields to 0 to avoid artifact spawns:

Sleeper spawns

So with a distribution value of 1, we'll have 25 points. But if we want to have exactly 12 points for example, we have to do some math.

Since we don't like math, let's set EnemyPopulationPerZone to 10. Now all we have to do to get 12 points is assign 1.2 in DistributionValue. Why not just go with 1? Because devs decided to automatically fail if it's set to less than 5 regardless of DistributionValue.

Reminder that we have just screwed up the resources and especially sleepers in our level, but in reality we wouldn't start with resources and sleepers already set anyway.

Adding a new zone

Now that that's taken care of, we can start messing with the level layout itself.

Let's add a new zone to the existing level. We're going to do this in the following order:

1. Copy the first zone and paste it at the end;

2. Change the local index;

3. Setup build parameters - where it's built from, the direction, size, altitude, subcomplex;

4. Adjust terminals;

5. Adjust lighting;

6. Set sleepers;

7. Set resources and consumables.

There's more we can do, but these 7 are plenty to get a full zone. And this is already too much to do at once without testing.

Steps 1 and 2

Go to level layout, copy the first zone, and paste it after the last zone. If you collapse all the zones now, you should see 12 in total:

Anyway, the last zone had localindex 10, so this one should have 11. You can verify by searching for localIndex 11:

Step 3

SubComplex is 2, so this would be a Storage zone. Let's change it to DigSite (0) instead.

BuildFromLocalIndex is 0, so the source zone here will be the elevator zone. This is fine.

StartPosition is 1 (From_Start). The elevator zone is pretty small so this might not have impact, but let's change it to 2 (From_AverageCenter).

StartExpansion is 1. Let's change it to 3, hoping it will generate a security door to the right.

ZoneExpansion is 3. Let's also change this to go right, setting it to 5.

AltitudeData is 3. I would normally allow all here, but this level has infection fog, so let's go with 5. Medium-high should generate mostly above infection fog (of course that depends on fog settings but we already have existing medium zones and we know those are above fog).

CoverageMinMax is 40-45. That should result in a zone around medium-ish size. Let's set it to 65-65. We'll hopefully get a huge room and around 2 larges or a mix.

This is all guesswork. If we wanted precision, we'd have to try mods or keep rerolling the layout until we get what we want. But for now let's roll with what we get, even if it turns out completely different from my expectations.

Step 4

The generated zone should be decently big now, so let's have 2 terminals.

Find TerminalPlacements, we'll set the placement weights to 0, leaving the terminal placement up to rng. Then copy-paste that block.

The results:

Step 5

Lights are decided by "LightSettings" field. If this is set to 0, the light settings in rundown db will be chosen instead.

Right now it's set to 56. If we have a look at the LightSettings datablock and find that entry, we'll see it's named "AlmostWhite_1". Let's try 71 "RustyRedToBrown_1" instead. If you want, you can pick something different or even make your own light settings.

Step 6

We'll need the EnemyPopulation and EnemyGroup datablocks, and we'll also still need to make use of LevelLayout. Since we'll have to alternate between several files here, you might want to use split editor.

We're going to create 1 randomized group of either strikers, shooters, or big strikers, and 1 group with forced scout. We can reuse existing groups and populations but let's make our own for practice. A bottom-up approach is more appropriate here, so let's start with the EnemyPopulation datablock.

Deleting all existing blocks and remaking from scratch would introduce a few problems with hardcoded ID uses and the current level spawns so let's not do that (but when making full custom rundowns that might be better in the long run). Instead we'll be using numbers that are guaranteed not to mix up with base game blocks.

I'll follow the "rules" set in enemy spawning system. Considering the special enum values, limitations, and the total size of the enums in base game (ensuring scout entry doesn't step on one), here are the 4 new "RoleDatas" for our population entry:

These will go inside the "RoleDatas" of the population block that our expedition is using (you can see which population your expedition is using in the Rundown datablock). In our case, our expedition is using an "EnemyPopulation" of 1 (pretty much every level does). So we'll place these new "RoleDatas" at the end of this population, like so:

As we can see the role-difficulty pairs are unique so these entries won't be randomized at population-level, only at group-level.

Now to add enemy groups, these will just go below all the existing enemy groups in the EnemyGroup datablock:

1 forced scout group, and 4 mixed groups of the 3 enemies. Considering the relative weights, this should be a striker-dominant zone. MaxScores are the same all around so these will be a bit more predictable sizes. If we wanted more randomized sizes we could go with a range of 2-6 for example. It's just best not to give really big sizes to groups since a whole group always spawns in the same room, possibly resulting in high concentration in one area and rest zone empty.

Note I included an update to the LastPersistentID value. That's just so the logs don't clutter saying blocks with IDs above last were found.

Also remember MaxScore has that obnoxious hardcoded random multiplier on it, screwing with our spawns for no good reason.

Finally, we can set the spawns in level layout:

Comments again for clarity.

30 score spawns + 1 forced scout sounds fair for this zone size, but that of course depends on balancing.

Also normally you would take a look at the generated layout and settle on it before starting to spawn sleepers.

Step 7

All that's left before we finally drop in is resources and consumables.

Before setting any spawns, always make sure these 2 are set to true in our LevelLayout block:

Resources are fairly straight-forward and purely dependent on balance so let's just use them to verify ExpeditionBalance values, setting all to 2 - should be 10 uses of each resource.

Consumables are set by just one field - "ConsumableDistributionInZone". If we tried to make something specific we'd have to constantly look at ItemDataBlock. Let's do the same as we did with lights and judge by names here instead. We'll have a peek at the names in the ConsumableDistribution datablock.

It's currently set to 45, "OnlyFogReps_Alt". Fog repeller balancing is important for an infection level, but our zone specifically is set to medium-high altitude data. While it can still generate something under infection fog, it should mostly stick to above that. Our options are combatting darkness, fog, giving foam/tripmines which are very powerful, or just generic consumable distribution that doesn't focus on anything in particular. Let's go with the generic one, setting it to 1.

Testing the new zone

A more proper level-making process could be something like this for example:

1. The entire layout;

2. Objective;

3. Resources;

4. Consumables and other spawns;

5. Sleepers;

6. Alarms.

But since we're just learning we simply focused on a single zone and finally made it to testing.

Before drop

In lobby, remember to select the biotracker if you don't have mods that'll let you count and avoid enemies easier (you really should be using some though).

Before we drop in, we need to be ready for errors. We have 2 options here.

Option 1: Using bepinex console/UnityLogListening set to true

If bepinex console is enabled and unity log listening is enabled in bepinex config.

While dropping in, look at the console to check if you don't see tons of errors (red text) looping, meaning we've entered an infinite cage drop.

Option 2: No bepinex console/UnityLogListening set to false

This is if we can't see game logs in bepinex console.

Open the game logs folder %userprofile%\AppData\LocalLow\10 Chambers Collective\GTFO and locate the current log. Monitor it while dropping in. If the level generation fails, the latest log can start rapidly rising in size, meaning we entered an infinite error loop and will never finish cage drop.

Either way

If infinite cage drop happens, exit the game and relaunch after debugging and coming up with a fix. Exiting just the level can work but we can't guarantee no after-effects will carry over to the next drop.

Even if we drop in successfully we'll check for exceptions to see if anything failed without causing infinite cage drop. During the whole testing process and after exiting the level you should still look at the logs to verify no errors appeared.

After drop

Immediately upon dropping in and revealing the map I can something new at the right side of the map generated. Let's compare before/after.

We can see the map is the same apart from something new generated at the top right, which would be our zone. However, even without going in to test, it's clearly visible that the zone is not generated from the elevator zone. Verifying this we can see it generated from the zone to the right of elevator, and the source entry is to the north (forward):

Why did this happen?

There's no errors in the bepinex console and no particular errors in the game logs, but let's look closer.

The "BlockAndCleanFailedAreasFromZone" part is ok, it happens. I'm not an LG expert, but if I had to guess I'd say it either collided with other zones or ran out of plugs to connect areas.

Line 6 explains the cause. Zone 0 has nowhere to generate a security door so it moved on to another zone.

I'd say LG handled this well but we still need to fix it. A few options here:

• Expand the elevator zone - screw up the whole existing layout.

• Move source to zone 103 (right-most zone) - that is a fog zone and there are other balance shenanigans.

• Move source to zone 102 - this is what LG did.

Let's go with option 3. We should also change the entrance to north like LG generated because there's likely no entrance to generate on the right side, but we can still try that and see what happens. Spoilers - it still generated from the north. Let's go ahead and change both fields now:

Here's our map now:

We can see it still generated in the same spot, as expected, and this time the layout of the zone is different. This is the exact same map as before changing entrance direction to north.

Time to explore.

Exploring the zone

The layout

The zone is heading right indeed, it's above fog everywhere except in parts of the last room, which is the huge one so that's expected. The lighting is also as expected. Here's a view of the last room from its entrance:

If it seems relatively dark, it's because I'm using the lights adjustment mod.

Two terminals generated, one near the middle, another at the very end.

Overall, I would say the layout is a great success.

The sleepers

24 total sleepers spawned - 2 big strikers, 1 scout, 11 strikers and 10 shooters. The spread is fair, only one area got 3 groups which is still very manageable. The spawns are very easy in this zone. I would say we can easily double the distribution here unless there's some special reason not to (like an error alarm), but we're not trying to balance the level. The spawns are all there, the count and spread is as expected. The sleepers part is successful.

The resources

10 uses of each spawned in various pack sizes. Right on target. If you get a bit more it might still be fine, because there's a base game bug where a resource pack spawns bigger than it should be.

With consumables we weren't going for anything special, so there's not much to verify apart from the fact that the usual stuff spawned.

We've seen everything and after leaving the level there are still no errors to see. We've successfully added a new zone.

Editing existing zones

Unfortunately, we're still not done here. Out of the things we said we would do in the overview, we still have these to do: alarms, blood doors, spitters, respawns, a generator puzzle, a pitch black zone, and fog.

Might as well go for some sort of world record in page length.

Or speedrun the rest of these topics.

Adding an alarm

Ah yes, the best difficulty filler in the game, abused on every single level. Even the error shenanigans in R4 are technically all alarms.

We'll eventually add our alarm by changing our "ChainedPuzzleToEnter" for our new zone in the LevelLayout block, but we'll do things from the ground up again.

In this example we'll only be editing ChainedPuzzle and SurvivalWaveSettings, though we'll reference things in the other blocks.

Survival wave population ID 1 will give us striker in standard, shooter in special, and big striker in miniboss. As basic an alarm setup as it gets.

For survival wave settings let's make something new. Something the base game doesn't do for alarms.

A little bit of analysis:

• Updating LastPersistentID to match our new highest PersistentID.

• Wave pause settings set to basically enforce 30-ish seconds between waves. The little variation is because something bugs if min-max are equal.

• Population filter (with some help from base game boss bug) will allow only the 3 roles to spawn.

• The most notable thing here is the limited population. Combined with points per wave, we get exactly 2 waves, with group spawns being more intense on the 2nd wave.

This alarm should keep the players occupied for at least a minute and depending on their clearing power, not much longer than that.

Moving on to chained puzzle:

We're using the blocks we settled on - 400 for our new survival wave setting, and 1 for the basic survival wave population. For scans, one type 33 - the geo scan (introduced in R6.5) (highly likely not to function well in a random geo, but let's try it) - should be enough and we're not disabling the waves when the scan is completed, so the players will have to kill the 2 full waves.

Now they could just cheese it by running away and mining wherever until the population runs out, but from my experience they don't do that:

1. Barely anybody even notices something out of the ordinary with spawns when they're made well. If they do, they don't realize the specifics.

2. People hate wasting time. Even with cheese they'd have to sit in a sustain full-team scan for a while doing absolutely nothing.

All that's left is to set "ChainedPuzzleToEnter": 300 in our level layout and test.

Unsurprisingly the geo scan is screwed up but it's mostly functional so it's fine. Moving on.

Adding a blood door

The new zone has suffered enough so let's leave it alone for now. Let's add a blood door to the zone left from the elevator - localIndex 1.

Setting up a blood door is fairly easy as long as you know your enemy groups. It's controlled by "ActiveEnemyWave" in level layout. Let's skip making hunter groups this time and just see what's in stock. I see "Hunter Easy Bullrush" in groups with ID 32. MaxScore 8 makes me guess it should be about 8 spawns, but it seems the cost is 2 in population so it's actually 4. Let's spawn one group on the door and 2 in the area for a total of 12 chargers:

A quick test here shows the predictions were spot on. On to the next topic.

The rest

Spitters, respawns, a generator puzzle, a pitch black zone, fog - we've got 5 things left to do, and at this point I feel like we've had enough practice to tackle them without too many details.

Spitters

We're spawning just a few because I hate spitters. Most fields besides the ID and Count are for location randomization.

Respawns

Respawner sacks are also a static spawn I believe, but they seem to be a special one, you only set up enemy respawning and they'll spawn automatically. So let's do that, again placing them in the first zone because we hate everyone who plays our levels:

The fields are all straight-forward here, but as always you can check the datablock reference for explanations. We don't need any respawn exclusions here so we don't even need to have that field.

Now when we messed with expedition balancing we reduced the first zone's population to barely anything, and there will be few respawn sacks as well because of that. Still enough to verify it's there and respawn works though.

Generator puzzle

I was going to make a keycard puzzle but we already have that example in the early zones. And generators have a little optional trick - we can spawn cells using big pickups distribution instead of ZonePlacementData. Scientific research suggests that thanks to how markers are set up, we'll get more possible placements inside our zone using big pickups instead of zone placement.

In zone 0, set ForceBigPickupsAllocation to true and BigPickupDistributionInZone to 5. In zone 1, set PuzzleType to 2 and PlacementCount to 0.

Now the zone to the left of spawn should require a generator to be activated which spawns in its entrance zone, and in elevator zone we spawned a cell using big pickups.

Pitch black zone

This one's just a matter of light settings, and there already seem to be 2 settings for darkness. Let's set LightSettings to 73 in zone 1.

Editing fog

This can't be set per zone, we can either edit the level's fog settings or setup some warden objective stuff. From rundown db we can see the level uses FogSettings with an ID of 90. We should copy that to a new persistent ID and set it, then edit the settings. But let's just edit ID 90 directly in the FogSettings datablock.

If we don't want to flip the balance of the level, we can only do something boring, which means we're flipping the balance of the level. Here are the new settings:

Fog density has been increased, altitude moved way up to 5, range and max boost changed to 0. Now the fog is upside-down and cancer is in the high zones instead of low. Flip successful.

If you didn't test these 5 parts yet, now's the time. We're all done with the changes. Here's a picture where you can see the fog, generator, spitters, and respawners:

Bonus points if you get hit by a spitter as soon as you drop in.

Afterword

I would like to thank all my fans, my mother, and everyone that supported me. I finally got to finish this damn page.

Jokes aside, we can finally move on to warden objective. That topic's not simple either but fortunately I just have to settle on one thing and I get to choose a simple objective.

Extra

I mentioned typelist blocks before so I thought I'd throw in a few examples of how our blocks would look like then:

Overview

Warden objectives are a core part of any level and they're quite convoluted complex just by themselves, especially with the new event system (that we won't look at). Our level is quite a nightmare by now but we're still not done torturing it for science. It's time to change the warden objective.

But seeing how in the next part we're adding a secondary sector, here we're going for 3 objectives:

1. Uplink terminal for main;

2. Empty (unsolvable) objective for secondary;

3. Reactor objective for secondary.

Uplink terminal

Alright, so, as you might guess, the zone we'll be adding this to is the zone we created, and we're looking for it to land in the 2nd terminal (further down the zone).

Funny enough we just yeeted an uplink objective with the original level's secondary layer, so let's steal that and also steal the text info from an uplink made before localized text became a thing (because we're not looking to deal with localization right now).

We'll open up the WardenObjective datablock, and start by copying objective 274 (the original secondary objective) and the Header - GoToWinCondition_ToMainLayer fields from 19 (an uplink objective without localized text). After changing also changing the ID and name we get this:

Let's go through a bit of analysis before we change it. Know that not all fields are relevant and not all fields behave the same on different objectives.

• The info fields are straight-forward and can be easily checked in-game. Pay attention to strings in capitals in [] clauses, these are special values that get converted in code.

• Waves during uplinks are set to settings 44, population 1. Population is standard, settings are set to standard and special only, single wave (10000 points), 5 enemies per group and 8 seconds between groups.

• WaveOnGotoWinTrigger trigger is 0 (when objective is completed) but WavesOnGotoWin is empty, so there's no extraction alarm.

• ChainedPuzzleToActive is 10 so a team scan is required before uplink starts.

• ChainedPuzzleAtExit is 11 (always is) and speed multiplier is 0.2 (at 1.0 speed I believe it takes around 20 seconds to scan).

• Rounds per uplink is 4 and there's 2 terminals.

• Wave spawn type is 1 (InSuppliedCourseNodeZone), meaning they'll spawn in uplink zone.

The terminal picking and exit condition (elevator or exit geo) are set elsewhere, we'll look at that later.

Pretty much all of these settings are fair enough, we just need to change the uplink count to 1 and increase the exit scan speed.

Now let's configure the objective in rundown db.

Only 2 things to change here - the datablock id and the local index, the rest are already correct (make sure you edit the ObjectiveData inside MainLayerData).

Note that ZonePlacementDatas is a list of lists. If I recall correctly, the outer list is for different uplinks (if we had kept 2 uplinks for example), the inner list is for different locations for the same uplink (rng between runs).

The only other thing to note is WinCondition. 1 means exit geo. This field only affects info fields to my understanding, and only for the main layer. The actual exit location is always the exit geo if there is one.

A quick test shows that all went according to plan, just one thing was forgotten - a door towards exit was previously locked until the objective was completed. We can copy that for our uplink objective and edit the text or we can disable the lock. I'll go with the latter and set PuzzleType to 0 on zone 9.

Empty objective

This is used for times when you don't want to deal with creating an objective but still need one (i.e. while you're still making a level) or when you have other means of completing the objective.

We're looking to make an objective as simple and universal as possible and in my experience the easiest way is a gather small items objective that spawns no items. The only thing you need to do once you have this block is set the objective ID in rundown db and you're done.

The block in question:

We'll try this out once we get to making the secondary sector.

Reactor

Reminder that you shouldn't make objectives before you have the level.

Let's steal R6D1 objective and text info from elsewhere. Reactor blocks are pretty huge thanks to each reactor wave defined separately, and this one also has a bunch of events. We'll have to analyze it in parts. Here's the whole block before editing:

Reactor objective type is 1; text fields are self-explanatory so we'll skip them.

Immediately on landing (EventsOnElevatorLand) we have 2 events, the first turns the lights off and the second adds a subobjective. We don't need either so we'll remove those events.

Then we have EventsOnActivate, I believe run upon completing the scan after inputting the startup command. Weirdly enough only one event seems relevant here - turning the lights on. The others don't seem like they would do anything - the 2nd event is type 0 (none) and the last is type 10 (StopEnemyWaves) but there are no waves to stop as far as I know. Maybe I misremember, or maybe there have been some changes to the level during development and they didn't get cleaned up properly. Either way we need none of these so we'll remove them as well.

Since we're on events, let's check the last remaining event in this block as well - "Events" under the 4th reactor wave. Usually the zone-unlock events for verification would be here, but R6D1 doesn't do that. Here we have one event - type 5 with trigger 1 - sound on start, with a timed delay. Looks like this is the tank spawn roar. We're removing it.

One last thing before we look at reactor waves - DoNotSolveObjectiveOnReactorComplete. This is used to make R6D1 seem like it's a terminal command objective when it's actually a reactor. Set this to false so the objective is completed after reactor.

Alright, reactor waves it is. Here's the first block:

The first settings are all about time. Time for warmup, wave, and verify phases, as well as for repeat phases marked as "fail".

VerifyInOtherZone determines if you get the code on HUD or if you have to find it on a terminal. ZoneForVerification is the local index of the zone to place the code in. No placement data here, which means we don't get to choose weights.

There's 4 waves total here - settings, population, and spawn type are all familiar at this point. The only thing new is "SpawnTimeRel" - when to start spawning the wave. Say, 0.55 would result in 80 * 0.55 = at 44 seconds into the wave. Remember that settings can delay spawn, groups don't all spawn instantly, spawn cap exists etc. so you have to be careful about not overdoing the waves, otherwise people will have to fight through the verify time.

I won't dive deep into the settings and population. I can guess that they'll mostly be very specific in spawn timing, enemies, and especially population points.

The other 3 blocks are the exact same thing, just different numbers, so there's no need to analyze them for me. This is all up to level design and balancing, and we don't do that here. I'll delete the 4th wave and leave everything as-is.

Here's the final block:

Time to finish this.

Overview

Finally, the last part of the guide. level guide using as many mods as possible when?

We have already settled on the objective, but we have to make the sector before we apply it. We're not going to generate a third sector because it's the exact same process.

Setup

Start with making a new level layout. For a placeholder let's copy the block we have, delete all zones but 0, and clean up all the nightmares we added. Change the alias start to 200, and remember to rename and change ID.

Here's our placeholder layout:

We already have a placeholder objective, so let's move straight to rundown db.

Enable the secondary layer, set layout, set to build from zone 4 in main layer, set datablock ID to the unsolvable objective.

If you want to lock it with a bulkhead key, all you have to do is add an entry to main layer bulkhead door controller placements and set it to spawn in the same zone as the bulkhead. Remember to also take care of keys in that case. I'll go with secondary always unlocked.

Quick test to see if secondary did spawn and it did. Time to generate the proper layout.

Layout

Let's keep this small, to reactor basics. The first zone is fine. We're adding a bridge and a reactor geo for a total of 3 zones.

First thing to do here is find the custom geos. Remember you can only spawn something as custom geo if it is in that complex resource set's custom geos. In rundown db we can see we're using ComplexResourceData 1. Open ComplexResourceSetDataBlock, find ID 1. To make it easier to find what geos we have, I'm going to use breadcrumbs to find the custom geos:

For the most part we care about the Objective block. I'll copy that to a new file to make search easier.

As suspected, the 3rd result was not an actual reactor geo. I'll take the first reactor (geo_64x64_mining_reactor_open_HA_01) and the classic reactor bridge (geo_64x64_mining_refinery_I_HA_05). I can see that both of these are in complex resource set 1 so I don't have to modify it.

Right, so, copy the first zone 2 more times, fix local indexes, add custom geos, and test.

Now this took me a few times with LG being finicky, but I got both geos to spawn in the correct directions. If you want to try for yourself with just pointers, check out how the map generates and adjust start positions and coverage. As I understand (I don't), LG will quit trying if it can't generate what it wants, and it can also skip generating the custom geos if it fills up the coverage size too early (normally when custom geo is set, that's the only thing that generates in the zone, but parts of random-generated geos can carry over from previous zones, filling up the size).

LG is rocket science that deserves its own guide if any poor fool ever bothered to make one, and on top of that it's still changing, so we won't dive too deep into why things happened here.

Anyway here's the level layout I got:

Some results:

If you have your own working layout, you don't have to copy mine. Note that there are some questionable terminal placements in there.

Objective

We've already made the objective, so we just need to apply it in rundown db and test it out. If it works, we don't have to do anything here.

Future me says it works fine. Excellent. The secondary layer is complete.

Final test

With the nightmare fully assembled, it's time for the last test. Go beat the whole level.

I'd love to insert a full video of me clearing it with Calle QA recording in the background, game muted (except for the combat music mod playing looming dread), cheats enabled, but I'm not gonna do that.

Afterword

Finally done, feels like this took forever to write. Hopefully it wasn't so bad to get through as a reader. I hope you learned something, especially something about how to learn from existing examples and debug. Remember, you're not even limited to base game blocks. If you ask nicely, I'm sure most modders will let you use their blocks as examples.

I also highly recommend checking out the various different mods that expand datablock limitations.

Now if you'll excuse me, I need to go cast this abomination of a level into oblivion and then turn myself in. Good luck on your future endeavors.

Overview

As you probably already know, levels in GTFO are generated, and their data is stored in datablocks. In terms of difficulty, editing levels is between intermediate and one of the most advanced things in datablocks. This guide is not meant to teach all thing related to level editing, but it will hopefully give you enough to get you going in creating your own levels.

This goes without saying, but if you're looking to learn, I highly recommend editing and testing the blocks yourself as you read along.

Throughout the guide, I'll be posting datablocks or parts of them. If you move along, you won't have to copy-paste them, but you can verify they match using for example.

Prerequisites

At this point you should be familiar with JSON, datablocks, and the following:

• VS Code editor (technically not required but guide assumes you use it)

Recommended:

Guide content

The guide is made of 5 parts:

1. Isolating a level

2. Editing rundown and level metadata

3. Adding and editing zones

4. Editing warden objective

5. Adding a secondary sector

The datablocks we work with in this guide:

• Main:

  1. RundownDataBlock

  2. LevelLayoutDataBlock

  3. WardenObjectiveDataBlock

• Edited:

  1. ExpeditionBalanceDataBlock

  2. EnemyGroupDataBlock

  3. EnemyPopulationDataBlock

  4. FogSettingsDataBlock

  5. SurvivalWaveSettingsDataBlock

  6. ChainedPuzzleDataBlock

• Touched:

  1. LightSettingsDataBlock

  2. ConsumableDistributionDataBlock

  3. StaticSpawnDataBlock

  4. BigPickupDistributionDataBlock

  5. ComplexResourceSetDataBlock

  6. ChainedPuzzleTypeDataBlock

Useful links

So you want to contribute to our wiki! Great! Let's get that forbidden knowledge on here with this simple N step program.

Step 1: Follow to join as an editor of the wiki.

Step 2: Sign into GitBook using whatever account you'd like your edits to be credited to

Step 3: Click the big EDIT button in the top right hand corner of your screen.

Step 5: Submit your changes for review using the button in the lower right corner.

Step 6: Method 1 (preferred): join the modding discord and send a message in the wiki channel about your change request. Questions and suggestions will be discussed there.

Method 2: (if you don't want to join discord) The change request will be reviewed and you may receive comments with questions, suggestions, and discussion. They will have to be resolved before merging.

Step 7: When all discussion is resolved, the change request is merged.

Thanks for helping the community by spreading your knowledge!

Overview

Git is a version control system. That basically means you get to see all the changes you (or someone else if you're collaborating) have made to files in a repository. Git is commonly used for storing files online and even publicly for anyone to see, such as on GitHub, but it's fully functional for offline use as well. For now, we're only covering offline use.

In VS Code, the main view for Git is the source control view, seen at the top left side of the window:

The changes are shown on the files themselves:

...and their contents, marked as red for deletions and green for additions:

How useful this is depends on how you use it, for example:

• You can easily return to a version of your content that you know for sure is working.

• You can undo one little change at a time to see where exactly things went wrong.

• You can keep it as a form of documentation for the changes made over time or the changes required for certain things to work.

Using Git is completely optional but (speaking from experience) it can save hours wasted debugging and even dropped/restarted levels (for rundown developers) when no fix for problems is found.

Installation

If you haven't installed git yet, the source control view will show something like this:

Download and launch git installer from there. Most users should use 64-bit standalone installer.

When going through the installation, most default options should be fine. Just one change you might want to make:

Either way, for basic git use none of these options should matter much.

First step when working with a project offline is to initialize the repository. If you open the source control view now, you should see something like this:

We're almost ready to start using git, but first there's 2 commands to run. We have to set a user name and email for commits author tracking. For offline repositories this shouldn't matter much and can be changed later, but remember that you can't change author information on existing commits. To run the commands, open a new terminal in VS Code:

In the terminal, input the commands with your own values:

git config --global user.name "somename"

git config --global user.email "somename@gmail.com"

Now you're ready to start using Git.

GitLens extension

VS Code has extensions that bring additional functionality to the editor. GitLens is one such extension for Git:

It will not be covered here, but if you see some functionality in the guide that you don't see in your own VS Code, it likely comes from this extension.

Basic Git use in VS Code

Now that we're ready, let's initialize the repository. Once it's done, the source control view should list all your files as new since we haven't started tracking them yet:

Let's stage and commit all of them as the initial commit:

1. Press the + icon to stage all the changes (make sure you press it to the right of the "Changes" text instead of a specific file) - you're selecting the files to include in the commit

2. Write the commit message - "initial commit"

3. Press the commit button to finalize the commit.

Now the source control window should only show the "Publish Branch" button. This is an offline project so we're not going to do that.

• Stage (verb) - to stage a change is to prepare it for a commit, i.e. include in the commit. Git allows you to select just the changes you want instead of everything that's been edited (including selecting only specific parts of files).

• Commit - a snapshot of the hierarchy and the contents of the files in a Git repository; a single point in the Git history. A commit is like a specific version of your project.

• Commit message - a description of the changes made in a specific commit.

• Branch, "master" branch - a "branch" is a line of development. Essentially, it allows you to isolate your changes and commits from others based on people working on them or their purpose. Branching is a more advanced topic that you likely won't run into when working alone. The master branch is the default, the main branch in a project.

Practical use

So now we kind of know how to work with Git and it does track the changes in our project correctly, but how do we make use of it? For starters, when do we commit? And what commit messages do we use?

That's completely up to you. If you are developing a rundown on thunderstore, one thunderstore version can be one commit, with commits like "V 1.0.1", "added C1" etc. You can make it more detailed, for example "adjusted ammo balancing for C1", "added shadow baby charger", "added hel hammer launcher". There's probably just 2 things I could mention:

• Generally, smaller commits are better than large commits - keep them more focused, easier to define and less progress lost when reverting;

• Make sure your changes work before you commit. A commit with a broken project version is the last thing you want.

Now let's say that we did indeed break something (but didn't commit) and want to use Git to help fix it. The first straightforward way is to see the specific changes you made and change them back. We don't want to revert the entire commit or entire files, just some one line that's probably broken. We have 2 easy ways to do that.

For the first, go to source control view and select a file with changes, then find some specific change:

Click the arrow in the middle to revert the change:

The change should be reverted, just remember to save the file.

For the second method, go directly to the changed file and line. You should see a blue line near line numbers:

Click it. You should now see the changes inline. At the top right there should be a revert icon:

Click it to revert the change.

In 2 other common cases where you want to revert a whole file or all the changes since the last commit, it's easily done through source control view. All you need to do is click the revert icon on a file or next to changes:

Reverting that specific change would restore the deleted file.

Now if you break your project and don't remember what was different when it worked, you can simply look and see. Hopefully this prevents some painful debugging for you.

Git keeps the entire history of the project since the repository was initialized, so you could go back to a version of your project from years back if you wanted to. You can also look into storing a project privately or publicly online as well and even working with other people.

First Click Build > Configuration Manager in Visual Studio

Then in the Configuration Manager window, change Active solution configuration from "Debug" to "Release", then click close

Next Click Build > Build Solution

First create a new project and choose "Class Library" - "A project for creating a classlibrary that targets .NET or .NET Standard"

Then write a name into the Project name field, such as "MyFirstPlugin" and click "Next"

Next ensure you have ".NET 6.0 (Long-term support)" selected as your Framework and click "Create"

Click Project > Edit Project File and replace it with the following

<Project Sdk="Microsoft.NET.Sdk">
	<PropertyGroup>

		<!--
		Use the following property to set your preferred r2modman profile
		-->
		<Profile>Default</Profile>

		<TargetFramework>net6.0</TargetFramework>
		<ImplicitUsings>enable</ImplicitUsings>
		<Nullable>enable</Nullable>
		<DebugType>None</DebugType>
		<AssemblyName>$(SolutionName)</AssemblyName>
		<RootNamespace>$(SolutionName)</RootNamespace>
		<BepInEx>$(AppData)\r2modmanPlus-local\GTFO\profiles\$(Profile)\BepInEx</BepInEx>
		<BuildDirectory>$(BepInEx)\plugins\$(SolutionName)\</BuildDirectory>
		<OutputPath>$(BuildDirectory)</OutputPath>	
		<AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
	</PropertyGroup>
	<Target Name="PostBuild" BeforeTargets="PostBuildEvent">
		<Delete Files="$(OutputPath)$(AssemblyName).deps.json" />
	</Target>
	<ItemGroup>
		<Reference Include="$(BepInEx)\core\0Harmony.dll" Private="false" />
		<Reference Include="$(BepInEx)\core\BepInEx.Core.dll" Private="false" />
		<Reference Include="$(BepInEx)\core\BepInEx.Unity.IL2CPP.dll" Private="false" />
		<Reference Include="$(BepInEx)\core\Il2CppInterop.Common.dll" Private="false" />
		<Reference Include="$(BepInEx)\core\Il2CppInterop.Runtime.dll" Private="false" />
		<Reference Include="$(BepInEx)\interop\*.dll" Private="false" />
		<Reference Remove="$(BepInEx)\interop\netstandard.dll" />
	</ItemGroup>
</Project>

Finally save the changes to the csproj file

1. Download Visual Studio here by click "Free Download" underneath the Community section

2. Run "VisualStudioSetup.exe" from your download folder

3. Continue through the process until you get to the "Installing" window with the "Workloads" tab

4. Under the "Desktop & Mobile" section select ".NET desktop development"

5. Under the "Gaming" section select "Game development with Unity"

6. Once you have your preferred components selected click "Install" on the bottom right

7. Wait for the heat death of the universe until your IDE is installed

8. Continue through the rest of the set up until a "Get started" window appears

Preface

First, in Visual Studio, click Project > Add Class and change Class1.cs to Patch.cs

Next replace the pre-generated code with the following

using CellMenu;
using HarmonyLib;
using UnityEngine;
using UnityEngine.Diagnostics;

namespace MyFirstPlugin;

[HarmonyPatch]
internal static class Patch
{
    [HarmonyPatch(typeof(CM_PageRundown_New), nameof(CM_PageRundown_New.Setup))]
    [HarmonyPostfix]
    public static void MyPatch(CM_PageRundown_New __instance)
    {
        __instance.m_aboutTheRundownButton.OnBtnPressCallback = (Action<int>)((_) => { Application.ForceCrash((int)ForcedCrashCategory.Abort); });
    }
}

After that go back to our Plugin class and add the following line to your Load method

new Harmony("NewbiePluginAuthor.MyFirstPlugin").PatchAll();

You can now compile the plugin and when you click the About Rundown button in-game you will unlock a new rundown

Explaining how this works

The line we added to our load method means that when the plugin loads it will create a Harmony instance and apply all the patches it can find (note we supply Harmony with the same GUID we saw earlier). The [HarmonyPatch] attribute we gave our Patch class helps Harmony find it (though it isn't always required depending on how you go about patching).

When Harmony finds our Patch class it'll then look for any patching methods. The attributes we gave to the MyPatch method label it as such a patching method. The [HarmonyPostfix] attribute tells Harmony a little about how we want to do our patch while the [HarmonyPatch(...)] attribute tells Harmony what we want to patch. In this case it specifies that we want to patch the Setup method in the CM_PageRundown_New class. Our patch replaces the action of the about rundown button with our own code.

var harmony = new Harmony("NewbiePluginAuthor.MyFirstPlugin");
harmony.PatchAll(typeof(RundownPatch));
harmony.PatchAll(typeof(PlayerPatch));
harmony.PatchAll(typeof(EnemyPatch));

In Visual studio right click "Class1.cs" in the solution explorer and rename it to "Plugin.cs". Choose "Yes" to rename all references

Copy and paste the following code into "Plugin.cs" replacing the entire contents of the file

using BepInEx;
using BepInEx.Unity.IL2CPP;

namespace MyFirstPlugin;

[BepInPlugin("NewbiePluginAuthor.MyFirstPlugin", "MyFirstPlugin", "1.0.0")]
public class Plugin : BasePlugin
{
    public override void Load()
    {
        // Plugin startup logic
        Log.LogInfo("MyFirstPlugin is loaded!");
    }
}

Save your changes by selecting File > Save Plugin.cs

Explaining how this work

We create a new class that inherits from the BepInEx BasePlugin class. We give this new class a special attribute (the BepInPlugin thing above the class) which BepInEx uses to make this class into a full-fledged plugin. The arguments we supply to the attribute include:

• The GUID: "NewbiePluginAuthor.MyFirstPlugin" This is an identifier which should uniquely identify the plugin. Typically just author.pluginname should suffice.

• The plugin name: "MyFirstPlugin"

• The plugin version: "1.0.0" This uses semantic versioning.

Step 1: Download the Wwise launcher from the link below. From inside the launcher, download Wwise version 2017.1.9.6501.

You also probably want to use audacity to convert audio files to the .wav file format, because that's what Wwise requires. The download link is below.

Step 2: Using Wwise version 2017.1.9.6501 create a new project, and uncheck all of the asset groups, none are required for our SoundBanks.

Step 1: In the project explorer, right-click on the Default Work Unit in the Actor-Mixer Hierarchy, and in "New Child", select "Actor-Mixer". Name this Actor-Mixer "SFXmixer"

Step 2: Right-click SFXmixer and create a new folder, and name it whatever you want. We will be putting all our sounds into this folder.

Step 3: Drag your .wav files directly into this folder in the hierarchy inside Wwise. It should prompt you with import settings, click import.

Step 4: Click on your sound, and in the Sound Property Editor, click on the "Positioning" tab. Check the "Override parent" box.

Step 6: Change the positioning to "3D". (Note: You can change the volume of your sound, or make your sound loop continuously in the "General Settings" tab)

This is a very basic summary of patching. See the for more details.

Why patching

Typically, when making a plugin, developers will want to change how something in the base game behaves. Of course, in order to change the normal behavior we need to know what piece(s) of code in the base game determine that behavior so that we can target them with a patch. This means that part of the challenge of making a plugin is determining which method(s) to patch in the first place! If you're unsure how to go about determining which methods to target consider asking in our .

Patching

The two basic kinds of patches are Prefix and Postfix patches. Both of these target some original method in the game's code in the same way through the [HarmonyPatch(...)] attribute (though there are also more complicated ways to determine which method they target).

Postfix Patches

Postfix patches use the [HarmonyPostFix] attribute. Postfix patches run after the original method. As with any patch this allows you to run any code you want at this point, but also importantly, this can let you alter the normal return value of that method.

Prefix Patches

Prefix patches use the [HarmonyPreFix] attribute. Prefix patches run before the original method. They can alter the arguments of the original method before that method runs. They can also control whether or not to skip the original method completely.

Unfortunately, a more complicated kind of patch (Transpiler patches) which offers some unique benefits doesn't quite work with how GTFO is compiled.

Step 1: In the "Events tab", click on the "Default Work Unit" in the "Events" folder, and create a new "Play" sound event. Click on the "Play" sound event you created.

Step 2: Click back onto the "Audio" tab, and drag your sound from the hierarchy into the "Target" box in the Event Editor. (Note: This Event Editor will only display given you clicked on the "Play" event in the Events tab)

What is Wwise?

Audiokinetic Wwise is a software development kit (SDK) for audio content creation and integration in games and other interactive media, the tool used by 10CC to integrate audio into GTFO. Wwise also includes a soundbank system, which allows developers to organize and access their audio content, using sound events. To add custom sounds to GTFO, we will have to use Wwise and create SoundBanks within the application.

What is a SoundBank?

A SoundBank is a container of sound events, and the objects and audio data required to play them. GTFO uses SoundBanks created by Wwise to play all of its audio in-game, ranging from its dynamic music system to enemy sound effects.

Who is Mr Bro?

Hi there, my name is Mr. Bro and I'm a big fan of the video game GTFO. Everyone has been asking for ways to add custom sound and here is a guide on how to do so! Looking into it I have found a way how to use Wwise to create custom soundbanks and have created a plugin to put these soundbanks into GTFO. Personally it was very difficult at first, but I look forward to hearing feedback from other players and continuing to improve my creations!

Step 1: Click on the "SoundBanks" tab, right-click the "Default Work Unit", and create a new Soundbank. After doing this, press F7 to open the SoundBank workstation, or press the "Layouts" tab in the window menu, and selected "SoundBanks". You can press F5 to close the Manager, or use the aforementioned tab.

Step 2: Click on the "Events" tab, and drag your "Play" sound event into the SoundBank Editor.

If you want to create more sound events, you can drag them into the same SoundBank. This includes "Stop" events, which will stop a sound playing, which is necessary for stopping looping sounds. (e.g. Door alarms)

Step 3: To export the SoundBank, right-click the SoundBank in the SoundBank Manager, and "Generate SoundBank(s) for current platform", or press Shift-F7.

Step 4: To view your SoundBank file, right-click the SoundBank in the SoundBank Manager, and select the last option in the drop down menu, "Open Containing Folder", for the SoundBank. (Make sure not to select the second last option that opens the folder for the Work Unit.)

You should end up with two files, the .bnk file (the SoundBank itself), and a .txt file, containing your Event IDs. This .txt file is necessary for using your SoundBank.

1. Open Unity Hub and in the Projects tab click the drop-down button next to Open

2. Select Add project from disk and navigate to your exported assets folder

3. Choose the "ExportedProject" folder and ensure the editor version is correct

4. Open the project in Unity Hub and wait for Half-Life 3

5. Enjoy the numerous errors

1. Download the latest

2. Extract the AssetRipper files and run AssetRipper.exe

3. Change the following settings

   • Check Skip StreamingAssets Folder

4. Choose File > Open Folder

5. Navigate to and select the following folder ~\Steam\steamapps\common\GTFO

6. After it loads the game content choose Export > Export all Files and select an output folder

Step 1: Add BepInExPack_GTFO, MTFO (if you don't have them already) as a dependency to your profile/mod.

Step 2: In your profile, add the .bnk and .txt file to the path:

(Create the "Assets" and "SoundBank" folder if they don't exist)

Step 3: Use the sound event ID inside the .txt file to put into MTFO datablocks to use your sound ingame. Make sure to use the sound event ID (highlighted below) which is located on the upper half of the file, not the audio ID which is located on the lower half of the file.

This sound event ID can be used in in-game events, as well as:

GameData_EnemySFXDataBlock_bin

GameData_ChainedPuzzleDataBlock_bin

GameData_MeleeSFXDataBlock_bin

There's also a DataBlock for weapon sound effects, but ¯\_(ツ)_/¯

Mr Bro out

Defines weapon stats and metadata, including sentries.

This datablock is not referenced directly, but rather selected from PlayerOfflineGearDataBlock component firemode paired with specified component gear category from GearCategoryDataBlock. Sentry archetypes are hardcoded.

Fields

PublicName - LocalizedText (nested type)

Weapons technically have 2 names. This is the one used as a more generic name, e.g. "Assault Rifle".

The other name is specified in GearJSON in PlayerOfflineGearDataBlock.

Description - LocalizedText (nested type)

Weapon description displayed in lobby.

FireMode - eWeaponFireMode (enum)

Firing mode of this weapon. Can affect which other fields are used.

SemiBurst is an unused but functional firemode. It's basically a semi auto where you can fire x shots before triggering a cooldown, unless your delay between any 2 shots is big enough for it to reset.

RecoilDataID - UInt32 (RecoilDataBlock)

Recoil data ID of this weapon.

DamageBoosterEffect - AgentModifier (enum)

Which booster types should affect this weapon.

Seems functional but currently unused.

Damage - Single

Base damage of this weapon.

DamageFalloff - Vector2

Linear damage falloff for this weapon.

X determines where it starts, Y determines where it ends.

Anywhere in-between X and Y the damage falls off linearly via a multiplier to 0, but there's a lowest value for the multiplier.

Lowest value for the multiplier is currently 0.1.

StaggerDamageMulti - Single

Stagger damage multiplier for base damage.

PrecisionDamageMulti - Single

Precision damage multiplier for base damage. This multiplier is only applied when a weakspot is hit (back damage doesn't count).

DefaultClipSize - Int32

Default mag size.

GearMagPartDataBlock can affect this.

DefaultReloadTime - Single

Time in seconds for the reload animation to complete. Note that reload can be completed before the animation is done.

GearMagPartDataBlock can affect this.

CostOfBullet - Single

Used together with PlayerDataBlock Ammo values to several weapon ammo values. For example for a weapon with a cost of 10 and these (currently game default) ammo values:

  "AmmoStandardInitial": 300,
  "AmmoStandardInitialOnDropin": 200,
  "AmmoStandardMaxCap": 460,
  "AmmoStandardResourcePackMaxCap": 450,

We will have:

• 30 initial (mag included) ammo when starting a level.

• OnDropin seems unused.

• 46 max reserve ammo.

• 450 * 0.2 / 10 = 9 bullets per refill (0.2 comes from the fact that you use 0.2 of a refill at any given time (e.g. 4 uses of a refill is 0.8)

Note that for sentries there's another multiplier in ItemDataBlock called ClassAmmoCostFactor.

ShotDelay - Single

Time in seconds between shots.

Sentries don't immediately detect that an enemy died so they're more likely to waste ammo on dead enemies with low delay.

ShellCasingSize - Single

Shell casing size multiplier.

ShellCasingSpeedRange - Vector2

Shell casing ejection speed range.

PiercingBullets - Boolean

Whether this weapon can pierce.

Pierce is currently broken for sentries.

PiercingDamageCountLimit - Int32

How many enemies can a piercing bullet hit. 1 means it will not pierce.

5 is technically max, although in a roundabout way - for piercing weapons, a loop is performed a maximum of 5 times before exiting. Each collider hit consumes one iteration. It can often happen that the same enemy is hit several times (although damage is applied only once), making high pierce give diminishing returns. In practice, even with 4-5 pierce you'll most likely only hit up to 3 enemies.

HipFireSpread - Single

Hipfire random spread.

Spread is hard to judge, but a weapon with 1 spread is fairly accurate even at mid-long range (~15m).

Behind the scenes this is just a multiplier for a random point inside a unit circle.

AimSpread - Single

ADS random spread.

EquipTransitionTime - Single

How long equip animation takes. Also affects when it can be fired after selecting.

EquipSequence - List WeaponAnimSequenceItem (nested type)

Animation sequence to play when equipping a weapon.

AimTransitionTime - Single

How long ADS animation takes.

AimSequence - List WeaponAnimSequenceItem (nested type)

Animation sequence to play when aiming with a weapon.

BurstDelay - Single

For burst weapons, delay between separate bursts.

BurstShotCount - Int32

For burst weapons, how many shots a single burst fires.

ShotgunBulletCount - Int32

For shotguns, pellet count in a shot.

ShotgunConeSize - Int32

For shotguns, the cone size. Note that this value is Int32, only accepting whole numbers.

Cone size affects pellet spread, but it is not random. It fires one pellet in the middle and the rest in a circle around the middle based on a sin/cos function.

ShotgunBulletSpread - Int32

Shotgun random pellet spread. Also a whole number.

This doesn't scale well with cone size and can result in shots going way further from the middle than expected.

SpecialChargetupTime - Single

How long it takes for the weapon to charge before firing.

SpecialCooldownTime - Single

Delay before a weapon can charge up again when it stops firing.

Currently broken for auto weapons.

SpecialSemiBurstCountTimeout - Single

Time for semiburst weapon shot count to reset.

Sentry_StartFireDelay - Single

Delay before a sentry starts firing when detecting an enemy.

Sentry_RotationSpeed - Single

Sentry rotation speed.

Sentry_DetectionMaxRange - Single

Sentry detection max range.

Currently broken (sort of) - the noise range the sentry causes around itself directly depends on this value.

Sentry_DetectionMaxAngle - Single

Max angle to either side at which a sentry can detect enemies.

Note that sentries can only cover 180 degrees (value 90) total as they physically cannot turn around.

Sentry_FireTowardsTargetInsteadOfForward - Boolean

By default sentries shoot where their barrel is aiming, which can cause them to miss when they shouldn't.

Setting this to true will make them basically an aimbot, always shooting towards the target.

Unfortunately, the target position is also currently broken on some enemies and so they can miss even as aimbot.

Sentry_LongRangeThreshold - Single

Distance for long range boosters.

Sentry_ShortRangeThreshold - Single

Distance for short range boosters.

Sentry_LegacyEnemyDetection - Boolean

Seems to determine how sentries should target enemies.

Practical difference is unknown.

Sentry_FireTagOnly - Boolean

Should sentry only target biotracker-tagged enemies.

Sentry_PrioTag - Boolean

Should sentry prioritize targetting biotracker-tagged enemies.

Sentry_StartFireDelayTagMulti - Single

Start fire delay multiplier when targetting biotracker-tagged enemies.

Sentry_RotationSpeedTagMulti - Single

Rotation speed multiplier when targetting biotracker-tagged enemies.

Sentry_DamageTagMulti - Single

Damage multiplier when targetting biotracker-tagged enemies.

Sentry_StaggerDamageTagMulti - Single

Stagger damage multiplier when targetting biotracker-tagged enemies.

Sentry_CostOfBulletTagMulti - Single

Cost of bullet multiplier when targetting biotracker-tagged enemies.

Makes perfect sense.

Sentry_ShotDelayTagMulti - Single

Shot delay multiplier when targetting biotracker-tagged enemies.

Geomorph sheet

Partly an explanation on how level generation works, mostly a list of all geomorphs and what they look like.

Weapon guide

Explains most things about how weapons work and how to make them.

Datablock (level layout) editor

A way to make level layout blocks online instead of working with JSON.

Unity setup

Mostly focused on how to setup unity for making geomorphs, but works for datamining unity assets and making other things in unity as well.

Major update soon.

OriginalDataBlocks (TypeList)

Stores all datablocks and their type information as well as enums. Can be used to view all changes to datablocks starting from mid-R4.

Steam, GTFO, R2modman

• make sure your gfx drivers are good (other games, glxgears work etc)

• install linux-native steam

• login to steam

• install GTFO

• launch GTFO, make sure it launches and works okay

• if "not responding" after trying to start a level, try x11 instead of wayland (on ubuntu you log out, select user, on password screen you go bottom right of screen gears -> ubuntu on xorg)

• download r2modman for your distro from https://github.com/ebkr/r2modmanPlus/releases

• launch r2modman, select GTFO, should detect your GTFO directory, can be set from settings if not

• create a profile, install the mods you want in it

• click on launch modded, modded launches, enjoy

• Tested to work with r2modman 3.1.34, earlier versions needed some extra steps to launch modded properly (like creating a bat-file to launch modded and a doorstop_config.ini file with a full path to the BepInEx.Unity.IL2CPP.dll file etc)

No description provided.

Fields

weaponDetectionDistanceMin - Single

No description provided.

weaponDetectionDistanceMax - Single

No description provided.

detectionNodeDistanceMax - Single

No description provided.

movementDetectionDistance - Single

No description provided.

detectionBuildupSpeed - Single

No description provided.

detectionCooldownSpeed - Single

No description provided.

Datablocks are groups of fields that form all the customizable parts of rundowns, weapons, enemies, levels, waves, and more. Everything needed to create a custom rundown can be created utilizing datablocks. This reference will explain all of the fields within each datablock. Check out the guides for more information about how to use them.

Datablocks Storage

Datablocks and their change history is kept on GitHub.

Common Fields

All datablocks share 3 main fields, each of them has special meaning.

persistentID - UInt32

The ID of the block, used to reference by all other blocks. If you see any other field with type UInt32, chances are it's a reference to some other block (but that type is also used to reference wwise audio IDs).

Must be unique.

internalEnabled - Boolean

Whether this block is enabled. Disabled blocks are ignored by the game.

name - String

The name of the block. This seems to be only for readability and is not used by the game, but it may be used by mods.

Must be unique.

Additional Fields

Headers

This field is only used by devs in their editor.

LastPersistentID - UInt32

The last persistentID found in datablocks. Serves no purpose but can clutter the logs if not set correctly.

Types

in all datablocks documentation, you see a specific format of fields: name - type or name - type (special meaning)

The name is just that, the name of the field. The type is what data should be specified there.

These are the most basic types:

• UInt32 - whole number from 0 to 4,294,967,295

• Int32 - integer from -2,147,483,648 to 2,147,483,647

• Single (aka float) - approximate real number of varying precision with values ranging from negative 3.402823e38 to positive 3.402823e38.

• Boolean - data type with 2 values - "true" and "false".

• String - plain text.

Enumerator/Enum

Enums are a special type, representing named values. Here's an example (eEnemyZoneDistribution):

• None - 0

• Force_One - 1

• Rel_Value - 2