Shipwright/ZAPDTR/docs/zapd_extraction_xml_reference.md

ZAPD extraction XML reference

This document aims to be a small reference of how to create a compatible xml file for ZAPD.

Table of contents

• ZAPD extraction XML reference
  • Table of contents
  • Basic XML
  • Resources types
    • File
    • ExternalFile
    • Texture
    • Background
    • Blob
    • DList
    • TextureAnimation
    • Scene and Room
    • AltHeader
    • Animation
    • PlayerAnimation
    • CurveAnimation
    • LegacyAnimation
    • Skeleton
    • LimbTable
    • Limb
    • Symbol
    • Collision
    • Scalar
    • Vector
    • Vtx
    • Mtx
    • Cutscene
    • Array
    • Path
    • PlayerAnimationData
    • Pointer

Basic XML

An example of an object xml:

<Root>
    <File Name="object_jj" Segment="6">

        <Animation Name="gJabuJabuAnim" Offset="0x1F4C"/>

        <Skeleton Name="gJabuJabuSkel" Type="Flex" LimbType="Standard" Offset="0xB9A8"/>

        <!-- Jabu Jabu eye textures -->
        <Texture Name="gJabuJabuEyeOpenTex" OutName="jabu_jabu_eye_open" Format="rgba16" Width="16" Height="32" Offset="0x7698"/>
        <Texture Name="gJabuJabuEyeHalfTex" OutName="jabu_jabu_eye_half" Format="rgba16" Width="16" Height="32" Offset="0x7A98"/>
        <Texture Name="gJabuJabuEyeClosedTex" OutName="jabu_jabu_eye_closed" Format="rgba16" Width="16" Height="32" Offset="0x7E98"/>


        <Collision Name="gJabuJabu1Col" Offset="0x0A1C"/>
        <Collision Name="gJabuJabu2Col" Offset="0x1830"/>
        <Collision Name="gJabuJabu3Col" Offset="0xBA8C"/>

    </File>
</Root>

Every xml must have a <Root> tag. It must have at least one <File> child.

Resources types

The following is a list of the resources/tags supported by ZAPD, and the attributes needed by each one.

For most resources inside a <File> tag you should also set an Offset attribute. This is the offset (within the file) of the resource you are exporting. The Offset attribute is expected to be in hexadecimal, for example Offset="0x41F0".

It's worth noting that every tag expects a Name="gNameOfTheAsset". This is will be the name of the extracted variable in the output C code. Every asset must be prefixed with g and the suffix should represent the type of the variable.

Every tag can accept a Static attribute to specify if the asset should be marked as static or not. There are 3 valid values (defaults to Global):

• Global: Mark static if the flag --static was used.
• On: Override the global config and always mark as static.
• Off: Override the global config and don't mark as static.

This table summarizes if the asset will be marked static (✅) or not (❌)

Static="" attribute in XML	Without --static flag	With --static flag
On	✅	✅
Global (default)	❌	✅
Off	❌	❌

---

File

• Example of this tag:

<File Name="object_gi_fire" Segment="6">

• Attributes:

  • Name: Required. The name of the file in baserom/ which will be extracted.
  • OutName: Optional. The output name of the generated C source file. Defaults to the value passed to Name.
  • Segment: Optional. This is the segment number of the current file. Expects a decimal number between 0 and 15 inclusive, usually 6 if it is an object. If not specified, the file will use VRAM instead of segmented addresses.
  • BaseAddress: Optional. RAM address of the file. Expects a hex number (with 0x prefix). Default value: 0.
  • RangeStart: Optional. File offset where the extraction will begin. Hex. Default value: 0x000000000.
  • RangeEnd: Optional. File offset where the extraction will end. Hex. Default value: 0xFFFFFFFF.
  • Game: Optional. Valid values: OOT, MM, SW97 and OOTSW97. Default value: OOT.

---

ExternalFile

Allows ZAPD to map segmented addresses to variables declared in other files by using its XML.

