### Quick Start and Installation

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Commands to install the tool and perform a basic disassembly and build process.

```bash
# 1. Install
cd snes2asm
sudo python setup.py install

# 2. Basic disassembly
snes2asm -o my_project rom.sfc

# 3. Build the project
cd my_project
make

# 4. Test in your emulator
# Output is my_project/game.smc
```

```bash
cd snes2asm
sudo python setup.py install
```

--------------------------------

### Example Usage

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Example command to disassemble specific banks of a ROM.

```bash
snes2asm -b 0 1 -o output_dir snes2asm/tests/classickong.smc
```

--------------------------------

### YAML Configuration Example

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Example configuration file for defining labels, memory addresses, and data decoders.

```yaml
---
# ROM label addresses for code and generic data
labels:
  snesinit: 0x2
# Memory address locations
memory:
  lives: 0x60
  snes_joypad_state: 0x7E2008
# Structured data for decoding
decoders:
- type: data
  label: hdmaGradient0List0
  start: 0x8A00
  end: 0x8B00
```

--------------------------------

### Configurator Class Usage

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Demonstrates initializing the Configurator class, which parses YAML files for custom asset extraction decoders. This is a partial example showing setup.

```python
from snes2asm.cartridge import Cartridge
from snes2asm.disassembler import Disassembler
from snes2asm.configurator import Configurator

# Load ROM
cart = Cartridge({})
cart.open('game.sfc')

options = type('Options', (), {'hex': False, 'nolabel': False})
disasm = Disassembler(cart, options)

```

--------------------------------

### Load and Apply YAML Configuration

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Load a YAML configuration file and apply it to the disassembler instance. This is the initial setup step before running the disassembly.

```python
config = Configurator('game_config.yaml')
config.apply(disasm)
```

--------------------------------

### Tilemap Decoder Examples

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Configures tilemap extraction, specifying tile dimensions, graphics reference, and map width. The second example shows a tilemap with explicit width and graphics reference.

```yaml
decoders:
  - type: tilemap
    label: bg_tiles_level1
    start: 0x2f940
    end: 0x2f960
```

```yaml
decoders:
  - type: tilemap
    label: bg_tiles_level1
    start: 0x46000
    end: 0x46800
    width: 32
    gfx: sprites1_gfx
```

--------------------------------

### Array Decoder Examples

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Defines structured data arrays. The first example shows a basic array of 16-bit integers. The second demonstrates an array with named fields and bitfield support.

```yaml
decoders:
  # Basic array of 16-bit integers with 256 elements
  - type: array
    label: enemy_stats
    start: 0x1000
    end: 0x1200
    size: 2
```

```yaml
decoders:
  # Array with structured fields
  - type: array
    label: enemy_stats
    start: 0x30000
    end: 0x30028  # 4 enemies * 10 bytes each
    struct:
      hp: 1
      attack: 1
      defense: 1
      sprite_id: 2
      ai_type: 1
      flags:
        size: 2
        bitfields:
          can_fly: {bit: 0}
          is_boss: {bit: 1}
          palette: {bits: "2-4", mask: 0x001C, shift: 2}
      drop_item: 2
```

--------------------------------

### Palette Decoder Example

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Defines a SNES color palette by specifying its start and end ROM offsets. This palette can then be referenced by graphic decoders.

```yaml
decoders:
  # Extract palette
  - type: palette
    label: sprites1_pal
    start: 0x2f940
    end: 0x2f960
```

--------------------------------

### YAML Configuration: Sound Decoder

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define a BRR audio sample, specifying its start and end addresses.

```yaml
  # BRR audio sample
  - type: sound
    label: jump_sfx
    start: 0x30000
    end: 0x30200
```

--------------------------------

### Configure Sound Decoders

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define sound assets to be extracted from the ROM using their labels, start and end addresses, and sample rates.

```yaml
decoders:
  - type: sound
    label: explosion_sfx
    start: 0x40000
    end: 0x40400
    rate: 32000  # Sample rate in Hz

  - type: sound
    label: music_sample
    start: 0x40400
    end: 0x40800
```

