Balloons

This compact server-side mod for Fabric allows you to attach personalized balloon models to players using simple commands.

⚠️ Important note: the mod does not include ready-made balloon models — you need to add them yourself!

Main Features

The mod allows you to configure balloons through a configuration file. Balloons can be permanent (persist after player death, don't require equipping) or tied to items with the minecraft:equippable component, and also work with trinkets.

You can add the balloons:balloon component to any item: /give @s minecraft:diamond_chestplate[balloons:balloon={"model":"flower_balloon","animation":"idle"] /give @s minecraft:diamond_chestplate[balloons:balloon={"model":"balloon_no_leash","animation":"idle","show_leash":false]

Each balloon with a unique identifier is defined in configuration files (more details below).

Each balloon is linked to a specific item, model file, and optional animation.

No client mod is required — models are processed through .bbmodel or .ajblueprint files and displayed using item displays and an automatically generated resource pack.

Setup

🪄 Adding Balloon Models

Place model files in the folder:

config/balloons/<model>.bbmodel

• The model filename (without extension) becomes the internal model identifier used in configuration.
• Supports .bbmodel (Blockbench) and .ajblueprint (Animated Java) formats.

⚙️ Configuration File

The mod reads balloon definitions from the file:

config/balloons.json

Here's a minimal configuration example:

{
  "mongo_db": {
    "enabled": true,
    "host": "127.0.0.1",
    "port": 27017,
    "collection": "balloons",
    "username": "",
    "password": "",
    "database": "game",
    "authSource": "admin",
    "useSSL": false
  },
  "balloons": [
    {
      "id": "test:one",
      "item": {
        "count": 1,
        "id": "minecraft:cobblestone"
      },
      "data": {
        "model": "flower_balloon",
        "animation": "idle"
      }
    },
    {
      "id": "test:two",
      "item": {
        "count": 1,
        "id": "minecraft:stone"
      },
      "data": {
        "model": "frog_balloon",
        "animation": "idle"
      }
    }
  ]
}

Each balloon entry includes:

• id: Internal balloon identifier
• item (optional): Item representing the balloon
• data.model: Model filename (without path and extension), e.g. "mynamespace:balloon_model"
• data.animation (optional): Name of animation to use. Default "idle"
• data.show_leash (optional): Whether to show the leash. Default true
• data.tilt (optional): Whether the balloon tilts while following the entity. Default true
• data.rotate (optional): Whether the balloon rotates. Default true
• data.follow_speed (optional): Speed at which the balloon follows its target. Default 0.25
• data.drag (optional): Drag factor slowing the balloon's movement when the attached entity stops moving. Default 0.2
• data.bob_frequency (optional): Bobbing frequency. Default 0.2
• data.bob_amplitude (optional): Bobbing amplitude (height). Default 0.2
• data.offset (optional): Position offset relative to the attached entity

🔧 MongoDB (Optional)

If you want the player's active balloon to persist across multiple servers (e.g., in a network), you can enable MongoDB in the configuration.

If the "enabled" parameter is set to true, the mod will sync player balloon states using the configured database.
If the "username" and "password" fields are empty, the connection will be established without authentication.

Commands

The mod adds simple commands for permanently attaching balloons to players and removing them:

/balloon show <id>
/balloon hide

Usage example:

/balloon show test:one

This command will attach the balloon with identifier test:one (from your configuration) to the player. The balloon will automatically restore after the player respawns.

Data Storage

• By default, balloon states are stored in player data in the Overworld.
• If MongoDB is enabled, the mod uses it instead of local storage — convenient for synchronization between multiple servers.

Filament Support

Items based on Filament with the balloons:balloon component are automatically added as options for the /balloon show <id> command, using item identifiers. The mod will also attempt to load Blockbench models from filament datapacks if it's installed and the model is loaded. In this case, be sure to specify a namespace!

Important Notes

• This is exclusively a server-side mod — it doesn't add items, recipes, or models directly.
• You need to provide your own models.
• Useful for customized servers, cosmetic elements, or just for entertainment.