The Slap My Forehead Patch

⚠️ NOTE: If you are playing on 1.21.1, you do not technically need this, unless you're seeing dozens of hamsters on your shoulder. Go have a snack.

Fixed

1.20.1

• Server Crash: "Unknown Message Type" (The 'I misunderstood how old Architectury works' bug)
  • The Issue: On dedicated 1.20.1 servers, the game would crash immediately upon trying to sync hamster data.
  • The Cause: I (sort of) copy-pasted the shiny, modern Architectury networking code from 1.21.1 into the 1.20.1 backport. Turns out, the older Architectury API requires you to introduce packets to the server politely before sending them. The server received the hamster data, said "I don't know her," and panicked.
  • The Fix: Refactored the network registration to actually work on 1.20.1.
  • Also, I have left several aggressively capitalized comments in the source code warning my future self that 1.20.1 Architectury networking is different. So hopefully this will never happen again!

1.21.1 and 1.20.1

• "Mutant Hamster Pile" Cleanup
  • The Issue: Players affected by the previous Invalid Player Data bug might have ended up with "ghost" hamster data, resulting in dozens of duplicate hamsters appearing on their shoulder.
  • The Fix: Spamming your dismount button should fix the issue, but not everyone reads changelogs so I added an auto-sanitizer that runs on login. It will instantly detect and delete any ghost/duplicate hamster entries, returning your character to normal without you needing to do anything.

The Tiny Patch

This patch is hamster-sized, but fixes a pretty big issue. In my zeal to make my code more defensive against Macaw's Mods on Sunday, I accidentally created a bug that locked players out of worlds if they logged out with a shoulder hamster. That is now fixed. Your worlds are safe, and you can log in again. I also squeezed in Xaero's Minimap support and a few other things while I was at it.

Added

• New Translations
  • Added 6 new locals for the Spanish translation thanks to @The Retro Stitcher.
• Xaero's Minimap Compatibility
  • Thanks to help from @Kazerio, added hamster icons to Xaero's Minimap!

Fixed

• Invalid Player Data / World Join Crash
  • Resolved a critical issue where the game would crash or lock players out of worlds if they had a hamster on their shoulder. This was accidentally introduced in version 3.4.1 when I refactored the code to defend against the network protocol error caused by Macaw's Mods.
  • I had accidentally introduced a race condition where the mod attempted to sync pet data before the player's network connection was fully established. If you had previously been locked out of any of your worlds due to this bug, you should now be able to join just fine and your hamsters will still be on your shoulder.
• Config Screen Localization
  • Implemented a work-around for an issue where the "Main Settings" and "World Gen Settings" descriptions were not translatable due to a known bug with Fzzy Config.
  • Fixed untranslated enum values (e.g., "Near/Medium/Far", "Sneak Key") in dropdown menus.
  • Fixed untranslated conditional help text (e.g., "Only available when...").
• EMI Compatibility
  • Resolved tooltip mod name duplication when EMI is installed.

The Edge Case Extravaganza Patch

This patch is dedicated to the 1% of you running modpacks complicated enough to break the space-time continuum. If you weren't crashing, you probably won't notice a difference. If you were crashing because you threw a hamster at a target more than 16 blocks away while running Shaders and Macaw's Furniture on NeoForge... your problems are solved!

Added

• Translations
  • Updated langage files with a few translated strings that Crowdin elected to omit from the last version!
  • Major overhaul to the Russian translation of the Hamster Tips guidebook to ensure the text fits better on the pages, thanks to @CasualAnimalEnjoyer!

Changed

• Mod Icon
  • As all true geniuses do, @The Retro Stitcher woke up in a cold sweat with ideas for improving the mod's icon even further. JK about the cold sweat part. His improvements have been implemented. Thanks again!
• The mod's README.md file (also known as the "landing page") has had a major overhaul!
  • Used the Flashback mod to render epic GIFs showing off almost every feature.
  • Added new graphic headings with cozy pixel art tree branches, featuring the actual Hamster Bedding item texture for their leaves.
  • Reworked info banners for layout clarity and added credits for everyone who has helped out with development, artwork, and translations.
  • Added a new pixel art banner image up at the top. Huge thanks to @The Retro Stitcher for helping me get it pixel-perfect. He and I both spent a considerable number of hours on it!
  • Go check it out right here, and turn off your ad blocker and watch a few ads while you're there to help support the development of Adorable Hamster Pets!

Fixed

(Note: If I sent you a preview jar file on Discord marked v3.5.0, those fixes are included here.)