--------------------------------

### Graphics Decoder Example

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Extracts SNES graphics data with a specified bit depth and references a previously defined palette. Ensure the palette is defined before this.

```yaml
decoders:
  # Extract graphics with palette reference
  - type: gfx
    label: sprites1_gfx
    start: 0x2bc60
    end: 0x2c860
    bit_depth: 4
    palette: sprites1_pal
```

--------------------------------

### YAML Configuration: GFX Decoder

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define graphics tiles, supporting various bit depths and referencing palettes. This example shows 4bpp graphics.

```yaml
  # 4bpp graphics with palette reference
  - type: gfx
    label: player_sprites
    start: 0x10020
    end: 0x10820
    bit_depth: 4
    palette: sprite_palette
    width: 128
```

--------------------------------

### Run Disassembler and Get Output (Disassembler Class)

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Executes the disassembly process and retrieves the generated assembly code for a specific bank or the support code.

```python
# Run the disassembler
disasm.run()

# Get assembly code for a specific bank
bank0_code = disasm.bank_code(0)

# Get support code (memory definitions, etc.)
support_code = disasm.support_code()
```

--------------------------------

### Array Decoder: Simple Array

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define a simple array of 16-bit values. Specify the start and end addresses and the size of each element.

```yaml
decoders:
  # Simple array of 16-bit values
  - type: array
    label: pointer_table
    start: 0x5000
    end: 0x5100
    size: 2
```

--------------------------------

### Text Decoder: Menu Strings with Index

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define menu strings extraction using a translation table and an index table for variable-length strings. The index table specifies the start, end, and size of pointers.

```yaml
  # Text with index table for variable-length strings
  - type: text
    label: menu_strings
    start: 0x12100
    end: 0x13000
    translation: game_charset
    index:
      start: 0x12000
      end: 0x12100
      size: 2
```

--------------------------------

### Index Decoder: Jump Table

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define an index table that automatically looks up labels for referenced addresses. Specify the start, end, and element size.

```yaml
labels:
  routine_a: 0x8100
  routine_b: 0x8200
  routine_c: 0x8300

decoders:
  # Index table with automatic label lookup
  - type: index
    label: jump_table
    start: 0x8000
    end: 0x8006
    size: 2
```

--------------------------------

### SPC700 Audio Decoder: Main

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define the SPC700 audio processor disassembly, including start address, custom labels, and nested decoders for data within the audio code.

```yaml
decoders:
  - type: spc700
    label: audio_driver
    start: 0x20000
    end: 0x20800
    start_addr: 0x0200
    labels:
      0x0000: main
      0x0040: process_commands
      0x0100: play_note
    decoders:
      # Nested data within SPC700 code
      - type: array
        label: volume_table
        start: 0x0500
        end: 0x0600
        size: 1
      - type: sound
        label: sample_kick
        start: 0x0600
        end: 0x0700
```

--------------------------------

### Define Sound Decoder for BRR Audio

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Use the 'sound' decoder type to extract BRR audio samples. Specify the start and end addresses of the audio data.

```yaml
decoders:
  - type: sound
    label: sample_brr
    start: 0x20800
    end: 0x20B84
```

--------------------------------

### Project Compilation

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Steps to compile the disassembled project using make.

```bash
cd output_dir
# Edit Makefile PREFIX to point to your wla-dx install path
make
# Done! Run the output_dir/game.smc file in your emulator.
```

--------------------------------

### CLI Usage and Options

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Displays the command line interface options for the snes2asm tool.

