FreeMinecraftModels Resource Pack Output

FreeMinecraftModels writes its generated pack into output.

Default Output Paths

The plugin rebuilds this folder during startup and on /fmm reload:

plugins/FreeMinecraftModels/output/FreeMinecraftModels

It then zips that folder into:

plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip

That zip path is the one ResourcePackManager expects when it integrates with FreeMinecraftModels.

Generation deletes everything in output except the last published FreeMinecraftModels.zip, then rebuilds it. Keep authored models and other files outside it. If FMM cannot clear the folder, generation fails with Failed to prepare output folder and FMM does not finish initializing.

What Gets Generated

Generation copies the bundled pack metadata, icon, and atlas, then adds the loaded models and textures:

• pack.mcmeta
• pack.png
• assets/minecraft/atlases/blocks.json
• assets/freeminecraftmodels/... model and texture output

A missing bundled resource, or a folder FMM cannot create, fails generation. A failure writing one model's files is logged and generation continues, so check the console as well as the output. Before creating the ZIP, FMM adds explicit atlas entries for its entity textures, including particle textures, and replaces its entity-directory atlas source. Other atlas sources are preserved. An atlas read or write failure fails generation.

FreeMinecraftModels generates item-model definition files under:

assets/freeminecraftmodels/items

A legacy leather-horse-armor override path still exists in the code for pre-1.21.4 servers, but the plugin declares api-version: 1.21.4, so no server that can load it takes that branch.

Display Model Output (1.21.4+)

When a model has a valid sibling .json display model file (see Model Authoring Notes), FMM processes its textures map and writes it into:

assets/freeminecraftmodels/models/display/{modelId}.json

It also generates a corresponding item definition at:

assets/freeminecraftmodels/items/display/{modelId}.json

Namespaced texture values remain unchanged. Other values resolve by numeric texture index, with an available extracted texture as the fallback. A malformed display JSON produces a warning and is not registered. The runtime registry lets FMM assign the processed display model to an item's in-hand and inventory appearance.

Particle Sprites

For every particle effect a model uses, FMM writes the effect's texture and one flat item model per sprite:

assets/freeminecraftmodels/textures/entity/fmm_particles/{modelId}/{effect}.png
assets/freeminecraftmodels/models/particle/{modelId}/{effect}/{index}.json
assets/freeminecraftmodels/items/particle/{modelId}/{effect}/{index}.json

Only Java players see these sprites. Bedrock players get the effect as a native particle from the Bedrock bundle below.

ResourcePackManager Sidecar Files

FMM writes small JSON files that ResourcePackManager reads while it converts the pack for Bedrock. They have no effect on Java clients.

File	Written when	Purpose
assets/freeminecraftmodels/rspm_item_bases/display/{modelId}.json	The model has a display model and its sibling .yml sets a material the server knows. A leather dye suffix such as LEATHER_CHESTPLATE:ff8800 skips the file	Names the vanilla item the custom item is based on, such as minecraft:blaze_rod, so Bedrock shows the model on the right base item instead of one guessed from the file name
assets/freeminecraftmodels/rspm_item_particles/display/{modelId}.json	The model has a display model and an animation with particle keyframes	Lists the effects, locators and looping particle timeline that ResourcePackManager adds to the item's Bedrock attachable
assets/freeminecraftmodels/rspm_item_java_only/particle/{modelId}/{effect}.json	The model uses a particle effect	Tells ResourcePackManager not to turn that effect's sprite items into Bedrock custom items

While particleEffectsEnabled is false, FMM skips the rspm_item_particles files and the Bedrock particle files. The Java particle sprites and their rspm_item_java_only files are still written.

Bedrock Custom-Entity Bundle

Alongside the Java pack assets, FreeMinecraftModels attempts to export a Bedrock custom-entity bundle for each loaded model with textures into:

plugins/FreeMinecraftModels/output/FreeMinecraftModels/assets/freeminecraftmodels/rspm_bedrock_pack

Each model contributes its textures, geometry, render controller, animations, animation controllers, and entity definition, all under the freeminecraftmodels: namespace (freeminecraftmodels:<model_id>). A model with particle effects also contributes particles/<model_id>_<effect>.json (identifier fmm:<model_id>_<effect>) and, when FMM found the effect's texture, textures/entity/fmm_particles/<model_id>/<effect>.png. See Particles.

Notes that matter when authoring:

• A model with no textures is skipped, with Skipping Bedrock custom entity export for <id>: model has no textures. in the console
• The Java importer still accepts that texture-less definition; the explicit skip applies only to its Bedrock custom-entity bundle entry
• Bedrock geometry excludes mount-point bones (m_), generated nametag bones (fmm_nametag_bone_*), and hitbox. Authored tag_ anchors remain in the geometry, often without cubes.
• A model with no animations still exports a single idle animation slot
• A model's geometry hangs from a generated freeminecraftmodels_lean bone, unless the model has more than 672 animations. The bone shows travel orientation and centring to Bedrock players. Animation channels with MoLang keyframes are written as authored, so Bedrock clients evaluate them
• Runtime hitbox width/height for the Bedrock entity come from the model's hitbox bone; without one it falls back to 1.0 x 2.0

