Format:IL2CPP global-metadata.dat
| Versions | metadata version 16 - 31 (24 has sub-versions 24.1-24.5; 27.1, 29.1) |
|---|---|
| Magic | AF 1B B1 FA (uint32 0xFAB11BAF little endian) |
| Extensions | .dat |
| Endianness | little endian |
| On this wiki | Facts · Code · Notes · Topics |
The metadata file of Unity's IL2CPP backend (Data/Managed/Metadata/global-metadata.dat, assets/bin/Data/Managed/Metadata/ in APKs): magic AF 1B B1 FA, a version int (16 to 31), and a header of (offset, size) pairs for type, method, field and string tables. With the registration structures inside libil2cpp/GameAssembly it restores class, method and field names and the addresses of native methods.
Overview
IL2CPP compiles C# to C++ and then to a native library (GameAssembly.dll, libil2cpp.so, UnityFramework in iOS). Names are not in the native code; they are in global-metadata.dat (one per game). Together with the native binary it allows restoring a full list of types, methods, fields and RVAs. Tool: Il2CppDumper (MIT), which writes dump.cs, DummyDll, script.json (names and addresses), stringliteral.json, il2cpp.h and IDA/Ghidra/Binary Ninja scripts.
Header
Little endian. Il2CppGlobalMetadataHeader begins uint32 sanity (0xFAB11BAF), int32 version, then (offset, size) pairs of int32/uint32 in this order: string literals, string literal data, strings (names for metadata, null-terminated UTF-8), events, properties, methods, parameter default values, field default values, field and parameter default value data, field marshaled sizes, parameters, fields, generic parameters, generic parameter constraints, generic containers, nested types, interfaces, vtable methods, interface offsets, type definitions, [rgctx entries up to 24.1], images, assemblies, then version dependent tables (metadata usages 19-24.5, field refs 19+, referenced assemblies 20+, attribute info 21-27.2, attribute data from 29, unresolved virtual call tables 22+, windows runtime tables, exported type definitions 24+). Il2CppDumper's Il2CppDumper/Il2Cpp/MetadataClass.cs annotates every field with the version range.
Il2CppDumper accepts versions 16 to 31 and rejects a value below 0 or above 1000 as not a valid metadata file.
Facts with the exact layouts (all from Il2CppDumper MetadataClass.cs/Il2CppClass.cs, commit 4741d46ba9cd): Fact:IL2CPP global-metadata.dat/struct/Il2CppGlobalMetadataHeader v29 to v31 (256 bytes, 31 pairs), Fact:IL2CPP global-metadata.dat/struct/Il2CppTypeDefinition v27 to v31, Fact:IL2CPP global-metadata.dat/struct/Il2CppMethodDefinition, Fact:IL2CPP global-metadata.dat/struct/Il2CppImageDefinition, Fact:IL2CPP global-metadata.dat/enum/Il2CppTypeEnum and Fact:IL2CPP global-metadata.dat/struct/Il2CppType bit layout. Table order at a glance (metadata 29): string literals, string literal data, strings, events, properties, methods, parameter default values, field default values, field and parameter default value data, field marshaled sizes, parameters, fields, generic parameters, generic parameter constraints, generic containers, nested types, interfaces, vtable methods, interface offsets, type definitions, images, assemblies, field refs, referenced assemblies, attribute data, attribute data ranges, unresolved virtual call parameter types and ranges, windows runtime type names and strings, exported type definitions. A pair is (offset, size) with the size in bytes, except the pairs rgctxEntries, metadataUsageLists, metadataUsagePairs, attributesInfo and attributeTypes of older versions, whose second member is named Count in the source. Method addresses and type tables are in the native binary, so the metadata alone does not give RVAs. The metadata usage pairs of versions below 27 (encodedSourceIndex) carry the usage kind in the top 3 bits ((x & 0xE0000000) >> 29: 1 TypeInfo, 2 Il2CppType, 3 MethodDef, 4 FieldInfo, 5 StringLiteral, 6 MethodRef) and the index in the low 29 bits (x & 0x1FFFFFFF; from 27, (x & 0x1FFFFFFE) >> 1). Unverified: the 24.x record-size rule of thumb (a method record is 32 bytes from 24.2 to 29 and 36 in 31) was computed by summing the dumper's field sizes, not checked against a real file.
Sub-version detection (version 24)
Version 24 changed several times without a number change. Il2CppDumper refines it in the Metadata constructor (checks in this order, see Fact:IL2CPP global-metadata.dat/behavior/Metadata version 24 sub-version detection): header length 264 (stringLiteralOffset == 264) is 24.2; otherwise, if any image definition has token != 1, it is 24.1 (else 24.0, header length 272); a 24.2 file with assembliesSize / 68 < image count is 24.4 (assembly records of 64 bytes, no hashValueIndex); a file taken as 24.1 whose assembliesSize / 64 == image count has its assemblies read with the 24.4 layout and is then set back to 24.1. 24.3 and 24.5 cannot be told from the metadata alone: the dumper promotes 24.2 to 24.3 and 24.4 to 24.5 from the native CodeRegistration, and 27 to 27.1/27.2 and 29 to 29.1 the same way (Fact:IL2CPP global-metadata.dat/behavior/Native side version refinement). Header lengths computed from the dumper's struct: 16: 192, 19: 216, 20: 224, 21: 240, 22: 256, 23: 264, 24.0 and 24.1: 272, 24.2: 264, 27 to 31: 256.
Recovering names
- Type name =
stringOffset + typeDef.nameIndex, namespace =stringOffset + typeDef.namespaceIndex(Il2CppTypeDefinition starts withnameIndex,namespaceIndex). Methods:Il2CppMethodDefinitionhasnameIndex,declaringType,returnType,parameterStart,token,flags,iflags,slot,parameterCount. Fields and parameters likewise hold name indices into the string table. - String literals used by C# code are read from
stringLiteralDataOffsetthrough the table atstringLiteralOffset(length, dataIndex). - Method addresses come from the native binary: in
Il2CppCodeRegistration,methodPointers(up to 24.1) or, from 24.2,codeGenModules(one module per image, each with amethodPointersarray indexed by the RID of the method token).Il2CppMetadataRegistrationholdstypes,fieldOffsets,genericClasses,methodSpecs.
Finding the registrations in the native binary
Il2CppDumper tries, in order (Fact:IL2CPP global-metadata.dat/behavior/Locating the registrations in the binary): PlusSearch (pattern scan), for a PE on Windows a retry with its own PE loader, Search() (version-specific, false for PE and ELF64), SymbolSearch(), then asks for both addresses (manual mode).
- Symbols: only the ELF parsers implement it: they look for the symbols
g_CodeRegistrationandg_MetadataRegistration(names read through the dynamic string table,DT_STRTAB). PE, 32-bit Mach-O and NSO returnfalse. Unverified: the 64-bit Mach-O parser; the nameil2cpp_codegen_registeris not used by this tool (not found in the files read). - CodeRegistration before metadata 24.2: scan the data sections for a pointer-sized value equal to the method count (methods whose
methodIndex >= 0) followed by a pointer to an array of that many pointers, all inside executable sections. - CodeRegistration from 24.2: find the bytes
mscorlib.dll\0in data (ELF: executable sections first, then data; other formats the reverse), then follow two levels of pointers that refer to it (module name pointer, entry of the codeGenModules array, the array itself); the registration lies 13 pointers before the array pointer for versions below 29 (27 and 28 also require the pointer-sized value before it to equal the image count) and 14 pointers before it from 29. - MetadataRegistration is not searched below metadata 19. For 19 to 26: a value equal to the type definition count at the
typeDefinitionsSizesCountposition (12 pointers into the structure), two pointers later a pointer tometadataUsageswhose entries point into bss. From 27: two consecutive pointer-sized values equal to the type definition count (fieldOffsetsCount,typeDefinitionsSizesCount) followed by a pointer to an array of that many pointers (into data, or into executable sections when the CodeRegistration was found there); the structure starts 10 pointers before the first value. - Version promotion afterwards: when the structure read with the assumed version has an implausible count (limit
0x50000), the dumper treats the file as the next sub-version and moves the address back by 1 or 2 pointers (31 stays 31 with a 2 pointer shift, else becomes 29; 29 becomes 29.1; 27 becomes 27.1; 24.4 always shifts 2 pointers and may become 24.5; 24.2 becomes 24.3 wheninteropDataCount == 0).
Not read: the Mach-O, NSO and WebAssembly section selection, and the 32-bit ELF Search() body. Structures: Fact:IL2CPP global-metadata.dat/struct/Il2CppCodeRegistration, Fact:IL2CPP global-metadata.dat/struct/Il2CppMetadataRegistration, Fact:IL2CPP global-metadata.dat/struct/Il2CppCodeGenModule; the native binary is recognized by its first 4 bytes (Fact:IL2CPP global-metadata.dat/identification/Binary container detection in Il2CppDumper).
Code & repositories
- https://github.com/Perfare/Il2CppDumper @
4741d46ba9cd6159c5d853eb9d6fc48b4bfa2b1a· license: MIT
Restores names and addresses from IL2CPP games. Useful without running: Il2CppDumper/Il2Cpp/MetadataClass.cs (metadata header and table structs per version), Il2CppClass.cs (Code/MetadataRegistration), Utils/SectionHelper.cs (registration search). Restores names and addresses from IL2CPP games. Useful without running: Il2CppDumper/Il2Cpp/MetadataClass.cs (metadata structs per version), Il2CppClass.cs (Code/MetadataRegistration, Il2CppType), Il2Cpp.cs (version promotion), Utils/SectionHelper.cs (registration search).
Tested on: source read, not run · checked 2026-10-19; last activity 2024-08-18; Note: the latest release ships binaries; the wiki links only the source, never the binaries
Pitfalls
- Games often encrypt or obfuscate the metadata. If the first 4 bytes are not
AF 1B B1 FA, the game decrypts it at start: look in the native binary for code touchingglobal-metadata.datand dump the decrypted buffer from memory. Unverified: no specific protection is documented in the repositories read here. - A memory-dumped libil2cpp.so needs the dump base address (Il2CppDumper asks for it).
- Il2CppDumper's README claims Unity 5.3 to 2022.2; newer metadata versions may need forks.