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 (a Feat picked at an Ability Score Improvement level may carry its own choice and abilities, whose picks go in the same maps), spellSwapPicks for the optional known-spell swaps the plan offers, 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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"characterId": "<characterId>",
"classRuleId": "<classRuleId>",
"hitPoints": "<hitPoints>"
},
"name": "vault_level_up_pc"
}
}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 (owned by the calling user, or any character for an admin with Admin Mode on). | |
| 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`; a Feat picked at an Ability Score Improvement level may carry its own `choice` and abilities, and their picks go in these same maps (the plan's option rows list them). Pools are prerequisite-filtered; an unqualified pick rejects the draft. | |
| spellSwapPicks | No | Optional spell swaps (known-spell casters whose plan offers them), keyed by the owning Spellcasting rule's `_id`: each entry `{ replace, with }` replaces one known spell with another. The plan's `growth[]` rows carry `spellSwap` (`{ count, known, options }`, each spell `{ _id, name, level, school }`) and `levelUpRules.spellSwapOptions` lists the known spells and the legal replacements per owner. A `spellSwap.schoolLimit` `{ schools, anySchoolPicks }` (a caster limited to two schools) allows a replacement outside `schools` only when, after the swap, the character knows no more spells outside them than `anySchoolPicks`; vault refuses a swap past it. Send at most the plan's count; a key whose rule swaps nothing this level is ignored. | |
| 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. Where a prepared count follows the casting ability modifier, the plan's `preparedSpells` row carries `countSource`, `castingAbility`, and `from`. | |
| 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 | |||