RED4ext

https://docs.red4ext.com
Admin
RED4ext is a script extender for Cyberpunk 2077 that enables modders to interact with and extend the...
Tokens:7,359
Snippets:85
Trust Score:5.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Query Documentation with GET Request

Source: https://docs.red4ext.com/getting-started

To get additional information not present on the current page, perform an HTTP GET request to the page URL with the 'ask' query parameter. The question should be specific and self-contained. Use this for clarifications or to retrieve related documentation.

```http
GET https://docs.red4ext.com/getting-started.md?ask=<question>
```

--------------------------------

### Query Red4Ext Documentation Dynamically

Source: https://docs.red4ext.com/mod-developers/red4ext-and-red4ext.sdk/browse-red4ext-nativedb

Perform an HTTP GET request to the documentation URL with the 'ask' query parameter to get dynamic answers to specific questions. The question should be self-contained and in natural language.

```http
GET https://docs.red4ext.com/mod-developers/red4ext-and-red4ext.sdk/browse-red4ext-nativedb.md?ask=<question>
```

--------------------------------

### Querying documentation with GET request

Source: https://docs.red4ext.com/mod-developers/installing-a-plugin-with-red-cli

To get additional information not present on the page, make a GET request to the page URL with an 'ask' query parameter containing your question.

```http
GET https://docs.red4ext.com/mod-developers/installing-a-plugin-with-red-cli.md?ask=<question>
```

--------------------------------

### Basic Plugin Logging Example

Source: https://docs.red4ext.com/mod-developers/logging

Demonstrates how to use the logger within a plugin's Main function to log messages at different levels. Ensure the logger is initialized before use.

```cpp
#include <RED4ext/RED4ext.hpp>

RED4EXT_C_EXPORT bool RED4EXT_CALL Main(RED4ext::PluginHandle aHandle, RED4ext::EMainReason aReason, const RED4ext::Sdk* aSdk)
{
    switch (aReason)
    {
    case RED4ext::EMainReason::Load:
    {
        aSdk->logger->Trace(aHandle, "Hello World!");
        aSdk->logger->TraceF(aHandle, "Hello %s!", "World");

        break;
    }
    case RED4ext::EMainReason::Unload:
    {
        break;
    }
    }

    return true;
}
```

--------------------------------

### Example red4ext Configuration

Source: https://docs.red4ext.com/getting-started/configuration

This TOML configuration file sets up logging, plugin system, and development options for red4ext. Ensure the file is placed in the correct directory for the game to load it.

```toml
version = 0

[logging]
level = "info"
flush_on = "info"
max_files = 5
max_file_size = 10

[plugins]
enabled = true
ignored = [ "RED4ext.Playgorund" ]

[dev]
console = false
wait_for_debugger = false
```

--------------------------------

### Add red-cli commands to CMakeLists.txt

Source: https://docs.red4ext.com/mod-developers/installing-a-plugin-with-red-cli

Configure CMake to automatically run 'red-cli install' in Debug mode and 'red-cli pack' in Release mode after building. This automates plugin installation and archive creation.

```cmake
## Debug mode: install scripts (+ tests) and plugin in game folder.
## Release mode: create archive with bundled scripts and plugin.
add_custom_command(
        TARGET ${CMAKE_PROJECT_NAME}
        POST_BUILD
        WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
        COMMENT "$<$<CONFIG:Debug>:Install scripts with red-cli>" "$<$<CONFIG:Release>:Build archive with red-cli>"
        COMMAND "$<$<CONFIG:Debug>:red-cli;install>" "$<$<CONFIG:Release>:red-cli;pack>"
        COMMAND_EXPAND_LISTS
)
```

--------------------------------

### Querying Documentation with 'ask' Parameter

Source: https://docs.red4ext.com/getting-started/configuration

To get specific information not readily available, append the 'ask' query parameter to the documentation URL with your question. This mechanism allows for dynamic querying of the documentation.

