repository·main·Indexed 41 days ago
https://github.com/devnatan/inventory-frameworkA Minecraft Inventory API framework providing a high-level, secure, and robust way to create custom inventories with specialized interaction behaviors. It includes a Minestom platform implementation featuring RenderContext for item manipulation and a ViewFrame for managing view lifecycles, as well as an IntelliJ plugin for static analysis-based visual previews of inventory layouts.
The IntelliJ plugin provides a split-view editor where the source code is on the left and a visual preview of the inventory view is on the right.
Key Characteristics:
The master branch is the only long-term branch. For short-term work, use the following naming patterns:
fix/something-needs-fix: Small routine patches for existing features.feat/something-new: New features or changes to existing features (be mindful of breaking changes).docs/improves-documentation-for-this-feature: Changes to documentation that do not impact source code.chore/update-gradle-version: Updates to project files not related to source code.To see items in the preview, you must use patterns that the static analyzer can resolve. The analyzer looks for literal new ItemStack(Material.X) calls or simple local variable initializers.
Supported Item Patterns:
slot(index, item), slot(index).withItem(item).firstSlot(item), lastSlot(item).layoutSlot(char, item).Material.X directly to a helper (e.g., withItem(ExampleUtil.displayItem(Material.STONE, "Label"))), the plugin uses the Material as a best-effort guess, even though it doesn't execute the helper.new ItemStack(Material.X, amount) renders a vanilla-style count badge if amount is a literal or a non-reassigned local variable.for (int i = 1; i <= 5; i++)), the plugin can resolve the loop counter i to render incrementing stack counts (e.g., 1 through 5).// Example of what the plugin can resolve
slot(0, new ItemStack(Material.DIAMOND, 64));
// Example of loop-based stack counts
for (int i = 1; i <= 5; i++) {
render.availableSlot(new ItemStack(Material.GOLD_INGOT, i));
}Commit messages should follow the seven rules of a great Git commit message to ensure clarity and maintainability:
Note: Vague messages like "fix tests" or "now it's working" will not be accepted. Additionally, always rebase your code to avoid reverse merge commits.
Comments should focus on explaining the why behind decisions rather than describing the code's structure or obvious behavior.
When to comment:
When NOT to comment:
The plugin attempts to render real item icons by reading model geometry directly from a local Minecraft client installation. If the plugin cannot auto-detect your Minecraft directory (e.g., if you use a portable launcher or a custom installation path), you can manually configure it.
Setup:
Go to Settings > Tools > Inventory Framework (MinecraftIconSettings) to override the .minecraft directory path.
All contributions to the inventory-framework project MUST use the English language. This requirement applies to:
To use the inventory framework in Minestom, you must create and register a ViewFrame. The ViewFrame acts as the central controller for managing views and their lifecycles.
ViewFrame.create(parentNode), passing in a Minestom EventNode (typically the server's main event node)..register() to initialize the framework, set up the element factory, and prepare the view pipeline.val viewFrame = ViewFrame.create(server.eventNode).register()Because the preview relies on static analysis rather than code execution, the following limitations apply:
renderWith/onRender lambdas, displayIf conditions, and complex item expressions will show as generic placeholders.row(n), column(n), firstRow(), etc., use a "fill the whole row/column" heuristic. The plugin treats every call site as if it fills the entire row/column, which may not match runtime behavior if you intended to fill only a single slot.availableSlot() Heuristics: The position of availableSlot() is estimated based on the layout and previously extracted slots. It does not simulate runtime interactability or complex nested loops.resultSlot() is unsupported: Items placed via resultSlot() will not appear in the preview.onClick and onSlotClick behaviors are not simulated.The ViewExtractor identifies several configuration properties to render the preview correctly:
.type(ViewType.X) or the Views.rows(n) shorthand (which implies CHEST)..size(n) or Views.rows(n)..title("literal string").layout(...) char grid.CHEST, HOPPER, DROPPER, DISPENSER, FURNACE, BLAST_FURNACE, CRAFTING_TABLE, BREWING_STAND, BEACON, ANVIL, SHULKER_BOX, SMOKER, VILLAGER_TRADING, and PLAYER.Use the open methods on a ViewFrame instance to display an inventory (a View) to one or more players.
View class and the Player object. You can optionally provide initialData to pass state to the view upon opening.Player objects. These players will share the same inventory context and see the same state.openActive to allow a player to join an already existing inventory context using its contextId.Note: Methods involving multiple players or active contexts are marked as @Experimental and may change in future releases.
// Open a new view for a single player
val contextId = viewFrame.open(MyView::class.java, player)
// Open a new view for a single player with initial data
viewFrame.open(MyView::class.java, player, myInitialData)
// Open a new view for multiple players (Experimental)
viewFrame.open(MyView::class.java, listOf(player1, player2))
// Open an existing context to a player (Experimental)
viewFrame.openActive(MyView::class.java, "existing-context-id", player)