{"id":"encodedlux/vide-backpack","name":"vide-backpack","scope":"encodedlux","platform":"roblox","description":"A modern and reactive backpack system for Roblox, built using Vide.","version":"0.1.0-rc.7","latest":"0.1.0-rc.7","versions":["0.1.0-rc.3","0.1.0-rc.4","0.1.0-rc.5","0.1.0-rc.6","0.1.0-rc.7"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{"1foreverhd/topbarplus":{"version":"^3.4.0","alias":"topbarplus"},"centau/vide":{"version":"^0.4.0","alias":"vide"}},"integrity":"77425e72adb34731aa0f016cfbb5d0f6290e173ece0b25c05027ef8d55e8c688","likes":0,"downloads":0,"install":"forest install encodedlux/vide-backpack","url":"https://forest.dev/p/roblox/encodedlux/vide-backpack","files":"https://api.forest.dev/ai/package/roblox/encodedlux/vide-backpack/files","readme":"# 🎒 VideBackpack\r\n\r\n![VideBackpack Preview](assets/preview.png)\r\n\r\nA modern and reactive backpack system for Roblox, built using [Vide](https://github.com/centau/vide).\r\n\r\n---\r\n\r\n## ⚡ Features\r\n\r\n- **Familiar UI**: Maintains a highly intuitive layout familiar to Roblox players, matching the core interface patterns they expect, but elevated with a sleek, premium, and modern aesthetic.\r\n- **Customizable Themes**: Highly customizable theme properties using `setTheme`. Easily switch between predefined themes (`default` and `white`) or define your own.\r\n- **Total Architectural Freedom**: Highly modular source code. You have absolute freedom to edit, extend, or rewrite UI components to match any unique design or specific gameplay behavior.\r\n- **Custom Categorization**: Group your inventory items into tab categories (e.g., Weapons, Potions, Resources) using simple, custom declarative predicate functions.\r\n\r\n---\r\n\r\n## 📦 Installation\r\n\r\n### Github Releases\r\n\r\n1. Download the `VideBackpack.rbxm` model file from the [Github Releases](https://github.com/GuiRios7/VideBackpack/releases).\r\n2. Open Roblox Studio and create a new place or open an existing place.\r\n3. In the Explorer window, insert **VideBackpack** into **ReplicatedStorage**.\r\n4. Select the **VideBackpack** model file you downloaded from GitHub.\r\n\r\n**VideBackpack** uses [RunContext](https://devforum.roblox.com/t/live-script-runcontext/1938784) to run anywhere, so you do not need to move it from Workspace, though it is recommended to parent it to **ReplicatedStorage** for better practices and organization.\r\n\r\n### Wally\r\n\r\nAdd **VideBackpack** to your `wally.toml` dependencies:\r\n```toml\r\n[dependencies]\r\nVideBackpack = \"encodedlux/vide-backpack@0.1.0\"\r\n```\r\nThen, run `wally install` in your project folder.\r\n\r\n---\r\n\r\n## 💡 Usage\r\n\r\n### 1. Basic Setup\r\nInitialize VideBackpack in your client script:\r\n```lua\r\n-- Require VideBackpack to run startup\r\nrequire(\"@game/ReplicatedStorage/Packages/VideBackpack\")\r\n```\r\n\r\n### 2. Registering Custom Categories\r\nGroup items dynamically based on tag configurations or attributes:\r\n```lua\r\nlocal VideBackpack = require(\"@game/ReplicatedStorage/Packages/VideBackpack\")\r\n\r\n-- Category for items tagged as \"Consumable\"\r\nVideBackpack.createCategory(\"Consumable\", function(item)\r\n    return item:HasTag(\"Consumable\")\r\nend)\r\n\r\n-- Category for tools whose name starts with \"Sword\"\r\nVideBackpack.createCategory(\"Swords\", function(item)\r\n    return string.match(item.Name, \"^Sword\") ~= nil\r\nend)\r\n```\r\n\r\n### 3. Subscribing to Inventory Lifecycles\r\nTrack when items are equipped and handle custom mechanics:\r\n```lua\r\nlocal VideBackpack = require(\"@game/ReplicatedStorage/Packages/VideBackpack\")\r\n\r\nlocal disconnect = VideBackpack.onBackpackEquipped(function(item)\r\n    print(\"Player is now holding their:\", item.Name)\r\nend)\r\n\r\n-- Clean up subscriptions when no longer needed (optional)\r\ndisconnect()\r\n```\r\n\r\n### 4. Changing Themes\r\nSeamlessly update colors, fonts, corner radius, and stroke values on the fly with smooth transition animations:\r\n```lua\r\nlocal VideBackpack = require(\"@game/ReplicatedStorage/Packages/VideBackpack\")\r\n\r\n-- Switch to the light theme (white)\r\nVideBackpack.setTheme(VideBackpack.themes.white)\r\n\r\n-- Switch to the default theme (dark)\r\nVideBackpack.setTheme(VideBackpack.themes.default)\r\n\r\n-- Or create a custom theme\r\nlocal customTheme = {\r\n    backgroundColor = Color3.fromHex(\"#492a17ff\"),\r\n    textColor = Color3.fromHex(\"#e09e74ff\"),\r\n    ...\r\n} :: VideBackpack.ThemeConfig\r\n\r\nVideBackpack.setTheme(customTheme)\r\n```\r\n\r\n---\r\n\r\n## 🛠️ API Reference\r\n\r\n### Functions\r\n\r\n#### `setEnabled(enabled: boolean)`\r\nEnables or disables the custom backpack interface.\r\n- **`enabled`**: Set to `true` to display the UI, or `false` to hide it.\r\n```lua\r\nVideBackpack.setEnabled(true)\r\n```\r\n\r\n#### `isEnabled() -> boolean`\r\nReturns whether the custom backpack UI is currently enabled.\r\n```lua\r\nlocal isEnabled = VideBackpack.isEnabled()\r\n```\r\n\r\n#### `openInventory()`\r\nOpens the inventory screen interface.\r\n```lua\r\nVideBackpack.openInventory()\r\n```\r\n\r\n#### `closeInventory()`\r\nCloses the inventory screen interface.\r\n```lua\r\nVideBackpack.closeInventory()\r\n```\r\n\r\n#### `toggleInventory()`\r\nToggles the visibility state of the inventory interface.\r\n```lua\r\nVideBackpack.toggleInventory()\r\n```\r\n\r\n#### `isInventoryOpen() -> boolean`\r\nReturns whether the inventory screen is currently open.\r\n```lua\r\nlocal isOpen = VideBackpack.isInventoryOpen()\r\n```\r\n\r\n#### `createCategory(name: string, predicate: (item: Tool | HopperBin) -> boolean)`\r\nCreates a custom category filtering items based on the provided predicate function.\r\n- **`name`**: The display name of the category (e.g., `\"Weapons\"`).\r\n- **`predicate`**: A function that receives an `item` and returns a `boolean` (whether the item belongs in the category).\r\n```lua\r\nVideBackpack.createCategory(\"Weapons\", function(item)\r\n    return item:HasTag(\"Weapon\")\r\nend)\r\n```\r\n\r\n#### `getTopbarIcon() -> Icon?`\r\nReturns the `TopbarPlus` icon instance generated by the module.\r\n```lua\r\nlocal icon = VideBackpack.getTopbarIcon()\r\nif icon then\r\n    icon:setLabel(\"Inventory\")\r\nend\r\n```\r\n\r\n#### `setTheme(config: ThemeConfig)`\r\nSets the active theme configuration.\r\n- **`config`**: The new `ThemeConfig` layout to apply. Individual values are automatically animated using spring physics.\r\n```lua\r\nVideBackpack.setTheme(VideBackpack.themes.white)\r\n```\r\n\r\n---\r\n\r\n### Events (Hooks)\r\n\r\nAll event listeners return a **disconnect function** when called, which can be executed to clean up and stop listening to the event.\r\n\r\n#### `onInventoryOpened(callback: () -> ()) -> (() -> ())`\r\nFires whenever the player's inventory interface is opened.\r\n```lua\r\nlocal disconnect = VideBackpack.onInventoryOpened(function()\r\n    print(\"Player opened their inventory!\")\r\nend)\r\n\r\n-- Unsubscribe when no longer needed:\r\ndisconnect()\r\n```\r\n\r\n#### `onInventoryClosed(callback: () -> ()) -> (() -> ())`\r\nFires whenever the player's inventory interface is closed.\r\n```lua\r\nVideBackpack.onInventoryClosed(function()\r\n    print(\"Player closed their inventory!\")\r\nend)\r\n```\r\n\r\n#### `onBackpackEquipped(callback: (item: Tool | HopperBin) -> ()) -> (() -> ())`\r\nFires when the player equips an item on character.\r\n- **`item`**: The `Tool` that was equipped.\r\n```lua\r\nVideBackpack.onBackpackEquipped(function(item)\r\n    print(\"Equipped item:\", item.Name)\r\nend)\r\n```\r\n\r\n#### `onBackpackUnequipped(callback: (item: Tool | HopperBin) -> ()) -> (() -> ())`\r\nFires when the player unequips their currently active item.\r\n- **`item`**: The `Tool` that was unequipped.\r\n```lua\r\nVideBackpack.onBackpackUnequipped(function(item)\r\n    print(\"Unequipped item:\", item.Name)\r\nend)\r\n```\r\n\r\n#### `onBackpackAdded(callback: (item: Tool | HopperBin) -> ()) -> (() -> ())`\r\nFires when an item is added to the player's backpack.\r\n- **`item`**: The `Tool` or `HopperBin` that was added.\r\n```lua\r\nVideBackpack.onBackpackAdded(function(item)\r\n    print(\"Added to backpack:\", item.Name)\r\nend)\r\n```\r\n\r\n#### `onBackpackRemoved(callback: (item: Tool | HopperBin) -> ()) -> (() -> ())`\r\nFires when an item is removed entirely from the player's backpack.\r\n- **`item`**: The `Tool` or `HopperBin` that was removed.\r\n```lua\r\nVideBackpack.onBackpackRemoved(function(item)\r\n    print(\"Removed from backpack:\", item.Name)\r\nend)\r\n```\r\n\r\n#### `onBackpackEmpty(callback: () -> ()) -> (() -> ())`\r\nFires when the backpack becomes entirely empty (contains no items).\r\n```lua\r\nVideBackpack.onBackpackEmpty(function()\r\n    print(\"The backpack is now empty!\")\r\nend)\r\n```\r\n\r\n---\r\n\r\n## 🤝 Credits\r\n\r\n- Special thanks to [Purse](https://github.com/ryanlua/purse) by [ryanlua](https://github.com/ryanlua) for some utility implementations used in this project.\r\n\r\n---\r\n\r\n## 📄 License\r\n\r\nVideBackpack is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.","readmeTruncated":false}