FFXIVClientStructs

https://github.com/wolfcomp/ffxivclientstructsdocs
Admin
FFXIVClientStructsDocs provides documentation generation for FFXIVClientStructs, keeping the main...
Tokens:3,621
Snippets:25
Trust Score:6.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Initializing FFXIVClientStructs Signature Resolver - C#

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Initializes the FFXIVClientStructs library's signature resolver. This step is required to populate locations from signatures for calling native functions, unless the library is being used via the Dalamud plugin loader which handles initialization automatically. The Setup method has optional arguments for providing a module pointer, a version string for caching, and a path to a JSON cache file.

```C#
InteropGenerator.Runtime.Resolver.GetInstance.Setup();
FFXIVClientStructs.Interop.Generated.Addresses.Register();
InteropGenerator.Runtime.Resolver.GetInstance.Resolve();
```

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

### Example C++ Fixed-Size Array

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Shows a typical declaration of a fixed-size array in C++, which requires special handling when mapping to C# due to differences in how fixed arrays are handled.

```C++
AtkResNode resNodeArray[10];
```

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

### Hooking Virtual Function using Static VTable C#

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Provides an example of how to use the generated static VTable pointer (`AddonRetainerTaskAsk.StaticVirtualTablePointer`) to obtain the address of a specific virtual function (`OnSetup`) and use it to create a hook.

```C#
this.onSetupHook = Hook<OnSetupDelegate>.FromAddress((nint)AddonRetainerTaskAsk.StaticVirtualTablePointer->OnSetup, this.OnSetupDetour);
```

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

### Defining Struct Fields with FieldOffset in C#

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Demonstrates how individual fields within an explicit layout C# struct are defined using the `FieldOffset` attribute. Shows examples of pointer fields (`AtkResNode*`) which are common in native structures.

```C#
[FieldOffset(0x20)] public AtkResNode* ParentNode;
[FieldOffset(0x28)] public AtkResNode* PrevSiblingNode;
[FieldOffset(0x30)] public AtkResNode* NextSiblingNode;
[FieldOffset(0x38)] public AtkResNode* ChildNode;
```

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

### Fetch GitHub Avatars with JavaScript

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/docs/introduction.md

This script fetches the avatar URLs for specific GitHub users (wolfcomp, pohky, notnite) using the GitHub API and updates the 'src' attribute of corresponding image elements on the page. It utilizes the Fetch API for asynchronous data retrieval.

```JavaScript
(function(){
    fetch("https://api.github.com/users/wolfcomp").then(res => res.json()).then(ret => {
        document.querySelector("#img-wildwolf").src = ret.avatar_url;
    });
    fetch("https://api.github.com/users/pohky").then(res => res.json()).then(ret => {
        document.querySelector("#img-pohky").src = ret.avatar_url;
    });
    fetch("https://api.github.com/users/notnite").then(res => res.json()).then(ret => {
        document.querySelector("#img-notnite").src = ret.avatar_url;
    });
})()
```

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

### Applying StaticAddress Attribute C#

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Demonstrates applying the `StaticAddressAttribute` to a static method `Instance()` that returns a pointer to the `Framework` singleton. The attribute specifies the signature, offset, and indicates that the target address is a pointer.

```C#
[StaticAddress("44 0F B6 C0 48 8B 0D ?? ?? ?? ??", 7, isPointer: true)]
public static partial Framework* Instance();
```

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

### Generated StaticAddress Wrapper Code C#

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Shows the C# code generated by the interop generator based on the `StaticAddressAttribute`. It creates a static class `StaticAddressPointers` to hold the raw pointer and a wrapper method `Instance()` that dereferences the pointer, including null address checks.

```C#
public unsafe static class StaticAddressPointers
{
    public static global::FFXIVClientStructs.FFXIV.Client.System.Framework.Framework** ppInstance => (global::FFXIVClientStructs.FFXIV.Client.System.Framework.Framework**)Framework.Addresses.Instance.Value;
}

public static partial global::FFXIVClientStructs.FFXIV.Client.System.Framework.Framework* Instance()
{
    if (StaticAddressPointers.ppInstance is null)
    {
        InteropGenerator.Runtime.ThrowHelper.ThrowNullAddress("Framework.Instance", "49 8B DC 48 89 1D ?? ?? ?? ??");
    }
    return *StaticAddressPointers.ppInstance;
}
```

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

