yourShika's Backpacks

yourShika Backpack's

Disclaimer: This project — its code and its project artwork — was created with the help of AI. The plugin itself is tested by real people, and bugs and issues are actively fixed.

A standalone, fully server-side backpack system for Paper/Spigot.
Players need no client mod.

---

📦 Description

yourShika Backpack's brings high-quality, dyeable backpacks with their own
inventories to your survival server – safe against dupe bugs, persistently stored
and prepared for custom textures.

The plugin is inspired by Sophisticated Backpacks
(GitHub), but is a
completely standalone re-implementation. No code, no asset and no texture
was taken from the mod. This is not a Forge/Fabric/NeoForge mod, but a
Paper/Spigot plugin.

---

🧲 v1.3.2

• Magnet pull fixed – two annoyances gone:
  • Items no longer fly up over your head. The pull previously forced a constant
    upward boost and aimed at hip height; it now targets your chest (the pickup
    centre) and only lifts items that are clearly below you.
  • Items you couldn't pick up are fixed. When an item got close the magnet used
    to stop pulling and leave its leftover upward momentum, so it drifted past you;
    it now dampens the item into the pickup box so vanilla collection grabs it
    reliably.

---

🗜️ v1.3.1

• Compacting filter no longer resets on rejoin – the filter now stores an
  independent copy of its sample items instead of live inventory references. With
  the async write-behind cache (v1.2.0), those references could go stale before the
  delayed save, so the filter serialized empty and looked cleared after a relog. The
  same hardening applies to the Pickup filter.
• Compacting on/off toggle – each backpack's Compacting upgrade now has an
  ON/OFF switch in its filter menu. When OFF, items are no longer compacted into
  blocks on close. The state is saved per backpack.

---

🧱 v1.3.0

• Minecraft / Paper 26.2 support – the plugin is now built against
  paper-api:26.2.build.62-beta and runs on Paper 26.1.2 – 26.2. No API
  breakage was needed: 26.2 still targets Java 25, and no 26.2-exclusive API
  is used, so the same jar works on both.
• api-version updated to '26.1.2' – the old '1.21' declaration
  predates the new YY.D.H versioning scheme. api-version is the minimum
  server version, so 26.1.2 keeps 26.1.2 servers working while correctly
  declaring modern-scheme compatibility.
• Anvil rename future-proofed – switched from the deprecated
  AnvilInventory#getRenameText() (marked for removal) to AnvilView#getRenameText().
  The build is now warning-free.

Note: Paper 26.2 currently only publishes alpha/beta builds (latest
26.2.build.62-beta); there is no -stable 26.2 build yet. The API surface this
plugin uses is unaffected.

---

🖼️ v1.2.3

• Restock & Feeding upgrades use their prepared Oraxen textures – in v1.2.0
  these two new upgrades were bound to made-up model IDs that collided with other
  items, so with Oraxen active they showed the wrong texture. They now bind to the
  bundled assets ysbp_upgrade_restock (restock.png, CMD 2110) and
  ysbp_upgrade_feeding (feeding.png, CMD 2137). The Auto-Restock upgrade is now
  simply called Restock. (config-version 11; fresh/merged configs pick this up —
  a test server from v1.2.0–1.2.2 should delete its config.yml to regenerate, or set
  feeding CMD 2137 / rename auto_restock→restock by hand.)

---

🇵🇱 v1.2.2

• Polish translation completed – the Polish locale was missing 25 keys
  (whole rename, transfer, locate, assets, doctor, trash sections plus
  some help/error entries) that fell back to English. All three bundled locales
  (en, de, pl) are now at full key parity (102/102) – no more English
  fallback for Polish players.

---

🌐 v1.2.1

• All languages ready via config – en, de and pl are now all extracted
  to the data folder on startup, so you can switch language: to any of them and
  edit any messages_<lang>.yml directly (previously only the active language and
  English were written out).
• Translations survive updates – on every start each bundled language file is
  merged: new message keys are added while your own edits are kept untouched, so
  upgrading the plugin never loses or overwrites your translations. Add your own
  language by creating messages_<code>.yml and setting language: to that code.

---

✨ v1.2.0

New features & QoL