```text
usage: snes2asm [-h] [-v] [-o OUTPUT_DIR] [-c CONFIG] [-b BANKS [BANKS ...]]
                [-hi] [-lo] [-f] [-s] [-nl] [-x] snes.sfc

Disassembles snes cartridges into practical projects

positional arguments:
  snes.sfc              input snes file

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         Verbose output
  -o OUTPUT_DIR, --output_dir OUTPUT_DIR
                        File path to output project
  -c CONFIG, --config CONFIG
                        Path to decoding configuration yaml file
  -b BANKS [BANKS ...], --banks BANKS [BANKS ...]
                        Code banks to disassemble. Default is auto-detect
  -hi, --hirom          Force HiROM
  -lo, --lorom          Force LoROM
  -f, --fastrom         Force fast ROM addressing
  -s, --slowrom         Force slow ROM addressing
  -nl, --nolabel        Use addresses instead of labels
  -x, --hex             Comments show instruction hex
```

--------------------------------

### Generate Assembly Project Files (ProjectMaker Class)

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Creates a complete, reassemblable assembly project structure including Makefile, header files, and bank assembly files, ready for compilation with WLA-DX.

```python
from snes2asm.cartridge import Cartridge
from snes2asm.disassembler import Disassembler
from snes2asm.project_maker import ProjectMaker

# Disassemble ROM
cart = Cartridge({})
cart.open('game.sfc')

options = type('Options', (), {'hex': False, 'nolabel': False})
disasm = Disassembler(cart, options)
disasm.run()

# Generate project files
project = ProjectMaker(cart, disasm)
project.output('output_dir')
```

--------------------------------

### Build Disassembled SNES Projects with WLA-DX and Make

Source: https://context7.com/nathancassano/snes2asm/llms.txt

After disassembling a SNES ROM using 'snes2asm', navigate to the generated project directory and use 'make' to rebuild the ROM. Ensure the output matches the original.

```bash
# Disassemble with configuration
snes2asm -c game.yaml -o my_project game.sfc

# Build the project
cd my_project
make

# Output: my_project/game.smc
# Test in emulator to verify identical output
```

--------------------------------

### YAML Configuration: Basic Settings

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define executable code banks, named code labels, and RAM variable symbols in the YAML configuration.

```yaml
---
# Code banks to treat as executable (others are data-only)
banks: [0, 1, 2, 3]

# Named code labels
labels:
  main_loop: 0x8000
  nmi_handler: 0x8100
  read_joypad: 0x8200

# RAM variable symbols
memory:
  player_x: 0x7E0010
  player_y: 0x7E0012
  health: 0x7E0014
```

--------------------------------

### Process Sample ROM with SNES2ASM

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Command-line usage for processing a sample ROM using a specified configuration file. This involves running SNES2ASM, changing into the output directory, and building the extracted assets.

```bash
snes2asm -c snes2asm/tests/classickong.yaml -o classickong snes2asm/tests/classickong.smc
cd classickong
make
```

--------------------------------

### Manage SNES Compression Algorithms with Python

Source: https://context7.com/nathancassano/snes2asm/llms.txt

The 'compression' module allows listing available algorithms, decompressing data, and compressing data. Specific algorithms can also be imported and used directly.

```python
from snes2asm import compression

# List available compression algorithms
algorithms = compression.get_names()
# ['aplib', 'byte_rle', 'hal', 'lz1', 'lz19', 'lz2', 'lz3', 'lz4', 'lz5', 'lz77', 'rle1', 'rle2']

# Decompress data
compressed_data = b'\x...'
decompressed = compression.decompress('lz3', compressed_data)

# Compress data
raw_data = b'\x...'
compressed = compression.compress('lz3', raw_data)

# Use specific algorithm directly
from snes2asm.compression import lz2

decompressed = lz2.decompress(compressed_data)
compressed = lz2.compress(raw_data)
```

--------------------------------

### Initialize Disassembler and Set Options (Disassembler Class)

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Initializes the Disassembler class with a Cartridge object and custom options. The options object mimics command-line flags.

```python
from snes2asm.cartridge import Cartridge
from snes2asm.disassembler import Disassembler

# Initialize cartridge and disassembler
cart = Cartridge({})
cart.open('game.sfc')

options = type('Options', (), {
    'hex': False,
    'nolabel': False
})()

disasm = Disassembler(cart, options)
```

