Level up a player character
vault_level_up_pcAdvance a character one level in a class, in one call, from a flat draft of choices, for a ruleset with guided level-up (vault answers an error naming the ruleset otherwise). A class-less character (no Class entries) is rejected — record its existing classes with vault_record_pc_classes first. Vault validates every pick against the plan's pools (prerequisites enforced; grown choices demand only their delta counts) and mutates the character: the class entry's stored level bumps (or a new class entry lands with the class's multiclassGrants), the level's features snapshot onto the sheet (a subclass picked through the class's subclass-choice ability lands as its own entry and cascades its features), ability-score increases bake, HP and hit dice grow per the hitPoints choice, use-counters resize (spent uses stay spent), the combined multiclass spell-slot pool reconciles, core.class updates to " , ...", XP floors at the new level's minimum (or your exact xp), and a level-up note records the choices; the engine applies every rule behind those changes. Read vault_get_levelup_options first — required: characterId, classRuleId, hitPoints. Supply abilityChoices for every feature choice the plan surfaced (including the subclass pick and grown choice lists), the sub-pick maps for anything the picked options themselves carry, multiclassSkillProficiencies/multiclassToolProficiencies when entering a class, and optional exact xp. The updated character and a summary of what changed are returned. On an invalid draft vault returns the specific reason as a tool error — fix the draft and retry; if a surfaced pick genuinely cannot be satisfied, allowIncomplete: true applies the level and skips the shortfall instead.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| xp | No | The character's total XP after this level-up, for tables tracking exact XP. Must be >= the plan's `xp.minimumForNewTotal`; omit to let vault floor the stored XP at that minimum. | |
| hitPoints | Yes | How the level's hit points are gained: `method` is one of the schema's methods (the plan's `hitPoints` fields carry what each one uses); `value` is a die the PLAYER rolled, for a method that takes one. | |
| characterId | Yes | `_id` of the character to level (must belong to the calling user). | |
| classRuleId | Yes | Required. The base Class rule to advance one level — a held class entry (its stored level bumps) or a class the character doesn't hold yet (multiclass: a new class entry is stamped). From the chooser's `classEntries[].classRuleId` / `multiclassOptions[]._id`. | |
| abilityChoices | No | ruleChoice picks, keyed by the OWNING rule's `_id`: a gained feature's choice (the class's subclass-choice ability — value = the picked subclass `_id`; a choice among feats — value = the picked feat `_id`) AND a grown held rule's choice (`growth[]` entries — supply the NEW picks only, the delta count). A picked option's own sub-choices (a feat's skill picks, its abilityScoreBump) go in the other maps keyed by the picked option's `_id`, exactly as in `vault_build_pc`. Pools are prerequisite-filtered; an unqualified pick rejects the draft. | |
| allowIncomplete | No | Sanctioned partial apply: `true` lets vault accept UNDER-filled pick families — the level lands and only what was picked is granted; the shortfall is simply skipped (the player can edit the sheet later). Overfilled, duplicate, out-of-pool, and prerequisite-failing picks still reject. Use it as the escape when a surfaced pick cannot be satisfied; never as a shortcut past picks you can supply. | |
| abilityBumpPicks | No | Ability-score-increase picks for a gained rule carrying an `abilityScoreBump`: `{ option, lines }` keyed by the granting rule's `_id`, same shape as `vault_build_pc`. The engine applies whatever the increase changes elsewhere on the sheet. | |
| spellChoicePicks | No | Picks for spellChoices blocks on gained/grown rules, keyed `"<ruleId>:<blockIndex>"` (authored index — the projected array may hold nulls; count them). Grown blocks demand only the DELTA count ("learn N more spells"). | |
| preparedSpellPicks | No | "Prepare N more" picks for rules whose preparedSpells count grew, keyed by the granting rule's `_id`. The pool is the character's UNPREPARED granted leveled spells plus any picked this level-up; send exactly the plan's surfaced count. | |
| castingAbilityPicks | No | Spellcasting-ability picks for blocks surfacing `castingAbilityOptions`, keyed like spellChoicePicks. | |
| spellListChoicePicks | No | Picks for a NEWLY gained rule's spellListChoices — `{ category, picks, castingAbility? }` keyed `"<ruleId>:<blockIndex>"`, exactly as in `vault_build_pc`. | |
| proficiencyChoicePicks | No | Picks for proficiencyChoices grants on gained/grown rules, keyed `"<ruleId>:<grantIndex>"` — same keying and rules as `vault_build_pc`. Grown grants demand only the DELTA count the plan surfaced. An EXPERTISE grant picks from the pool the rule authoring guide describes (vault_get_authoring_guide, entityType .rule., proficiencyChoices); vault rejects picks that do not fit. | |
| multiclassToolProficiencies | No | Tool picks for the entered class's `multiclassGrants.toolChoices` (multiclass only): exactly `count` names from its (group-expanded) options. | |
| multiclassSkillProficiencies | No | Skill picks for the entered class's `multiclassGrants.skillChoices` (multiclass only): exactly `count` names from its options. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||