• Async storage cache – backpack data now lives in an in-memory cache with
  asynchronous, batched write-behind. Reads (open, page-flip, pickup, furnace
  ticks, %ysbp_*% placeholders) no longer hit the disk on the main thread, and
  writes are bundled off-thread. A full flush always runs on a clean shutdown.
  Tune the interval with storage.flush-seconds (default 5).
• Config merge on update – updating to a new config version now keeps your
  own settings and only adds the new keys/comments (a timestamped backup is still
  written), instead of overwriting the whole file.
• Auto-Restock Upgrade (new) – when a hotbar/inventory stack runs out, it is
  refilled from the backpack with the same item. Craft with Comparators + Chests
  around Upgrade Leather.
• Feeding Upgrade (new) – automatically eats food from the backpack when you
  get hungry (with an eat sound). Craft with Hay Bales + Bread around Upgrade Leather.
• Quick-Stack – Shift-click the Info button to sweep all matching items from
  your inventory into the backpack. (Normal click still sorts.)
• Shift-click fills all pages – shift-clicking items in now spreads them across
  every page of a multi-page backpack, not just the visible one.
• Last page remembered – a multi-page backpack reopens on the page you last used.
• /bp stats – total / placed / per-tier backpack counts and storage size.
• /bp purge [dry|confirm] – safely removes empty, orphaned backpack data
  (destroyed or churned empties). Non-empty data is never touched, so nothing an
  offline player still holds can be lost.

Bug fixes & hardening

• Soulbound dupe fixed – a backpack no longer duplicates when another plugin sets
  keepInventory after the death event starts; give-back is now loss-safe on disconnect.
• Off-hand swap (F) can no longer sneak a backpack into a mount inventory.
• Creative protection now covers every sub-GUI (Upgrade / Furnace / Filter / Trash / XP).
• Corruption resilience – a single broken item no longer aborts loading the whole
  backpack; per-slot recovery keeps the rest.
• Deeper nesting check, /bp list [Open] works for owners, recipe/achievement
  edits apply on /bp reload, and assorted null-safety fixes.

---

🐞 v1.1.3

• Magnet chat messages fixed – /bp magnet on|off (and the no-argument
  toggle) now correctly shows the “Magnet enabled/disabled” confirmation
  instead of a “Missing message: magnet.on / magnet.off” error. Cause: on
  and off are reserved YAML booleans, so the keys were parsed as
  magnet.true / magnet.false and never resolved. The keys are now quoted in
  all message files (messages_de/en/pl.yml), so the fix applies to every
  language – deleting a message file is not required.

---

✨ v1.1.2

• Magnet toggle – switch the magnet pull on/off per player with
  /bp magnet on|off (no argument toggles). A short chat message confirms the
  new state; the setting also gates the Advanced Pickup vacuum.
• One Magnet / one Pickup backpack at a time – you can own many backpacks
  with these upgrades, but only one Magnet backpack and one Pickup backpack may be
  active in your inventory. Carrying more auto-disables that upgrade (dupe/behaviour
  safety) until only one remains, with a throttled action-bar notice.
• Pickup filter – the Pickup upgrade now has a filter menu (like the
  Compacting filter). Only the items you place there are pulled straight into the
  backpack. Matching is NBT-exact, so custom items / custom NBT can be
  whitelisted precisely. An empty filter picks up everything. Open it from the
  Pickup Filter button in the backpack menu.

---

🐞 v1.1.1

• Textures update after /oraxen reload – after redeploying assets and
  reloading Oraxen, freshly added/changed textures didn't apply to crafted, given
  or /bp info items (the plugin still served its cached item models) until you
  toggled the module off and on. The plugin now listens for Oraxen's reload event
  and auto-resyncs its canonical items, carried backpacks and placed models, so
  new textures apply immediately – no module toggle needed.
• Placed models follow the module state – disabling the Oraxen module (or
  removing Oraxen entirely) left placed backpack 3D models in the world, which would
  show missing textures once Oraxen is gone. Placed models now fall back to the
  vanilla look when the hook is off – updated on toggle/reload for loaded ones and
  automatically when their chunks load.

---

✨ v1.1.0

• Soulbound Upgrade (new) – a new functional upgrade with its own Oraxen
  texture. A backpack with this upgrade stays with you when you die instead of
  dropping, and you keep it after respawn. It is dupe-safe next to grave/deadbody
  plugins: the death handler runs at LOWEST priority and removes soulbound
  backpacks from the death drops before grave plugins read them, and the backpack
  content lives server-side by ID (so even a stray copy shares the same storage).
  Craft it with a Totem of Undying + Soul Soil around Upgrade Leather.
