create-actor-from-compendium
Copy an official compendium actor (e.g., Monster Manual) into your world, with optional stat modifications for custom creatures.
Instructions
Copy one or more actors from a premium-book compendium pack — the DEFAULT, preferred path for official content (e.g. pull the Owlbear from the Monster Manual). Find the entry with search-compendium / get-compendium-entry, then pass its packId + itemId plus names[] for the new actors. PREFAB-AS-BASE (the §6 step-2 bridge): to make a CUSTOM creature, copy the closest Monster Manual match and pass modifications (update-actor-shaped stat edits — cr/hp/ac/abilities/skills/defenses/biography/currency) to layer onto the world copy in the SAME call; the edits land on the copy only, never the source entry. For a fully hand-authored NPC with no compendium base, use author-npc (last resort).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| names | Yes | Custom names for the created actors (e.g., ["Flameheart", "Sneak", "Peek"]) | |
| itemId | Yes | ID of the specific creature entry within the pack (get this from search-compendium results) | |
| packId | Yes | ID of the premium-book pack containing the creature (e.g., "dnd-monster-manual.actors"). Premium MM/PHB/DMG only — never the dnd5e.* SRD (design.md §2.3). | |
| quantity | No | Number of actors to create (default: based on names array length) | |
| placement | No | Token placement options (only used when addToScene is true) | |
| addToScene | No | Whether to add created actors to the current scene as tokens | |
| disposition | No | Prototype-token disposition for the created copies — YOUR judgment call (shared authoring-policy house token rules): 'neutral' for civilians/townsfolk/bystanders, 'friendly' for allies, 'hostile' for enemies. Omit to default by source type (copied PC pregen → friendly, copied monster → hostile). | |
| modifications | No | PREFAB-AS-BASE bridge: stat edits to layer onto the instantiated WORLD COPY — copy a close-matching Monster Manual creature, then customize it in one call (the §6 step-2 path). Same shape as update-actor, e.g. {cr, hp:{value,max,formula}, ac:{calc,flat}, abilities:{str,…}, skills:[{skill,proficiency}], damageResistances:{values}, biography, currency:{mode,gp,…}}. Applied to the copy ONLY — the source compendium entry is never modified. Use names[] for the name, not this. Applies to every copy when quantity > 1. |