Build a player character
vault_build_pcAssemble a complete, playable player character in one call from a flat draft of choices, in a ruleset with guided creation (the ruleset field's list). Vault validates every pick against the user's own + stock content and builds the full sheet — ability scores (with background bump), skills, saves, hit points, starting equipment + derived weapon actions, granted rules / feats / abilities, trackables, and a creation-recap note. Read vault_get_pc_creation_options first to get legal ids and pools. Required: name, classRuleId, abilityScoreMethod, abilityScoreAssignments, skillProficiencies, toolProficiencies, startingEquipmentLabel. Required when present: backgroundFeatRuleId (an open featOpen background's feat, from the originFeatCategory feats — the build rejects the draft without it). Optional: speciesRuleId, backgroundRuleId, backgroundSkillProficiencies (when the background grants skills as a choice), the background bump (backgroundBumpMode + backgroundBumpAssignments), backgroundFeatRuleId (as a swap on a fixed-feat background), languages, languageChoicePicks (background/species language-choice grants), alignment, description/image/appearances/token, and the choice maps (proficiencyChoicePicks, abilityChoices, speciesAbilityChoices, backgroundFeatChoices, equipmentChoices, weaponAbilityChoices, abilityBumpPicks) plus the spell maps (spellChoicePicks, spellListChoicePicks, preparedSpellPicks, castingAbilityPicks) for spellcasters / spell-list-choice grants. proficiencyChoicePicks and spellChoicePicks are keyed ":" and only needed where a grant's count is smaller than its option pool. castingAbilityPicks is required for any spellChoices block surfacing castingAbilityOptions — the projection only surfaces that array when a pick is genuinely needed (a spellListChoices block's ability pick rides its spellListChoicePicks entry as castingAbility instead). The projected spellChoices/spellListChoices arrays may hold null entries (blocks inert at the starting level) — count them when keying picks by index. A feat chosen via an ability's ruleChoice (in abilityChoices/speciesAbilityChoices) brings its own sub-choices — supply them in those same maps keyed by the picked feat's _id. A repeatable feat filling the background slot (backgroundFeatRuleId) instead prefixes its pick keys bg:<featId>. The created character is owned by the calling user and returned in full. On an invalid draft vault returns the specific reason (e.g. a pick out of pool, a wrong pick count, a missing required choice) as a tool error — fix the draft and retry.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Character name. Required. | |
| image | No | Character portrait — `{ url }`. | |
| token | No | Default battlemap token art — `{ url }`. | |
| ruleset | Yes | A ruleset with guided character creation: the one the options were read for with `vault_get_pc_creation_options`. | |
| alignment | No | ||
| languages | No | The character's OWN chosen language names. The build adds any language the ruleset gives every character. `constants.languages.options` + `pickCount` are the conventional pool and count, but vault stores whatever is passed here — free-form names are allowed and the count is not enforced. (Languages a background/species GRANTS go in `languageChoicePicks`, not here.) | |
| appearances | No | Appearance roster — `[{ url }]`. The portrait (`image`) is typically the default appearance. | |
| classRuleId | Yes | Required. `_id` of a base Class rule (from `vault_get_pc_creation_options({ kind: 'class' })`). | |
| description | No | Character description / biography. | |
| speciesRuleId | No | `_id` of the heritage rule (from `kind: 'species'`). | |
| abilityChoices | No | Picks for a class ability's `choice` (ruleChoice). Key is the ability rule `_id`; value is exactly `choice.count` picked option `_id`s from `choice.options`. Each option carries a `type`. When a picked option carries its OWN sub-choices (any type — an Ability or a Feat), supply them in `proficiencyChoicePicks` / `spellChoicePicks` / `spellListChoicePicks` / `preparedSpellPicks` keyed by the picked option's `_id`, just like the background feat. | |
| abilityBumpPicks | No | Ability-score-increase picks for any applied rule carrying an `abilityScoreBump` (a feat / ability that raises a score by your choice). Key is the granting rule `_id`; value is `{ option, lines }`: `option` is the 0-based index of the chosen alternative in that bump's `options` (the player picks exactly ONE — the OR), and `lines` is parallel to that option's `lines`, each entry the lowercase ability names assigned to that line (the AND). Each line needs exactly its `count` distinct abilities drawn from its `eligible` pool (empty = any ability in the schema's abilities list), none exceeding its `max`. The build bakes the increases onto the ability scores before it derives the rest of the sheet. A `repeatable` feat filling the background slot keys `bg:<featId>` instead of `<featId>`. | |
| backgroundRuleId | No | `_id` of a Background rule (from `kind: 'background'`). | |
| equipmentChoices | No | Resolves equipment groups in the chosen bundle. Key is the group parent item `_id` (a `startingEquipmentOptions[].items[]` entry that carries `group.options`); value is the picked member `_id`. Every group in the chosen bundle needs an entry. | |
| spellChoicePicks | No | Picks for `spellChoices` blocks across ALL applied rules (class/species/feat/abilities). Key is `"<ruleId>:<blockIndex>"` (the Rule `_id` and the 0-based index into that rule's `spellChoices` AS PROJECTED — the array may contain null entries holding the position of blocks that grant nothing at the starting level; count them when indexing, never compact the array). Value is the chosen spell `_id`s. Only supply where a block's `count` < its option-pool size — a whole-pool block is granted automatically. Each block's options come from `vault_get_pc_creation_options` (an applied ability/feat's `spellChoices[].options`). A `repeatable` feat filling the background slot prefixes its keys `bg:<featId>:<blockIndex>`. | |
| toolProficiencies | Yes | The class tool picks. Exactly `class.toolChoices.count` names from `class.toolChoices.options`. If an option is a group, pick a concrete member name, not the group. Empty array if none. | |
| abilityScoreMethod | Yes | How ability scores were chosen. See `constants.abilityScoreMethods` for the array / point-buy budget / costs. | |
| backgroundBumpMode | No | Required when the background grants an ability bump; each mode's amounts are the wizard constants' `backgroundBumpModeOptions`. | |
| preparedSpellPicks | No | Which spells the player keeps prepared, for rules carrying a `preparedSpells` count. Key is the granting rule `_id`; value is spell `_id`s drawn from the character's preparable granted spells — `spellChoices` picks, whole-pool fixed grants, and `spellListChoices` picks alike — EXCLUDING any granted by a block whose `prepared` flag is true (an always-prepared grant; the options projection ships `prepared` on each block so you can tell) and any the count does not cover (the rule authoring guide's preparedSpells section says which). The rule authoring guide.s preparedSpells section gives the required count; vault rejects picks that do not fit. A `repeatable` feat filling the background slot keys `bg:<featId>` instead of `<featId>`. | |
| skillProficiencies | Yes | The class skill picks. Exactly `class.skillChoices.count` names, each from `class.skillChoices.options`, no duplicates. Empty array if the class grants no skill choices. | |
| castingAbilityPicks | No | Spellcasting-ability picks for `spellChoices` blocks that carry `castingAbilityOptions` (a grant that lets the player choose the casting ability). Key is `"<ruleId>:<blockIndex>"` (same keying as `spellChoicePicks`); value is ONE lowercase ability name from that block's `castingAbilityOptions`. The projection surfaces `castingAbilityOptions` only when a pick is genuinely required (a fixed ability or a single option self-resolves server-side) — so whenever you see the array, supply a pick or the build rejects the draft. The resolved ability is stamped on each granted spell (`spells[].castingAbility`). A `repeatable` background feat prefixes the key `bg:<featId>:<blockIndex>` (same keying as spellChoicePicks). | |
| languageChoicePicks | No | Picks for a background's or species' language-CHOICE grant (`background.languages.choose` / `species.languages.choose`). Key is the granting rule's `_id`; value is exactly `languages.choose.count` names from `languages.choose.options` (an empty options pool means any `constants.languages.options`). The grant's `languages.fixed` are auto-applied and need no pick. Distinct from `languages` (the character's own picks). | |
| backgroundFeatRuleId | No | The background's feat, from the `originFeatCategory` feats. REQUIRED when `background.featOpen` is true (an open slot — the build rejects the draft without it); optional on a fixed-feat background, where supplying it swaps the authored default. Must be a feat in the `originFeatCategory` (from `kind: 'feat'`). | |
| spellListChoicePicks | No | Picks for `spellListChoices` blocks (choose ONE of the block's lists, then spells from that one list). Key is `"<ruleId>:<blockIndex>"` (the projected array may contain null entries holding the position of blocks the build skips — count them when indexing, never compact); value is `{ category, picks }` where `category` is one of the block's `categories` and `picks` is `{ "<pickIndex>": [spellId, …] }` — the chosen spells for each pick, drawn from that pick's `optionsByCategory[category]`. When the block carries `castingAbilityOptions`, also set `castingAbility` (one lowercase ability name from those options) — the build rejects the draft without it. A `repeatable` feat filling the background slot prefixes its keys `bg:<featId>:<blockIndex>`. | |
| weaponAbilityChoices | No | For a weapon in the chosen bundle whose attack ability is a player pick: key is the item `_id`, value is the attack ability (one of the schema's enum). | |
| backgroundFeatChoices | No | Picks for the background feat's `choice` (ruleChoice) AND for any choice carried by the feat's granted abilities. Key is the feat `_id` (its own choice) or the granted ability's `_id` (that ability's choice); value is the picked rule `_id`s. | |
| speciesAbilityChoices | No | Same as `abilityChoices`, for a species ability's `choice`. A picked option's own sub-choices (any type — Ability or Feat) go in the proficiency/spell pick maps keyed by that option's `_id`. | |
| proficiencyChoicePicks | No | Picks for proficiencyChoices grants across ALL applied rules (class/species/feat/abilities). Key is `"<ruleId>:<grantIndex>"` (the Rule `_id` and the 0-based index into that rule's `proficiencyChoices`); value is the chosen names (skills/tools/saves/weapons/armor/languages). Only supply for grants where `count` < the option-pool size — fixed grants (count >= pool) are auto-applied and need no pick. A grant with `level: "expertise"` grants the expertise state rather than proficiency, from the pool the rule authoring guide describes (proficiencyChoices). A `repeatable` feat filling the background slot prefixes its keys `bg:<featId>:<grantIndex>` (not `<featId>:<grantIndex>`). | |
| startingEquipmentLabel | Yes | The chosen equipment bundle — must equal one `class.startingEquipmentOptions[].label` exactly. | |
| abilityScoreAssignments | Yes | Final ability scores by ability key, every key required. Must satisfy the chosen `abilityScoreMethod` as `constants.abilityScoreMethods` describes it (still send every value you intend). | |
| abilityScorePointBudget | No | Budget override for an ability-score method that spends a budget. Defaults to that method's budget in `constants.abilityScoreMethods`. Ignored for a method without one. | |
| backgroundBumpAssignments | No | Background ability-score bump per key, as `backgroundBumpMode` distributes it (each mode's amounts are the wizard constants' `backgroundBumpModeOptions`, from `vault_get_pc_creation_options` kind `constants`). Keys not bumped are omitted or 0. Only the background's `abilityScores` keys are eligible. | |
| backgroundSkillProficiencies | No | The background skill picks, when the background grants skills as a CHOICE (`background.skillChoices`). Exactly `background.skillChoices.count` names from `background.skillChoices.options`, no duplicates. Parallel to `skillProficiencies` (the class picks). Omit when the background has no `skillChoices` block; a background's fixed `skillProficiencies` are auto-applied and need no pick. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||