oot/tools/ZAPD/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
    • Texture
    • Background
    • Blob
    • DList
    • Scene and Room
    • Animation
    • PlayerAnimation
    • CurveAnimation
    • LegacyAnimation
    • Skeleton
    • LimbTable
    • Limb
    • Symbol
    • Collision
    • Scalar
    • Vector
    • Vtx
    • Mtx
    • Cutscene
    • Array
    • Path

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.

---

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: Required. This is the segment number of the current file. Expects a decimal number, usually 6 if it is an object, or 128 for overlays (It's kinda a whacky hack to get around of the 0x80 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.

---

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. Suxffixed 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.

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	rgba8

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. Suxffixed 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. Suxffixed 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. Suxffixed by DL.

---

Scene and Room

TODO. I'm hoping somebody else will do this.

---

Animation

• Example:

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

• Attributes:

  • Name: Required. Suxffixed by Anim.

---

PlayerAnimation

• Example:

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

• Attributes:

  • Name: Required. Suxffixed by Anim.

---

CurveAnimation

• Example:

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

• Attributes:

  • Name: Required. Suxffixed 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. Suxffixed by Anim.

---

Skeleton

• Example:

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

• Attributes:

  • Name: Required. Suxffixed by Skel.
  • Type: Required. Valid values: Normal, Flex and Curve.
  • LimbType: Required. Valid values: Standard, LOD, Skin, Curve and Legacy.

※ 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. Suxffixed by Skel.
  • LimbType: Required. Valid values: Standard, LOD, Skin, Curve and Legacy.
  • Count: Required. Amount of limbs. Integer.

---

Limb

• Example:

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

• Attributes:

  • Name: Required. Suxffixed by Limb.
  • LimbType: Required. Valid values: Standard, LOD, Skin, Curve and Legacy.

---

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.

---

Collision

• Example:

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

• Attributes:

  • Name: Required. Suxffixed 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. Suxffixed 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="D_04002040" Count="24" Offset="0x2040">
    <Vector Type="s16" Dimensions="3" />
</Array>

Will be extracted as:

Vec3s D_04002040[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. Suxffixed 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. Suxffixed by Vtx.

※ Can be wrapped in an Array tag.

---

Mtx

• Example:

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

• Attributes:

  • Name: Required. Suxffixed 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. Suxffixed 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 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. Suxffixed by Path.
  • NumPaths: Optional. The amount of paths contained in the array. It must be a positive integer.

---