Library reference

Source-linked API reference for the versioned library.

Declarations, signatures, property defaults and adjacent comments are extracted from the library modules. Extensions are merged into their declaring type and retain their own source links. Member indexes cover declared members; type pages also show local inheritance.

The guides describe behavior and disclosure requirements. Trusted assessment objects may contain hidden information: publish the redacted event envelopes to a player-facing host.

Classes and objects · Functions · Alphabetical symbols · Alphabetical members

Built from revision 2162b49e5d78e2e8a4deb3c94a164dec928866ea.

Core mechanics

  • RpgApproach — One method of pursuing a goal. Hooks use original game-specific content. blockedReason, modifierFor and oppositionModifierFor must be observational. apply runs once per fresh resolution, including failures and ties.
  • RpgAssessment — Trusted, observational preparation. Reporting extensions can add odds to this temporary value. ready is the only status that permits a fresh roll.
  • RpgAttempt — Predeclare one slot per permitted (profile, approach) pair. Scalar state is journalled without allocating permanent entities during play. The slot is also the retry authority shared by parser, structured and dialogue actions.
  • RpgCalculation — Temporary explanation, shared by assessment and execution. Only scalar snapshot data is retained by attempts. Modifier triples are category, label, amount; after 31 components, remaining adjustments are grouped as other.
  • RpgChallenge — A shared goal. completed closes every approach for every character. advance() permits fresh attempts after a meaningful, authored world change. Never call advance merely because a command, preview or refresh occurred.
  • rpgCheck — Pure numerical check; no randomness, world writes, output or time costs. Scores below three cannot be attempted. critical is success, failure or nil.
  • RpgContext — Temporary execution context. Do not retain it in persistent properties.
  • rpgDX — Attribute identifier accepted by RpgProfile.attributeScore().
  • RpgError — Invalid configuration or an invalid mechanics API argument.
  • rpgHT — Attribute identifier accepted by RpgProfile.attributeScore().
  • rpgIQ — Attribute identifier accepted by RpgProfile.attributeScore().
  • rpgLedger — Only accounted challenge time, in seconds; not a replacement world clock. vhyl continues to schedule one cycle per accepted command.
  • rpgPerception — Attribute identifier accepted by RpgProfile.attributeScore().
  • rpgPrepare — Trusted observational preparation shared by assessment and resolution. Configuration errors throw. Ordinary impossibility returns blocked without rolling, charging or caching it. Prerequisite and modifier hooks must be pure.
  • RpgProfile — Share this model between protagonists and supporting characters. skills and traits are authored lists. Optional modules add injury, recovery and progression; a core-only profile retains the simple energy pool.
  • rpgPublish — Explicit, player-safe result envelope. No skill scores, rolls, opponent identities, margins or critical flags are published automatically.
  • rpgRandom — Deterministic, journalled generator with overflow-safe arithmetic. Set a seed from 1 through 2147483646 at game initialisation.
  • rpgResolve — Commit an attempt using the shared preparation. Call only from a gameplay execution/selection hook. Exceptions roll back the enclosing turn.
  • RpgResult — Temporary result. Scores and dice are private unless the author discloses them. status: resolved, reused, blocked or complete. outcome: success, costly-success, setback, complication or tie (nil when not resolved).
  • RpgSkill — A skill's governing attribute, training difficulty and explicit default. difficulty: 0, 1 or 2. defaultPenalty: a nonpositive integer, or nil for training only. Do not infer a default from difficulty.
  • rpgSpendTime — Charge explicit adventure time with a checked persistent counter.
  • rpgST — Attribute identifier accepted by RpgProfile.attributeScore().
  • RpgTraining — Investment in one skill. Zero reserves an untrained slot for progression; positive values buy training. The core never awards or spends points itself.
  • RpgTrait — An authored benefit or limitation. The modifier hook is observational. Use c.skill and c.isOpposition to keep its application appropriately narrow.
  • rpgWill — Attribute identifier accepted by RpgProfile.attributeScore().
  • Thing — Optional binding from a vhyl world entity to its authored profile.

Optional reporting

  • rpgAssess — Trusted assessment, not a player-safe disclosure. No dice are drawn, no attempts recorded, and no consequences or persistent writes occur.
  • RpgDisclosure — An author ceiling or a player's requested level of detail. Every group is opt-in. A player preference can reduce, but never broaden, author permission.
  • rpgFullDisclosure — Opt in explicitly on an approach; never the implicit disclosure default.
  • RpgOdds — Exact integer counts. Outcome categories are mutually exclusive. Raw roll success and critical flags overlap those categories, especially in contests.
  • rpgOddsFor — Enumerate exact weighted outcomes for a trusted prepared assessment. Returns nil unless ready. This helper does not apply disclosure policy.
  • rpgPublishAssessment — Emit a redacted assessment and optional calculation events. nil preferences means use the author's ceiling. Hidden checks emit nothing, including IDs.
  • rpgPublishRoll — Report recorded faces and calculation snapshots, never a fresh roll or a recalculation against today's attributes. Automatic attempts have no dice.
  • rpgRecordedResult — Trusted retrieval of the latest recorded attempt, including a completed goal. No current skill/prerequisite hooks are evaluated. nil means no record.

Playable resilience

  • RpgBody — Authored persistent body, bound one-to-one to a profile. Injury is a deficit from current capacity. Defeat at zero HP is deterministic; lethal outcomes require an explicit author opt-in. No parser-turn death or healing timers.
  • RpgCareResult — Temporary injury/recovery result. Trusted code chooses whether to publish it.
  • rpgInjuryFor — Pure armor and wounding arithmetic. Positive penetration always wounds at least one HP. Ratios are explicit authored numbers, not weapon taxonomies.
  • rpgPublishBody — Explicit player-visible condition summary. Calling this is a disclosure decision; hidden NPC bodies must not be published automatically.
  • rpgRecoverStun — One committed recovery maneuver. A failed health check leaves stun in place.
  • rpgRest — Explicit uninterrupted quiet rest, charged in seconds. One energy per ten minutes; one health check per full day of rest for one HP. No WAIT hook.
  • rpgTreat — Treat only untreated injury. Ordinary failure still supplies one HP of bandaging; critical failure adds two HP instead. Never grants a free retry.
  • RpgTreatment — Original bounded care procedure: includes bandaging, then one skill check. One charge and the declared duration buy one attempt. Healing is capped by untreated injury; new minor wounds cannot reopen old treatment budgets.
  • rpgWound — Commit injury after armor. Major wounds make one health check; zero HP incapacitates. A lethal body dies at minus five times its maximum HP.

Physical and social conflicts

  • rpgBeginConflict — Begin a fresh authored conflict once. Resuming a finished scene requires a different conflict object, rather than erasing its recorded outcome.
  • RpgCombatant — One owned combatant. Defaults describe a modest unarmed attack; games explicitly author weapons, armor and permission to use them.
  • RpgConflict — Two-sided authored scene. One player maneuver and one eligible reply form an exchange, not a parser-wide combat clock. No unconscious actor attacks. A bounded stalemate, escape and surrender keep nonlethal routes available.
  • RpgConflictResult — Temporary exchange outcome; publishing it is an explicit game decision.
  • rpgConflictStep — Commit attack, defend, recover, escape or surrender. Only a resolved exchange spends time or advances the bounded encounter. Queries do neither.
  • RpgDisposition — Authored NPC disposition. Permission to consider a request is separate from the chance of persuasion. A success never overrides an explicit refusal.
  • rpgPublishConflict — Explicit conflict report. Roll details are omitted unless authored opt-in permits them. No NPC health, defense rating or hidden calculation is inferred.
  • RpgSocialApproach — Persistent social opposition using ordinary challenge retry records. New facts or concessions, rather than repeated wording, reopen the goal.
  • RpgStrike — Temporary strike details. Raw checks and damage dice are trusted data.

Progression

  • rpgAssessDevelopment — Observational purchase query. It consumes no points, randomness or history.
  • RpgAward — Predeclared receipt per allowed profile/milestone pair; saved and undoable.
  • rpgAwardMilestone — Commit an eligible milestone exactly once per profile. Receipt, bank and unlock consequences are in the same gameplay transaction.
  • rpgDevelop — Commit a current affordable offer, with no refunds or automatic rerolls. Attribute purchases preserve Will/Perception offsets and energy deficits.
  • RpgDevelopment — An owned, authored purchase. kind is skill, attribute, trait or remove-trait. Skill/attribute costs are differences; trait costs are explicit positive prices. Unlocks and downtime are separate gates. Reopened goals are explicit.
  • RpgMilestone — Authored objective award. Eligibility is observational; apply can unlock opportunities after the receipt has been claimed. Never award for retries.
  • RpgProgressResult — Temporary award or purchase assessment/result. No output is implicit.
  • rpgPublishProgress — Explicit publication of an award or purchase result. Call only for a player-visible character; the library never reveals NPC development itself.