### Applying GenerateStringOverloads Attribute (C#)

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Demonstrates how the GenerateStringOverloads attribute is applied to a partial method declaration that represents a native function. The native function expects a byte* argument for a C string. The MemberFunction attribute specifies the native address pattern.

```csharp
[MemberFunction("E8 ?? ?? ?? ?? 48 8B F8 41 B0 01")]
[GenerateStringOverloads]
public partial AtkUnitBase* GetAddonByName(byte* name, int index = 1);
```

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

### Defining Native Game Struct in C#

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Illustrates how native game classes are represented as C# structs using `StructLayout(LayoutKind.Explicit)` and `FieldOffset`. Shows the basic structure definition including the `unsafe` keyword and `ICreatable` interface for creatable UI objects.

```C#
namespace FFXIVClientStructs.FFXIV.Component.GUI;
[StructLayout(LayoutKind.Explicit, Size = 0xA8)]
public unsafe partial struct AtkResNode : ICreatable { }
```

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

### StaticAddress Attribute Constructor C#

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Defines the constructor for the `StaticAddressAttribute`, used to mark methods that return the location of static objects in the game binary. It takes a signature string, an offset, and an optional boolean indicating if the address is a pointer.

```C#
public StaticAddressAttribute(string signature, int offset, bool isPointer = false)
```

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

### Generated VTableAddress Wrapper Code C#

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Shows the C# code generated based on the `VTableAddressAttribute`. It creates an `Addresses` class with a static `Address` field for the VTable and a struct `AddonRetainerTaskAskVirtualTable` defining the layout of the VTable, allowing access to virtual function pointers like `OnSetup`.

```C#
public static class Addresses
{
    public static readonly global::InteropGenerator.Runtime.Address StaticVirtualTable = new global::InteropGenerator.Runtime.Address("FFXIVClientStructs.FFXIV.Client.UI.AddonRetainerTaskAsk.StaticVirtualTable", "48 8D 05 ?? ?? ?? ?? 48 89 03 33 C0 48 89 83 ?? ?? ?? ?? 48 89 83 ?? ?? ?? ?? 48 89 83 ?? ?? ?? ?? 48 89 83 ?? ?? ?? ?? 48 89 83 ?? ?? ?? ?? 48 89 83 ?? ?? ?? ?? 48 89 83 ?? ?? ?? ?? 48 89 83 ?? ?? ?? ?? 48 89 83 ?? ?? ?? ?? 48 89 83 ?? ?? ?? ?? 48 89 83 ?? ?? ?? ?? 80 8B ?? ?? ?? ?? ?? ??", new ushort[] {3}, new ulong[] {0x4800000000058D48, 0x00838948C0330389, 0x0000838948000000, 0x0000008389480000, 0x0000000083894800, 0x4800000000838948, 0x8948000000008389, 0x8389480000000083, 0x0083894800000000, 0x0000838948000000, 0x0000008389480000, 0x0000000083894800, 0x0000000000008B80}, new ulong[] {0xFF00000000FFFFFF, 0x00FFFFFFFFFFFFFF, 0x0000FFFFFF000000, 0x000000FFFFFF0000, 0x00000000FFFFFF00, 0xFF00000000FFFFFF, 0xFFFF00000000FFFF, 0xFFFFFF00000000FF, 0x00FFFFFF00000000, 0x0000FFFFFF000000, 0x000000FFFFFF0000, 0x00000000FFFFFF00, 0x000000000000FFFF}, 0);
}

[global::System.Runtime.InteropServices.StructLayoutAttribute(global::System.Runtime.InteropServices.LayoutKind.Explicit)]
public unsafe partial struct AddonRetainerTaskAskVirtualTable
{
    [global::System.Runtime.InteropServices.FieldOffsetAttribute(384)] public delegate* unmanaged <AddonRetainerTaskAsk*, uint, global::FFXIVClientStructs.FFXIV.Component.GUI.AtkValue*, void> OnSetup;
}

public static AddonRetainerTaskAskVirtualTable* StaticVirtualTablePointer => (AddonRetainerTaskAskVirtualTable*)Addresses.StaticVirtualTable.Value;
```

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

### Apply MemberFunction Attribute to C# Method

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Demonstrates applying the `MemberFunctionAttribute` with a signature string to a `partial` C# method. This method declaration serves as the source for the code generator to create a wrapper for the native function.

```csharp
[MemberFunction("E8 ?? ?? ?? ?? C1 E7 0C")]
public partial void AddEvent(AtkEventType eventType, uint eventParam, AtkEventListener* listener,
        AtkResNode* nodeParam, bool isGlobalEvent);
```

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

### VTableAddress Attribute Constructor C#

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Defines the constructor for the `VTableAddressAttribute`, used on structs to mark the static location of their Virtual Tables (VTables) in the game binary. It takes a signature string, an offset, and an optional boolean.

```C#
public VTableAddressAttribute(string signature, int offset, bool isPointer = false)
```

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

### Generated C# Wrapper for Virtual Function

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Shows the C# code generated for a method marked with `VirtualFunctionAttribute`. This code defines necessary structures (`CharacterVirtualTable`) and uses function pointers accessed via the instance's virtual table to call the native virtual method.

```csharp
[StructLayout(LayoutKind.Explicit)]
public unsafe struct CharacterVirtualTable
{
    [global::System.Runtime.InteropServices.FieldOffsetAttribute(624)] public delegate* unmanaged <Character*, global::FFXIVClientStructs.FFXIV.Client.Game.StatusManager*> GetStatusManager;
}

[global::System.Runtime.InteropServices.FieldOffsetAttribute(0)] public CharacterVirtualTable* VirtualTable;
  
[global::System.Runtime.CompilerServices.MethodImpl(global::System.Runtime.CompilerServices.MethodImplOptions.AggressiveInlining)]
public partial global::FFXIVClientStructs.FFXIV.Client.Game.StatusManager* GetStatusManager() => VirtualTable->GetStatusManager((Character*)global::System.Runtime.CompilerServices.Unsafe.AsPointer(ref this));
```

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

### Generated String Overloads for Native Function (C#)

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Shows the C# code for the overloads automatically generated by the GenerateStringOverloads attribute. Includes an overload accepting a standard C# string (which is converted to a null-terminated UTF-8 byte array) and an overload accepting a ReadOnlySpan<byte> (useful for UTF-8 string literals). These overloads simplify calling the native function from C#.

```csharp
public global::FFXIVClientStructs.FFXIV.Component.GUI.AtkUnitBase* GetAddonByName(string name, int index = 1)
{
    int nameUTF8StrLen = global::System.Text.Encoding.UTF8.GetByteCount(name);
    Span<byte> nameBytes = nameUTF8StrLen <= 512 ? stackalloc byte[nameUTF8StrLen + 1] : new byte[nameUTF8StrLen + 1];
    global::System.Text.Encoding.UTF8.GetBytes(name, nameBytes);
    nameBytes[nameUTF8StrLen] = 0;
    fixed (byte* namePtr = nameBytes)
    {
        return GetAddonByName(namePtr, index);
    }
}

public global::FFXIVClientStructs.FFXIV.Component.GUI.AtkUnitBase* GetAddonByName(ReadOnlySpan<byte> name, int index = 1)
{
    fixed (byte* namePtr = name)
    {
        return GetAddonByName(namePtr, index);
    }
}
```

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

### Applying VTableAddress Attribute C#

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Demonstrates applying the `VTableAddressAttribute` to a struct `AddonRetainerTaskAsk`. The attribute provides the signature and offset needed to locate the struct's VTable in memory.

```C#
[VTableAddress("48 8d 05 ?? ?? ?? ?? 48 89 03 48 8d 83 50 02 00 00 48 89 93 20 02 00 00", 3)]
public unsafe partial struct AddonRetainerTaskAsk
```

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

### Define C# VirtualFunctionAttribute Constructor

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Shows the constructor signature for the `VirtualFunctionAttribute`. This attribute is used to mark C# methods that correspond to native virtual member functions, taking the virtual table index as a parameter.

```csharp
public VirtualFunctionAttribute(uint index)
```

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

