Puffsprout

Puffsprout is a companion pet mod for Minecraft NeoForge. It adds a round, floating, leaf-eared companion that is highly adaptive, levelable, and reactive to your actions. Unlike standard static pets, Puffsprouts dynamically transition between behaviors depending on what you are doing in real time. They can fight alongside you, ride on your shoulder to scan for danger, fetch dropped items, and play games with other pets when you are resting.

Core Behavior States

Every game tick, the server checks your current activity to instantly transition your Puffsprout into one of four states:

Behavior State	Trigger Condition	Actions and Mechanics
Neutral	Default / Idle	Floats nearby, performing custom idle variant animations (alert, startle, sleepy, flourish) and glancing at nearby players or creatures.
Combat	Owner is attacking or attacked	Launches high-velocity pinball-like dash attacks and fires wind charges at hostile targets.
Stealth	Owner is crouching	Rides on your shoulder and scans the surroundings for hidden hostiles, highlighting them with glowing outlines (similar to the glowing effect).
Fetching	Dropped items are nearby	Flies to collect dropped items and throws them back directly to you. An internal cap prevents automated farm exploitation.

Stealth Mode Shoulder Ride

Behavior Modes

You can manage your pet's general behavior by opening its GUI (right-click with an empty hand) and selecting one of three modes:

FOLLOW: Default mode. The pet follows you and actively switches between Combat, Stealth, Fetching, and Neutral states based on your actions.
SIT: The pet freezes in place and suppresses all follow and activity goals. If attacked in this mode, it immediately snaps back to FOLLOW mode to defend itself.
PLAY: Anchors the pet to its current position within a 30-block play radius. It will ignore combat and follow goals to interact with other pets or toys.

[!NOTE] Dodge Projectiles: Puffsprouts have a high-priority dodge behavior that runs regardless of the active mode. They will automatically dodge incoming arrows, tridents, and other projectiles not fired by you.

The Pet GUI

Interactive Play Mode

When left in PLAY mode, Puffsprouts execute three distinct sub-behaviors based on their surroundings:

Ball Play: Throwing a Play Ball toy initiates a turn-based game. Nearby play-mode pets will gather in a rotation to chase and nudge the ball toward each other.
Infection Tag: If two or more pets are in Play mode without a ball, they will start a game of tag. One pet is randomly chosen to be infected and chases the others. Once all pets are caught, a new round begins after a short delay.
Wander: If no toys or other pets are present, the pet orbits gently around its anchor with custom bouncing and hopping animations.

Play Mode and Toy Physics

RPG progression

Puffsprouts earn experience from their own actions (e.g., landing hits, killing mobs, pinging hidden targets, and fetching items). Earning XP allows them to level up and gain skill points, which you can distribute into three stats via the pet's GUI:

Combat (Attack Damage): Increases melee hit damage.
Fetch (Fetch Radius): Expands the range in which the pet scans for and retrieves dropped items.
Stealth (Scan Radius): Expands the distance at which the pet highlights hidden enemies.

Stackable Traits

At levels 10, 20, and 30, you can choose a permanent trait. These traits stack if selected multiple times:

Feisty: Reduces the cooldown of the pet's Wind Charge attack.
Fetcher: Increases the base item search range.
Sneaky: Increases the base stealth scanning range.

Unlockable Abilities

Distributing skill points unlocks powerful active abilities that you can equip via the GUI and trigger remotely using the Whistle item:

Protective Barrier (Combat): Grants the owner an Absorption shield.
Wind Burst (Combat): Emits a burst that knocks back all nearby entities.
Decoy (Stealth): Clears the targeting aggro of nearby hostiles targeting you.
Invisibility (Stealth): Grants the owner brief invisibility.

Craftable Equipment and Blocks

The mod introduces several custom items and blocks to manage your companion:

Air Compressor

Used to revive a Deflated Puffsprout. If your pet is defeated in combat, it turns into an item form as a Deflated Puffsprout, preserving its level, stats, and traits. Placing it in the Air Compressor revives it after a short delay. But a penalty to XP and Bond will be dealt.

Journal

Crafted with a Book and a Feather. Right-click your pet to link the Journal, then right-click in the air to open a custom parchment GUI. It displays your pet's statistics—including times fed, kills, items fetched, and balls thrown—along with a chronological timeline of your bond progression (Stranger, Acquaintance, Friend, and Bonded).

The Journal Timeline

Whistle

Crafted with a Goat Horn and String. Allows you to trigger your pet's equipped active ability from a distance. Shift-right-click opens an ability-selection screen to swap between unlocked abilities.

Play Ball

Crafted with a Slime Ball and Wool. A throwable toy with custom bounce physics (impact sounds and particles) that pets chase and nudge when in PLAY mode.

Personalization and Cosmetics

Headbands: Right-click your pet with any wool block to apply a colored headband. Use shears to remove it.
Naming: Apply a vanilla Name Tag to name your pet, which will be displayed in its GUI and hover nameplate.
Animations: Built with GeckoLib integration, featuring smooth flight-direction body rotation, grid snapping on landings to prevent sliding, and unique idle variations.

Advancement Tree

A dedicated advancement tab tracks your pet's progression milestones:

Puffsprout: Bring a Puffsprout into your world.
Puffsprout is here!: Tame your first Puffsprout.
Growing Strong: Level your pet up for the first time.
True Identity: Select your first permanent trait tier.
Peak Puff: Train your pet to its maximum level.
Chronicler: Link a journal to record your pet's history.
Call of the Wild: Use the whistle to trigger an ability.
Reinflated: Revive a deflated pet in the Air Compressor.
True Companion: Maximize your pet's level and bond, and revive it at least once.

Deflated Puffsprout is given to the player on first join by default, but you can also find it in chests.

Feedback and Bug Reporting

Feedback is highly valued. If you encounter any bugs, performance issues, or have suggestions for future features and improvements, please report them.

Technical Specifications

Minecraft Version: 26.2
NeoForge Version: 26.2.0.25-beta or compatible
Java Version: 25
Dependencies: GeckoLib 5.5.3

Puffsprout

GeckoLib