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 the chosen campaigns' and Worlds' 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, and the equipment picks (startingEquipmentLabel for options without a set; startingEquipmentSetLabels where the class's options carry a set). What a ruleset asks for differs and the options and constants say which applies: a ruleset whose constants list no background bump modes and whose backgrounds carry no feat takes no background bump or background feat, gives ability score increases through the heritage rule and its subrace (fixed ones need no pick; chosen ones go in abilityBumpPicks keyed by that rule's _id), offers the roll method (abilityScoreRolls), and takes backgroundToolProficiencies, the background equipment picks, backgroundAbilityChoices, and skillReplacements / toolReplacements; where its class option carries startingGold dice it may take startingGold with startingGoldRolls in place of every equipment pick. 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>. When the background option carries a non-null featSpellList, its own feat's spell-list pick must use that list. Campaigns and Worlds: pass the same campaignIds and worldIds the options were read with (none means stock plus the user's own content only). The character joins each chosen campaign and World when it is built and gets the chosen Worlds' extra skills as skill rows; a choice that can no longer be joined fails the build with CREATION_CONTEXT_LOST, naming it and the reason, and nothing is created. 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.
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": {
"ruleset": "<ruleset>",
"name": "<name>",
"classRuleId": "<classRuleId>",
"abilityScoreMethod": "<abilityScoreMethod>",
"abilityScoreAssignments": "<abilityScoreAssignments>",
"skillProficiencies": "<skillProficiencies>",
"toolProficiencies": "<toolProficiencies>"
},
"name": "vault_build_pc"
}
}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`. | |
| worldIds | No | imagine Worlds the new character will join, by `_id`, from imagine_list_my_worlds (the user's own and role Worlds) and imagine_search_public_worlds (public Worlds by name). At most 10 (the app answers 400 for more). Each adds its house content and extra skills, and the stock every chosen World hides is left out of the 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. | |
| campaignIds | No | Campaigns the new character will join, by `_id`, from play_list_joinable_campaigns for this ruleset, at most 10 (the app answers 400 for more). Each adds its house rules, spells, and items to the options. | |
| classRuleId | Yes | Required. `_id` of a base Class rule (from `vault_get_pc_creation_options({ kind: 'class' })`). | |
| description | No | Character description / biography. | |
| startingGold | No | true takes the class's starting gold in place of the class's AND the background's starting equipment, where the class option carries `startingGold` dice (`{ count, sides, multiplier, label }`; null or absent = the option is not offered). The character gets the rolled gold in its Gold row and no starting equipment; every proficiency, spell, and trait is unchanged. Send `startingGoldRolls` with it and omit the equipment picks. | |
| 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. A picked option's (or its abilities') own `choice` goes in this map too, keyed by that rule's `_id`. | |
| 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 or chosen set options. Key is the group parent item `_id` (a `startingEquipmentOptions[].items[]` entry that carries `group.options`); value is the picked member `_id`, or, for a group entry with a quantity above 1, a list of that many member `_id`s (one per unit, repeats allowed). Every group in the chosen options 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 block's `addedOptions` entry (it carries `addedBy`, rule `_id`s) is a spell a rule's expanded spell list adds — a subclass's, such as a Warlock patron's: it may be picked like an option only when one of those rules is in the build (picked through `abilityChoices` or granted by a pick); otherwise vault refuses it. A `repeatable` feat filling the background slot prefixes its keys `bg:<featId>:<blockIndex>`. | |
| toolReplacements | No | As `skillReplacements`, for a tool gained from two sources. | |
| abilityScoreRolls | No | For the `roll` ability score method: one roll per ability score, each the dice faces as rolled, in the roll count, dice count, and face range this schema states. The app drops each roll's lowest faces; `abilityScoreAssignments` must assign each roll's total exactly once. | |
| skillReplacements | No | Where the ruleset lets a character that gains the same skill from two sources take a different skill instead: key is the duplicated skill, value is the replacement skill the character does not already have. | |
| startingGoldRolls | No | With `startingGold`: the faces of the class's starting gold dice as rolled — exactly `startingGold.count` whole numbers from 1 to `startingGold.sides`. The gold is their sum times `startingGold.multiplier`. Roll them yourself; vault refuses faces that do not fit the dice. | |
| 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` (for the background's own feat, the background's `featSpellList` when it names one) 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. A picked option's own sub-choices go in the proficiency/spell pick maps keyed by that option's `_id`; its (or its abilities') own `choice` goes in this map, keyed by that rule's `_id`. | |
| 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`; its (or its abilities') own `choice` goes in this map, keyed by that rule'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 | No | The chosen equipment bundle among the class's options that carry no `set` — must equal one such `class.startingEquipmentOptions[].label` exactly. Required when the class has options without a `set`; omit when every option carries a `set`. | |
| 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. | |
| backgroundAbilityChoices | No | Picks for a choice carried by one of the background's own `abilities` (its feature). Key is the ability `_id`; value is the picked rule `_id`s. A picked rule's (or its abilities') own `choice` goes here too, keyed by that rule's `_id`. | |
| backgroundEquipmentLabel | No | The chosen bundle among the background's `startingEquipmentOptions` that carry no `set`, when the background has such options. | |
| 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. | |
| backgroundEquipmentChoices | No | As `equipmentChoices`, for groups in the background's chosen equipment. | |
| startingEquipmentSetLabels | No | For a class whose `startingEquipmentOptions` carry a `set` number (options sharing a set are alternatives): one pick per set that has more than one option. Key is the set number as a string; value is the chosen option's `label`. A set with a single option is given to every character and takes no entry. | |
| backgroundToolProficiencies | No | The background tool picks, when the background offers tools as a choice (`background.toolChoices`): exactly `background.toolChoices.count` names from its options (a concrete member name for a group), no duplicates. | |
| backgroundEquipmentSetLabels | No | As `startingEquipmentSetLabels`, for the background's `startingEquipmentOptions`. | |
| 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 | |||