Latest revision as of 14:38, 11 July 2026

Load Context

The relationship is:

Global DB state
├── Zone registry
│   ├── patch_mp       -> its own XZoneMemory
│   ├── common_mp      -> its own XZoneMemory
│   ├── ui_mp          -> its own XZoneMemory
│   ├── mp_boneyard_load -> its own XZoneMemory
│   └── mp_boneyard    -> its own XZoneMemory
├── Current stream state
│   └── points at one zone's XZoneMemory while that zone is loading
└── Global XAsset registry
    └── shared by assets from every loaded zone

XZoneMemory is per zone.
Dependencies do not combine their blocks into one XZoneMemory.
The global XAsset registry spans all loaded zones.
Each XAssetEntry records its owning zoneIndex.
Asset overrides and deduplication happen through the shared registry.
Unloading a zone frees that zone’s XZoneMemory and removes or reveals its registry entries as appropriate.

Conceptually:

void DB_LoadZone(XZone *zone, DBFile *file)
{
    DB_AllocXZoneMemory(file->blockSizes, &zone->memory);
    DB_InitStreams(&zone->memory);

    // The global stream state now points into this zone's seven blocks.
    DB_LoadXFile(&zone->memory, file);

    // Loaded assets are registered into the shared global XAsset registry.
    DB_PostLoadXZone(zone);
}

XZone

The encompassing live zone record appears shaped like:

// PROVEN: PS3 DB_LoadXAssets and its callers use these five numeric bits as
// zone allocation/free categories. CORRELATED: Xbox IW4 symbols provide the
// DB_ZONE_* member names for those bits.
enum XZoneFlags : int
{
    None = 0,
    DB_ZONE_COMMON = 0x01,
    DB_ZONE_UI = 0x02,
    DB_ZONE_GAME = 0x04,
    DB_ZONE_LOAD = 0x08,
    DB_ZONE_DEV = 0x10
}

typedef struct XZone
{
    uint32_t zoneId;          // 0x00
    uint32_t unknown04;       // 0x04
    char     name[64];        // 0x08
    uint32_t unknown48;       // 0x48
    XZoneFlags zoneFlags;     // 0x4C
    uint32_t unknown50;       // 0x50
    XZoneMemory memory;       // 0x54
} XZone;

XZoneInfo

PS3 function 0x0011B968, corresponding to DB_LoadXAssets, independently proves the field behavior:

It iterates XZoneInfo using a 0x0C stride.
+0x08 is intersected with each loaded XZone flag word at +0x4C.
Every zone where (freeFlags & zoneFlags) != 0 is selected for unloading.
+0x04 is copied into the internal queued request at +0x40 and becomes the loaded zone’s category/lifetime flags.
Freeing happens before new named records from the same batch are queued.

Value	Meaning	PS3 usage
`0x01`	`COMMON`	`code_post_gfx_mp`, `patch_mp`, `common_mp`
`0x02`	`UI`	`ui_mp`, DLC UI zones
`0x04`	`GAME`	Main map/game zone path
`0x08`	`LOAD`	`<map>_load` path
`0x10`	`DEV`	Appears in free masks, but no standalone PS3 allocation observed yet

Common combined masks include:

0x06 = UI | GAME
0x18 = LOAD | DEV
0x1E = every category except COMMON

The Xbox builds also contain the assertion !(freeFlags & DB_ZONE_COMMON). That prohibition is Xbox-proven and strongly PS3-correlated. patch_mp and common_mp have 0x01, while ui_mp has 0x02.

typedef struct XZoneInfo
{
    char* Name,
    XZoneFlags AllocFlags,
    XZoneFlags FreeFlags
} XZoneInfo; // 0x0C

XZoneMemory

XZoneMemory is the memory-block allocation for one loaded zone/fastfile. It is only one component of the engine’s broader database loading state.

typedef enum XFileBlockType
{
    XFILE_BLOCK_TEMP     = 0,
    XFILE_BLOCK_PHYSICAL = 1,
    XFILE_BLOCK_RUNTIME  = 2,
    XFILE_BLOCK_VIRTUAL  = 3,
    XFILE_BLOCK_LARGE    = 4,
    XFILE_BLOCK_CALLBACK = 5,
    XFILE_BLOCK_VERTEX   = 6,

    XFILE_BLOCK_COUNT    = 7
} XFileBlockType;