• Carried backpack now uses your colors – the carried/held Oraxen backpack
  baked the tier color into its overlay layer (e.g. an Emerald backpack stayed
  green and dyeing the accent didn't fully show). The overlay is now neutral
  (tier-independent), so the body takes your main color (dyeable base) and the
  accent variant colors the straps/pockets – the same fix v1.0.9 shipped for placed
  backpacks. (Resource-pack change – run /oraxen reload after updating; existing
  backpacks refresh automatically on open/join.)

---

🐞 v1.0.9

• Placed backpack now uses the main color – the body of a placed Oraxen
  backpack had the tier's default main color baked in (e.g. an Emerald backpack
  stayed green) regardless of the chosen color. The body texture is now dyeable
  (tintindex 0 + neutral base), so the placed backpack body takes your main
  color while the accent variant still colors the frame/side parts. (Resource-
  pack change – run /oraxen reload after updating.)

---

🐞 v1.0.8

• Accent color now updates when dyeing – dyeing a backpack (or /bp color)
  only re-tinted the main color and lore but kept the old Oraxen accent model, so
  the accent stayed at its previous color. The item is now fully refreshed so the
  accent texture switches to the new color too.
• Existing backpacks get updated – opening a backpack now also refreshes all
  other backpacks carried by the player, so previously dyed backpacks pull the
  corrected accent model (in addition to the existing refresh on join).

---

🐞 v1.0.7

• Achievement chat broadcast fixed – unlocks are now announced in chat
  reliably. Programmatically awarding an advancement only fired the toast (not the
  chat line) on this version, so the broadcast is now sent by the plugin itself
  (gated by achievements.broadcast, default on).

---

🐞 v1.0.6

• Tab background fixed for MC 26.x – newer versions resolve the background
  via the texture-id convention (the client adds textures/ + .png). Even the
  classic full path renders as a missing texture there. The default is now the
  guaranteed minecraft:block/dirt. Changeable via achievements.background
  (block/stone, block/netherrack, … or none for no background).

---

🐞 v1.0.5

• Tab background configurable + new texture format – it can be changed in
  the config without a new release if it shows up as missing texture.
• Chat broadcast on by default – unlocked achievements are now announced in
  chat by default (achievements.broadcast: true, respects the
  announceAdvancements gamerule).
• Nicer menu – achievements are now chained into themed branches (tiers,
  customization, placing, upgrades, stations) instead of one long column; tier
  achievements use the "goal" frame, hard ones the "challenge" frame.

---

🐞 v1.0.4

• Switched the tab background to a dedicated advancement background texture.
• Tab & all achievements visible – the (invisible) root is granted to every
  player on join so the achievement tab appears and all achievements (greyed
  out until earned) are shown.

---

🐞 v1.0.3

• Advancement datapack fix – the background field of the achievement tab
  must be a string; otherwise the advancements failed to load (Not a string: {...}). The tab and all achievements load cleanly now.

---

✨ v1.0.2

• Achievements are now real Minecraft advancements – instead of a custom
  command/menu they appear as their own tab ("yourShika Backpack's") in the
  normal advancements screen (toast + progress handled by vanilla). The plugin
  generates a small datapack automatically and loads it on first start. Still
  configurable via achievements.enabled / broadcast / disabled.
• /bp achievements was removed (replaced by the native integration).

---

✨ v1.0.1

• Achievements – 28 achievements (title, description, icon). Unlocking gives
  a message + sound, optional server-wide announcement. Fully configurable.
• Pickup sound – the Pickup upgrade plays a pickup sound when vacuuming items.
• Magnet now pulls items over blocks instead of dragging them into the
  ground (a slight lift, nothing disappears anymore).
• Compacting recipe reworked – it collided with the Iron upgrade before; now
  made from pistons + iron blocks (distinct and a bit harder).
• Everlasting more expensive – now needs a Nether Star (Wither) + netherite + obsidian.
• Anvil protection – upgrade items (Upgrade Leather, tier & function upgrades)
  can no longer be renamed in an anvil.

---

🎉 v1.0.0 – First stable release