It is useful for objects that use variables from gameplay_keep, gameplay_dangeon_keep, gameplay_field_keep, etc.

This tag can be used in the global config.xml file.

• Example of this tag:

<ExternalFile XmlPath="objects/gameplay_keep.xml" OutPath="objects/gameplay_keep/"/>

• Attributes:

  • XmlPath: Required. The path of the XML, relative to the value set by ExternalXMLFolder in the configuration file.
  • OutPath: Required. The path were the header for the corresponding external file is. It is used to #include it in the generated .c file.

---

Texture

Textures are extracted as .png files.

• Example:

<Texture Name="gCraterSmokeConeTex" OutName="crater_smoke_cone" Format="ia8" Width="32" Height="32" Offset="0xC30"/>

Will be defined as:

u64 gCraterSmokeConeTex[] = {
#include "assets/objects/object_spot17_obj/crater_smoke_cone.ia8.inc.c"
};

• Attributes:

  • Name: Required. Suffixed by Tex, unless it is a palette, in that case it is suffixed by TLUT.
  • OutName: Required. The filename of the extracted .png file.
  • Format: Required. The format of the image. Valid values: rgba32, rgba16, i4, i8, ia4, ia8, ia16, ci4 and ci8.
  • Width: Required. Width in pixels of the image.
  • Height: Required. Height in pixels of the image.
  • TlutOffset: Optional. Specifies the tlut's offset used by this texture. This attribute is only valid if Format is either ci4 or ci8, otherwise an exception would be thrown.
  • ExternalTlut: Optional. Specifies that the texture's tlut is in a different file. Takes the filename of the file that contains the tlut.
  • ExternalTlutOffset: Optional. Specifies the offset in the ExternalTlut of the tlut for the given texture.
  • SplitTlut: Optional. Specifies that the given texture should take from the upper half of the tlut. Takes a bool, i.e. one of true, false, 1, 0.

The following is a list of the texture formats the Nintendo 64 supports, with their gfxdis names and ZAPD format names.

Format name	Typing in gsDPLoadTextureBlock	"Format" in xml
4-bit intensity (I)	G_IM_FMT_I, G_IM_SIZ_4b	i4
4-bit intensity with alpha (I/A) (3/1)	G_IM_FMT_IA, G_IM_SIZ_4b	ia4
4-bit color index (CI)	G_IM_FMT_CI, G_IM_SIZ_4b	ci4
8-bit I	G_IM_FMT_I, G_IM_SIZ_8b	i8
8-bit IA (4/4)	G_IM_FMT_IA, G_IM_SIZ_8b	ia8
8-bit CI	G_IM_FMT_CI, G_IM_SIZ_8b	ci8
16-bit red, green, blue, alpha (RGBA) (5/5/5/1)	G_IM_FMT_RGBA, G_IM_SIZ_16b	rgba16
16-bit IA (8/8)	G_IM_FMT_IA, G_IM_SIZ_16b	ia16
16-bit YUV (Luminance, Blue-Y, Red-Y)	G_IM_FMT_YUV, G_IM_SIZ_16b	(not used)
32-bit RGBA (8/8/8/8)	G_IM_FMT_RGBA, G_IM_SIZ_32b	rgba32

If you want to know more about this formats, you can check gsDPLoadTextureBlock for most formats, or gDPLoadTextureBlock_4b for the 4-bit formats.

---

Background

• Example:

<Background Name="gGoronShopBackground" OutName="goron_shop_background" Offset="0x9D0"/>

• Attributes:

  • Name: Required. Suffixed by Background.
  • OutName: Required. The filename of the extracted .jpg file.

※ Explicit use of this tag isn't often necesary because it would probably be extracted automatically by another extracted element. You can use this to name them if you don't like the autogenerated name.

---

Blob

Blob are binary data that will be extracted as .bin files.

• Example:

<Blob Name="gFireTempleBlob_00CCC0" Size="0x10E" Offset="0xCCC0"/>

