@game-infra/common-data-model

Generic data-model mechanism for narrative game content: a codec registry, entity/schema-config types (items, personas, organizations, cities), display and editor schema types, maturity tiers, event-JSON types, formation and objective types. Every file here is mechanism; games supply the actual content via value-level registries and config injection.

Published to npm. Also consumable as sibling source.

Install

"@game-infra/common-data-model": "link:../../game-infra/packages/common-data-model"
// or from npm
"@game-infra/common-data-model": "^0.1.0"

valibot is a peer dependency (^1.4.0).

Usage

The extension pattern is value-level registries + config injection, not module augmentation. A game defines extra codecs and merges them with the common set:

import { createCodecRegistry, commonPreconditionCodecs } from "@game-infra/common-data-model";
import { myGameCodecs } from "./codecs.js";

const registry = createCodecRegistry(
  [...commonPreconditionCodecs, ...myGameCodecs],
  "Precondition",
);
registry.get("HasItem"); // the common HasItem codec

Schema-config types (ItemSchemaConfig, PersonaSchemaConfig, EntityDisplaySchemaConfig, …) let a game supply a valibot schema plus UI metadata; editors render data-driven UI with compile-time key checking.

Tracking play state

The common*Codecs cover the state a game keeps as a number on the player — stats, skills, resources, items — plus whether a persona has been met, and the activations that move reputation, relationships and inventory in one direction. stateTrackingCodecs adds the rest of what a narrative game tracks, so the things an event can change are also things an event can gate on:

| Reads it | Writes it | | ----------------------------------------------------------------- | ----------------------------------------------- | | ReputationSufficient, ReputationBelow | ModifyReputation (common) | | RelationshipSufficient, PersonaMetStatusPrecondition (common) | ModifyRelationship (common), MarkPersonaMet | | KnowsSecret | LearnSecret | | HasCondition | ApplyCondition, RemoveCondition | | SkillSufficient (common) | ModifySkill | | ResourceSufficient (common) | ModifyResource, ConsumeResource | | HasItem (common) | RemoveItemFromInventory, ConsumeItem |

ConsumeResource and ConsumeItem are consumable conditions: checked before a choice is offered and paid when it is taken, which is what stops a choice that checks for ten and subtracts twelve.

They are opt-in — kept out of the common* arrays, because accepting a term is a promise to apply it, and a game whose engine has no notion of illness should not start validating events that inflict one:

import { createStrictEventSchemas } from "@game-infra/event-schemas";
import {
  commonActivationCodecs,
  commonPreconditionCodecs,
  stateTrackingCodecs,
} from "@game-infra/common-data-model";

const strict = createStrictEventSchemas({
  preconditions: [...commonPreconditionCodecs, ...stateTrackingCodecs.preconditions],
  activations: [...commonActivationCodecs, ...stateTrackingCodecs.activations],
  consumableConditions: [...stateTrackingCodecs.consumableConditions],
});

Each codec carries its params schema, its editor fields, its human-readable rendering and its AI instructions, so adopting the set gives the event editor forms for these terms and the generator prompts that use them.

Extension points

• Codec registries — concatenate common*Codecs with game codecs, pass to createCodecRegistry (or EventEditorConfig.codecs).
• Schema-config objects — provide a game valibot schema + display metadata.
• State-tracking codecs — stateTrackingCodecs, opt-in, for a game that tracks reputation, relationships, secrets or conditions.
• Game-specific codecs (e.g. CastSpell, UseItem) live in the game's own data-model package, not here.

Dependencies

Peer valibot. No internal @game-infra/* deps.

Consumers

@game-infra/event-schemas (re-exports EntityInfo / AvailableEntities), event-editor, and game data-model packages.