An empty hitbox group has zero dimensions; it does not use that fallback. The b_ prefix hides Java rendering but is not filtered from Bedrock geometry. Bedrock animation export does not bake FMM's runtime IK solution; see Animations. Export errors are logged and can leave incomplete bundle output.

The Bedrock runtime backend requires an enabled plugin named floodgate, Geyser-Spigot, or Geyser. Name matching for that gate ignores case. Per-player detection separately checks Floodgate or Geyser-Spigot; passing the backend gate alone does not establish player detection or pack delivery. On a Java-only server, FMM still exports the bundle files but does not construct or tick that backend.

Bow And Crossbow Conditional Item Output

When FMM detects a complete set of loaded bow or crossbow state models with registered display JSONs (see Model Authoring Notes), it generates one item definition under the base model ID. That definition switches between states on the client. The authored item must use the appropriate BOW or CROSSBOW material.

Bow Output

For bows, the generated item definition uses minecraft:condition on using_item with a minecraft:range_dispatch on use_duration (scale 0.05):

Condition	Model used
Not using the item	_idle
Using, fallback (just started)	_draw_start
Using, threshold 0.65	_draw_half
Using, threshold 0.9	_draw_full

Crossbow Output

For crossbows, the generated item definition uses minecraft:select on charge_type. When charged (arrow or rocket), it shows the _charged model. The uncharged fallback uses minecraft:range_dispatch on crossbow/pull:

Condition	Model used
Not using, not charged	_idle
Using, fallback (just started)	_draw_start
Using, threshold 0.58	_draw_half
Using, threshold 1.0	_draw_full
Charged (arrow or rocket)	_charged

Output Location

The generated conditional item definition is written alongside other item definitions at:

assets/freeminecraftmodels/items/display/{baseModelId}.json

The base ID becomes the public display item. Individual state item definitions are removed from the output and runtime registry; their display geometry remains because the conditional definition references it.

Minecraft 26.1+ Compatibility Fixes

The pack generator applies these fixes on all supported versions, including Minecraft 26.1 and newer:

• UV clamping: face UVs are clamped to the texture's UV bounds (0–textureWidth / 0–textureHeight) before being rescaled into Minecraft's 16x16 UV space. These bounds use texture UV metadata when present, otherwise image dimensions or the model's fallback resolution. Clamping negative or oversized coordinates can lose texture detail on the affected face.
• Empty and anchor-only bones are skipped: a bone with no cubes writes no geometry JSON, so writing an item-model definition for it would leave a dangling reference. 1.21.x tolerated that silently; 26.1+ logs every one as Missing block model: freeminecraftmodels:.... The generator now skips both the geometry file and the item definition for such bones. This also covers hitbox bones (collision-only), tag_name positional anchors, FMM's auto-generated fmm_nametag_bone_* variants, and pure wrapper/anchor bones.

These fixes apply automatically; no configuration is required.

note

A tag_ nametag anchor does not need cubes. Cube-free anchors write no geometry; the prefix alone does not hide every authored bone that contains cubes. The exact tag_name bone is treated specially. See Nametag Anchors.

Deterministic Output

FMM reduces unnecessary output changes by using insertion-ordered maps for per-bone item definitions and model display blocks. The ZIP writer also fixes entry timestamps.

Identical ZIP bytes are not guaranteed: the ZIP writer traverses directories in filesystem order without sorting entries. Changes to models, textures, display JSON, configuration, or generator/server version can also legitimately change the pack.

If the pack hash changes unexpectedly, compare archive entry contents and ordering as well as generation inputs. A repeated download alone does not identify the cause.

Reload Behavior

For /fmm reload, FMM first imports content and prepares the candidate item, enchantment and recipe catalogs while the current runtime remains active. If that preparation fails, it rejects the reload and retains the current catalog. After successful preparation, it:

• tears down active models, props, disguises, script runtimes, listener state, and script cooldown stores before rebuilding them
• reloads configuration and recipes
• rebuilds the output/FreeMinecraftModels folder
• regenerates output/FreeMinecraftModels.zip
• dispatches resourcepackmanager reload if ResourcePackManager is enabled
• schedules FmmReloadedEvent on the primary thread 40 ticks later, so dependent plugins can recreate model attachments

FMM writes the archive to output/FreeMinecraftModels.zip.pending first and then moves it over FreeMinecraftModels.zip. If writing or moving fails, generation fails and the previous ZIP stays in place. A complete ZIP does not prove delivery, so verify ResourcePackManager delivery and client acceptance too. See Configuration for the distinction between a full reload and an imported-content refresh.