Visual Inventory

README Generated by AI

A visual inventory plugin for Godot 4.8. It provides both configurable item, inventory and interface resources in the editor, as well as runtime capabilities for item placement, picking, rotation, stacking and transfer.

Current plugin version: 0.5 (see addons/visual_inventory/plugin.cfg). The repository comes with a demo project; for actual integration, simply copy the addons/visual_inventory entire directory.

Feature Overview

• Highest Integration Node: Highly integrated, all the work from creating a backpack from scratch can be completed in one node of InventoryHost.
• Visual Editing: In the Inspector, provide visual panels for editing ItemData, InventoryData, and InventoryHostDefinition, as well as the grid panels for editing Shape and OccupyMap.
• Multiple Layouts: Provide Host presets for grid, directory and surround layouts. The interface layout and available functions are configured separately.
• Item Data: Item templates can set name, icon, description, maximum stack size and combinable Part; item instances save quantity, direction and instance state.
• Inventory Operations: Support placement, moving, picking, rotation, merging, splitting quantity and transfer between inventories. The operations are planned, rule-based and submitted, and the results include success status and failure reasons.
• Optional Extensions: The repository also contains nested inventories, tags, counting, reactions, animations and store-related Parts, Features and runtime implementations. Configure corresponding resources and dependencies according to project needs.

Installation

1. Open your project using Godot 4.8. This repository declares version 4.8 for project.godot; other Godot versions have not yet been proven compatible in this repository.
2. Copy the entire addons/visual_inventory/ directory from the repository to the target project's res://addons/visual_inventory/. Preserve the directory structure and the resources, scenes, images and scripts within.
3. Enable VisualResEditorPanel in Project > Project Settings > Plugins. When enabled, InventoryInputMapSetup.ensure_bindings() will be automatically called, writing the following table of actions to Project Settings > Input Mapping (existing bindings will not be overwritten). You can also manually run the same API in Tools > Register Inventory Input Mapping; the runtime script can call the same API.

The input actions are used by the Feature configured in the Host; when no corresponding Feature is configured, adding the input mapping itself will not enable this behavior.

Run the Demo First

Clone this repository and open the root directory with Godot 4.8. Run the project to enter addons/visual_inventory/visual_inventory_dome.tscn. The demo scene displays the same visual_inventory_dome_inventory.tres in the grid, directory, and surround layout Host, making it suitable for observing different layouts and input behaviors.

To try the editor:

1. Select addons/visual_inventory/visual_inventory_dome_inventory.tres in the file system, use the visual inventory editor at the top of the Inspector, make changes, and save the resource.
2. Select an item resource under addons/visual_inventory/gdbase/inventory/presets/item/, click Open Item Creator in the Inspector. You can also start from the Tools > New Item in the editor.
3. Select addons/visual_inventory/gdbase/inventory/presets/host/grid_inventory_host.tres, click Open Visual Editor, view the layout and function configuration; make changes and click Apply.

The demo resources are also editable data. If you want to retain the original example, first copy the corresponding .tres and then make modifications.

Use in Your Own Scene

The main resources and node relationships of the plugin are as follows:

The most straightforward integration method is to copy a InventoryHost node and its child nodes from the demonstration scene, then replace its inventory_data and definition. You can first select a grid, directory, or surrounding preset from gdbase/inventory/presets/host/, and then open the definition editor in the Inspector to adjust the layout and Features. The Create Backpack Assembly and Remove Backpack Assembly tool buttons of InventoryHost are used to rebuild or remove its interface assembly.

If you need to bind runtime data from scripts, you can use InventoryHost.apply_runtime_binding(next_inventory, next_owner, next_dependencies, next_transfer_target). Ordinary interfaces without entity dependencies can directly set inventory_data and definition. To connect a quick transfer target, point the transfer_target_host of the source Host to the target Host and configure the corresponding Feature.

The item members of InventoryData are based on the occupancy records of occupy_map; item_instances are derived caches. In normal gameplay, please modify the content through the inventory operation interface, do not just rewrite item_instances. System calls without an interface need to explicitly use InventoryOperationContext.system(); Calls initiated by the Host should use the corresponding operation endpoint and strategy.

Directory Structure

addons/visual_inventory/
├── plugin.cfg                 # Entry file for the editor plugin
├── visual_inventory_dome.tscn # Demonstration scene
├── visual_inventory_dome_inventory.tres
├── item_data/                 # Item Editor
├── inventory_data/            # Inventory Editor
├── inventory_host_definition/ # Host Layout and Function Editor
├── shape/  and occupy/        # Grid Resource Editor
└── gdbase/
├── inventory/core/       # Items, inventory, operation protocols
├── inventory/parts/      # Composable items, Part and extension functions
├── inventory/ui/         # Host, layout, input and presentation
└── inventory/presets/    # Replicable or modifiable preset resources

Erw's Words

It was simply impossible to write a large number of visual editing panels specifically for the inventory system before. It was cumbersome and not very user-friendly. For me, I would rather write more code using nodes to create a backpack than to write dedicated editing panels for these resources. But the emergence of AI has changed all this. To reduce the burden of human interaction, using AI's powerful capabilities to write visual resource editing panels has become an option. For me, it can alleviate a lot of repetitive configuration work. I can use it to create many different inventories and don't need to make wishes to the AI. Because this process of making wishes has been shifted to the initial stage. So why not let the AI configure the backpack characters and other things? I'm not sure about the answer to this question, but I think this is very Cool

Visual Inventory

README由AI生成

