Skip to content
ct
Docs
Menu

Item Vault v1.0

JSON Catalogs and Saves

Load item catalogs from JSON and keep ItemStack dictionaries save-friendly.

Status
Draft
Version
v1.0
Updated
Development docs generated from GDScript source

This is unreleased documentation in active development. APIs, class names, and behavior may change before the final release.

ItemVault supports both resource-authored item definitions and JSON-authored catalogs. Both paths produce the same runtime ItemDefinition objects and the same ItemStack save dictionaries.

Use JSON catalogs when your pipeline is data-heavy, spreadsheet-driven, or shared with other parts of your game.

Load a JSON Catalog

Configure ItemDatabase.definition_json_files and call reload():

var database:= ItemDatabase.new()
database.definition_json_files= ["res://items/catalog.json"]
database.reload()

You can also load one file directly:

var loaded_count:= database.load_json_file("res://items/catalog.json")
print("Loaded%d item definitions" % loaded_count)

Catalog Shape

JSON catalog files use this shape:

{
  "version":1,
  "items": [
    {
      "id":"iron_ore",
      "display_name":"Iron Ore",
      "category":"material",
      "tags": ["ore","smithing"],
      "max_stack":99,
      "weight":0.25,
      "world_scene":"res://pickups/ore_pickup.tscn"
    }
  ]
}

Supported item fields:

  • id: stable save/load id.
  • display_name: player-facing name.
  • category: inventory category, for example material or currency.
  • tags: array of query tags.
  • max_stack: default stack limit.
  • weight: default weight per unit.
  • icon: optional Texture2D resource path.
  • world_scene: optional PackedScene resource path for world drops.

Resource and JSON Catalogs Can Mix

ItemDatabase.reload() scans definition_dirs and then loads definition_json_files:

var database:= ItemDatabase.new()
database.definition_dirs= ["res://items/resources"]
database.definition_json_files= ["res://items/catalog.json"]
database.reload()

If the same id appears twice, the later registration replaces the earlier one and ItemVault warns about the duplicate. Keep ids stable and unique for release builds.

Stack Save Dictionaries

ItemStack.to_dict() produces the compact stack shape used by ItemVault saves:

var stack:= ItemStack.new(database.get_def(&"iron_ore"),12)
stack.instance_id= &"mine_drop_042"
var data:= stack.to_dict()

Result:

{
  "id":"iron_ore",
  "qty":12,
  "iid":"mine_drop_042"
}

ItemStack.from_dict(data, database) restores a stack when the item id resolves through the database.

Pass Stack Data to Other Game Systems

If another part of your game keeps its own world state, pass the stack dictionary at the project boundary:

var stack:= WorldItemStackMeta.read(spawned_pickup)
if stack!= null:
	world_items.restore_stack(stack.to_dict())

ItemVault remains the item/drop/pickup source. Your game owns the world object and any extra state it attaches to the stack. An ECS can map the same dictionary into its own components through a small project script.

Persistent World Drops

Pickup stack metadata lives on the pickup node. If the node is freed or the world unloads, the metadata disappears with that node. To persist dropped-world-items, save the stack dictionary before removing the pickup:

var stack:= WorldItemStackMeta.read(pickup)
if stack!= null:
	save_world_drop({
		"position": pickup.global_position,
		"stack": stack.to_dict(),
	})

On load, resolve the stack through ItemStack.from_dict(data, database), spawn a pickup scene, and write the stack back with WorldItemStackMeta.write(pickup, stack).

Related References