--------------------------------

### Load ROM with Automatic Detection (Cartridge Class)

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Initializes the Cartridge class and opens a ROM file, automatically detecting its type (LoROM/HiROM).

```python
from snes2asm.cartridge import Cartridge

cart = Cartridge({})
cart.open('game.sfc')
```

--------------------------------

### Run Disassembly

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Execute the disassembly process using the currently applied configuration. This should be called after loading and applying the configuration.

```python
disasm.run()
```

--------------------------------

### Verbose Disassembly with Hex Comments CLI

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Enables verbose output and hex comments during disassembly. Useful for detailed analysis.

```bash
snes2asm -v -x -o output_dir game.sfc
```

--------------------------------

### Access ROM Data and Properties (Cartridge Class)

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Demonstrates accessing raw ROM data via slicing and retrieving cartridge properties like size, bank count, and title.

```python
# Access ROM data directly
first_byte = cart[0x0000]
bank_slice = cart[0x8000:0x8100]

# Get ROM properties
print(f"ROM Size: {cart.size()} bytes")
print(f"Bank Count: {cart.bank_count()}")
print(f"Bank Size: {cart.bank_size()}")
print(f"HiROM: {cart.hirom}")
print(f"FastROM: {cart.fastrom}")
print(f"Title: {cart.title}")
print(f"Country: {cart.country}")
```

--------------------------------

### Output Directory Structure

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

The file structure generated by the disassembler.

```text
output_dir/
├── Makefile              # Build configuration
├── bank_00.asm           # Bank 0 assembly code
├── bank_01.asm           # Bank 1 assembly code
├── ...                   # Additional banks
├── sprites1_gfx.chr      # Extracted graphics
├── sprites1_gfx.png      # PNG preview (if palette provided)
├── sprites1_pal.pal      # Extracted palettes
├── spc700.S              # SPC700 assembly (if configured)
└── game.smc              # Reassembled ROM (after make)
```

--------------------------------

### Sound Decoder Configuration

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Extracts a BRR audio sample from the specified ROM range.

```yaml
  # Extract BRR audio sample
  - type: sound
    label: sample_brr
    start: 0x20800
    end: 0x20B84
```

--------------------------------

### Graphics Decoder: Palette

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define a background palette with 32 colors. Palettes should be defined before any graphics that use them.

```yaml
decoders:
  # Define palette first
  - type: palette
    label: bg_palette
    start: 0x8000
    end: 0x8040  # 32 colors
```

--------------------------------

### Force LoROM Mode with Fast ROM Addressing CLI

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Forces LoROM mode and enables fast ROM addressing. Use when the ROM is known to be LoROM and benefits from faster access.

```bash
snes2asm -lo -f -o output_dir game.sfc
```

--------------------------------

### Pack and Unpack Files with SNES Compression using packer

Source: https://context7.com/nathancassano/snes2asm/llms.txt

The 'packer' command-line tool compresses and decompresses files using various SNES compression algorithms. Specify the algorithm with the '-x' flag.

```bash
# Compress a file with LZ3
packer pack input.bin -x lz3 -o output.lz3

# Decompress a file
packer unpack input.lz3 -x lz3 -o output.bin

# Available algorithms: aplib, byte_rle, rle1, rle2, lz1, lz2, lz3, lz4, lz5, lz19, lz77, hal
packer pack data.bin -x hal -o data.hal
```

--------------------------------

### Basic Disassembly with SNES2ASM CLI

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Use this command for basic ROM disassembly with automatic ROM type detection. Specify the output directory with -o.

```bash
snes2asm -o my_project game.sfc
```

--------------------------------

### YAML Configuration: Palette Decoder

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define a palette for use with graphics decoders. Palettes must be defined before graphics that reference them.

```yaml
# Asset decoders
decoders:
  # Palette must be defined before graphics that reference it
  - type: palette
    label: sprite_palette
    start: 0x10000
    end: 0x10020
```