```http
GET https://docs.red4ext.com/getting-started/configuration.md?ask=<question>
```

--------------------------------

### Use Native Function in Redscript

Source: https://docs.red4ext.com/mod-developers/adding-a-native-function

Instantiate your custom class and call the native function from Redscript. This example demonstrates logging the result of the native function call.

```swift
public class MyCustomClassPrinter extends ScriptableSystem {
    public func OnAttach() -> Void {
        LogChannel(n"DEBUG", "Hello!");
        let c = new CustomController();
        let vector = new Vector4(1.0, 2.0, 3.0, 4.0);
        let num = 50;
        LogChannel(n"DEBUG", "Number: " + FloatToString(c.GetNumber(vector, num)));
    }
}
```

--------------------------------

### Plugin Entry Point with RedLib

Source: https://docs.red4ext.com/mod-developers/creating-a-plugin-with-redlib

Sets up the main entry point for a RED4ext plugin using RedLib. Includes handling of plugin load and unload events and registering discovered types.

```cpp
/// File: src\main.cpp

#include <RED4ext/RED4ext.hpp>
// You must include RedLib. Note that it introduces an alias
// such as namespace RED4ext can be replaced by Red.
#include <RedLib.hpp>

RED4EXT_C_EXPORT bool RED4EXT_CALL Main(RED4ext::PluginHandle aHandle,
                                        RED4ext::EMainReason aReason,
                                        const RED4ext::Sdk* aSdk) {
  switch (aReason)  {
  case RED4ext::EMainReason::Load: {
    // It will automatically register types declared below.
    Red::TypeInfoRegistrar::RegisterDiscovered();
    break;
  }
  case RED4ext::EMainReason::Unload: {
    break;
  }
  }
  return true;
}

// ...
```

--------------------------------

### RED4ext Plugin Entry Point and Information

Source: https://docs.red4ext.com/mod-developers/creating-a-plugin

This C++ code defines the core functions for a RED4ext plugin: Main for handling plugin lifecycle events (load/unload), Query for providing plugin metadata, and Supports for indicating API version compatibility. Use Main for initialization and cleanup, and Query to set plugin details like name, author, and version.

```cpp
#include <RED4ext/RED4ext.hpp>

RED4EXT_C_EXPORT bool RED4EXT_CALL Main(RED4ext::PluginHandle aHandle, RED4ext::EMainReason aReason, const RED4ext::Sdk* aSdk)
{
    switch (aReason)
    {
    case RED4ext::EMainReason::Load:
    {
        // Attach hooks, register RTTI types, add custom states or initalize your application.
        // DO NOT try to access the game's memory at this point, it is not initalized yet.
        break;
    }
    case RED4ext::EMainReason::Unload:
    {
        // Free memory, detach hooks.
        // The game's memory is already freed, to not try to do anything with it.
        break;
    }
    }

    return true;
}

RED4EXT_C_EXPORT void RED4EXT_CALL Query(RED4ext::PluginInfo* aInfo)
{
    aInfo->name = L"Plugin's name";
    aInfo->author = L"Author's name";
    aInfo->version = RED4EXT_SEMVER(1, 0, 0); // Set your version here.
    aInfo->runtime = RED4EXT_RUNTIME_LATEST;
    aInfo->sdk = RED4EXT_SDK_LATEST;
}

RED4EXT_C_EXPORT uint32_t RED4EXT_CALL Supports()
{
    return RED4EXT_API_VERSION_LATEST;
}
```

--------------------------------

### Hook RTTI Registration Callbacks (C++)

Source: https://docs.red4ext.com/mod-developers/creating-a-custom-native-class

Integrate the type registration and parent setting functions into the RED4ext plugin's main entry point by hooking them using RTTIRegistrator::Add.

