百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
F

FFXIVClientStructs

> 编程语言
开源

用于反向工程 FFXIV 客户端原生类的资源。

323 stars0 点赞2 次浏览
访问官网GitHub

工具介绍

用于反向工程 FFXIV 客户端原生类的资源。

FFXIVClientStructs

This library encapsulates community efforts to reverse engineer the object layout of native classes in the game Final Fantasy XIV and provide tools to assist in interop with native objects and functions in the running game. The library is written in C# as the main third party plug-in loader, Dalamud, is also written in C#.

Interacting with native game code is fundamentally unsafe and the library makes no attempt to prevent the user from shooting themselves in the foot. There is no type marshalling and all types are represented as explicit layout unmanaged structs that map 1:1 in memory with the game's objects. Since the game is written in C++, pointers are everywhere and you will likely need unsafe blocks when doing much of anything.

We make extensive use of C# Source Generators to reduce the boilerplate necessary to call native functions. Rather than marshalled delegates, all functions are represented by function pointers resolved by the library from signatures and wrapped in a null safety check. From the user standpoint, calling these functions is as simple as calling a native C# method.

Reverse Engineering Rename Database

A database and script(s) are maintained in the ida folder which can be used to import a large number of location names to IDA or Ghidra. This database is updated with every patch, although keep in mind this is volunteer work and some patches require more effort than others. There is more info in the readme in the folder itself.

Credits

This project would not be possible without significant work from many members of the FFXIV RE/Dalamud communities.

Project Maintainers

  • aers
  • pohky
  • Caraxi
  • daemitus
  • wolfcomp
  • Haselnussbomber

Contributors

Too many to list.

For Library Users

Signature Resolution

The library uses signatures to resolve locations at runtime. In order to populate locations from signatures to call functions, you need to initialize the library once at load. However, if you're writing a Dalamud plugin using the built-in copy of the library, you can just reference it in the project and Dalamud will have already initialized it for you.

The following code is only necessary if you are not using Dalamud or using a local copy of the library in your plugin.

csharp
InteropGenerator.Runtime.Resolver.GetInstance.Setup();
FFXIVClientStructs.Interop.Generated.Addresses.Register();
InteropGenerator.Runtime.Resolver.GetInstance.Resolve();

Setup has three optional arguments. The first allows you to pass a pointer to a copy of the FFXIV module somewhere in memory. The primary use of this is to allow the resolver to scan a fresh copy of the binary rather than one modified by active hooks from other sources. You can access Dalamud's module copy via the SigScanner service's SearchBase argument if you are trying to resolve your local copy within a Dalamud plugin. the second argument takes a string for the version of which is the key for what cache index to use from the file supplied in the third argument. The third argument takes a path to a JSON file as a C# FileInfo object. This will cause the resolver to use that JSON file as a signature cache, speeding up resolving on future runs. The resolver is relatively fast, but using the cache is near-instant, so using it is your choice.

Library Design

Native classes are represented as fixed-offset structs. If you have a pointer or reference to one of these structs, you can access native memory the same way you'd access a field on any C# class or struct. Native function calls are wrapped in methods on these structs and can be called the same way you would call a C# method. Source generation creates wrappers that automatically pass the struct's pointer to C++ member and virtual functions making them mostly-seamless.

Many native singletons can be accessed via static instance methods, which should get you started accessing native objects.

Caveats

C# is not C++. There are some constructs that aren't possible to represent properly as well and some rough edges around the interop process.

String types

The game has a string class, Utf8String, which is roughly analogous to std::string and is used in most places where strings are stored. However, it also uses C-style strings, aka pointers to null terminated character (UTF-8-encoded) arrays. C# strings are UTF-16 and pointers to them cannot be passed directly to functions requiring these C string pointers. Also, the C# char type is 16-bit and cannot be used to represent the arguments. All functions that take C string arguments therefore have byte* as the argument type.

The library generates overloads for these methods that take string and perform the UTF-16 -> UTF-8 byte array conversion for you. Be aware this conversion is happening and consider storing your own copies of UTF-8 converted strings if you are noticing a performance hit from the string conversions. This is unlikely, but could happen.

