path: root/tools/assets/descriptor/spec.md

This document describes the expected structure of xml files describing assets.

# Top elements

## `Root`

```xml
<Root>
    ...
</Root>
```

This is the root element in the file, containing exclusively `<File>` and `<ExternalFile>` elements as direct children.

## `File`

```xml
<File Name="baserom_file" Segment="11">
    ...
</File>
```

A `<File>` contains resources elements as children.

- Required attributes: `Name`
- Optional attributes: `Segment`

`Name` is the name of the baserom file from which the data is to be extracted.

`Segment` (decimal) is the segment number for the file.

## `ExternalFile`

```xml
<ExternalFile OutPath="assets/name"/>
```

Declare the `<File>`s in the xml may reference symbols from an external file.

The external file is located by matching its name against the list of assets in the version's `config.yml`.

For example, `baseroms/gc-eu/config.yml` contains

```yml
assets:
- name: objects/gameplay_keep
  xml_path: assets/xml/objects/gameplay_keep.xml
```

then `<ExternalFile OutPath="assets/objects/gameplay_keep/"/>` refers to that gameplay_keep entry, which uses the `gameplay_keep.xml` xml file when extracting assets for version gc-eu.


# Resource elements

Resource elements describe resources. Resources are pieces of data corresponding to a symbol each.

One attribute is required on all resource elements: `Name`.

- `Name` is the name of the symbol associated to the resource.

Another attribute, optional, is common to all resource elements: `Offset`.

If `Offset` is set to a (hexadecimal) number such as `Offset="0x421"`, it specifies the location of the resource in bytes from the start of the file data.

If `Offset` is not set, the resource is assumed to start where the previous resource ended, or at 0 if the resource is the first in the `<File>`.

`Offset` can also be set to be a relative offset like `Offset=".+0x421"`, which makes the resource location be that many bytes after the end of the previous resource.

## `Blob`

```xml
<Blob Name="gNameBlob" Size="0x421" Offset="0x1230">
```

Unstructured binary data.

- Required attributes: `Size`

`Size` is the size of the binary blob in bytes.

## `DList`

```xml
<DList Name="gNameDL" Offset="0x1230" Length="123" Ucode="f3dex2" RawPointers="0x08000000,0x09000000"/>
```

A display list.

- Optional attributes: `Length`, `Ucode`, `RawPointers`

`Length` can be set to indicate the length (amount of `Gfx` double-words) of the dlist. If not set, the dlist length is automatic.

`Ucode` (defaults to `f3dex2`) picks the graphics microcode for which to disassemble the dlist. It may be `f3dex` or `f3dex2`.

`RawPointers` (defaults to an empty value) is a comma-separated list of values the display list uses as raw pointers ("hex" instead of a symbol). The purpose of this attribute is to silence extraction warnings.

## `Mtx`

```xml
<Mtx Name="gNameMtx" Offset="0x1230"/>
```

A fixed-point matrix.

## `Texture`

```xml
<Texture Name="gNameTex" Format="rgba16" Width="16" Height="16" Offset="0x1230"/>
<Texture Name="gNameTex" Format="ci8" Width="16" Height="16" Offset="0x1230" Tlut="gNameTLUT"/>
<Texture Name="gNameTex" Format="ci8" Width="16" Height="16" Offset="0x1230" TlutOffset="0x2340"/>
<Texture Name="gNameTex" Format="ci8" Width="16" Height="16" Offset="0x1230" ExternalTlut="baserom_file" ExternalTlutOffset="0x2340"/>
```

A texture, an image in one of the native N64 formats.

- Required attributes for all formats: `Format`, `Width`, `Height`
- Required attributes for CI formats (`ci4`, `ci8`): `Tlut`, or `TlutOffset`, or `ExternalTlut` and `ExternalTlutOffset`

`Format` is the format of the texture, one of `rgba32`, `rgba16`, `i4`, `i8`, `ia4`, `ia8`, `ia16`, `ci4` or `ci8`.

`Width` and `Height` specify the dimensions of the texture.

For CI formats, the TLUT (Texture Look Up Table, or palette) must be specified with either `Tlut` or `TlutOffset` if the TLUT is in the same file as the texture, or both of `ExternalTlut` and `ExternalTlutOffset` if the TLUT is in a different file. `ExternalTlut` is the name of the baserom file where the TLUT is. In both cases, the TLUT must also be declared as a resource.

