MINECRAFTBIBLE
Loading...
Serverside mod/library that allows you to add balloons to your server!
A small serverside mod for Fabric that lets you attach custom balloon models to players using commands.
⚠️ This mod does not include any balloon models — you have to add your own!
This mod lets you define balloons in a config file.
Balloons can be permanent (persist after death, does not require them to be equipped)
or based on items with the minecraft:equippable component or using trinkets
You can add the balloons:balloon component to any item.
Each balloon is linked to a specific item, a model file, and an optional animation.
There is no client mod required — models are handled via .bbmodel or .ajblueprint files, and shown using item displays and a generated resourcepack.
Put your model files in:
config/balloons/<model>.bbmodel
.bbmodel (Blockbench) and .ajblueprint (Animated Java) formats.The mod reads balloon definitions from:
config/balloons.json
Storage options:
storage-type: Can be LPMETA, MONGODB, MARIADB, POSTGRESQL, or SQLITEdatabase: Defines connection details for databases** gui: **
** permissions: **
Allows to assign vanilla permission levels for the luckperm nodes.
** messages: **
Player facing messages / strings
Here’s a minimal example:
{
"permissions": {
"balloons.reload": 2,
"balloons.list": 2,
"balloons.command": 2,
"balloons.direct": 2,
"balloons.give": 2,
"balloons.remove": 2
},
"messages": {
"player-not-found": "Player not found",
"back": "Back",
"browse": "Browse All",
"prev": "Previous Page",
"next": "Next Page",
"confirm": "Confirm",
"cancel": "Cancel",
"component-tooltip": "Balloon: %s",
"already-owning": "<green>You own this balloon</green>",
"added": "%s was added to your balloons!",
"equip-tooltip": "<green>🎈</green> Press <keybind:key.attack> to equip",
"unequip-tooltip": "<color:#800080>↔</color> Press <keybind:key.use> to unequip",
"get-item-tooltip": "<color:#802080>↔</color> Press <keybind:key.use> to get item"
},
"gui": {
"add-back-button": true,
"back-button-item": "minecraft:arrow",
"back-button-location": [
1,
1
],
"selection-menu-height": 6,
"selection-menu-title": "Select Balloon",
"prev-button-item": "minecraft:arrow",
"next-button-item": "minecraft:arrow",
"prev-button-location": [
8,
6
],
"next-button-location": [
9,
6
],
"browse-menu-height": 6,
"browse-menu-title": "Browse Balloons",
"confirmation-menu-height": 1,
"confirmation-menu-title": "Confirm",
"add-browse-button": true,
"browse-button-item": "minecraft:chest",
"browse-button-location": [
1,
6
],
"confirm-button-item": "minecraft:emerald",
"confirm-button-location": [
7,
1
],
"cancel-button-location": [
3,
1
]
},
"storage-type": "SQLITE",
"database": {
"host": "localhost",
"port": 3306,
"user": "username",
"password": "secret",
"filepath": "cosmetic.sqlite",
"max-pool-size": 10,
"ssl-enabled": false,
"database-name": "balloon_db",
"connection-timeout": 30000,
"idle-timeout": 600000,
"keepalive-time": 300000,
"validation-timeout": 5000,
"use-srv": false
},
"balloons": [
{
"id": "test:one",
"item": {
"id": "minecraft:cobblestone",
"count": 1
},
"data": {
"model": "flower_balloon"
},
"glint": false,
"lore": [],
"permission-level": 0
},
{
"id": "test:two",
"item": {
"id": "minecraft:stone",
"count": 1
},
"data": {
"model": "satyr_balloon"
},
"glint": false,
"lore": [],
"permission-level": 0
},
{
"id": "test:three",
"item": {
"id": "minecraft:stone",
"count": 1
},
"data": {
"model": "apple_balloon",
"glint": true
},
"glint": false,
"lore": [],
"permission-level": 0
},
{
"id": "test:segments",
"item": {
"id": "minecraft:stone",
"count": 1
},
"data": {
"segments": [
{
"model": "dragon1",
"distance": 0.5
},
{
"model": "dragon2",
"distance": 0.5
},
{
"model": "dragon3",
"distance": 0.5
}
],
"tilt": false,
"model": "dragon_root"
},
"glint": false,
"permission-level": 0
}
]
}
Each balloon entry includes:
id: Internal identifier for the balloon.item (optional): The item used to represent the balloon. Supports componentstitle (optional): Formatted titlelore (optional): List of formatted lore linesglint (optional): Flag whether the balloon has an enchantment glintdata.model: The model filename (without extension or path), e.g., "balloon_model" for balloons from config/ballons/ or for filament managed models with a namespace: "mynamespace:balloon_model".data.animation (optional): Name of the animation to use. Defaults to "idle".data.show_leash (optional): Whether the leash is shown. Defaults to true.data.tilt (optional): Whether the balloon tilts (pitch) while following the entity. Defaults to true.data.rotate (optional): Whether the balloon rotates (yaw). Defaults to true.data.follow_speed (optional): How quickly the balloon follows its target. Defaults to 0.25.data.drag (optional): Drag factor slowing the balloon's movement when the attached entity stopped moving. Defaults to 0.2.data.bob_frequency (optional): Frequency of the bobbing motion. Defaults to 0.2.data.bob_amplitude (optional): Amplitude (height) of the bobbing motion. Defaults to 0.2.data.offset (optional): Position offset relative to the attached entity.data.segments (optional): List of additional segments for the balloonSegment format:
model: Model filename, same as the model for the main balloon segmentanimation: Name of the animation to playdistance: Distance to the previous segmentThis mod adds simple commands to allow permanent attachment of the balloon to the player and to remove it.
/balloon show <id>
/balloon hide
Example:
/balloon show test:one
This will attach the balloon with ID test:one (from your config) to the player.
The balloon will respawn immediately after the player respawns.
To add balloons to the players available selection, use /balloon give <player> <id or *>
To remove balloons from the players available selection, use /balloon remove <player> <id or *>
/balloon will display the selection UI
/balloon <id> run by a player will set the balloon with the given id as active
/balloon reload to reload the config and db connection
balloons:token: For voucher items that can be redeemed by using the item (the item won't be consumed if the player already has the balloon available to them)
balloons:balloon: For items that should display the balloon if worn as equipment or trinket. Has the same fields the "data" object in the config has, for example "model", "animation", "show_leash", etc.
Filament based items with the balloons:balloon will be automatically added as option to the /balloon show <id> command, using the items' id.
The mod will also try to load blockbench models from filament datapacks if its installed and has the model loaded.
Make sure to specify a namespace in this case!