Warning

This is a work in progress and may not be accurate or complete. The C# API has not yet been released.

REFramework.NET

REFramework provides a C# scripting API (REFramework.NET) that allows developers to create powerful mods and plugins for games using the RE Engine. The C# API targets the .NET 8.0 runtime and supports the x64 architecture.

Features

  • Runtime compilation of C# code
  • Loading of arbitrary compiled .NET 8.0 assemblies
  • Automatic generation of reference assemblies based on TDB data
  • Integration with the REFramework plugin system
  • Access to engine functionality and data structures through the API

Getting Started

To start developing C# plugins for REFramework, you'll need to have the .NET 8.0 runtime installed on your system. The backend of the C# API is primarily implemented in C++/CLI, with C# components for runtime compilation and reference assembly generation.

When the C# API is loaded, it automatically generates reference assemblies from the TDB data before loading any plugins. These reference assemblies provide autocomplete functionality in your C# IDE and can be inspected using a decompiler to gain insights into the engine codebase.

Project setup

In Visual Studio (or your preferred IDE), create a new C# class library project targeting .NET 8.0. Add a reference to REFramework.NET.dll and any other dependencies you need.

Required Project References

  • The REFramework.NET.dll in the reframework/plugins folder that came with the API
  • The REFramework.NET.*.dll files that were autogenerated in the reframework/plugins/managed/dependencies folder
    • These are the reference assemblies that provide autocomplete functionality
  • ImGui.NET.dll may need to be added as well (in reframework/plugins/managed/dependencies)

Precompiled Plugins

Make sure the target architecture targets x64 for the best compatibility.

Place the compiled DLL inside the reframework/plugins/managed folder. The plugin manager will automatically load the DLL when the API is initialized.

Source Plugins

Plugins can be written in a single .cs file and placed in the reframework/plugins/source folder. The plugin manager will automatically compile and load the source files when the API is initialized.

Source plugins can still have autocomplete and dependencies like compiled plugins, if you follow the instructions for creating a project. The difference is, you can either copy the file over when you need it, or use a symlink to your source file.

Source plugins are best for simpler projects, testing, or quick prototyping. They also will likely have the highest compatibility with future versions of the API, as the assembly references will always be up-to-date.

Dependencies

Copy any dependencies your project requires (e.g., .dll files) to the reframework/plugins/managed/dependencies folder. The plugin manager will automatically load these dependencies prior to loading any plugins.

Plugin Structure

C# plugins for REFramework follow a specific structure. Here's an example of a basic plugin:

using REFrameworkNET;

public class REFrameworkPlugin {
    [Attributes.PluginEntryPoint]
    public static void Main() {
        // Your plugin code goes here
        API.LogInfo("Hello from C#!");
    }
}

The entry point for a C# plugin is any method marked with the PluginEntryPoint attribute.

Plugin Manager

REFramework.NET includes a plugin manager that handles the loading and execution of C# plugins. The plugin manager is responsible for:

  • Loading dependencies from the reframework/plugins/managed/dependencies directory
  • Generating reference assemblies which are output to the reframework/plugins/managed/generated directory
  • Compiling and loading C# source files from the reframework/plugins/source directory
  • Loading pre-compiled assemblies from the reframework/plugins/managed directory
  • Invoking the Main method of each plugin

API Documentation

REFramework.NET provides a wide range of functionality for interacting with the RE Engine and extending the game's behavior. Some of the key components of the API include:

  • API: The main entry point for accessing REFramework functionality
  • TDB: Access to the game's type database
  • ManagedObject: Represents a managed object in the RE Engine
  • NativeObject: Represents a native object in the RE Engine
  • TypeDefinition: Provides information about a type in the RE Engine
  • Callbacks: Allows hooking into various engine events and callbacks

For detailed documentation on each component of the API, please refer to the individual pages in this documentation.