面向 Godot 4.8 的可视化库存插件。它同时提供可在编辑器中配置的物品、库存与界面资源，以及运行时的物品放置、拾取、旋转、堆叠和转移能力。

当前插件版本：0.5（见 addons/visual_inventory/plugin.cfg）。仓库自带演示项目；实际集成时只需复制 addons/visual_inventory 整个目录。

功能概览

• 最高集成节点：高度集成，在InventoryHost一个节点全可完成从零创建一个背包的所有工作。
• 可视化编辑：在 Inspector 中提供编辑 ItemData、InventoryData、InventoryHostDefinition的可视化面板，并编辑 Shape 和 OccupyMap 的格子面板。
• 多种布局：提供网格、目录和环绕布局的 Host 预设。界面布局与可用功能分开配置。
• 物品数据：物品模板可设置名称、图标、描述、最大堆叠数和可组合的 Part；物品实例保存数量、方向及实例状态。
• 库存操作：支持放置、移动、拾取、旋转、合并、拆分数量与库存间转移。操作经过规划、规则裁决和提交，结果包含成功状态及失败原因。
• 可选扩展：目录中还包含嵌套库存、标签、计数、反应、动画与商店相关的 Part、Feature 和运行时实现。按项目需要配置相应资源和依赖。

安装

1. 使用 Godot 4.8 打开你的项目。本仓库的 project.godot 声明了 4.8；其他 Godot 版本尚未在本仓库中证明兼容。
2. 将仓库的 addons/visual_inventory/ 完整复制到目标项目的 res://addons/visual_inventory/。保留目录结构和其中的资源、场景、图片与脚本。
3. 在 项目 > 项目设置 > 插件 中启用 VisualResEditorPanel。启用时会自动调用 InventoryInputMapSetup.ensure_bindings()，把下表动作写入 项目设置 > 输入映射（已有绑定不会被覆盖）。也可在 工具 > 注册库存输入映射 手动再跑一次；运行时脚本可调用同一 API。

输入动作由 Host 中配置的 Feature 使用；没有配置对应 Feature 时，添加输入映射本身不会启用该行为。

先运行演示

克隆本仓库后用 Godot 4.8 打开根目录，运行项目即可进入 addons/visual_inventory/visual_inventory_dome.tscn。演示场景把同一份 visual_inventory_dome_inventory.tres 显示在网格、目录和环绕布局的 Host 中，适合先观察不同布局及输入行为。

要尝试编辑器：

1. 在文件系统中选中 addons/visual_inventory/visual_inventory_dome_inventory.tres，在 Inspector 顶部使用可视化库存编辑器，修改后保存资源。
2. 选中 addons/visual_inventory/gdbase/inventory/presets/item/ 下的一个物品资源，点击 Inspector 中的 打开物品创建器。也可以从编辑器的 工具 > 新建物品 开始。
3. 选中 addons/visual_inventory/gdbase/inventory/presets/host/grid_inventory_host.tres，点击 打开可视化编辑器，查看布局与功能配置；修改后点击 应用。

演示资源也是可编辑数据。希望保留原始示例时，先复制对应 .tres 再修改。

在自己的场景中使用

插件的主要资源与节点关系如下：

最直接的集成方式是复制演示场景中的一个 InventoryHost 节点及其子节点，然后替换它的 inventory_data 与 definition。可先从 gdbase/inventory/presets/host/ 选择网格、目录或环绕预设，再在 Inspector 中打开定义编辑器调整布局和 Feature。InventoryHost 的 创建背包装配、移除背包装配 工具按钮用于重建或移除其界面装配。

如果需要从脚本绑定运行时数据，可使用 InventoryHost.apply_runtime_binding(next_inventory, next_owner, next_dependencies, next_transfer_target)。不需要实体依赖的普通界面也可以直接设置 inventory_data 和 definition。要连接快捷转移目标，在源 Host 的 transfer_target_host 指向目标 Host，并配置相应 Feature。

InventoryData 的物品成员以 occupy_map 的占用记录为准；item_instances 是派生缓存。正常玩法中请通过库存操作接口修改内容，不要只改写 item_instances。无界面系统调用需显式使用 InventoryOperationContext.system()；由 Host 发起的调用应使用对应的操作端点与策略。

目录说明

addons/visual_inventory/
├── plugin.cfg                 # 编辑器插件入口
├── visual_inventory_dome.tscn # 演示场景
├── visual_inventory_dome_inventory.tres
├── item_data/                 # 物品编辑器
├── inventory_data/            # 库存编辑器
├── inventory_host_definition/ # Host 布局和功能编辑器
├── shape/ 与 occupy/          # 格子资源编辑器
└── gdbase/
    ├── inventory/core/       # 物品、库存、操作协议
    ├── inventory/parts/      # 可组合物品 Part 与扩展功能
    ├── inventory/ui/         # Host、布局、输入与呈现
    └── inventory/presets/    # 可复制或修改的预设资源

erw的话

以前专门为库存系统写非常多可视化的编辑面板根本是不可能的事情，它吃力又不讨好。对于我来说，宁愿多敲代码用节点去拼一个背包也不愿意去为这些资源写专门的编辑面板。但AI的出现改变了这一切，为了减轻人类交互的负担，利用AI强大的能力写可视化的资源编辑面板成为了一个可选项。对我而言，它能够减轻许多重复化的配置工作。我能利用它做出非常多样的库存，并且不需要向AI许愿。因为这将许愿的流程转移到了前期。 那为什么不让AI去配置背包人物还有别的东西？我不清楚这个问题的回答，但我觉得这样很Cool

许可证

本项目以 MIT License 发布。