Will be defined as:

u8 gFireTempleBlob_00CCC0[] = {
#include "assets/objects/object_hidan_objects/gFireTempleBlob_00CCC0.bin.inc.c"
};

• Attributes:

  • Name: Required. Suffixed by Blob.
  • Size: Required. Amount of bytes to extract. Hex.

※ We usually use blobs when we can't figure out the content's type of chunk of data.

---

DList

A.k.a. Display list, or Gfx.

• Example:

<DList Name="gGiGreenRupeeInnerColorDL" Offset="0x04A0"/>

• Attributes:

  • Name: Required. Suffixed by DL.

---

TextureAnimation

A data type exclusive to Majora's Mask, that has scrolling, color changing, and texture changing capabilities. Declaring the main array will generate everything else; textures for the TextureCycle type must be declared manually in the XML to use symbols. (If it does reference any undeclared textures, ZAPD will warn and give the their offsets.)

<TextureAnimation Name="gRosaSistersTexAnim" Offset="0xD768"/>

• Attributes:

  • Name: Required. Suffixed by TexAnim.

---

Scene and Room

Scenes and Rooms are a bit special, because Rooms usually needs assets declared in their respective Scene (which is in a different file), so they need to be extracted together.

To accomplish this, the scene and each of their rooms must be declared in the same XML.

• Example:

<Root>
    <File Name="spot12_scene" Segment="2">
        <Cutscene Name="gSpot12Cs_006490" Offset="0x6490"/>

        <Scene Name="spot12_scene" Offset="0x0"/>
    </File>
    <File Name="spot12_room_0" Segment="3">
        <Room Name="spot12_room_0" Offset="0x0"/>
    </File>
    <File Name="spot12_room_1" Segment="3">
        <Room Name="spot12_room_1" Offset="0x0"/>
    </File>
</Root>

• Attributes:

  • HackMode: Optional. This is a simple non-hardcoded way to handle some edge cases. Valid values: syotes_room.

---

AltHeader

Like Scenes and Rooms, AltHeaders is special too. It should always be declared in the same File as a Scene or a Room.

• Example:

<File Name="spot01_scene" Segment="2">
    <Path Name="gSpot01Path_0003D0" NumPaths="3" Offset="0x3D0"/>

    <Texture Name="gSpot01TLUT_00A870" OutName="spot01_tlut_A870" Format="rgb5a1" Width="220" Height="1" Offset="0xA870"/>
    <Texture Name="gSpot01GrassTex" OutName="spot01_grass" Format="rgb5a1" Width="32" Height="32" Offset="0xAA50"/>

    <Texture Name="gSpot01WindowDayTex" OutName="spot01_window_day" Format="rgb5a1" Width="32" Height="64" Offset="0x15b50"/>
    <Texture Name="gSpot01WindowNightTex" OutName="spot01_window_night" Format="rgb5a1" Width="32" Height="64" Offset="0x16b50"/>

    <Cutscene Name="gKakarikoFirstTimeCs" Offset="0xA540"/>

    <Scene Name="spot01_scene" Offset="0x0"/>
    <AltHeader Name="gKakarikoAltHeader_009980" Offset="0x9980"/>
</File>

• Attributes:

  • Name: Required. Suffixed by AltHeader.

---

Animation

• Example:

<Animation Name="gWallmasterDamageAnim" Offset="0x590"/>

• Attributes:

  • Name: Required. Suffixed by Anim.

---

PlayerAnimation

• Example:

<PlayerAnimation Name="gPlayer3Anim" Offset="0x2310"/>

• Attributes:

  • Name: Required. Suffixed by Anim.

---

CurveAnimation

• Example:

<CurveAnimation Name="gEnBoxCurveAnim_4B60" SkelOffset="0x5EB8" Offset="0x4B60"/>

