FreeMinecraftModels Setup

FreeMinecraftModels still supports manual .bbmodel imports, but the current setup flow is Nightbreak-aware and menu-driven.

Prerequisites

• A Java 21 runtime for the server
• Minecraft 1.21.4 or newer — the plugin declares api-version: 1.21.4 and will not load on older lines
• FreeMinecraftModels installed and started once so it can generate its data folders. MagmaCore is bundled inside the plugin jar, so it needs no separate install
• A way to deliver the generated resource pack to players

ResourcePackManager is the recommended delivery path because FreeMinecraftModels only generates the pack; it does not host it by itself.

First-Time Flow

Command	Purpose
/fmm setup	Player-only content-management / first-time onboarding menu (the command players are pointed at on first boot)
/fmm recommendedplugins	Browse companion plugins that pair well with FreeMinecraftModels
/fmm downloadall	Bulk install helper: downloads the latest plugin update plus all accessible Nightbreak packs
/fmm downloadallcontent	Bulk install helper for accessible Nightbreak packs (content only)
/fmm updatecontent	Bulk update helper for outdated Nightbreak packs
/fmm downloadpluginupdate	Downloads the latest plugin jar update only
/fmm applypluginupdate	Applies a downloaded plugin update without restarting the server
/fmm forcereinstallcontent <package|all>	Repair helper: re-downloads content you already have even when the version numbers say it is current
/nightbreaklogin [token]	Shared Nightbreak account link: prints a link to approve the server, or saves a pasted token (permission: nightbreak.login)
/nightbreaklogout	Clears the stored Nightbreak token from this server

If config.yml still has setupDone: false, players with freeminecraftmodels.* get a reminder about 10 seconds after each login if still online. Opening /fmm setup saves setupDone: true for the server and dismisses future reminders. The reminder also surfaces /fmm admin and /fmm. Completing a choice in /fmm initialize also marks setup done; this flag is not proof that a pack was installed or delivered.

The /fmm setup toolbar also has a Pets button that switches the pet mode between cosmetic pets and more creatures, and saves the choice to pets.yml.

Recommended Workflow

1. Install FreeMinecraftModels and start the server once.
2. Link the server to your Nightbreak account with /nightbreaklogin, then approve it at the link it prints.
3. Open /fmm setup to inspect available packs and current state.
4. Use /fmm downloadall if you want to install every official pack your token can access (this also pulls the latest plugin jar update).
5. Use /fmm updatecontent later to refresh outdated official packs.
6. Wait for successful initialization and make sure players receive the generated output/FreeMinecraftModels.zip pack, usually through ResourcePackManager. FMM notifies an enabled ResourcePackManager after successful generation, but that notification alone does not prove client delivery.

Interactive package downloads reload FMM after content changes. A downloaded plugin jar takes effect after a restart, or right away with /fmm applypluginupdate. /fmm reload validates authored items, enchantments and prop recipes before rebuilding; a rejected validation keeps the current catalog active, so check the result rather than assuming the command applied the files.

If you would rather have the server fetch updates on its own, set nightbreak.autoDownloadPluginUpdates: true in config.yml (default false). Downloaded plugin and content updates are applied after the next restart. To apply plugin updates without a restart, set nightbreak.applyPluginUpdatesWithoutRestart to when-empty or immediately (default never). See Configuration.

Manual Model Imports

Direct model import still works through:

plugins/FreeMinecraftModels/imports

That path is still useful for:

• local development
• custom models you are not pulling from Nightbreak
• converting .bbmodel content into the current runtime format when you run /fmm reload

Manual imports and official package downloads both end up depending on a reload/import pass before the runtime model list and resource pack are rebuilt.

Place a loose .bbmodel directly in imports/. That route writes a converted .fmmodel into the models directory and leaves the source import in place, so a later reload can convert it again. It does not import a loose companion .yml alongside it. Plain subfolders without pack.meta are not recursively imported by this route. For a model with companion settings or scripts, use the active models/ directory and scripts/, or a correctly packaged archive; see Model authoring notes.

Official Content Packs

The current plugin ships with five premade Nightbreak-managed packages:

• Basic Furniture Pack (props)
• BetterStructures Prop Pack (props)
• EliteMobs Prop Pack (props)
• Craftenmine's Weapons Item Pack (custom items)
• Craftenmine Tools Item Pack (custom items)

These appear inside /fmm setup, can be bulk-downloaded with /fmm downloadall, and can be updated with /fmm updatecontent. The two Craftenmine item packs are custom items (models with material: set) and use the current authored-item and enchantment formats. Older item packs with equipped-item scripts require updated content.

Resource Pack Reminder

FreeMinecraftModels always needs its generated resource-pack output to reach the client one way or another.

See Resource pack output for the current output paths and ResourcePackManager integration.