typedef struct XZoneMemoryBlock
{
    void* address;  // Live address; null when size is zero
    uint32_t size;     // Declared allocation size
} XZoneMemoryBlock;

typedef struct XZoneMemory
{
    XZoneMemoryBlock blocks[XFILE_BLOCK_COUNT];
} XZoneMemory;

XAssetEntry

The engines load context keeps a record of semantic asset names to it's place in memory. The engine more or less does this:

typedef struct XAssetEntry
{
    uint32_t assetType;          // 0x00: XAssetType
    XAsset*  headerPointer;      // 0x04: canonical asset-header pointer

    uint8_t  zoneIndex;          // 0x08: owning zone-record index
    uint8_t  flags09;            // 0x09: bit 0 is tested by registry logic
    uint8_t  state0A;            // 0x0A: initialized to zero; meaning OPEN
    uint8_t  pad0B;              // 0x0B: no semantics proven

    uint16_t nextHashIndex;      // 0x0C: next entry in the name-hash chain
    uint16_t nextOverrideIndex;  // 0x0E: override/replacement chain
} XAssetEntry;

This category currently contains no pages or media.

@@ Line 41: / Line 41: @@
 The encompassing live zone record appears shaped like:
 <syntaxhighlight lang="C">
+// PROVEN: PS3 DB_LoadXAssets and its callers use these five numeric bits as
+// zone allocation/free categories. CORRELATED: Xbox IW4 symbols provide the
+// DB_ZONE_* member names for those bits.
+enum XZoneFlags : int
+{
+    None = 0,
+    DB_ZONE_COMMON = 0x01,
+    DB_ZONE_UI = 0x02,
+    DB_ZONE_GAME = 0x04,
+    DB_ZONE_LOAD = 0x08,
+    DB_ZONE_DEV = 0x10
+}
 typedef struct XZone
 {
@@ Line 47: / Line 60: @@
      char     name[64];        // 0x08
      uint32_t unknown48;       // 0x48
-     uint32_t zoneFlags;       // 0x4C
+     XZoneFlags zoneFlags;     // 0x4C
      uint32_t unknown50;       // 0x50
      XZoneMemory memory;       // 0x54
 } XZone;
+</syntaxhighlight>
+=== XZoneInfo ===
+PS3 function 0x0011B968, corresponding to DB_LoadXAssets, independently proves the field behavior:
+* It iterates XZoneInfo using a 0x0C stride.
+* +0x08 is intersected with each loaded XZone flag word at +0x4C.
+* Every zone where (freeFlags & zoneFlags) != 0 is selected for unloading.
+* +0x04 is copied into the internal queued request at +0x40 and becomes the loaded zone’s category/lifetime flags.
+* Freeing happens before new named records from the same batch are queued.
+{| class="wikitable"
+! Value
+! Meaning
+! PS3 usage
+|-
+| <code>0x01</code>
+| <code>COMMON</code>
+| <code>code_post_gfx_mp</code>, <code>patch_mp</code>, <code>common_mp</code>
+|-
+| <code>0x02</code>
+| <code>UI</code>
+| <code>ui_mp</code>, DLC UI zones
+|-
+| <code>0x04</code>
+| <code>GAME</code>
+| Main map/game zone path
+|-
+| <code>0x08</code>
+| <code>LOAD</code>
+| <code>&lt;map&gt;_load</code> path
+|-
+| <code>0x10</code>
+| <code>DEV</code>
+| Appears in free masks, but no standalone PS3 allocation observed yet
+|}
+Common combined masks include:
+* 0x06 = UI | GAME
+* 0x18 = LOAD | DEV
+* 0x1E = every category except COMMON
+The Xbox builds also contain the assertion !(freeFlags & DB_ZONE_COMMON). That prohibition is Xbox-proven and strongly PS3-correlated.
+patch_mp and common_mp have 0x01, while ui_mp has 0x02.
+<syntaxhighlight lang="C">
+typedef struct XZoneInfo
+{
+    char* Name,
+    XZoneFlags AllocFlags,
+    XZoneFlags FreeFlags
+} XZoneInfo; // 0x0C
 </syntaxhighlight>
@@ Line 88: / Line 151: @@
 {
      uint32_t assetType;          // 0x00: XAssetType
-     uint32_t headerPointer;      // 0x04: canonical asset-header pointer
+     XAsset*  headerPointer;      // 0x04: canonical asset-header pointer
      uint8_t  zoneIndex;          // 0x08: owning zone-record index