How to YAML: Tweak modding basics
This is a tutorial created with new modders in mind. Some terms may not be correct, but you will be able to create a functional tweak with this method. It's not optimal; it's slow, tedious, and redundant. However, it was the only way I could understand how to make YAML tweaks.
Take into consideration that I'm not an expert, but I've helped a lot of people to start on tweaks and this knowledge will allow you to, at least, navigate more easily at first.
For this tutorial, you need:
Visual Studio Code (or Notepad++, but the tutorial will show you VSCode)
A bookmark for YAMLlint (you can check your YAML files for indentation errors)
Patience, lots of patience. Please, read this guide completely and re-read if needed.
After downloading and installing all the requirements (and yes, SAVE that bookmark, trust me), let's start with the basics.
Understanding YAML Tweaks
YAML tweaks are like a decompiled version of the .tweaks files that you can find inside the REDmod folder. YAML format is easier to read and understand, but have some differences with REDmod syntax. You can also try and make tweaks using the REDmod syntax inside TweakXL, but personally I have no experience with that yet.
There are some concepts you need to understand before starting:
Indentation
Indentation organizes code using blank spaces, as shown below:
In the past, using indentation wasn't mandatory and mostly used by pro coders to order their files as a good practice. However, for YAML files, indentation is MANDATORY. If you indent wrong, your mod won't work, simple as.
The best way to indent, in my opinion, is using 2 blank spaces (pressing space bar twice) to make indentations.
"But what about just using tab?" you may think. DON'T. DON'T USE TAB FOR INDENTATION. Using tab for indentation could cause issues, because not all text editors interpret tab in the same way.
Using double space will guarantee your file will keep the same structure everywhere. It even feels natural and VSCode will put nice and useful lines to show your indentation.
Records
Think of records as unique containers grouping multiple properties — which can be other records, or Flats.
Record names must be unique!
You can't create two records with the same name — they will overwrite each other!
You can learn more on psiberx's github readme, or head over to Types of tweak records
Flats
Flats are values. They can be numbers (integers <like 1 or 2> or floats <like 1.5 or 2.3>), characters (even entire words) or boolean (True or False). They can be more complex things, for that I suggest you to read what Psiberx has to say about this.
Inlines
This is where most new modders make mistakes.
Inline is a way to create records without nesting them under a record name, but coded and nested directly in the property of another record. Yeah, I know, it's hard to understand. Let's do some examples.
This example is a named record with other named records nested on it:
This is the same as above but with inline coding:
When to use inlines or whole named records? That depends on your project. Sometimes creating a record with a UNIQUE name will save you more space and work than creating it on inlines every single time. Sometimes it's the other way around. It's ok to even not using inlines at all if you aren't comfortable with them.
Later in this tutorial, you'll see that some records are named to something like this RecordName_inline0, RecordName_inline1, etc. Those inlineX names are created automatically for easier reading and the number can change without ANY warning on every single game update. The number generated will be dependent on the position of the inline record inside another record. Inline means literally "this is IN LINE X".
NEVER useinlineX records as base in your items, that will only create headaches for the future you. Using inlineX records as base for your items is a BAD PRACTICE and could prevent your mod from working on ANY update.
Please, DON'T USE inlineX RECORDS AS BASE FOR YOUR OWN RECORDS.
Let me explain it better with more examples:
In this example, this a record using inlines in update 2.1
In this example, is the same record, but on update 2.2
In this example, MyBigRecord_inline0 will have a completely different value depending on the update.
In update 2.1 the value1 and related to BaseStats.ExampleBaseStat1, but then in update 2.2 the value will be 8 and related to BaseStats.ExampleBaseStat3.
If you used MyBigRecord_inline0 in your item code, your item would stop working as intended. It doesn't matter that popular modders do this, DON'T USE INLINES AS BASE FOR YOUR RECORDS.
Check psiberx's YAML bible about inline records.
Prereqs
You'll see this word a lot inside TweakDB. Prereqs means Prerequisites and, as the name states, is used to check that certain conditions are met to start, for example, something like an Effector.
Effector
Those are records that are used to be activated under certain conditions depending on their Prereqs. So Effector means "Something that activates some Effect". That effect could be almost anything, from stats to visual effects.
TweakDB
Tweaks and Scripts are 2 sides of the same coin.
On its own, a tweak does nothing — the engine makes use of the records via scripts.
Think of a script as the instruction, and a tweak as the definition. That way, a script doesn't actually need to understand what it's doing, and all the logic is neatly encapsulated.
For example: Take 500g (the instruction) of Items.Flour (the definition).
In this tutorial we will use Wolvenkit Tweak Browser. There are many ways of Browsing the tweak database, but you can save them for later, when you are more advanced (or feeling bold).
How to make a research for your YAML Tweak mod
Having clarified some very basic concepts, let's start this guide:
1: Find the thing you want to do
Let's say you want to do a new item that have the Thrusters mechanics from Rogue Boots that you use in certain endings.
What's the best approach to this? Using those Thrusters boots logic in your item.
Unfortunately, most items don't share the same internal name as the name you can see in the description. The best way I've found to deal with this, is going to the community Cyberpunk wiki and looking for your specific item, in this case, those cool Boots.
Internally, that item is called q115_thrusters. Now that we know that, we can search the item in Wolvenkit Tweak Broswer.
Read Spawn Codes (BaseIDs/Hashes) for how to find an item's unique ID.
2: Using Wolvenkit Tweak Browser
Open the Tweak Browser tab and pin it. It should look like this:
Paste q115_thrusters into the search bar and click on Filter... and activate Show inline records. This should look like this:
Do a right click into the first item and select Add TweakXL Override. Do the same for the inline0 and inline1, but ignore the rogue and weyland versions, we don't need that, just the first 3 results shown in this image:
Those tweaks should be stored in the left panel inside these folders in the image:
Put the cursor above the YAML files and click on the yellow folder to open the folder containing those tweaks in Windows Explorer:
3: Working with the YAML files
Open the 3 YAML files in VSCode:
Now, from the latest inline (inline1 in this example), copy the whole contents and paste it below the anterior record (in this case, inline0):
Now, copy the mixed contents and paste them into the base record (the item on this case). This is how it should look:
Those records below the main item record (inline0 and inline1) are the ones that manages the Thrusters logic/mechanics.
You can add them to almost any item, but you'll have to research on your own how to do it on each case. Not all items needs the effects nested in the same places, and not all effects needs to be nested like this.
ALWAYS FIND A WORKING EXAMPLE IN THE BASE GAME IF YOU ARE NEW ON THIS AND IF YOU WANT TO KEEP YOUR SANITY. Trust me.
Now, the importance of VSCode in this tutorial. VSCode has an incredibly powerful and useful highlighting system for text by just doing double click on ANY WORD. With this system, you'll understand how things are nested on ANY item you find. Look at this example:
If you pay attention to the miniature code on the right side and the scroll bar, there is a highlight that will point you exactly where things are nested:
If you move over that highlight, you will finally have your answer.
Final thoughts
This tutorial logic can be applied to ANYTHING that can be found in TweaksDB, how many inline records you are going to find will depend on each particular case. I picked a simple example to not extend this too much, but some items have more than 30 inlines... You are warned.
I've tested this method with many users, and all of them have been able to create their mods. This is not a way to do all items you have in mind, because is extremely inefficient, but once you understand how things are nested and how records are structured, you'll have a better time creating items afterwards.
I hope this will be helpful for you.
Thank you for reading, and good luck in your projects!
REMEMBER TO BOOKMARK THE PSIBERX YAML TWEAK BIBLE
You can also use this online tool to see if your YAML file has errors
Last updated