• Attributes:

  • Name: Required. Suffixed by Anim.
  • SkelOffset: Required. Offset of the CurveSkeleton (I.e. a Skeleton resource with Type="Curve") related to this animation.

---

LegacyAnimation

Useful only for the unused object_human's animation data.

• Example:

<LegacyAnimation Name="gHumanAnim_011A9C" Offset="0x11A9C"/>

• Attributes:

  • Name: Required. Suffixed by Anim.

---

Skeleton

• Example:

<Skeleton Name="gEnBoxCurveSkel" Type="Curve" LimbType="Curve" Offset="0x5EB8"/>

• Attributes:

  • Name: Required. Suffixed by Skel.
  • Type: Required. Valid values: Normal, Flex and Curve.
  • LimbType: Required. Valid values: Standard, LOD, Skin, Curve and Legacy.
  • EnumName: Optional. The name of typedef'd limb enum.
  • LimbNone: Optional. The name of the limb with index zero in the limb enum.
  • LimbMax: Optional. The name of the max limb index in the limb enum.

ZAPD is able to generate a limb enum by itself only if all the required data is provided. Providing some but not all the required data would trigger an error and the execution will halt.

The required data is providing the EnumName, LimbNone and LimbMax attributes in the Skeleton or LimbTable node and the EnumName attribute in every Limb of this skeleton.

※ There are no restrictions in the Type and LimbType attributes besides the valid values, so any skeleton type can be combined with any limb type.

---

LimbTable

• Example:

<LimbTable Name="gHumanLimbTable_011FC8" LimbType="Legacy" Count="41" Offset="0x11FC8"/>

• Attributes:

  • Name: Required. Suffixed by Skel.
  • LimbType: Required. Valid values: Standard, LOD, Skin, Curve and Legacy.
  • Count: Required. Amount of limbs. Integer.
  • EnumName: Optional. The name of typedef'd limb enum.
  • LimbNone: Optional. The name of the limb with index zero in the limb enum.
  • LimbMax: Optional. The name of the max limb index in the limb enum.

See Skeleton for info on the limb enum generation.

---

Limb

• Example:

<Limb Name="gChuGirlHeadLimb" LimbType="Standard" Offset="0x6E34"/>

• Attributes:

  • Name: Required. Suffixed by Limb.
  • LimbType: Required. Valid values: Standard, LOD, Skin, Curve and Legacy.
  • EnumName: Optional. The name used for this limb in the limbs enum. It must be either present in every limb or in none.

See Skeleton for info on the limb enum generation.

---

Symbol

A special element that allows declaring a variable without actually extracting it from the current file. Useful when a resource references an element from another file. The symbol will be declared as extern.

• Example:

<Symbol Name="gJsjutanShadowTex" Type="u8" Size="1" Count="0x800" Offset="0x4E70"/>

Will be declared as:

extern u8 gJsjutanShadowTex[2048];

• Attributes:

  • Type: The type of the declared variable. If missing, it will default to void*.
  • TypeSize: The size in bytes of the type. If missing, it will default to 4 (the size of a word and a pointer). Integer or hex value.
  • Count: Optional. If it is present, the variable will be declared as an array instead of a plain variable. The value of this attribute specifies the length of the array. If Count is present but it has no value (Count=""), then the length of the array will not be specified either in the declared variable. Integer or hex value.
  • Static: This attribute can't be enabled on a Symbol node. A warning will be showed in this case.

---

Collision

• Example:

<Collision Name="gDesertColossusBombableWallCol" Offset="0x1A58"/>

• Attributes:

  • Name: Required. Suffixed by Col.

---

Scalar

Allows the extraction of a single number.

• Example:

<Scalar Type="u64" Name="pad34F8"/>

Will be extracted as:

u64 pad34F8 = { 0 }; 

• Attributes:

  • Name: Required. Suffixed by TBD.
  • Type: Required. Valid values: s8, u8, x8, s16, u16, x16, s32, u32, x32, s64, u64, x64, f32 and f64.

※ Can be wrapped in an Array tag.

