---
name: add-asset-to-yaml
description: Adding a new asset to snowboardkids2.yaml requires following specific steps to ensure assets are in the correct order and properly declared. Use this skill when you need to add a new binary asset.
---

# Add a new asset to snowboardkids2.yaml

## Overview

Binary assets (data blobs extracted from the ROM) must be defined in `snowboardkids2.yaml` before they can be used in C code via the `USE_ASSET()` macro. This skill documents how to identify when an asset needs to be added and how to add it correctly.

## When to add an asset

You need to add an asset when you see code that uses raw ROM addresses directly, such as:

```c
animationDataStart = (void *)0x0045B130,
animationDataEnd = (void *)0x0045D620,
```

These should be converted to use asset references:

```c
animationDataStart = (void *)&_45B130_ROM_START,
animationDataEnd = (void *)&_45B130_ROM_END,
```

## Steps to add an asset

### 1. Check if the asset already exists

Search `snowboardkids2.yaml` for the asset name. Asset names follow the pattern `_<hex_address>`:

```bash
grep "_45B130:" snowboardkids2.yaml
```

The asset may exist as:

- A named asset:
  ```yaml
  - name: _45B130
    type: bin
    vram: 0
    start: 0x45B130
  ```
- An unnamed bin entry:
  ```yaml
  - [0x45B130, bin]
  ```

### 2. Add or convert the asset in snowboardkids2.yaml

#### If it's an unnamed bin entry:

Convert it to a named asset:

```yaml
- name: _45B130
  type: bin
  vram: 0
  start: 0x45B130
```

#### If the asset doesn't exist:

Add it in **numerical order** with other assets at the same address range. This is critical - the yaml must be in ascending order by start address.

For example, when adding `_45D620` after `_45B130`:

```yaml
- name: _45B130
  type: bin
  vram: 0
  start: 0x45B130

- name: _45D620 # Must come AFTER _45B130 (0x45B130 < 0x45D620)
  type: bin
  vram: 0
  start: 0x45D620
```

### Common Mistakes

#### Out of Order Declaratinos

Adding assets out of order will cause a build error:

```
Error: segments out of order - (_5AD910 starts at 0x5AD910, but next segment starts at 0x5AD1C0)
```

To fix this, ensure assets are sorted by their start address (hexadecimal numerically).

#### Incorrect Asset Size

If an asset is not properly sized then our \_ASSET_ROM_END value will not be correct and the code will not match. We can use unnamed bin entries to ensure the correct size.

For example, if we wanted to insert a 0x20 sized asset named \_45B100 before this asset:

```
  - name: _45B200
    type: bin
    vram: 0
    start: 0x45B130
```

We would need to do:

```
  - name: _45B100
    type: bin
    vram: 0
    start: 0x45B130

  - [0x45B120, bin]

  - name: _45B200
    type: bin
    vram: 0
    start: 0x45B130
```

### 3. Add USE_ASSET declaration

In the C file that uses the asset, add a `USE_ASSET()` declaration after the includes and before any code:

```c
#include "20F0.h"

USE_ASSET(_45B130);
USE_ASSET(_45D620);
// ... more assets ...

typedef struct {
    // ...
} SomeStruct;
```

The `USE_ASSET` declarations should be sorted numerically by address for consistency.

### 4. Update code to use asset references

Replace raw addresses with the asset's `ROM_START` and `ROM_END` symbols:

**Before:**

```c
.animationDataStart = (void *)0x0045B130,
.animationDataEnd = (void *)0x0045D620,
```

**After:**

```c
.animationDataStart = (void *)&_45B130_ROM_START,
.animationDataEnd = (void *)&_45B130_ROM_END,
```

The pattern is:

- Start address → `_<ADDRESS>_ROM_START`
- End address → `_<ADDRESS>_ROM_END`

Note: The `_ROM_END` symbol points to the end of the asset as defined in the yaml, not necessarily the end address used in the original code. The `animationDataSize` field or actual code logic determines how much of the asset is used.

## Validation

After adding assets, verify the build succeeds:

```bash
./tools/build-and-verify.sh
```

Common errors to watch for:

- **Segments out of order**: Assets are not in numerical order by start address
- **Undefined reference**: Missing `USE_ASSET()` declaration
- **Asset not found**: Asset definition missing from yaml

## Example: Adding multiple assets

When adding multiple related assets (e.g., a series of animation data blocks), ensure:

1. All assets are added to yaml in numerical order
2. All assets have `USE_ASSET()` declarations
3. All address pairs in the code are converted to use `ROM_START/ROM_END`

Example batch of assets:

```yaml
- name: _4ED9C0
  type: bin
  vram: 0
  start: 0x4ED9C0

- name: _4F45E0
  type: bin
  vram: 0
  start: 0x4F45E0

- name: _4FDE20
  type: bin
  vram: 0
  start: 0x4FDE20
# ... and so on in ascending order
```

## Tips

- Use `grep` to find all instances of a raw address pattern: `grep -r "0x0045B130" src/`
- When converting many addresses, consider using `sed` for batch replacements
- Always verify the numerical order in yaml - hexadecimal values can be tricky to sort manually
- Null pointers (`0x00000000`) should not be converted to assets