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.

Characters & Creatures Manual

This manual provides a detailed technical reference for the character, avatar, NPC, and monster entity subsystems in Cataclysm: Cleanwater Bomb (CCB).

1. Entity Hierarchy & Lifecycle

All living entities in CCB inherit from the Creature base class:

  • Creature: Base class providing 3D coordinates (tripoint), speed counter (moves), HP regeneration, line-of-sight checks (sees), and damage dispatch.
  • Character: Humanoid actor managing distinct anatomical body parts (body_part), pain, stamina, inventory trees, and martial arts.
  • avatar: The player entity bound to the input manager and mission logs.
  • monster: Non-humanoid creatures with AI trees, aggression, morale, and special attacks.

2. Anatomical Health Model (body_part)

A Character's health is tracked across 12 anatomical body parts:

Body Part ID Name Impact
"head" Head Vital part. Zero HP results in instant death. Concussions degrade stats.
"torso" Torso Vital part. Zero HP causes death. Governs armor encumbrance and carry mass.
"eyes" / "mouth" Eyes / Mouth Determines visual acuity, hearing, and gas mask filtration efficiency.
"arm_l" / "arm_r" Left / Right Arm Governs melee swing speed, ranged weapon aim stability, and blocking.
"hand_l" / "hand_r" Left / Right Hand Determines fine crafting agility and grip strength.
"leg_l" / "leg_r" Left / Right Leg Dictates base movement speed. Fractures drastically increase AP movement costs.
"foot_l" / "foot_r" Left / Right Foot Influences rough terrain traversing and stamina drain.

3. Core APIs

character:get_hp(part) -> integer

Queries the current hit points of the designated body part.

Parameters: * part (string, required): Target body part identifier (e.g., "head", "torso", "arm_l").

Returns: * integer: Current HP value.

Example: 

local torso_hp = player:get_hp("torso")
if torso_hp < 20 then
    game.add_msg("danger", "Your torso is critically wounded, bandage immediately!")
end

character:mod_pain(amount)

Modifies the pain index of the character. Pain decreases stats and movement speed.

Parameters: * amount (integer, required): Value delta. Positive increases pain, negative alleviates pain (analgesic).

character:add_effect(effect_id, duration)

Attaches a status buff or debuff to the character.

Parameters: * effect_id (string, required): Status identifier (e.g., "adrenaline", "bleed", "poison"). * duration (integer, required): Duration in turns.

Example: 

player:add_effect("adrenaline", 60)
game.add_msg("info", "Adrenaline rushes through your bloodstream!")

4. Key Event Subscriptions

events.on("character_takes_damage", function(event)
    local victim = event.character
    local damage = event.damage
    -- Custom energy shield absorption logic
end)

events.on("character_wakes_up", function(event)
    game.add_msg("info", "You awaken as morning light filters through the shelter.")
end)