The first official milestone. Contains all features of the 0.x line – tiers &
upgrade chain, dyeable backpacks, placeable backpacks with holograms, functional
upgrades (Pickup, Magnet, Crafting/Smithing/Stonecutter, portable
Furnace/Smoker/Blast Furnace with background operation, Compacting with filter,
Ender-Link, Trash, Recall, Everlasting, XP Storage), dupe-safe storage, Oraxen
assets incl. 3D models for placed backpacks, plus multi-language support (EN/DE/PL).

• The XP Storage upgrade now has its own, style-matching item asset
  (experience bottle) for Oraxen.
• Tier upgrade keeps the name – a custom backpack name (incl. colors) is kept
  when upgrading at the smithing table.
• Final review: assets, code and recipes checked; CI model check green.

---

✨ v0.9.1

• Hologram name rendered correctly – placed backpacks with gradient/hex/
  color-code names now show the name properly (instead of e.g. "<#aabbcc>…").
• New XP Storage upgrade – store your experience in the backpack and
  withdraw it any time. Own button in the control bar with a GUI
  (deposit/withdraw, 1 level or all) and a live display of the stored XP.

---

✨ v0.9.0

• Rename in the anvil – backpacks can be renamed directly in an anvil,
  with full color support: hex (&#RRGGBB / <#RRGGBB>),
  gradient/rainbow (<gradient:#a:#b>…) and Minecraft color codes (&a, &l …).
• Name persists when placed – a placed and then picked-up backpack no longer
  loses its custom name (the name is stored server-side).
• Portable furnace runs in the background – smelting stations keep working
  even when the menu is closed. The furnace icon in the backpack shows a
  live-updating lore: what is being smelted, fuel type/amount and how many
  items will be smelted in total.
• Compacting chat message – on close the backpack reports what was compacted
  (e.g. "3x Diamond Block").
• /bp recall menu now shows the owner of each placed backpack.
• Trash protects backpacks – backpacks (also inside shulkers/bundles) can no
  longer be put into the trash.
• Station limit – at most 5 station upgrades fit per backpack so all icons
  in the control bar stay visible and don't fight for space.

---

✨ v0.8.0

Commands & management

• /bp rename <name|reset> – rename backpacks (config rename.allow-players, admins always)
• Clickable /bp list – [Open] [Copy] [TP]
• /bp locate [player|ID] + /bp goto <ID> – locate placed backpacks & teleport to them
• /bp transfer <ID> <player> – change owner
• /bp recall opens a selection menu when you have several backpacks (otherwise direct)
• /bp assets <status|redeploy> & /bp doctor (diagnostics)
• Admin audit log (audit.log): give/openid/transfer/recall/pickup
• More PlaceholderAPI: placed, used_slots, free_slots, tiers, count_<tier>

GUI

• Info item shows used/free slots
• Shift-click the paging arrows jumps to the first/last page

Placed backpacks

• Rotate to face the player; optional hologram (name + owner); particles + sound when placing/picking up

Upgrades

• Trash with delete confirmation (trash.confirm) – closing without a click returns the items
• Compacting preview (chat) + presets (ores/farm/redstone/misc)
• Magnet: throttle against lag + respect for item owner & pickup delay

Robustness & CI

• Deep-nesting protection: backpacks in shulkers/bundles are detected & blocked
• Auto-recovery: save on page change + crash detection
• Recipe validation with clear config error messages
• CI asset check: prevents one-sided faces in Oraxen models

---

✨ v0.7.2 (Placed Backpack Geometry)

• Placed Oraxen backpacks now use real cuboid geometry for flap, pocket,
  side pouches, straps and buckle instead of one-sided faces, so they no longer
  disappear from certain viewing angles.
• Oraxen asset bundle bumped to version 6 so managed model files update
  automatically while custom server assets stay protected by the deployer.

---

✨ v0.7.1 (Portable Stations, Filter, configurable recipes)

• Items auto-update on join/update: existing backpacks and upgrade items are
  brought to the latest state when a player joins (and on reload), so nothing
  breaks or looks stale after a plugin update.
• Portable Furnace / Blast Furnace / Smoker: the Smelting/Blasting/Smoking
  upgrade now adds a GUI station (icon in the backpack) that smelts like a real
  furnace. State is saved in the backpack – logout, crash or server stop never
  lose items, and progress persists. Only one furnace-type upgrade per backpack.
• **Compacting Filter: