home / skills / plurigrid / asi / nbt

nbt skill

safe

/skills/nbt

This skill helps you encode Minecraft NBT data and text components using the nbt!

npx playbooks add skill plurigrid/asi --skill nbt

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.5 KB

---
name: nbt
description: Use the nbt! macro from mc_protocol for creating NBT (Named Binary Tag) data for Minecraft protocol encoding.
---

# NBT Encoding Skill

Use the `nbt!` macro from `mc_protocol` for creating NBT data.

## When to Use

Use this skill when you need to:
- Encode NBT data for Minecraft packets
- Create text components for chat, action bar, titles
- Build compound NBT structures

## Basic Usage

```rust
use mc_protocol::nbt;

// Simple compound
let compound = nbt! {
    "text" => "Hello",
    "count" => 42i32,
    "flag" => true,
};

// Convert to network bytes
let bytes = compound.to_network_bytes();
```

## Nested Compounds

```rust
use mc_protocol::nbt;

let nested = nbt! {
    "outer" => nbt! {
        "inner" => 123i32,
    },
};
```

## Supported Types

- `i8` - Byte
- `i16` - Short
- `i32` - Int
- `i64` - Long
- `f32` - Float
- `f64` - Double
- `&str` / `String` - String
- `bool` - Byte (0 or 1)
- `NbtCompound` - Nested compound
- `NbtList` - List of same-type elements

## Text Components (Chat/Action Bar)

For Minecraft text components (used in chat, action bar, titles):

```rust
use mc_protocol::nbt;

// Simple text
let text_component = nbt! {
    "text" => "Hello World",
};

// With color
let colored = nbt! {
    "text" => "Red text",
    "color" => "red",
};
```

## Best Practices

1. **Always use the `nbt!` macro** instead of manual byte manipulation
2. Use explicit type suffixes (`42i32`, `1.0f32`) for numeric literals
3. Use `to_network_bytes()` for protocol encoding (adds type tag, no root name)

Overview

This skill shows how to use the nbt! macro from mc_protocol to build Named Binary Tag (NBT) data for Minecraft protocol encoding. It focuses on creating compound structures, nested compounds, lists, and text components for chat or UI. The guidance targets safe, explicit encoding and conversion to network bytes for packet use.

How this skill works

The nbt! macro lets you declare NBT structures in Rust-like literal form: keys map to typed values or nested compounds. Numeric literals should use explicit type suffixes (for example 42i32) so the macro emits the correct NBT tag. After building the NBT value, call to_network_bytes() to get the byte sequence suitable for Minecraft packets.

When to use it

Encoding NBT payloads for Minecraft protocol packets
Constructing text components for chat, action bar, or title packets
Building nested compound structures or typed lists
Creating entity/item/block NBT payloads for server-client communication
Testing or generating deterministic NBT fixtures for protocol code

Best practices

Always prefer nbt! instead of manual byte assembly to avoid tag mistakes
Add explicit numeric type suffixes (e.g., i8, i16, i32, i64, f32, f64)
Represent booleans as bytes (true -> 1, false -> 0) when required
Use nested nbt! blocks to keep complex compound structures readable
Call to_network_bytes() to produce the final encoded bytes for sending

Example use cases

Create a chat text component: nbt!{"text" => "Hello", "color" => "green"}
Encode an item NBT payload with enchantments and custom name
Build nested entity data before sending an update packet
Generate a typed list of ints or compounds for inventory data
Produce network-ready bytes for automated protocol tests

FAQ

What numeric types are supported?

Byte(i8), Short(i16), Int(i32), Long(i64), Float(f32), and Double(f64) are supported. Use explicit suffixes.

How do I produce bytes for sending over the network?

After constructing the NBT value with nbt!, call to_network_bytes() to get the protocol-encoded byte sequence.