---

Vector

Extracts a vector.

Current supported types are Vec3s, Vec3i or Vec3f.

• Example:

<Array Name="gLinkPauseChildDekuShieldJointTable" Count="24" Offset="0x2040">
    <Vector Type="s16" Dimensions="3" />
</Array>

Will be extracted as:

Vec3s gLinkPauseChildDekuShieldJointTable[24] = {
    { -37, 2346, 93 },
    { 0, 11995, 0 },
    { -16385, -305, -16333 },
    { 0, 51, 12 },
    { 3761, 2263, -384 },
    { 0, 0, 3786 },
    { 1594, 1384, -18344 },
    { -2288, -2428, -1562 },
    { 0, 0, 3219 },
    { -2148, -5, -16840 },
    { 15365, -1708, 15611 },
    { 1761, 8365, 17711 },
    { 0, 0, 18859 },
    { 0, 0, 0 },
    { -9392, -9579, 28686 },
    { 0, 0, -7093 },
    { -2748, 685, -14092 },
    { 213, 6553, -32212 },
    { 0, 0, -1877 },
    { 3267, 3309, -16090 },
    { -18101, 25946, -2670 },
    { -104, 0, 0 },
    { 0, 0, 0 },
    { 0, 0, 0 }
}; 

• Attributes:

  • Name: Required. Suffixed by TBD.
  • Type: Required. Specifies the vector's type (Vec3s, Vec3i and Vec3f). Valid values: s16, s32 and f32.
  • Dimensions: Required. The amount of dimensions of the vector. Valid values: 3.

※ Can be wrapped in an Array tag.

---

Vtx

• Example:

<Array Name="gTriforceVtx" Count="32" Offset="0x0000">
    <Vtx/>
</Array>

• Attributes:

  • Name: Required. Suffixed by Vtx.

※ Can be wrapped in an Array tag.

---

Mtx

• Example:

<Mtx Name="gBdanMtx_000C40" Offset="0xC40" />

• Attributes:

  • Name: Required. Suffixed by Mtx.

※ Explicit use of this tag isn't often necesary because it would probably be extracted automatically by another extracted element.

---

Cutscene

• Example:

<Cutscene TODO/> <!-- Currently there are 0 xml in the repo using this tag. -->

• Attributes:

  • Name: Required. Suffixed by Cs.

※ Explicit use of this tag isn't often necesary because it would probably be extracted automatically by another extracted element.

---

Array

The Array element is special, because it needs an inner element to work. It will declare an array of its inner element.

Currently, only Pointer, Scalar, Vector and Vtx support being wrapped in an array.

• Example:

<Array Name="gTrialBarrierEnergyVtx" Count="102" Offset="0x4FD0">
    <Vtx/>
</Array>

• Attributes:

  • Name: Required. How the variable will be named. By our convention it should be prefixed by g. The sufix is mandated by the element contained.
  • Count: Required. Amount of elements. Integer.

---

Path

• Example:

<Path Name="gSpot09Path_002F60" Offset="0x2F60"/>

• Attributes:

  • Name: Required. Suffixed by Path.
  • NumPaths: Optional. The amount of paths contained in the array. It must be a positive integer.

---

PlayerAnimationData

Allows the extraction of the specific data of the player animations which are found in the link_animetion file.

• Example:

<PlayerAnimationData Name="gPlayerAnimData_000000" FrameCount="20" Offset="0x0"/>

• Attributes:

  • Name: Required. Suffixed by AnimData.
  • FrameCount: Required. The length of the animation in frames. It must be a positive integer.

---

Pointer

Allows the extraction of a variable that contains a pointer

• Example:

<Array Name="object_hanareyama_obj_DLArray_004638" Count="54" Offset="0x4638">
    <Pointer Type="Gfx"/>
</Array>

• Attributes:

  • Name: Required.
  • Type: Required. The type of the extracted pointer.

※ Can be wrapped in an Array tag.

---