--------------------------------

### Address Translation (Cartridge Class)

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Shows how to translate between SNES addresses and ROM offsets using the Cartridge class methods.

```python
# Address translation
rom_index = cart.index(0x008000)  # Address to ROM offset
address = cart.address(0x0000)     # ROM offset to address
```

--------------------------------

### Tilemap Decoder with LZ3 Compression

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Configure a 'tilemap' decoder to extract tilemap data, specifying 'lz3' as the compression algorithm. This decoder also requires tile size, width, and start/end addresses.

```yaml
decoders:
  - type: tilemap
    label: map1
    compress: lz3
    tilesize: 8x8
    width: 32
    start: 0x137AB
    end: 0x139B7
```

--------------------------------

### Specify Code Banks for Disassembly (Disassembler Class)

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Sets the specific ROM banks to be disassembled as code. Other banks will be treated as data by default.

```python
# Set specific banks to disassemble as code (others become data)
disasm.code_banks = [0, 1, 2]
```

--------------------------------

### Decode and Encode BRR Audio with Python

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Use the 'brr' module to convert SNES BRR audio files to WAV format and vice versa. Ensure files are opened in binary mode.

```python
from snes2asm import brr

# Decode BRR to WAV
with open('sample.brr', 'rb') as f:
    brr_data = f.read()

wav_data = brr.decode(brr_data, rate=32000)

with open('sample.wav', 'wb') as f:
    f.write(wav_data)

# Encode WAV to BRR
with open('input.wav', 'rb') as f:
    wav_data = f.read()

brr_data = brr.encode(wav_data)

with open('output.brr', 'wb') as f:
    f.write(brr_data)
```

--------------------------------

### Disassembly with Custom Asset Extraction Config CLI

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Performs disassembly using a custom YAML configuration file for asset extraction. Essential for games with complex or non-standard assets.

```bash
snes2asm -c config.yaml -o output_dir game.sfc
```

--------------------------------

### YAML Configuration: Tilemap Decoder

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define a compressed tilemap, specifying compression type, dimensions, and associated graphics.

```yaml
  # Compressed tilemap
  - type: tilemap
    label: level1_map
    start: 0x20000
    end: 0x22000
    compress: lz3
    width: 32
    gfx: player_sprites
```

--------------------------------

### Force HiROM Mode and Specify Code Banks CLI

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Forces HiROM mode and allows specifying code banks to disassemble. Use for ROMs where automatic detection might fail.

```bash
snes2asm -hi -b 0 1 2 3 -o output_dir game.sfc
```

--------------------------------

### Bitfield Syntax and Output

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Defines bitfield extraction rules and the resulting assembly output for WLA-DX.

```yaml
field_name:
  size: 2  # Total field size in bytes
  bitfields:
    subfield1: {bits: "0-9", mask: 0x03FF}           # Bit range
    subfield2: {bit: 10}                             # Single bit
    subfield3: {bits: "12-14", mask: 0x7000, shift: 12}  # With custom shift
```

```asm
.dw ($042 << 0) | (1 << 10) | (7 << 12)  ; field_name: subfield1=$042 subfield2=1 subfield3=7
```

--------------------------------

### Add Custom Labels and Memory Names (Disassembler Class)

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Adds custom labels at specific ROM offsets and assigns names to memory locations. Useful for improving disassembly readability.

```python
# Add custom labels at specific ROM offsets
disasm.label_name(0x0000, "reset_vector")
disasm.label_name(0x0100, "nmi_handler")

# Add memory variable names
disasm.set_memory(0x7E0000, "player_x")
disasm.set_memory(0x7E0002, "player_y")
```

--------------------------------

### Index Decoder with Label Lookup

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Configures an index table that automatically resolves addresses to labels.

```yaml
labels:
  music_game_start: 0xA020
  music_game_end:   0xA040
decoders:
  # Index table with automatic label lookup
  - type: index
    label: music_table
    start: 0x50000
    end: 0x50006  # 3 entries * 2 bytes
    size: 2
```

