> For the complete documentation index, see [llms.txt](https://developers.wiki.resourcefulbees.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.wiki.resourcefulbees.com/formats/readme.md).

# Overview

Resourceful Bees uses several top-level JSON formats for defining reusable game content. The four primary formats documented here are **Bees**, **Honeys**, **Traits**, and **Honeycombs**. Each format has its own loader behavior and nested data structure, but they are designed to work together: bees can reference honeycomb variations and traits, while honey and honeycomb definitions provide reusable outputs and content shared across multiple bees.

## Bees

[Bee definitions](broken://pages/UPgxhxuxuaYGPc0sYtTe) describe the behavior, appearance, breeding, mutation, traits, and trade configuration of a custom bee.

Bee JSON is a flat map of versioned serializer IDs rather than a single monolithic object. Built-in sections include:

* `resourcefulbees:core/v1` for pollination targets, hive timing, lore, and honeycomb variation
* `resourcefulbees:combat/v1` for aggression and entity attributes
* `resourcefulbees:rendering/v1` for layers, colors, models, textures, animation, and size
* `resourcefulbees:mutation/v1` for mutation output configuration
* `resourcefulbees:breeding/v1` for breeding families, feed items, and delays
* `resourcefulbees:trait/v1` for attaching standalone traits and configuring aura range
* `resourcefulbees:trade/v1` for beekeeper trade configuration

The bee identifier itself is supplied by the loader/file context rather than by a root JSON `id` field. Serializer sections are largely optional unless the specific serializer codec requires a field when that section is present.

## Honeys

[Honey definitions](broken://pages/NS3aY1V29fW97npX9001) configure the block, fluid, and bottled forms associated with a custom honey.

Honey JSON is also a versioned serializer map. The built-in sections are:

* `resourcefulbees:block/v1` for honey-block properties such as color, movement factors, replacement block/item, and trade data
* `resourcefulbees:fluid/v1` for fluid rendering, physical attributes, sounds, rarity, and trade data
* `resourcefulbees:bottle/v1` for bottled-honey color, food behavior, potion effects, rarity, replacement item, and trade data

The bottle serializer is required by the current schema; block and fluid serializers are optional. The honey identifier/name comes from the file context rather than a root `name` field.

## Traits

[Standalone trait definitions](broken://pages/1m72I6uiDbtjoAI9fPro) describe reusable behavior that can be attached to bees through the bee trait serializer.

Trait JSON can configure:

* the display item
* potion-based damage effects
* damage immunities
* potion immunities
* custom damage-type entries
* special abilities
* particles
* one or more auras

Most top-level trait fields are optional and default to empty collections or codec-defined defaults. Trait files are reusable: multiple bees can reference the same trait identifier rather than duplicating the behavior in each bee definition.

## Honeycombs

[Honeycomb definitions](broken://pages/j5pbSwMFAE527D0biTjd) configure registered honeycomb content and the output variations used by bees and hive/apiary processing.

A honeycomb file can contain two major sections:

* `honeycomb` for registration properties such as name override, color, edible/block/enchanted flags, and trade data
* `variations` for reusable output mappings, including hive-tier outputs, apiary-tier outputs, a default comb, and a default comb block

Both sections are optional at the top-level codec, and `variations` defaults to an empty list. Honeycomb variation identifiers are what bee core data uses through `honeycombVariation`.

## How the formats relate

A typical custom-content setup may use all four formats together:

1. Define a **Honeycomb** and one or more output variations.
2. Optionally define a reusable **Honey** with block, fluid, and bottle behavior.
3. Define reusable **Traits** for special bee behavior.
4. Define the **Bee**, referencing the honeycomb variation and any traits it should use.

Recipes and biome modifiers are documented separately because they are datapack-style integration formats rather than primary content-registration files.

## Detailed reference

Use the child pages in this section for field-level documentation, including required/optional status, defaults, ranges, accepted compact forms, and runtime/codec caveats. Machine-readable templates and Draft 2020-12 schemas are available in the [JSON Schemas and Templates](https://github.com/Team-Resourceful/wiki/tree/main/resourcefulbees/reference/README.md) section.