```cpp
RED4EXT_C_EXPORT bool RED4EXT_CALL Main(RED4ext::PluginHandle aHandle,
    RED4ext::EMainReason aReason, RED4ext::RED4ext* aRED4ext)
{
    switch (aReason)
    {
        case RED4ext::EMainReason::Load:
        {
            RED4ext::RTTIRegistrator::Add(RegisterTypes, PostRegisterTypes);
            break;
        }
        case RED4ext::EMainReason::Unload:
        {
            break;
        }
    }
    
    return true;
}
```

--------------------------------

### Test Zoo System in RedScript

Source: https://docs.red4ext.com/mod-developers/creating-a-plugin-with-redlib

Implements a 'ZooSystem' in RedScript that creates and manages a collection of 'Wolf' objects. It demonstrates how to instantiate native classes, call their methods, and log information to the game console.

```swift
/// File: scripts\ZooTest.reds

import Zoo.*

public class ZooSystem extends ScriptableSystem {
  private let m_animals: array<ref<Animal>>;

  private func OnAttach() {
    // Create a pack of wolves.
    ArrayPush(this.m_animals, new Wolf());
    ArrayPush(this.m_animals, new Wolf());
    ArrayPush(this.m_animals, new Wolf());
    ArrayPush(this.m_animals, new Wolf());

    for animal in this.m_animals {
      LogChannel(n"Info", s"Class name: s\(animal.GetClassName())");
      LogChannel(n"Info", "");
      LogChannel(n"Info", s"Can fly? s\(animal.CanFly())");
      LogChannel(n"Info", s"Can walk? s\(animal.CanWalk())");
      LogChannel(n"Info", s"Is carnivore? s\(animal.IsCarnivore())");
      LogChannel(n"Info", s"Is herbivore? s\(animal.IsHerbivore())");
      let wolf = animal as Wolf;

      LogChannel(n"Info", "");
      LogChannel(n"Info", s"Can hunt? \(wolf.CanHunt())");
      LogChannel(n"Info", "");
    }
  }

  private func OnDetach() {
    ArrayClear(this.m_animals);
  }

}
```

--------------------------------

### Registering Custom Game States

Source: https://docs.red4ext.com/mod-developers/custom-game-states

This C++ code demonstrates how to register custom game states for BaseInitialization and Shutdown using the RED4ext SDK. It defines the OnEnter, OnUpdate, and OnExit functions for these states.

```cpp
#include <RED4ext/RED4ext.hpp>

bool BaseInit_OnEnter(RED4ext::CGameApplication* aApp)
{
    return true;
}

bool BaseInit_OnUpdate(RED4ext::CGameApplication* aApp)
{
    static uint32_t i = 0;
    if (i == 3)
    {
        return true;
    }

    i++;
    return false;
}

bool BaseInit_OnExit(RED4ext::CGameApplication* aApp)
{
    return true;
}

bool Shutdown_OnUpdate(RED4ext::CGameApplication* aApp)
{
    static uint32_t i = 0;
    if (i == 3)
    {
        return true;
    }

    i++;
    return false;
}

RED4EXT_C_EXPORT bool RED4EXT_CALL Main(RED4ext::PluginHandle aHandle, RED4ext::EMainReason aReason, const RED4ext::Sdk* aSdk)
{
    switch (aReason)
    {
    case RED4ext::EMainReason::Load:
    {
        RED4ext::GameState initState;
        initState.OnEnter = &BaseInit_OnEnter;
        initState.OnUpdate = &BaseInit_OnUpdate;
        initState.OnExit = &BaseInit_OnExit;

        aSdk->gameStates->Add(aHandle, RED4ext::EGameStateType::BaseInitialization, &initState);
        
        RED4ext::GameState shutdownState;
        shutdownState.OnEnter = nullptr;
        shutdownState.OnUpdate = &Shutdown_OnUpdate;
        shutdownState.OnExit = nullptr;

        aSdk->gameStates->Add(aHandle, RED4ext::EGameStateType::Shutdown, &shutdownState);

        break;
    }
    case RED4ext::EMainReason::Unload:
    {
        break;
    }
    }

    return true;
}

```