```asm
music_table:
music_table_0:
    .dw music_game_start  ; Address matched label
music_table_1:
    .dw music_game_end    ; Address matched label
music_table_2:
    .dw $7FFF             ; No label, uses hex
```

--------------------------------

### Disassembly Using Addresses Instead of Labels CLI

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Disassembles the ROM using memory addresses instead of generated labels. Useful for specific debugging scenarios or when label generation is not desired.

```bash
snes2asm -nl -o output_dir game.sfc
```

--------------------------------

### Convert BMP to SNES CHR Tiles with bmp2chr

Source: https://context7.com/nathancassano/snes2asm/llms.txt

The 'bmp2chr' command-line tool converts indexed bitmap images into SNES CHR tile data. Options include specifying bits per pixel (bpp), palette export, and linear format.

```bash
# Convert to 4bpp (16 colors) - defaultmp2chr input.bmp -o output.chr

# Convert to 2bpp (4 colors)mp2chr input.bmp -b2 -o output.chr

# Convert to 8bpp (256 colors)mp2chr input.bmp -b8 -o output.chr

# Export palette filemp2chr input.bmp -o output.chr -p

# Linear format instead of planarmp2chr input.bmp -l4 -o output.chr

# Ignore destination file size limitsmp2chr input.bmp -o output.chr -f
```

--------------------------------

### Graphics Decoder: 2bpp GFX

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define 2bpp graphics tiles with 4 colors, specifying the width.

```yaml
  # 2bpp graphics (4 colors)
  - type: gfx
    label: font_tiles
    start: 0xB000
    end: 0xB400
    bit_depth: 2
    width: 128
```

--------------------------------

### Force LoROM and FastROM (Cartridge Class)

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Initializes the Cartridge class, forcing LoROM mode and fast ROM timing. Use for known LoROM games that support fast ROM access.

```python
cart_lo = Cartridge({'lorom': True, 'fastrom': True})
cart_lo.open('game.sfc')
```

--------------------------------

### Force HiROM Mode (Cartridge Class)

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Initializes the Cartridge class and forces HiROM mode when opening a ROM file. Use when automatic detection is incorrect.

```python
cart_hi = Cartridge({'hirom': True})
cart_hi.open('game.sfc')
```

--------------------------------

### Specify Code Banks in ROM

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Explicitly define the bank numbers in a ROM that contain executable code. Other banks will be disassembled as data only. Omitting this option allows for automatic code tracing.

```yaml
banks: [0, 1, 2, 3, 4, 5, 8]
```

--------------------------------

### Graphics Decoder: 4bpp GFX

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define 4bpp graphics tiles with 16 colors, referencing a specific palette and setting the width.

```yaml
  # 4bpp graphics (16 colors)
  - type: gfx
    label: background_tiles
    start: 0x9000
    end: 0xB000
    bit_depth: 4
    palette: bg_palette
    width: 128
```

--------------------------------

### Text Decoder Configuration

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Defines a text decoder linked to a translation table and an index table.

```yaml
- type: text
  label: dialog1_text
  start: 0x80400
  end: 0x88000
  translation: default
  index:
    start: 0x80000
    end: 0x80400
```

--------------------------------

### Graphics Decoder: Compressed GFX

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define compressed graphics tiles, specifying the compression type, bit depth, and palette.

```yaml
  # Compressed graphics
  - type: gfx
    label: compressed_sprites
    start: 0xE000
    end: 0xF000
    compress: lz2
    bit_depth: 4
    palette: bg_palette
```

--------------------------------

### Define Palette Decoder

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Use the 'palette' decoder type to extract palette data. This decoder must be defined before any graphics decoders that reference the palette.

```yaml
decoders:
  - type: palette
    label: sprites1_pal
    start: 0x2f940
    end: 0x2f960
```

--------------------------------

### Translation Decoder Configuration

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Defines a character translation table and applies it to a text decoder.