## `Array`

```xml
<Array Name="gNameVtx" Count="42" Offset="0x1230">
    <Vtx/>
</Array>
<Array Name="gNameVec3sArray" Count="42" Offset="0x1230">
    <Vector Type="s16" Dimensions="3"/>
</Array>
<Array Name="gNameS16Array" Count="42" Offset="0x1230">
    <Scalar Type="s16"/>
</Array>
```

An array of vertices, vectors or scalars. The child element determines the array's element type.

- Required attributes: `Count`

`Count` is the length of the array.

The child element may be one of `<Vtx/>` (for `Vtx[]`), `<Vector Type="s16" Dimensions="3"/>` (for `Vec3s[]`) or `<Scalar Type="s16">` (for `s16[]`).

## `Scene`

```xml
<Scene Name="name" Offset="0x1230"/>
```

Scene commands.

## `Room`

```xml
<Room Name="name" Offset="0x1230"/>
```

Room commands.

## `Collision`

```xml
<Collision Name="gNameCol" Offset="0x1230"/>
```

Collision header.

## `Cutscene`

```xml
<Cutscene Name="gNameCs" Offset="0x1230"/>
```

Cutscene script.

## `Path`

```xml
<Path Name="gNamePathList" Offset="0x1230" NumPaths="12"/>
```

Path list.

- Required attributes: `NumPaths`

`NumPaths` is the length of the path list.

## `Skeleton`

```xml
<Skeleton Name="gNameSkel" Type="Normal" LimbType="Standard" LimbNone="NAME_LIMB_NONE" LimbMax="NAME_LIMB_MAX" EnumName="NameLimb" Offset="0x1230"/>
```

Skeleton header.

- Required attributes: `Type`, `LimbType`
- Optional attributes: `LimbNone`, `LimbMax`, `EnumName`

`Type` is the type of the skeleton, one of `Normal`, `Flex` or `Curve`.

`LimbType` is the type of limb used in the skeleton, one of `Standard`, `LOD`, `Skin`, `Curve` or `Legacy`.

Not all skeleton types are compatible with all limb types:

`LimbType` | Compatible skeleton `Type`
-----------|---------------------------
`Standard` | `Normal`, `Flex`
`LOD`      | `Normal`, `Flex`
`Skin`     | `Normal`
`Curve`    | `Curve`
`Legacy`   | none

`LimbNone`, `LimbMax`, `EnumName` can be set to override the corresponding names in the generated limb enum:

```c
typedef enum NameLimb {
    NAME_LIMB_NONE,
    ...
    NAME_LIMB_MAX
} NameLimb;
```

## `LimbTable`

```xml
<LimbTable Name="gNameLimbs" LimbType="Standard" Count="12" Offset="0x1230"/>
```

Limb table.

- Required attributes: `LimbType`, `Count`

`LimbType` is one of `Standard`, `LOD`, `Skin`, `Curve` or `Legacy`.

`Count` is the amount of limbs.

## `Limb`

```xml
<Limb Name="gNameLimb" LimbType="Standard" EnumName="NAME_LIMB_NAME" Offset="0x1230"/>
```

Limb of a skeleton.

- Required attributes: `LimbType`
- Optional attributes: `EnumName`

`LimbType` is one of `Standard`, `LOD`, `Skin`, `Curve` or `Legacy`.

`EnumName` can be set to override the limb name in the generated limb enum.

## `Animation`

```xml
<Animation Name="gNameAnim" Offset="0x1230"/>
```

Animation header.

## `CurveAnimation`

```xml
<CurveAnimation Name="gNameAnim" SkelOffset="0x120" Offset="0x1230"/>
```

Curve animation header.

- Required attributes: `SkelOffset`

`SkelOffset` is the offset of the skeleton which uses this animation. The skeleton must also be declared as a resource.

## `LegacyAnimation`

```xml
<LegacyAnimation Name="gNameAnim" Offset="0x1230"/>
```

Legacy animation header.

## `PlayerAnimation`

```xml
<PlayerAnimation Name="gNamePlayerAnim" Offset="0x1230"/>
```

Player animation header.

## `PlayerAnimationData`

```xml
<PlayerAnimationData Name="gNamePlayerAnimData" FrameCount="20" Offset="0x1230"/>
```

Player animation data.

- Required attributes: `FrameCount`

`FrameCount` is the amount of frames in the animation.