The Multi-Shoulder Hamster & Mega-Configurability Update

Just when you thought your shoulders were safe, I've gone and turned them into a hamster condominium. This update completely overhauls the shoulder pet system, adds a frankly irresponsible amount of configuration, injects a hefty dose of unnecessary realism, and more!

Added

• Multi-Hamster Shoulder & Head Mount System
  • Players can now have up to three hamsters mounted simultaneously: one on each shoulder and one on their head.
  • The mounting system will automatically place a hamster in the next available slot (Right Shoulder -> Left Shoulder -> Head).
  • Shoulder-mounted hamsters will automatically adjust their offset to fit both slim and wide player models, and will sit even further out to rest on top of equipped chestplates.
  • A configurable dismount order (LIFO/FIFO) determines which hamster is removed first by the standard dismount key.
  • Added a client-side hand-swing animation when mounting a hamster to the player's shoulder.
• Dynamic & Reactive Shoulder Hamster Animations
  • Shoulder-mounted hamsters are now fully animated using their primary GeckoLib model and no longer use a separate, static vanilla model.
  • They dynamically cycle through standing, sitting, and unique, slot-specific "laying down" animations.
  • Hamsters now react when the player sprints by entering their "laying down" animation, as if holding on for dear life. A randomized micro-delay ensures each hamster reacts independently.
• Physics-Based Animation for Shoulder Hamsters
  • Shoulder-mounted hamsters now have a dynamic, physics-lite simulation applied to them, making them feel more alive.
  • Vertical Bounce: Hamsters will bounce on the player's shoulder in response to jumping and falling, with their motion driven by the player's vertical velocity.
  • Squash and Stretch: The hamster's model will visually squash and stretch to simulate inertia and impact forces, making jumps and landings feel more impactful.
  • Impact Effects: A unique squash effect and a new custom sound effect will now trigger at the moment a hamster lands back on the shoulder after a fall or jump, with the sounds staggered for a more natural feel when multiple hamsters are mounted.
• Configuration Options for Shoulder Hamster Audio
  • Added a "Silence Idle Sounds" toggle to mute the ambient squeaks from shoulder hamsters.
  • Added a "Silence Physics Sounds in First-Person" toggle to mute the new landing/bounce sound effect specifically when in first-person view.
• Configurable Animation Control for Shoulder Hamsters
  • Added a config group for "Animation Settings" to give players full control over shoulder hamster behavior.
  • Players can disable the "Dynamic Animations" toggle to force all shoulder hamsters into a single, static pose using the "Forced Animation State" dropdown.
  • The duration of each dynamic state can be customized/randomized with "Min/Max Animation State Duration" sliders, controlling how long a hamster will stay in one pose before transitioning.
  • Added a forceLayDownOnWalk config option (disabled by default) that makes hamsters enter their "laying down" pose during any player movement, not just sprinting.
• Config-Driven Item Tags for All Interactions
  • All hardcoded item checks have been replaced with a high-performance, config-driven system, allowing users to customize nearly every hamster interaction.
  • Players can now define custom lists of items or item tags for taming, standard feeding, buff foods, shoulder mounting, cheek pouch unlocking, and basically every other hamster interaction.
  • This new system includes built-in default compatibility for popular mods like Farmer's Delight and its addon Cultural Delights.
• Conditional Headshake Animations
  • Added a new anim_hamster_moving_headshake animation.
  • When a hamster refuses a food item, it will now intelligently play either a stationary or a moving headshake animation depending on whether it is standing still or walking.
• Visual Height Adjustment on Snow Layers
  • Hamsters will now render slightly higher when standing on snow layers, preventing their model from sinking into the snow and creating a more realistic and visually polished effect. Now your white hamsters won't be so invisible in snow biomes! Lol.
• Fresh Moves Compatibility for Shoulder Hamsters
  • The new shoulder hamster rendering system automatically supports player animation-overhaul resource packs like Fresh Moves, because shoulder hamsters are now anchored directly to the player's animated body parts (arms and head), allowing them to realistically move and bounce along with the player's enhanced walk cycle.

Changed