```yaml
decoders: 
  # Define character translation table
  - type: translation
    label: default
    table:
      0x0: "A"
      0x1: "B"
      0x2: "Long string"

  # Extract text using translation table
  - type: text
    label: dialog
    translation: default
    start: 0x10000
    end: 0x10010
```

--------------------------------

### SPC700 Decoder with Nested Decoders

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Disassembles SPC700 audio code and extracts embedded data tables using nested decoders.

```yaml
decoders:
  # Disassemble SPC700 audio driver with nested data
  - type: spc700
    label: audio_driver
    start: 0x20000
    end: 0x20533
    start_addr: 0x0200
    labels:
      0x0000: main
      0x0040: loop
      0x0100: handleInput
    decoders:
      - type: array
        label: divTable
        start: 0x390  # Relative to SPC700 start
        end: 0x410
        size: 2
      - type: array
        label: vibratoTable
        start: 0x410
        end: 0x510
```

--------------------------------

### Struct Decoder Configuration

Source: https://github.com/nathancassano/snes2asm/blob/main/README.md

Defines a standalone struct decoder for level headers with bitfield sub-fields.

```yaml
decoders:
  # Standalone struct decoder for level headers
  - type: struct
    label: level_headers
    start: 0x40000
    end: 0x40020
    count: 4  # 4 levels
    fields:
      width: 1
      height: 1
      tileset_id: 2
      music_id: 1
      bg_color:
        size: 2
        bitfields:
          red: {bits: "0-4", mask: 0x001F}
          green: {bits: "5-9", mask: 0x03E0, shift: 5}
          blue: {bits: "10-14", mask: 0x7C00, shift: 10}
```

--------------------------------

### Struct Decoder: Standalone Struct

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define a standalone struct with named fields and bitfield definitions. Specify the count, and fields with their sizes and bitfield configurations.

```yaml
  # Standalone struct decoder
  - type: struct
    label: level_header
    start: 0x7000
    end: 0x7020
    count: 4
    fields:
      width: 1
      height: 1
      tileset_id: 2
      music_id: 1
      bg_color:
        size: 2
        bitfields:
          red: {bits: "0-4", mask: 0x001F}
          green: {bits: "5-9", mask: 0x03E0, shift: 5}
          blue: {bits: "10-14", mask: 0x7C00, shift: 10}
```

--------------------------------

### Text Decoder: Translation Table

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define a custom character encoding translation table for use with the TextDecoder. Map byte values to characters or strings.

```yaml
decoders:
  # Define translation table
  - type: translation
    label: game_charset
    table:
      0x00: "A"
      0x01: "B"
      0x02: "C"
      0x10: " "
      0x11: "."
      0x12: "!"
      0xFF: "[END]"
```

--------------------------------

### Array Decoder: Structured Array

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define an array with structured elements, including nested bitfields. Each field can have a size and bitfield definitions.

```yaml
  # Array with structured elements
  - type: array
    label: enemy_data
    start: 0x6000
    end: 0x6050
    struct:
      hp: 1
      attack: 1
      defense: 1
      sprite_id: 2
      ai_flags:
        size: 2
        bitfields:
          can_fly: {bit: 0}
          is_boss: {bit: 1}
          element: {bits: "2-4", mask: 0x001C, shift: 2}
      drop_rate: 1
```

--------------------------------

### Text Decoder: Dialog Text

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define dialog text extraction using a specified translation table. This decoder handles variable-length strings.

```yaml
  # Text with translation
  - type: text
    label: dialog_text
    start: 0x10000
    end: 0x11000
    translation: game_charset
```

--------------------------------

### Graphics Decoder: Mode 7 GFX

Source: https://context7.com/nathancassano/snes2asm/llms.txt

Define Mode 7 graphics, referencing a palette. Mode 7 is a special graphics mode for SNES.

```yaml
  # Mode 7 graphics
  - type: gfx
    label: mode7_bg
    start: 0xC000
    end: 0xE000
    mode7: true
    palette: bg_palette
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.