Modding Introduction

[HJHughJanus]

Cyberpunk 2077 Modding Introduction (redscript)

This is a short introduction on how to get started with modding Cyberpunk 2077 using redscript.
It will help you set up your game (so you are able to load redscript mods) as well as your Visual Studio Code (so you are able to create them).

Setting up your Cyberpunk 2077 installation

1. Download redscript from github: https://github.com/jac3km4/redscript/releases
   
2. Extract the downloaded zip-archive.
   
3. Copy the contents to your Cyberpunk 2077 installation directory.
   
4. Start Cyberpunk 2077 once, so redscript can set itself up (then close the game).
5. Done. Now you can put your redscript mods into _D:\PATH\TO\CYBERPUNK2077\r6\scripts_ and they will be automatically loaded upon game start.

Setting up VS Code

1. Download Visual Studio Code and install it: https://code.visualstudio.com/
2. Open Visual Studio Code and click on the „Extensions“ symbol in the left menu bar.
   
3. Search for „redscript“ and install the „Redscript Syntax Highlighting“ extension (keep this view open, another extension needs to be installed).
   
4. Download the redscript extension from github: https://github.com/jac3km4/redscript-ide-vscode/releases
   
5. In VS Code (your „Extensions“ manager should still be open) click the „three dots symbol“ and „Install from VSIX…“.
   
6. In the popup which should have just opened, navigate to your downloaded .vsix file and open it – VS Code should now automatically install your extension.
7. In your „Extensions“ manager, go to the newly installed extension and click the cog symbol and choose the settings (last option in the context menu).
   
8. There you have to fill in the path to your Cyberpunk 2077 installation and the path to a file the extension needs.
   
9. Save the settings and close VS Code.
10. Create a folder for your Cyberpunk 2077 mod development somewhere.
11. In there you create a plain text file called „MyMod.reds“, or whatever you want to call your mod (.reds is the file extension for redscript files).
12. Open VS Code and click „Open Folder…“, then choose your newly created Cyberpunk 2077 modding folder.
13. On the left you should see your „MyMod.reds“ file – open it and paste the following:

//add field to NPC class
@addField(NPCPuppet)
let testField: bool;

17. Save the file via „Ctrl“+“S“ and if everything is working correctly, VS Code should throw an error now (because the type „bool“ is supposed to be upper case „Bool“). When you hover your cursor over the text underlined in red, the error should be displayed:
    
18. Once you correct that and save the file again, everything should be fine.
    
19. Done. You can start coding now.

References

Red Modding Wiki
Source: https://wiki.redmodding.org/redscript/language/intro
How to use: Self-Explanatory :)

Cyberdoc
Source: https://jac3km4.github.io/cyberdoc
How to use: This is a searchable compendium including native functions, classes, etc..
Example: If you wanted to know which ragdolling functions there are, you could search for the keyword „ragdoll“ and check the results.

Decompiled Game Scripts
Source: https://codeberg.org/adamsmasher/cyberpunk/src/branch/master/
How to use: Download the whole bunch of data as a zip-file and either use Notepad++ or VS Code to search it.
Example: If you wanted to know how the ragdolling functions you found with Cyberdoc are actually used, you search the function name in the decompiled game scripts and can find lots of examples of how the function is used in game.

Native Database
Source: https://nativedb.red4ext.com/
How to use: This is a searchable compendium of native classes, enums and bitfields. It also includes native functions and fields, but they do not show up in the search, unfortunately. If you know in which class to look for, you can find the fields and functions there.
Example: If you didn‘t find something in Cyberdoc or want to check if there is more information on it, use the Native Database.

How to create a hook (with code snippets)

How to overwrite or extend game functions is explained in the Red Modding Wiki.
Injecting your code without altering anything existing works via wrapping.
Once you‘re sure what you want to do, you need to find out which system and which function within that system handles something close to your goal and then use this function as a wrapper function for your code.

Example
Goal: Ragdoll any NPC hit by a bullet.
System: I need to find out how Cyberpunk 2077 handles bullets and damage → a look through the decompiled game scripts shows there is a class called „DamageSystem“. This class looked up on Cyberdoc shows there is a function wihtin that class called „ProcessLocalizedDamage“. Back in the decompiled game scripts the code of this function seems to handle a „hit event“ and checking if the bullet hit the head or any weak spots. That is very close to my goal, so I will use this function for the hook.
Functions: I want to ragdoll an NPC, so I will need a function to do that. I search on Cyberdoc for „ragdoll“ and find something called „ApplyRagdollImpulseEvent“. I search this function in the decompiled game scripts to find out how it is used.
Code: First, I need to specify which system I want to use for injection, then specify the function.