• AppleSkin Compatibility for Configurable Food
  • The CheeseItem's properties are now fully dynamic*, ensuring that changes to its nutrition or saturation values in the config are correctly reflected in AppleSkin's "on-eat" HUD preview. *Unfortunately due to major API changes between MC versions, this only works on 1.21.1.
• Shoulder Mounting Behavior
  • The logic has been updated to allow players to mount a hamster onto their shoulder with a lure item (like cheese) even while sneaking.
• Wander AI Frequency
  • The default chance for a hamster's idle WanderAroundFarGoal to activate has been slightly increased, making them a bit more active when not following the player.
• Reworked mob fleeing behavior from hamsters.
  • Replaced the hardcoded Creeper-fleeing mechanic with a new configurable system. Ravagers and Spiders will now flee from hamsters by default, restoring the unique anti-Creeper role to vanilla cats. These new fleeing behaviors can be individually toggled in the config.
• Hamster Textures
  • Increased the saturation of the lavender hamster variant's texture to make it appear more purple and less gray.
  • Slightly tweaked two of the white overlay textures to make them look a little bit cuter— very subtle changes here.

Fixed

• Hamster Teleportation
  • Fixed a bug on 1.20.1 where hamsters would not teleport to their owner.
• Baby Shoulder Hamster Rendering Offset
  • Corrected the vertical offset for baby shoulder-mounted hamsters, ensuring they now move up and down correctly with the player's model when sneaking.
• Hamster Suffocation
  • Implemented a "self-rescue" mechanic for hamsters that have been thrown. If they somehow manage to phase inside a block, they will now automatically teleport upwards to the nearest safe block, preventing suffocation deaths.
• AI Goal Visual Flickering
  • Resolved a visual glitch where the hamster's head would flicker during its wander animation by preventing the LookAt and Wander goals from running at the same time.
  • The effective range of the HamsterLookAtEntityGoal was slightly reduced to prevent the hamster from looking up at an unnatural angle when the player is nearby but not directly adjacent.

If you’re thinking hey, this changelog looks awfully familiar… you’re not wrong.

This is essentially the same feature set as 3.1.0 — but with one critical difference: these jars are ACTUALLY BUILT CORRECTLY.

Version 3.1.0’s jars (especially for 1.20.1) were missing a bunch of generated data files, because I had just finished implementing a new CI (Continuous Integration; i.e. 'automated workflow that publishes my jar files for me') configuration, and it had a slight but not so slight oversight. I’ve removed that release from Modrinth and CurseForge so nobody new grabs the broken jars. This is the fixed re-release, under a new version number, so everyone’s launcher will properly prompt for an update.

Added

• Sunflower De-Modding Station
  • Added a simple shapeless crafting recipe to convert one custom, harvestable sunflower back into one vanilla sunflower. For when you need the original for... reasons.
