Skip to content
Sources: data/lua/README.md data/lua/manifest.schema.json data/lua/types/ccb_api_v5.d.lua data/lua/reference/ccb_public_api_v5.json data/lua/reference/ccb_public_api_v5_coverage.json tools/lua_api/README.md commit d32b9cc880a8 api-contract

Lua sections need revision: This page contains removed v5 APIs or old runtime examples. Do not use its Lua examples for current development. Start with Platform v1.

Items & Pockets Manual

This manual details the item entity model, physical unit conversions, and the Pocket tree container architecture in Cataclysm: Cleanwater Bomb (CCB).

1. Physical Units & Standards

CCB enforces consistent metric standards across all items:

  • Weight: Stored as an integer in grams (g). E.g., 1500 is 1.5 kg.
  • Volume: Stored as an integer in milliliters (ml). E.g., 2500 is 2.5 L.
  • Length Constraints: Stored in millimeters (mm) for holsters and scabbards.
  • Price: Stored in cents. E.g., 1000 is $10.00.

2. Pocket Container Tree Architecture

Single-layer inventory arrays are replaced by recursive Pocket trees:

  • max_contains_volume (integer): Maximum volume limit (ml).
  • max_contains_weight (integer): Maximum weight limit (g).
  • max_item_length (integer): Maximum length limit (mm).
  • watertight (boolean): Fluid sealing for liquids and gases.
  • rigid (boolean): If false, total volume expands as internal pockets are filled.
  • moves (integer): Action point cost to draw or stow items into this pocket.

3. Core APIs

game.items.register(config)

Registers a new item archetype with the engine.

Example: 

game.items.register({
    id = "ccb_canteen_sealed",
    name = "Sealed Military Canteen",
    weight = 250,  -- 250g dry mass
    volume = 1200, -- 1.2L external volume
    category = "container",
    pockets = {
        {
            pocket_type = "CONTAINER",
            max_contains_volume = 1000, -- 1.0L liquid
            max_contains_weight = 1200,
            watertight = true,          -- Sealed against leaks
            open_container = false
        }
    }
})

item:get_total_weight() -> integer

Recursively calculates the total weight of the item including all contents inside nested pockets.