Pets

Status: Design Date: 2026-04-04

Companion creatures that follow the player, deal minor combat damage, and appear in room descriptions. Simple system — no feeding, no leveling, no death.

Acquisition

Pets are purchased from shops in rooms with the pet-shop flag. Each pet-shop NPC sells a fixed selection of pet templates. Buying a pet costs gold.

{
  "id": 9001,
  "name": "Shadow Cat",
  "description": "A sleek black cat with faintly glowing eyes. It moves without sound.",
  "damage-type": "slash",
  "damage-pct": 8,
  "price": 500
}

Template Fields

Rules

• One active pet at a time. Buying a new pet replaces the current one (with confirmation prompt).
• Pets don’t die. They can’t be targeted in combat.
• Pets don’t level. Damage scales with the player’s level via the percentage model.
• No feeding or happiness. Zero maintenance.
• Pets are not tradeable. Bound to the player on purchase.
• Pets persist across sessions. Stored on the character for citizens, on the session for guests.

Combat

When the player is in combat, the pet attacks the same target each round. Damage is calculated as:

pet-damage = floor(player-base-damage * damage-pct / 100)

Where player-base-damage is the weapon damage + stat bonus (before armor reduction on the target). The pet’s damage is then reduced by the target’s armor as normal.

The pet attack appears in the combat log:

Your Shadow Cat slashes the goblin for 3 damage.

If the pet’s attack kills the mob, the player gets full credit (XP, loot, quest progress).

Commands

No summon or dismiss — the pet is always active once bought.

Room Display

The pet appears in the room description when looking:

Your companion Shadow Cat pads silently beside you.

Other players see:

Grendel’s Shadow Cat watches you with glowing eyes.

State

Character

Add pet=(unit pet-instance) to the character type:

+$  pet-instance
  $:  template-id=@ud
      name=@t
      description=@t
      damage-type=@tas
      damage-pct=@ud
  ==

The pet is stored directly on the character — no separate instance map needed. Template data is copied at purchase time so the pet works even if the template is later removed.

Pet Templates

Pet templates are defined at the world level in the area JSON. The full set of pets is the world’s roster — every pet-shop draws from this list.

{
  "pet-templates": [
    {"id": 9001, "name": "Shadow Cat", "description": "A sleek black cat with faintly glowing eyes.", "damage-type": "slash", "damage-pct": 8, "price": 500},
    {"id": 9002, "name": "Ember Hound", "description": "A red-furred hound that leaves faint scorch marks where it steps.", "damage-type": "fire", "damage-pct": 10, "price": 750},
    {"id": 9003, "name": "Bone Raven", "description": "A raven assembled from tiny bones, held together by will alone.", "damage-type": "shadow", "damage-pct": 6, "price": 400},
    {"id": 9004, "name": "Marsh Toad", "description": "An oversized toad that secretes a mildly corrosive slime.", "damage-type": "poison", "damage-pct": 7, "price": 350},
    {"id": 9005, "name": "Iron Beetle", "description": "A fist-sized beetle with a metallic carapace that glints in the light.", "damage-type": "blunt", "damage-pct": 12, "price": 900},
    {"id": 9006, "name": "Wisp Lantern", "description": "A will-o-wisp trapped in a cracked lantern. It bobs and hums softly.", "damage-type": "holy", "damage-pct": 5, "price": 600},
    {"id": 9007, "name": "Dust Serpent", "description": "A thin sandy-colored snake that coils around your arm when idle.", "damage-type": "slash", "damage-pct": 9, "price": 550},
    {"id": 9008, "name": "Frost Sprite", "description": "A tiny blue figure that perches on your shoulder and breathes mist.", "damage-type": "cold", "damage-pct": 7, "price": 650}
  ]
}

Shop Integration

Pet templates are defined at the world level, not per-shop. When a world is loaded, each room with the pet-shop flag gets a random selection of 2-4 pets from the world’s full pet template list. The selection is seeded by the room ID so it’s deterministic — same room always gets the same pets. Different pet-shop rooms get different selections.

The list command in a pet-shop room shows the available pets alongside any regular shop items. The buy command checks if the target matches a pet name and handles accordingly.

Pet-shops do not need explicit pet entries in the shop JSON. The room flag pet-shop is sufficient — the system populates the selection automatically from the world’s pet templates.

Impact on Existing Systems

Not Included

• No pet leveling. Damage scales via player level already.
• No pet death or HP. Pets are invulnerable flavor companions.
• No feeding or happiness. Zero maintenance burden.
• No pet trading. Bound on purchase.
• No pet abilities. Pets only auto-attack. No special skills.
• No multiple pets. One active, period. No stable or collection.
• No pet naming. Uses the template name. Could add pet rename later.