• Advanced Dismount Engineering
  • To prevent accidental hamster ejections when dismounting a horse or building a bridge in the nether (don't ask), the shoulder dismount mechanic is now highly configurable.
  • Players can now choose between using the SNEAK key or a new, separate CUSTOM_KEYBIND for dismounting.
  • Additionally, the action can be set to trigger on a SINGLE_PRESS or a quick DOUBLE-TAP, preventing conflicts with toggle-sneak or bridge-building. For the double-tap setting, the delay is also configurable. Find the new settings in the "Shoulder Hamster Settings" config group.

Changed

• Internal Hamster Wiring Overhaul
  • The hamster's entire internal state-tracking system has been refactored. I've packed seventeen separate on/off switches (booleans) into one glorious, hyper-efficient integer using bit-masking. This change is purely under-the-hood but drastically reduces the chances of mod conflicts and crashes related to entity data. This was specifically to address a mod conflict on 1.20.1 with the Sortilege mod. Apparently it's trying to track a lot of data on Entities, and my mod is also doing that, so they had a conflict on slot #41. But even just in general, your hamsters are now more stable and less likely to have an existential crisis when another mod is present.

Fixed

• Publishing Mishap Autopsy
  • In 3.1.0, my CI pipeline built jars without running the data generators, so critical JSON assets never made it into the finished files. This slipped by on 1.21.1 because those generated files happened to be present from earlier work, but 1.20.1 exposed the issue immediately with crashes. However, I did not notice these crashes myself because I test with manually built jar files, not the ones that the CI pipeline automatically creates. This has now been fixed at the Gradle level so the problem cannot recur — runDatagen is now a build dependency for all relevant jar tasks.
• Corrected Overly-Trusting Hamsters
  • Hamsters will no longer beg for food from any random player waving a cucumber slice. They will now only perform their adorable begging routine for their rightful owner, as intended. And for that matter, I also fixed a similar issue with the Diamond Stealing, Knocked Out, Diamond Sniff Celebration/Sulking, & Pink Petal Application/Cycling/Removal interactions, all of which were in the wrong spot in my interactMob method, which meant they were sneaking past the "is player the owner?" check.
• NeoForge Composting and Key-bind Registration
  • Fixed an issue where compostable items (seeds, crops) were not functional on the NeoForge version of the mod. They now correctly register as compostable.
  • The "Throw Hamster" keybind, previously missing on NeoForge, now correctly appears in the Controls menu.
• Resolved Critical Mod Incompatibility Crash
  • Fixed a hard crash caused by a DataTracker ID collision when running alongside certain other mods (like Sortilege on 1.20.1). The internal wiring overhaul (see "Changed") resolves this issue by significantly reducing the number of data slots the hamster entity occupies.

B.T.S.

Here's how the superbly juicy magnificent and fantastic publish.yml file works:

• Automatically builds both Fabric/Quilt and NeoForge versions in a single workflow
• Publishes each build to both Modrinth and CurseForge with correct, consistent file names
• Attaches a specific snippet of my changelog content directly from the separate public repository for each release
• Includes explicit dependency listings for both Modrinth and CurseForge to ensure proper mod loading
• Supports multiple Minecraft versions with separate version strings for each loader
• Allows manual or tag-based triggering for flexible release management
• Keeps build and publish logic in one place for easier maintenance and fewer manual steps

Anyway IT'S AWESOME

[3.0.1] - 2025-08-02

Fixed

• Spammy Console Icky Gross Stuff
  • Fixed my spammy .info level logging in HamsterFollowOwnerGoal.java that I had forgotten to switch back to .trace.

[3.0.0] - 2025-07-27

The Heist & The Haste Update

Your hamsters have developed expensive taste, learned new languages, and also contracted the zoomies.

Introducing the brand new Diamond Stealing mechanic, where your furry companions will snatch your valuables and challenge you to a game of keep-away. Feed them some Steamed Green Beans and witness the true meaning of "zoomies" as they tear around you in a chaotic, super-charged sprint.

This update also includes a complete, config-driven overhaul of the entire biome spawning system for incredible mod compatibility, smarter AI, new animations, and a ton of critical bug fixes.

IMPORTANT: Due to the extensive changes to the spawning system, it is highly recommended that you delete your existing config file (/config/adorablehamsterpets/main.toml) before loading a world with this version. This will allow the new, more detailed settings to generate correctly. Your old settings will be lost.

Added

• Russian, Chinese, and Korean Language Support
  • Ever heard a hamster squeak in Chinese? I didn't think so. But now, you can! Or perhaps you would prefer a little bit of cooing in Russian... or a squeal in Korean? Thanks to a few of the awesome people in The Cheek Pouch Discord channel, the mod has been fully translated to three languages and more on the way!
• New Major Feature: Item Stealing & Chase Mechanic
  • Tamed hamsters now have a configurable chance to notice valuable items dropped on the ground (defaults to just diamonds).
  • Nearly every aspect of this feature is configurable, including which items can be stolen (you can add any item, multiple items simultaneously, and even items from other mods!).
  • When they spot one, they'll perform a unique pounce animation and snatch the item, initiating a playful game of keep-away. The pounce sound effect is even dynamic, changing based on the material of the stolen item in case you modify it in the config!
  • While in "heist mode," the hamster will flee if you get too close and cheekily taunt you from a distance with a new animation, encouraging a chase.
  • The stolen item is visually rendered in the hamster's mouth, synced with all head movements and animations.
  • To get your item back, you have to catch your speedy thief and right-click it. If you take too long, the hamster will get bored and drop the item. But then, hamsters have a short memory, so it will probably pick it up again.
• New Major Feature: "Zoomies" for Buffed Hamsters
  • Hamsters under the effect of Steamed Green Beans will now get the "zoomies," a burst of energetic, high-speed activity.
  • Instead of wandering aimlessly, they will sprint in dynamic, chaotic circles around their owner.
  • When following their owner, they will no longer run in a straight line but will instead dart around randomly in the owner's general direction.
  • This frenetic behavior is accompanied by a new custom particle trail that bursts outwards from the hamster as it sprints.
• New Sprinting Animation & Standardized Speeds
  • A third-tier "sprinting" animation has been added for the hamster's highest speeds, used during zoomies and fleeing.
  • All hamster movement speeds have been standardized across all AI goals for more consistent and predictable behavior.
  • Walking and running animations are cuter.
• Enhanced Idle Animations
  • Hamsters will now occasionally play one of three new, randomized "looking up" animations when their LookAtEntity AI goal is active and they are looking at a nearby target (like you).
• New Wild Hamster Settle to Sleep Animations
  • Hamsters will now play one of three new, randomized "settle to sleep" animations, paired with the three already-existing sleeping animations when going to sleep, similar to how tamed hamsters already did when sitting.
• Configurable Biome Spawning System (Major Rework)
  • The entire spawning system for both hamsters and world-gen features (bushes, sunflowers) is now controlled by the config file.
  • Users can now define exactly where things spawn using biome IDs, vanilla biome tags, and "convention tags" (c:is_cold, c:is_forest, etc.) for vastly improved compatibility with modded biomes from packs like Terralith and Biomes O' Plenty.
  • Each feature and the hamster itself has its own set of include/exclude lists and tag lists, offering granular control over world generation.
• New Faster Throw Velocity for Buffed Hamsters
  • Throwing a hamster while it's under the effect of the Steamed Green Bean buff will now launch it at nearly double the default velocity.
  • Both the default and buffed throw velocities are now configurable in a new "Hamster Yeet Settings" group in the config.
  • (A special thanks to @Petite on Discord, who planned to defeat the Ender Dragon using only hamster projectiles. This idea inspired me to ensure they had enough velocity to reach the dragon in the first place! 😂)
• Improved Shoulder Dismount Logic
  • When the player dismounts the hamster from their shoulder, it will now be placed at the location where the player was looking if it was safe and within reach. If not within reach, it will spawn at the player's feet.
• New Config Option
  • Added a config option to change the default name of the hamster entity to "Hampter" instead of "Hamster," because I wanted to, so I did.

Changed

• Spawning Logic Overhaul
  • The internal logic for determining hamster color variants has been completely rewritten to be "hamster-centric." It now uses a combination of specific biome checks, vanilla tags, and universal convention tags to ensure hamsters spawn in thematically appropriate locations, even in heavily modded worlds. Note: I only had time to test this with Terrralith— so if you're using a different biome generation mod (Biomes O' Plenty, Oh The Biomes You'll Go) you may see more frequent orange hamsters, since they are the default fall back. Or maybe it will work perfectly! Lol.
  • The custom sunflower replacement system is now also tag-aware. It will now correctly replace vanilla sunflowers with the harvestable version in any biome that is supposed to have them (including modded biomes), not just the vanilla Sunflower Plains.
• Diamond Seeking AI Improved
  • The independent ore-seeking AI is now smarter. Hamsters will now prioritize pathfinding to exposed ores that are visible to the player before considering ores that are completely buried.
  • A new particle breadcrumb trail has been added. When a hamster is leading you to an ore, it will now create a faint trail of dust particles along its intended path, making it much easier to see where your tiny prospector is headed.
• Death Message Attribution
  • Death messages will now credit the hamster by its name (e.g., "Player was slain by Hampter") instead of attributing the kill to the hamster's owner. Hamsters are now fully complicit in their actions. 😁
• Dependencies
  • The Jade mod is no longer a required dependency and is now correctly listed as optional for all mod loaders. The game will no longer crash if Jade is not installed.
• Pathfinding & AI
  • Hamster pathfinding penalties around hazards have been strengthened. They will now be much more reluctant to pathfind into or near fire and lava.
  • The idle AI goals (Wander, Look At, Look Around) have been re-balanced to prevent them from fighting with each other, resulting in much more natural and less "flickery" idle behavior.
• Textures & Animations
  • The textures for the Blue and Lavender hamster variants have been updated with slightly increased saturation to make their colors more distinct and recognizable without being neon.
  • The textures for the Wild Cucumber Bushes have been slightly desaturated to help them blend more naturally into the warmer, drier biomes where they typically spawn.
  • The transition speed between animations has been reduced from 5 ticks to 2 ticks, resulting less of the "hamster sliding across the ground" type of effect when it is transitioning between movement animations.
  • The rotation speed of the hamster has been overhauled to account for it not having a separate head and body like vanilla models, resulting much more snappy rotations and accurate target-facing. Vanilla Minecraft mobs move their head first, and body follows second at a much slower pace. Since my hamsters use Geckolib for the model, they do not have a separate head and body in the same way that vanilla mobs do, which resulted in a quick initial turn where the hamster would turn halfway toward its target, and then a slower finish. I basically combined both of them together to eliminate that weird behavior.
  • The speed of the running animation has been decreased by 25% to better differentiate it from the new sprinting animation, giving it a more natural pace.

Fixed

• Fixed Shoulder Hamsters Being Deleted on Player Death
  • Resolved a critical bug where a shoulder-mounted hamster would be permanently deleted if the player died, even with keepInventory enabled. The system now correctly detects the player's respawn and safely dismounts the hamster at the player's death location.
• Fixed Hamster Suffocation on Dismount/Throw
  • Implemented a robust safe-spawning algorithm that performs a multi-stage search for a valid, non-obstructed location when a hamster dismounts or lands from a throw. This should completely resolve all known suffocation bugs.
• Fixed Right-Click Stack Splitting in Hamster Inventory
  • Corrected the underlying inventory logic to properly handle the amount parameter when removing items. Players can now correctly right-click to split stacks of items inside the hamster's cheek pouch inventory, just like in a vanilla chest.
• Fixed Thrown Hamster Particle Desync
  • Adjusted the spawn position calculation for the in-flight particle trail. The trail now correctly originates from the hamster's model instead of appearing slightly ahead of it, which was most noticeable when viewing from a second player's perspective or with replay mods.
• Fixed Black Hamster Overlay Spawning
  • Wild black hamsters will now only spawn with their solid base color. This makes their appearance in dark environments like caves more thematic and reserves their white overlay patterns as a special trait achievable only through breeding.

[2.3.0] - 2025-07-16

1.20.1 Forge/Fabric/Quilt support has arrived!

After a long and surprisingly complex battle with the Forge 1.20.1 datapack and build systems, the mod is now fully functional on Forge. Your hamsters are now free to cause chaos across multiple mod loaders.

Added

• Official support for Minecraft 1.20.1 for Forge and Fabric.
• Official Quilt support for 1.21.1 and 1.20.1

Changed

• Improved hamster dismount logic. Hamsters will now be placed at the block the player is looking at (within a 4.5 block range), providing more precise and intuitive placement. I don't know about you, but when I take a hamster off my shoulder in real life, I get to choose where I put it down. It just made sense lol
• Particle Changes:
  • The ominous trial spawner particles (diamond celebration) and GUST particles (hamster flight trail) both had to be switched out since they don't exist in 1.20.1. I'm using composting particles for the diamond celebration since they have an upward bias, and cloud particles for the hamster flight trail.

Fixed

• Fixed a critical bug where hamsters could suffocate inside blocks when dismounted from the shoulder or after impacting a block from being thrown. A robust safe-spawning algorithm now works in tandem with the new dismount logic to ensure hamsters are always placed in a valid, non-obstructed location.
• Fixed a visual bug where the particle trail for a thrown hamster would appear ahead of its model during flight.
• Removed the non-functional Hamster Guide Book from the creative mode inventory tab to prevent confusion.
• Resolved a critical issue on Forge where no custom world generation (hamsters, wild bushes, custom sunflowers) would occur.
• Fixed a startup crash on Forge related to the Hamster Spawn Egg item registration order by implementing a platform-specific solution.
• Wrestled the Forge build process to properly include all necessary models, textures and data files.