• Added defensive measures for crashes with Shaders and optimization mods.
  • While not directly caused by Adorable Hamster Pets, shaders often create "fake" player entities to render shadows and aggressive optimization mods sometimes leave these entities in a broken/uninitialized state. Then when this mod would ask, "Does this shadow have a pet?" for the shoulder hamster feature, the game would panic and crash.
  • Added defensive checks to both the Renderer and the Physics Simulation for shoulder hamsters to safely ignore these corrupted entities. This should not have any visual effect on the game except that your hamster may not have a shadow for a few seconds when you first load into the world.
• Fixed a crash when managing Announcements from the Title Screen.
  • Clicking "Mark as Read" or "Snooze" while on the main menu no longer causes a NullPointerException.
• Fixed stray semi-transparent pixels on the Hamster Bedding texture.
• Fixed localization and text errors.
  • Corrected the "Icon Position Preset" buttons in the config menu to show translated text instead of raw enum names.
  • Fixed a few other grammatical errors.
• Network Protocol Error (Macaw's Mods Conflict)
  • Refactored the shoulder pet data system to use custom network packets instead of vanilla DataTrackers.
  • This eliminates ID collisions with mods like Macaw's Furniture that inject their own data into the player entity.
• "Failed to encode packet" Disconnects
  • Fixed a race condition where the item stack used for particle effects was emptied before the network packet could be sent.
  • This prevents players from being kicked when feeding/mounting hamsters cheese with a stack size of 1.
• Crash when throwing hamsters at targets further than 16 blocks away on NeoForge
  • Resolved a NoSuchMethodError caused by a mapping mismatch when sending vanilla sound packets by migrating the "distant impact" sound logic to a custom network packet to ensure stability across loaders.
  • Minecraft cuts off any sound that happens more than 16 blocks away from your player— this logic exists in order for players to hear those distant impacts.

The Cuteness Overhaul Update

Beds, wander mode, new animations, suspiciously advanced leaf physics, and more!

Give your tamed hamsters an actual home with the new Hamster Bed, Wander Mode, and cozy bedding that doubles as a tiny leaf particle generator. Yeeted hamsters are now cuter, more terrifying, and broadcast their sound effects farther, so your friends can fully appreciate incoming fur missiles. Added new animations, updated some existing ones. Under the hood, variant spawning is now fully biome-configurable and a pile of long-suffering bugs—ghost shoulder hamsters, startup crashes, and more—have finally been escorted off the premises.

Added

• Fully Configurable Biome-Based Variant Spawning System
  • The logic determining which hamster color variants spawn in which biomes is no longer hardcoded.
  • It is now entirely driven by new settings in the config file under Spawn Settings > Variant Spawning by Biome.
  • Users can now define custom lists of biome IDs, biome tags (including c: convention tags), and exclusion lists for each of the seven main color variants/biome groups (Blue, Lavender, White, Gray, Black, Cream, and Chocolate).
  • This provides significantly greater compatibility with world-generation mods like Terralith and Biomes O' Plenty, allowing users to fine-tune hamster diversity in any modded environment. The default values have been set to preserve the existing spawning behavior that was present already.
  • The Orange variant acts as the default fallback and will spawn in any biome where hamsters are allowed that does not meet the criteria for the other configured colors. That's why it does not have its own set of biome lists in the config.
• Hamster Yeet Audio Overhaul & Visual Enhancement
  • Completely re-worked the hamster_flying animation. It's now much cuter. Not that you'll ever see it, unless of course you record yourself throwing the hamster with the Flashback mod. Hint hint. It's quite fun.
  • Re-designed the hamster_throw sound so you can hear the hamster's ears flapping in the wind, which is part of the updated animation.
  • The throw sound now plays directly at the thrower's location, ensuring the full baked-in Doppler effect is heard instead of cutting off abruptly as the hamster flies outside Minecraft's 16-block sound attenuation cutoff.
  • Added a new predictive "incoming" sound effect (reverse Doppler) that plays at the target's location, giving victims a one-second audible warning before impact.
  • Thrown hamsters now dynamically rotate their pitch to match their flight trajectory (nosing up when ascending, down when falling) instead of remaining perfectly horizontal like a frisbee.
  • Implemented a custom sound broadcasting system for long-range throws. Players between 16 and 50 blocks away (who would normally hear silence due to vanilla limits) will now hear a faint impact sound, which dynamically adjusts its volume and changes type depending on whether the hamster impacted a block or an entity. Similar to the old logic, but now you'll actually hear something if you're trying to throw a 50-yard pass.
• New Block: The Hamster Bed
  • Introducing the Hamster Bed, a new block that serves as an anchor point for the new feature, Tamed Wander Mode.
  • Craftable with a new "Hamster Bedding" item and wood planks. It comes in all nine vanilla wood variants (Oak, Spruce, Birch, Jungle, Acacia, Dark Oak, Mangrove, Cherry, and Bamboo).
  • A tamed hamster can be linked to a bed by right-clicking it with the bed item in hand. The bed item will then store the hamster's data. Placing the linked bed in the world activates Wander Mode for that hamster.
  • Placing the bed while targeting the underside of a block places it upside-down, triggers a new advancement, disables the bed's sleep function until it is broken, and begins to spawn floaty, cozy leaf particles. More on that in a sec.
• New Item: Hamster Bedding
  • Added "Hamster Bedding," a new crafting component for the Hamster Bed, made from a cozy blend of leaves, podzol, and dead bushes. (The leaves will be replaced with Leaf Litter when I port the mod to 1.21.5, giving them a fun purpose).
  • Beyond its use in crafting, this item can be used by hand or from a Dispenser to release a decorative cloud of leaf particles, perfect for adding a touch of autumnal ambiance to your life.
• Advanced Particle Physics System for Bedding
  • The new leaf particles are driven by a custom client-side physics simulation with two distinct behavioral models.
  • Particles spawned from bed interactions use a standard gravity-and-friction model for a simple settling effect.
  • Particles spawned from an upside down Hamster Bed, the Hamster Bedding item or a dispenser use a "floaty" physics model, featuring a gentle pendulum-like sway based on sinusoidal motion.
  • This floaty mode includes a deterministic, spatially-coherent wind gust simulation. It uses a grid-based hashing function to ensure particles in the same area react to the same pseudo-random wind events, creating synchronized, emergent behavior.
• New Intelligent Indoor/Outdoor Detection Algorithm for Particles
  • Implemented a custom algorithm to prevent the wind gusts from the particle system from having an effect on particles that are "indoors."
  • The system analyzes three environmental factors in real-time: skylight levels, vertical roof clearance, and horizontal openness (i.e., proximity to open doorways or windows).
  • It uses a high-performance caching system to minimize performance impact and employs hysteresis to prevent visual flickering when particles are near the threshold between an indoor and outdoor space.
• New Feature: Tamed Wander Mode
  • Tamed hamsters can now be set to "Wander Mode," allowing them to roam freely within a configurable radius of their linked bed instead of constantly following the player.
  • Activation: Link a Hamster Bed item to a hamster, then place it in the world.
  • Control: Right-click the placed bed to toggle Wander Mode on or off for the linked hamster. Sneak + right-click to cycle through three wander distances (Near, Medium, Far), which are configurable.
  • Hamsters in Wander Mode will automatically seek out their bed to sleep based on the time of day (or the "Circadian Chaos" random timer) if enabled in the config.
• Added "The Great Escape" Guide Book Entry:
  • Details the crafting and use of the new Hamster Bed and Hamster Bedding items, featuring custom artwork.
  • Explains how to link a bed to a hamster to enable "Tamed Wander Mode."
  • Outlines all interactions for configuring wander distance, luring to bed, and unlinking.
• New Animations and Sounds for Sit/Stand/Sleep
  • Added new animations for sitting down, standing up, and waking from sleep.
  • Added new hamster_swish and hamster_thump sound effects that play during these transitions, making interactions feel more realistic and fun.
• New Dispenser Behavior for Hamster Bedding
  • Dispensers can now be loaded with Hamster Bedding. When activated, they will shoot out a decorative puff of the new floaty leaf particles, consuming one Hamster Bedding item.
• New Advancements for Wander Mode and Crafting
  • Added a new branch to the "The Hamster Life" advancement tab to guide players through the new features.
  • New advancements include: "Artisanal Floor Mulch" (crafting bedding), "Luxury Leaf Pile" (crafting a bed), "Home is Where the Leaves Are" (linking a bed), "Sweet Dreams 'r Made of Leaves" (hamster sleeping in a bed), and a hidden challenge advancement for placing a bed upside-down.
• New Jade Integration for Hamster Bed
  • If the Jade mod is installed, looking at a Hamster Bed will now display a detailed tooltip.
  • It shows which hamster the bed is linked to, whether Wander Mode is active, the current wander distance, and whether the hamster is allowed to sleep in the bed. Sneaking reveals detailed instructions on how to control the bed's functions.
• Added Compatibility for Croptopia, Immersive Engineering, Serene Seasons, and Thermal Expansion
  • A huge thank you to @CasualAnimalEnjoyer for creating 30 new resource files to ensure out-of-the-box compatibility.
  • Croptopia: Food recipes now accept AHP vegetables via tags. Seed crafting recipes have been separated to ensure crafting an AHP vegetable yields an AHP seed, preventing conflicts with Croptopia's own seed recipes.
  • Serene Seasons: Cucumber and Green Bean crops now have defined growing seasons and will bloom accordingly.
  • Tech Mods: Added support for growing Cucumber and Green Bean crops in the Immersive Engineering Garden Cloche and the Thermal Expansion Phytogenic Insolator.
• New Mod Icon
  • Huge thanks to @The Retro Stitcher for re-designing the mod's icon!

Changed

• Announcement icon position in Creative Inventory
  • The announcement bell icon that appears in the Creative Inventory screen has been moved from the bottom-right corner to the top-right corner of the screen.
  • This relocation prevents the icon from being overlapped by popular inventory utility mods such as JEI, REI, and EMI.
  • The maximum configurable X/Y offsets for the creative inventory widget have also been increased from 100 to 500 to allow for greater user customization.
• Improved the "Settle to Sleep" Animations
  • Tweaked the "Settle to Sleep" Animations to make them considerably cuter and more compatible with scenarios where the hamster might be "jumping into bed."
• Smarter Hamster Pathfinding (Bed Avoidance)
  • Hamsters now have a custom navigation system that makes them aware of Hamster Beds.
  • By default, a hamster will now attempt to pathfind around any Hamster Bed that is not its own linked bed. After all, hamsters can be a bit territorial irl.
  • To prevent hamsters from getting stuck in complex environments, they will only try a few alternate routes before giving up and taking a more direct path. This avoidance behavior can be disabled in the config.

Fixed

• Personality ID assignment for command-spawned hamsters
  • Resolved an issue where hamsters created using the /summon command were not being assigned a random "personality ID," causing them all to use the same animations and sitting poses.
  • This was caused by the /summon command bypassing the initialize() method where the ID was being set.
• Orange hamster spawning in Stony Shore biomes
  • Fixed a bug where orange hamsters were incorrectly spawning in the minecraft:stony_shore biome instead of the intended light/dark gray variants.
  • The biome was being correctly excluded from the "white" variant spawn list but did not match any other specific criteria, causing it to fall back to the default orange variant. The spawn conditions for gray hamsters now explicitly include this biome.
• Startup crash (StackOverflowError) related to the announcement system
  • Fixed a critical StackOverflowError crash that would occur on game launch if the "Snooze (Session)" feature had been used in the previous session.
  • The crash was caused by a recursive loop in the AnnouncementManager's initialization logic. The redundant check causing the loop has been removed.
• "Snooze (Session)" functionality and state synchronization with Patchouli
  • The "Snooze (Session)" button now correctly snoozes only the specific announcement being viewed, rather than incorrectly disabling all notifications globally for the session.
  • The underlying disabled_until_launch system, which was the source of the startup crash, has been completely removed and replaced with a non-persistent, in-memory list for session-snoozed items.
  • Fixed a bug where announcements snoozed for the session would remain marked as "read" in the Patchouli guide book after restarting the game. The system now correctly syncs the "unread" status of all pending notifications with Patchouli's data when a world is loaded.
• Ghost Shoulder Hamsters on Player Death
  • Resolved a critical bug where shoulder-mounted hamsters would remain on the player after death, becoming permanently stuck. They will now correctly spawn at the player's death location in a 'knocked out' state, and a new config option allows players to keep them on their shoulder upon respawn if desired.
  • Implemented a backward-compatibility fix to ensure any hamsters that were previously stuck on a player's shoulder can now be dismounted correctly.
• Stale triggerable animations playing when entity is rendered
  • Fixed a visual desynchronization where a one-shot animation (like the "Settle to Sleep" transition) triggered while a hamster was off-screen would play belatedly as soon as the hamster was rendered, causing it to be out of sync with the new sound effects.
  • A server-side cancellation scheduler now ensures that any triggered animation automatically expires if it has not been played by a client within its expected duration.
• Hamster and wild bush spawning on Sculk, Clay, and Moss blocks
  • Black hamsters can now correctly spawn on Sculk blocks, decreasing their unintentional rareness in the Deep Dark biome.
  • Wild Green Bean and Wild Cucumber bushes can now generate on Clay and Moss blocks, allowing them to spawn more frequently in biomes like Swamps, especially if you have a mod that modifies the block palette of the ground in those areas.
• Resolved "Unknown message ID" errors on dedicated servers (1.20.1)
  • Split the 1.20.1 network packet registration into distinct client-to-server and server-to-client methods. (This had already been done on 1.21.1)
  • Ensured that the server correctly registers handlers for client packets (like render state updates), preventing disconnects or log errors when players interact with hamsters.
• Corrected Gray Hamster spawning in deserts.
  • Gray hamsters were incorrectly spawning in sandy biomes like deserts, where Cream hamsters are intended to appear.
  • Added the c:is_sandy tag to the Gray variant's exclusion list to prevent this overlap.
  • Note: If you're still seeing Gray hamsters in deserts, navigate to Spawn Settings > Variant Spawning > Gray Variants > Excluded Tags in the config menu, right-click the setting, and select "Restore Defaults."
• Fixed Uninteractable Hamsters with Force-Mount Keybind
  • Resolved a critical bug where enabling the "Force Shoulder Mount" keybind in the config would prevent all interactions with tamed hamsters.
  • This was caused by the server trying to access client-side keybinding code.
  • The logic has been refactored to use a network packet, ensuring interactions work correctly regardless of the keybind setting.
• Resolved World Gen Config Weirdness
  • Previously, world-gen settings like spawn weights and biome lists were locked on the title screen because they were bundled with other synced server settings, making it impossible to configure them before creating a Singleplayer world.
  • The configuration system has been restructured: clicking "Adorable Hamster Pets" in the mod menu now opens a new landing page with two distinct buttons: "Main Settings" (gameplay & client options) and "World Gen Settings".
  • The new "World Gen Settings" menu uses a special save mode (SaveType.SEPARATE), allowing you to freely edit your local defaults for Singleplayer worlds while still respecting server-side overrides when joining a Multiplayer server.

The More Polite Notifications Patch

The announcement system was always intended as a personal touch—a cozy newspaper to share news and updates directly while you sip your coffee. But your feedback made it clear that 'personal touch' can feel a bit intrusive when you've got two or three hundred other mods vying for your attention. I get it.

This patch is all about handing the controls over to you. Based on some fantastic feedback, I've added a suite of new more accessible options to let you decide exactly how—or if—you see notifications. The goal is to keep the feature useful for those who want it, while making it completely unobtrusive for those who don't.

Added

• Added click-and-drag functionality to the announcement screen scrollbar.
  • You can now scroll down on announcements by dragging the scrollbar handle with your mouse, in addition to using the mouse wheel.
• Enhanced control over the announcement system with new UI options and quality-of-life features.
  • A new "Enable Announcements" master switch has been added to the config screen, allowing you to control all notification icons at once.
  • You can now instantly mark all announcements as read from a new button in the config screen.
  • A "Snooze (Session)" button is now available on the announcement screen to temporarily hide all notifications until the game is restarted.
  • Holding Shift while clicking "Mark As Read" on any announcement will now mark all pending notifications as read.

Changed

• The inventory key now closes the announcement screen.
  • Pressing the inventory key (default 'E') while viewing an announcement will now correctly close the screen, mimicking standard Minecraft UI shenanigans.
• Overhauled the announcement screen's action buttons for clarity and control.
  • The button layout has been reorganized into two rows and simplified. The old, confusing "Disable These" button has been replaced with a clearer "Disable All" button that permanently turns off the notification icons (this can be undone in the config).
• Patchouli's "Mark All as Read" button now includes announcements.
  • The "Mark All as Read" button on the main page of the Hamster Tips guide book now correctly marks all pending announcements as read in both Patchouli's system and mine, so now it behaves exactly as you'd expect it to.

Fixed

• Resolved major UI scaling issues with the announcement screen.
  • The entire announcement GUI (background, content, and buttons) now dynamically scales down to fit the available window space, preventing elements from being cut off.
• Attempted fix for a startup crash on NeoForge with large modpacks.
  • A NullPointerException was reported by one person on game launch, likely caused by a race condition with the new announcement system in heavily modded environments. While I couldn't reproduce the crash myself, I've refactored the system to initialize itself on demand, which should resolve this kind of loading order issue. This change is safe and may prevent similar problems in the future.
• Removed the concept of "mandatory" announcements.
  • You are now the master of your own notification destiny. The system no longer distinguishes between optional messages and "mandatory" update notifications, giving you full control to dismiss, snooze, or disable any and all announcements as you see fit.
• Upgraded Fzzy Config library to resolve UI bugs.
  • Updated from v0.7.0 to v0.7.3 to fix an issue where nested, collapsed groups in the config screen would incorrectly appear expanded by default. This should make navigating the configuration screen much less overwhelming.
  • This Fzzy Config update also resolves a data generation bug that was preventing tooltips from appearing for the "Survival Inventory" and "Creative Inventory" announcement bell icon offset settings.