--------------------------------

### Declare Wolf Class Inheriting from Animal with RedLib

Source: https://docs.red4ext.com/mod-developers/creating-a-plugin-with-redlib

Defines a 'Wolf' class that inherits from 'Animal'. Overrides base class methods and adds a new 'CanHunt' method. Uses RedLib's RTTI macros for class registration.

```cpp
/// File: src\Wolf.hpp

#include <RedLib.hpp>

#include "Animal.hpp"

class Wolf : public Animal {
public:
  //Wolf() = default;

  bool CanWalk() const override {
    return true;
  }

  bool IsCarnivore() const override {
    return true;
  }

  bool CanHunt() const {
    return true;
  }

  RTTI_IMPL_TYPEINFO(Wolf);
  RTTI_IMPL_ALLOCATOR();
};

RTTI_DEFINE_CLASS(Wolf, {
  RTTI_ALIAS("Zoo.Wolf");

  RTTI_PARENT(Animal);

  // Redeclare methods you override.
  RTTI_METHOD(CanWalk);
  RTTI_METHOD(is_carnivore, "IsCarnivore");

  RTTI_METHOD(CanHunt);
});
```

--------------------------------

### Define Native Function in C++

Source: https://docs.red4ext.com/mod-developers/adding-a-native-function

Implement the C++ function that will be exposed to Redscript. Ensure correct parameter handling using `RED4ext::GetParameter` and manage the stack frame.

```cpp
void GetNumber(RED4ext::IScriptable* aContext, RED4ext::CStackFrame* aFrame,
    float* aOut, int64_t a4)
{
    RED4ext::Vector4 worldPosition;
    int32_t count;
    
    RED4ext::GetParameter(aFrame, &worldPosition);
    RED4ext::GetParameter(aFrame, &count);
    aFrame->code++; // skip ParamEnd
    
    if (aOut)
    {
        *aOut = 6.25;
    }
}
```

--------------------------------

### Instantiate and Define Native Type (C++)

Source: https://docs.red4ext.com/mod-developers/creating-a-custom-native-class

Use the TTypedClass template to create an instance representing your custom class within RED4ext's RTTI system. Implement GetNativeType to return a reference to this instance.

```cpp
RED4ext::TTypedClass<CustomController> customControllerClass("CustomController");

RED4ext::CClass* CustomController::GetNativeType()
{
    return &customControllerClass;
}
```

--------------------------------

### Declare Generic Animal Class with RedLib

Source: https://docs.red4ext.com/mod-developers/creating-a-plugin-with-redlib

Defines a base 'Animal' class inheriting from Red::IScriptable, with virtual methods for behavior and a position property. Uses RedLib's RTTI macros for class registration.

```cpp
/// File: src\Animal.hpp

#include <RED4ext/Scripting/Natives/Generated/Vector4.hpp>
#include <RedLib.hpp>

class Animal : public Red::IScriptable {
public:
  //Animal() = default;

  virtual bool CanFly() const {
    return false;
  }
  virtual bool CanWalk() const {
    return false;
  }

  virtual bool is_carnivore() const {
    return false;
  }
  virtual bool is_herbivore() const {
    return false;
  }

  Red::Vector4 position{};

  RTTI_IMPL_TYPEINFO(Animal);
  RTTI_IMPL_ALLOCATOR();
}

RTTI_DEFINE_CLASS(Animal, {
  // You only need to add an alias when declaring scripts 
  // with 'module' and 'import' keywords.
  RTTI_ALIAS("Zoo.Animal");

  RTTI_ABSTRACT();

  RTTI_METHOD(CanFly);
  RTTI_METHOD(CanWalk);

  // You can use another name to declare instead.
  RTTI_METHOD(is_carnivore, "IsCarnivore");
  RTTI_METHOD(is_herbivore, "IsHerbivore");
  
  RTTI_GETTER(position);
});
```

