add-asset-to-yaml

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:

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

These should be converted to use asset references:

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>:

grep "_45B130:" snowboardkids2.yaml

The asset may exist as:

• A named asset:

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

• An unnamed bin entry:

  - [0x45B130, bin]
  

2. Add or convert the asset in snowboardkids2.yaml

If it's an unnamed bin entry:

Convert it to a named asset:

- 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:

- 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:

#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:

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

After:

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

./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:

- 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