### Generated C# Wrapper for Member Function

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Shows the C# code generated by the interop generator for a method marked with `MemberFunctionAttribute`. This wrapper handles looking up the native function pointer and calling it, including passing the `this` pointer for instance methods.

```csharp
public partial void AddEvent(AtkEventType eventType, uint eventParam, global::FFXIVClientStructs.FFXIV.Component.GUI.AtkEventListener* listener, global::FFXIVClientStructs.FFXIV.Component.GUI.AtkResNode* nodeParam, bool isGlobalEvent)
{
    if (MemberFunctionPointers.AddEvent is null)
    {
        InteropGenerator.Runtime.ThrowHelper.ThrowNullAddress("MemberFunctionPointers.AddEvent", "E8 ?? ?? ?? ?? C1 E7 0C ?? ?? ?? ?? ?? ?? ?? ??.");
    }
    MemberFunctionPointers.AddEvent((AtkResNode*)global::System.Runtime.CompilerServices.Unsafe.AsPointer(ref this), eventType, eventParam, listener, nodeParam, isGlobalEvent)
}
```

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

### Define C# MemberFunctionAttribute Constructor

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Shows the constructor signature for the `MemberFunctionAttribute`. This attribute is used to mark C# methods that correspond to native non-virtual member functions or static functions, taking a signature string for lookup.

```csharp
public MemberFunctionAttribute(string signature)
```

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

### Apply VirtualFunction Attribute to C# Method

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Demonstrates applying the `VirtualFunctionAttribute` with a virtual table index to a `partial` C# method. This declaration is used by the generator to create code that calls the native virtual function via the object's virtual table.

```csharp
[VirtualFunction(78)]
public partial StatusManager* GetStatusManager();
```

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

### GenerateStringOverloads Attribute Constructor (C#)

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Defines the constructor for the GenerateStringOverloads attribute, which can optionally take an argument name to ignore during overload generation.

```csharp
public GenerateStringOverloadsAttribute(string? ignoreArgument = null)
```

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

### Generated C# Property for Fixed-Size String

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Shows the C# property generated by the interop tool to provide safe string access (get/set) for the fixed-size byte array field. It handles UTF8 encoding/decoding, null termination, and includes a size check for setting the value.

```csharp
/// <inheritdoc cref="_freeCompanyTag" />
public string FreeCompanyTagString
{
    get => global::System.Text.Encoding.UTF8.GetString(global::System.Runtime.InteropServices.MemoryMarshal.CreateReadOnlySpanFromNullTerminated((byte*)global::System.Runtime.CompilerServices.Unsafe.AsPointer(ref _freeCompanyTag[0])));
    set
    {
        if (global::System.Text.Encoding.UTF8.GetByteCount(value) > 7 - 1)
        {
            InteropGenerator.Runtime.ThrowHelper.ThrowStringSizeTooLarge("FreeCompanyTagString", 7);
        }
        global::System.Text.Encoding.UTF8.GetBytes(value.AsSpan(), _freeCompanyTag);
        _freeCompanyTag[6] = 0;
    }
}
```

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

### Mapping C++ Fixed-Size Array to C# Inline Array

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Illustrates the C# approach to mapping C++ fixed-size arrays using the `FixedSizeArrayX<>` type and the `FixedSizeArray` attribute. This pattern generates an inline array struct accessible via `Span`.

```C#
[FixedSizeArray] internal FixedSizeArray10<AtkResNode> _resNodeArray;
```

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

### Define C++ Fixed-Size String Array

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Shows how a fixed-size character array is typically defined in C++ for inline strings within native structs. This represents a null-terminated string with a maximum length.

```c++
char freeCompanyTag[7];
```

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

### Define C# Field for Fixed-Size String

Source: https://github.com/wolfcomp/ffxivclientstructsdocs/blob/main/index.md

Defines a C# struct field using `FixedSizeArray<byte>` and the `FixedSizeArrayAttribute` with `isString: true`. This attribute signals to the code generator that this byte array should be treated as a null-terminated string.

```csharp
[FixedSizeArray(isString: true)] internal FixedSizeArray7<byte> _freeCompanyTag;
```
Tokens:
Raw