--------------------------------

### Define Custom Native Class Structure (C++)

Source: https://docs.red4ext.com/mod-developers/creating-a-custom-native-class

Define the basic structure of your custom native class by inheriting from RED4ext::IScriptable. This struct serves as the C++ representation of your class.

```cpp
struct CustomController : RED4ext::IScriptable
{
    RED4ext::CClass* GetNativeType();
};
```

--------------------------------

### Register Native Function in C++

Source: https://docs.red4ext.com/mod-developers/adding-a-native-function

Register the C++ native function with your custom class in the `PostRegisterTypes` callback. This involves creating a `CClassFunction` object and setting its properties.

```cpp
RED4EXT_C_EXPORT void RED4EXT_CALL PostRegisterTypes()
{
   // This section is from the previous page.
   auto rtti = RED4ext::CRTTISystem::Get();
   auto scriptable = rtti->GetClass("IScriptable");
   customControllerClass.parent = scriptable;

   auto getNumber = RED4ext::CClassFunction::Create(&customControllerClass, 
       "GetNumber", "GetNumber", &GetNumber, { .isNative = true });
   getNumber->AddParam("Vector4", "worldPosition");
   getNumber->AddParam("Int32", "count");
   getNumber->SetReturnType("Float");
   customControllerClass.RegisterFunction(getNumber);
}
```

--------------------------------

### Register Custom Type with RTTI (C++)

Source: https://docs.red4ext.com/mod-developers/creating-a-custom-native-class

Register your custom type with the RED4ext RTTI system during the plugin's load phase. This makes the class known to the game's runtime type information.

```cpp
void RegisterTypes()
{
    RED4ext::CRTTISystem::Get()->RegisterType(&customControllerClass);
}
```

--------------------------------

### Set Custom Class Parent (C++)

Source: https://docs.red4ext.com/mod-developers/creating-a-custom-native-class

After initial registration, manually set the parent class of your custom type to IScriptable to ensure correct inheritance in the RTTI system.

```cpp
void PostRegisterTypes()
{
   auto rtti = RED4ext::CRTTISystem::Get();
   auto scriptable = rtti->GetClass("IScriptable");
   customControllerClass.parent = scriptable;
}
```

--------------------------------

### Declare Native Function in Redscript

Source: https://docs.red4ext.com/mod-developers/adding-a-native-function

Declare the native function within your Redscript class using the `native` keyword. The signature should match the C++ implementation.

```swift
public native class CustomController extends IScriptable {
    public native func GetNumber(worldPosition: Vector4, count: Int32) -> Float;
}
```

--------------------------------

### Declare Native Animal Types in RedScript

Source: https://docs.red4ext.com/mod-developers/creating-a-plugin-with-redlib

Declares native 'Animal' and 'Wolf' classes in RedScript, mirroring the C++ definitions. This allows these types to be used within the game's scripting environment.

```swift
/// File: scripts\Zoo.reds

// Again, declaring native types within a module
// is not required.
module Zoo

public abstract native class Animal extends IScriptable {
  public native func CanFly() -> Bool;
  public native func CanWalk()-> Bool;

  public native func IsCarnivore() -> Bool;
  public native func IsHerbivore() -> Bool;

  public native func GetPosition() -> Vector4;
}

public native class Wolf extends Animal {
  // You don't need to redeclare methods of the parent,
  // even when you override them.

  // But you have to declare new methods.
  public native func CanHunt() -> Bool;
}
```

--------------------------------

### Declare Native Class in Redscript

Source: https://docs.red4ext.com/mod-developers/creating-a-custom-native-class

Declare the corresponding native class in Redscript, extending IScriptable. This declaration makes the C++ class accessible from Redscript scripts.

```swift
public native class CustomController extends IScriptable {

}
```
Tokens:
Raw