@bugchud/core

@bugchud/core is the shared schema, content catalog, runtime model layer, and validation surface for Bugchud applications.

It gives downstream apps two things at once:

• Plain JSON-friendly schemas for authored rulesets and live runtime state.
• Ergonomic runtime classes for creating, editing, validating, and serializing that state safely.

Live runtime state now includes both aggregate injury tracking and explicit anatomy data, so applications can store wound totals alongside limb-by-limb status such as impaired, lost, prosthetic, or mutation-added body parts.

Install

npm install @bugchud/core

The package is ESM-only and targets Node 18.17+ plus modern TypeScript/bundler setups.

Quick Example

import { BugchudCore } from "@bugchud/core";
import { importedRuleset } from "@bugchud/core/data";

const core = new BugchudCore({ ruleset: importedRuleset });

const character = core.createCharacter({
  name: "Marta Rust",
  currentFate: 1,
});

character.addDream(importedRuleset.progression.dreamRefs[0]);
character.setWounds(2);
character.patchBodyPart("leftArm", {
  status: "lost",
  notes: ["Crushed in a scrap-hauler accident."],
});

const npc = core.createNpc({
  name: "Roadfang",
  allegiance: "Raiders",
});

const characterIssues = character.getIssues();
const combatDraft = character.getCombatProfileDraft();
const payload = character.toJSON();

Package Map

Applications will usually interact with these surfaces:

• @bugchud/core The app-facing runtime layer: BugchudCore, model classes, wrappers, factories, serialization, and validation exports.
• @bugchud/core/foundation Primitive building blocks such as branded ids, typed refs, constants, dice/effect types, and helper builders.
• @bugchud/core/content Immutable authored ruleset definitions like BugchudRuleset, RaceDefinition, WeaponDefinition, and CreatureDefinition.
• @bugchud/core/state Plain serializable runtime snapshots like CharacterState, CreatureState, EncounterState, and CampaignState.
• @bugchud/core/contracts Simulator-facing interfaces for actions, events, and resolution contracts. Important for engine work, but not a finished rules engine by itself.
• @bugchud/core/views Computed projections like ComputedCombatProfile and draft calculators that turn state plus ruleset into UI/combat-facing read models.
• @bugchud/core/validation Structured validation result types and helpers for rulesets and runtime snapshots.
• @bugchud/core/character Character-specific initializer and factory surface.
• @bugchud/core/npc Creature/NPC-specific initializer and factory surface.
• @bugchud/core/data The imported canonical ruleset and transcribed BUGCHUD content. Heavy by design and intended as read-only source data.

Core Idea

The library is intentionally layered:

1. content describes what may exist in the ruleset.
2. state describes what currently exists in a running game or editor.
3. model classes like CharacterModel and NpcModel provide an ergonomic editing API over plain state.
4. views derive read models from state plus ruleset.
5. validation and snapshot serialization protect persistence and transport boundaries.

The important design rule is that classes are for application ergonomics, but plain snapshots remain the persistence boundary.

That means explicit body-part changes belong in plain BodyState too, not only in model helpers. If a character loses an arm, gains a prosthetic tail, or carries a long-term torso injury, those facts should survive serialization as regular runtime state.

Documentation

• Documentation Index
• Getting Started
• Using The Library In An Application
• Runtime API Guide
• Character And NPC Workflows
• Imported Data Guide
• Schema Reference Overview
• Generated API Reference

To sync the packaged docs onto a local machine, run:

npx --yes --package @bugchud/core finalchud-docs

That command copies the published docs/ tree into ./finalchud-docs, compares each file with a SHA-256 hash on reruns, and only overwrites files whose contents changed. Pass a custom destination as a positional argument or with --dir.

Development

npm run verify
npm run docs:check

docs:check regenerates docs/api/, validates internal markdown links, and verifies that key public symbols appear in the generated reference.

Versioning

The package is still pre-1.0. Pin versions precisely if a downstream application needs a stable integration surface.