There are also generated overloads that take ReadOnlySpan arguments. This is primarily to allow the use of UTF-8 string literals as function arguments.

No functions will ever return a C# string type in order to avoid making assumptions about the memory lifetime of pointers returned by the game.

Fixed-Size Arrays

C# fixed size arrays are not the same as C++ fixed size arrays. This means that we have to use another feature called Inline Arrays. This feature allows us to create structs that represents the array type with a set size. This is done through generators which means that the array is only done after the Roslyn analyser has run after file modification.

These will be accessible through Span when used.

Generic Pointers

C# doesn't allow pointer types in generics. This makes it impossible to represent constructs like std::vector. The library uses a wrapper type Pointer to get around this. Pointer will implicitly convert to T* but you might need to do explicit conversions when working with collections of pointers.

STD collections

There are wrappers for accessing data from a handful of C++ std library collections used by the game such as vector and map.

For Library Developers

FFXIV is built with the MSVC 64-bit compiler and any mention of the way the compiler works applies to that compiler.

Signatures

All signatures in the library must use ?? for wildcard bytes and include 2 characters per byte.

Native Game Classes

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

Native game classes are represented as explicit layout structs. If the official name of the class is available (via old RTTI) use that for the name and namespace. For new classes or classes without virtual functions, make up a name that seems appropriate.

If the struct has unsafe members, mark the struct unsafe rather than the individual members. If you are using a generator, the struct must also be partial. If you are unable to get the exact size, use your best estimate.

ICreatable

If you give the struct a Ctor function and the interface ICreatable it will be creatable using game allocators via convenience methods on IMemorySpace. This is only relevant for objects that you might want to create, which at this point in time is entirely UI objects.

Class Fields

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

Because struct layouts are explicit, all fields are required to have a FieldOffset defined.

Field types can (generally) only be types that the runtime considers unmanaged. This boils down to most primitive integer/float types, enums, pointers, fixed-size primitive arrays, and structs that only contain fields meeting the definition.

Arrays

Native fixed size arrays such as

cpp
AtkResNode resNodeArray[10];

has to be defined with the FixedSizeArrayX<> type and contain the Attribute FixedSizeArray this attribute has an optional parameter if it is a cstr.

cs
[FixedSizeArray] internal FixedSizeArray10 _resNodeArray;

This will create a Span that is used to access the information that is in the array that has the correct size for how large the array is.

Inline C strings

C strings are usually passed in C++ with char* but inline struct strings have been defined with

cpp
char freeCompanyTag[7];

which means we can use the same FixedSizeArray definition as above with the optional parameter.

cs
[FixedSizeArray(isString: true)] internal FixedSizeArray7 _freeCompanyTag;

This will then be used in the generator to create a method to be able to set and get the string as follows

…

Native Game Functions

Native game functions are represented by methods with the correct signature and annotated with an attribute that causes generation of the appropriate wrapper to call the native function.

It is important to note that this assembly has the DisableRuntimeMarshalling attribute enabled, so only types that can be sent to native functions without marshalling are allowed (no string - use byte* and the CStr generator).

All native functions are called via C# function pointers and incur the minimum possible managedunmanaged penalty.

[MemberFunction]

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

Used for functions that are non-virtual members of native classes. This includes static functions.

This will generate the following wrapper:

…

Note that the wrapper takes care of passing the object instance pointer (known as the this pointer) to the function for you. This allows you to call native functions on library struct types as if they were regular C# methods. Static functions do not pass an object instance and the generator will not do this if the method is marked static.

[VirtualFunction]

csharp
public VirtualFunctionAttribute(uint index)
csharp
[VirtualFunction(78)]
public partial StatusManager* GetStatusManager();

Used for functions that are virtual members of native classes.

This will generate the following wrapper:

…

Virtual functions are referenced via the index in the class's virtual table. These cannot be static and always include the object instance pointer. Since these calls resolve the function pointer via the instance object's virtual table they will work the same way they do in native code and call the appropriate virtual overload for the class.

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

C#ffxiv

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言