@wrapMethod(DamageSystem)
private func ProcessLocalizedDamage(hitEvent: ref<gameHitEvent>) {
}

In this function I must now call the vanilla function first, so I don‘t overwrite any of the vanilla action – you can do this via the function wrappedMethod(params) (this one automatically calls the vanilla function).

@wrapMethod(DamageSystem)
private func ProcessLocalizedDamage(hitEvent: ref<gameHitEvent>) {
wrappedMethod(hitEvent);
}

Then I copy some code from the vanilla function to handle some errors and set up my variables.

@wrapMethod(DamageSystem)
private func ProcessLocalizedDamage(hitEvent: ref<gameHitEvent>) {
    wrappedMethod(hitEvent);
    
    //variables
    let hitUserData: ref<HitShapeUserDataBase>;
    let hitShapes: array<HitShapeData> = hitEvent.hitRepresentationResult.hitShapes;
    
    //error handling and setting up hitUserData (copy & paste from original)
    if !hitEvent.attackData.GetInstigator().IsPlayer() {
      return;
    };
    
    if AttackData.IsAreaOfEffect(hitEvent.attackData.GetAttackType()) {
      return;
    };
    
    if ArraySize(hitShapes) > 0 {
      hitUserData = DamageSystemHelper.GetHitShapeUserDataBase(hitShapes[0]);
    };
    
    if !IsDefined(hitUserData) {
      return;
    };
}

Now my actual code can take effect. Since I found the „ApplyRagdollImpulseEvent“ and looked up how it is used, I know this will not be done in one line. So, to keep the code in the wrapper function simple, I will write a separate function below which sets up the ragdolling for me.

private func RagdollNPC(target: ref<NPCPuppet>, pushForce: Float) -> Void {
  if IsDefined(target) {
    target.QueueEvent(CreateForceRagdollEvent(n"Debug Command"));
    if pushForce > 0.0 {
      GameInstance.GetDelaySystem(target.GetGame()).DelayEvent(target, CreateRagdollApplyImpulseEvent(target.GetWorldPosition(), Vector4.Normalize(target.GetWorldPosition()) * pushForce, 5.00), 0.10, false);
    };
  };
}

This function I will now use above to ragdoll the hit NPCs.

@wrapMethod(DamageSystem)
private func ProcessLocalizedDamage(hitEvent: ref<gameHitEvent>) {
    //start vanilla function, so everything at least runs normally (even if the mod doesnt work)
    wrappedMethod(hitEvent);
    
    //variables
    let hitUserData: ref<HitShapeUserDataBase>;
    let hitShapes: array<HitShapeData> = hitEvent.hitRepresentationResult.hitShapes;
    
    //error handling and setting up hitUserData (copy & paste from original)
    if !hitEvent.attackData.GetInstigator().IsPlayer() {
      return;
    };
    
    if AttackData.IsAreaOfEffect(hitEvent.attackData.GetAttackType()) {
      return;
    };
    
    if ArraySize(hitShapes) > 0 {
      hitUserData = DamageSystemHelper.GetHitShapeUserDataBase(hitShapes[0]);
    };
    
    if !IsDefined(hitUserData) {
      return;
    };

    //actual mod code
    let npc: ref<NPCPuppet> = hitEvent.target as NPCPuppet;
    let npcID: StatsObjectID = Cast(npc.GetEntityID());
    if IsDefined(npc) {
      RagdollNPC(npc, 10.0);
    };
}

The whole file now looks like this:

This file I save and then put into _D:\PATH\TO\CYBERPUNK2077\r6\scripts_ so the game will load it.
When I start the game, every NPC hit by a bullet should be ragdolled with a push.

[Elec0]

Apparently Cyberdoc moved: https://cyberdoc.surge.sh/

[HJHughJanus]

Thank you. Updated.

[keless]

This actually returns "project not found" for me currently

[Elec0]

I'm not sure why the thing is having so much trouble staying up.

jekky posted this in the discord:

[11:20 AM] jekky:
cyberdoc is now available here
https://jac3km4.github.io/cyberdoc/
slightly improved version btw

[KirkH420]

Just a reminder, the directory has been changed to "C:\Games\Cyberpunk 2077\r6\cache\modded\final.redscripts.bk"

[manavortex]

Hey,
I stole this put it on the wiki, since I'm trying to make a redscript mod :) Thank you so much for the guide, made my start a lot easier!