Resourceful Bees is designed around data-driven content. A custom bee is not one giant JSON object that must define everything at once; instead, the mod separates reusable content into several formats and lets those pieces work together.
This site documents those formats, the supporting recipes and biome modifiers, and the machine-readable schemas/templates you can use while authoring custom content.
If you are creating your first custom bee, a good workflow is:
Run Resourceful Bees once with default generation enabled. This allows the mod to create its initial folders and default bee definitions.
Set generateDefaults = false in the Resourceful Bees config after that initial run. This is important when you intend to override or customize the default bee variants; leaving default generation enabled can cause the mod's generated defaults to take precedence over or replace your customized default definitions.
Create or customize the bee definition. Start small and rely on defaults where they fit your design.
Add a honeycomb variation if the bee should produce custom comb output.
Add reusable traits if the bee needs special effects, immunities, particles, auras, or other trait behavior.
Add custom honey if you want a reusable block, fluid, or bottled-honey definition.
Add recipes for machine processing or other datapack-driven integrations.
Add biome modifiers if the bee or its nest should participate in world generation or natural spawning.
Validate against the schemas/templates and then test the content in-game.
Important: After the first mod run, set
generateDefaults = falsebefore editing or replacing any of the generated default bee variants. Treat the generated defaults as a starting point: once you begin overriding them, disabling default generation prevents the mod from regenerating its stock definitions over your changes.
Most customization is optional. The codecs provide defaults for many fields, so it is usually easier to begin with the smallest definition that expresses your idea and add complexity incrementally.
The four primary top-level content formats are independent but designed to reference one another.
Bee definitions control the bee itself: pollination targets, hive behavior, combat attributes, rendering, breeding, mutation behavior, attached traits, and trades.
Bee JSON is a flat map of versioned serializer sections such as:
resourcefulbees:core/v1
resourcefulbees:combat/v1
resourcefulbees:rendering/v1
The bee identifier comes from the file/loader context rather than a root id field.
Honeycomb definitions describe registered honeycomb content and output variations. A variation can define hive-tier and apiary-tier outputs plus default comb/block fallbacks.
The important relationship for bee authors is that a bee's core serializer can reference a honeycomb variation through honeycombVariation.
Standalone traits are reusable behavior definitions. They can contain potion or damage effects, immunities, custom damage entries, special abilities, particles, and auras.
A bee attaches these reusable definitions through its trait serializer, so the same trait can be shared by multiple bees.
Honey definitions configure reusable block, fluid, and bottled forms. Like bees, honey uses versioned serializer sections. The built-in serializers cover block behavior, fluid rendering/physical attributes, and bottled-honey behavior.
The site is divided into four reference areas after this landing section:
Formats — field-level documentation for Bees, Honeycombs, Honeys, and Traits.
Recipes — mutation, solidification, hive, flow-hive, and honey-generator recipes, plus shared nested recipe types.
Biome Modifiers — bee spawning, nest placement, holder sets, and spawn predicates.
JSON Schemas and Templates — machine-readable Draft 2020-12 schemas and starter JSON templates.
Use the human-readable pages to understand intent and runtime behavior. Use the schema/template section when you need exact field names, types, required fields, ranges, and accepted JSON shapes.
For pack authors using the Resourceful Bees config-folder workflow, the custom-content layout is organized by content type:
The resources directory behaves like resource-pack content and is where supporting client assets such as language files can be placed. Textures, models, and animations can also be used to customize a bee's appearance when the corresponding rendering data references them.
Resourceful Bees content can also participate in datapacks. Recipes and biome modifiers are datapack-style integrations, while the primary bee/honey/honeycomb/trait definitions are documented separately because their loaders and registration behavior are distinct. Exact datapack directory conventions can depend on the Minecraft/NeoForge version, so this reference focuses on the JSON contracts rather than guessing version-specific pack paths.
A reliable way to build custom bees is to treat each change as a small, testable layer:
Choose a short, consistent name for the bee and for related content. Keep those identifiers consistent across bee definitions, honeycomb variations, traits, recipes, textures, and translations.
Start from the Bee template/schema and add only the serializer sections you actually need. Many fields have useful defaults; omitting a field is often better than copying a value you do not intend to customize.
If you are modifying one of Resourceful Bees' generated default variants, make sure generateDefaults = false before making your changes so the generated stock definition does not overwrite your customized version on a later launch.
If the bee should produce a custom comb, define the honeycomb/variation and reference that variation from the bee's core serializer. Keep hive/apiary output mapping separate from the bee itself so it can be reused or changed independently.
Use the rendering serializer for layers, colors, textures, models, animations, and size. Add resource-pack assets only when you need something beyond the provided/default resources.
Use the dedicated serializer for the concern you are changing:
combat for aggression and attributes
breeding for parents, feed items, and delays
mutation for bee mutation configuration
traits for reusable special behavior
Keeping concerns in their own serializer sections makes definitions easier to debug and maintain.
Once the bee itself works, add machine recipes, spawning rules, or nest placement. This makes it easier to tell whether a problem comes from the bee definition or from the integration layer.
Before launching or reloading the pack, compare the JSON with the corresponding schema/template. Pay particular attention to:
required fields inside serializer sections
numeric ranges
compact string forms versus expanded object forms
registry identifiers and tags
Then test one behavior at a time in-game.
Many codecs provide defaults. If the default is what you want, leaving a field out is usually clearer than specifying it redundantly. Some nested objects also have a meaningful distinction between being omitted and being explicitly present as {}; the detailed pages call these cases out.
Honeycombs, honeys, and traits are intentionally reusable. If several bees share an effect or output, prefer one reusable definition referenced by multiple bees rather than duplicating the same data everywhere.
Many fields accept registry identifiers, tags, holder sets, or other compact codec forms. A tag such as #minecraft:is_overworld represents a registry tag rather than one specific entry. Check the relevant field page before assuming a list accepts tags, IDs, or both.
The documentation distinguishes between what a codec can deserialize and what makes sense at runtime. For example, an empty list may sometimes be structurally valid even when it produces no useful gameplay behavior. Runtime caveats are documented separately from schema constraints where necessary.
Open Formats to begin defining Bees, Honeycombs, Honeys, or Traits.
Open Recipes after the core content is working and you want machine/process integration.
Open Biome Modifiers for natural bee spawning or nest world generation.
Open JSON Schemas and Templates whenever you want a copyable starting point or machine-readable validation reference.
For a first custom bee, start with the Bee format and keep the initial definition small. Add honeycomb output, rendering, traits, recipes, and spawning only as your design needs them.
resourcefulbees:mutation/v1resourcefulbees:breeding/v1
resourcefulbees:trait/v1
resourcefulbees:trade/v1
trade for beekeeper trade configuration
fields whose omitted value behaves differently from an explicitly empty object
<instance>/
└── config/
└── resourcefulbees/
├── bees/
│ └── <bee>.json
├── honeycombs/
│ └── <honeycomb>.json
├── honey/
│ └── <honey>.json
├── bee_traits/
│ └── <trait>.json
└── resources/
└── assets/
└── resourcefulbees/
└── lang/
└── en_us.json