Provisioning Behavior for Authors

Why it Matters

When you reference actors or locations from scripts, the VM has to decide whether to reuse an existing entity or create a new one. Understanding that decision helps you predict narrative outcomes, especially when multiple templates could satisfy the same role.

Quick Rules

  1. Existing always wins – Reusing an existing node costs between 10 and 30 depending on proximity. Creating a new node costs 200, so reuse wins unless you explicitly set requirement_policy: CREATE.

  2. Scope still applies – Templates tagged with scope (scene, block, ancestor selectors) are only considered if the requesting node is in scope. See :doc:TEMPLATE_SCOPE for YAML examples.

  3. Template references (*_template_ref) short-circuit GraphProvisioner – Those requirements go straight to TemplateProvisioner. Inline templates (*_template) continue to work.

  4. Everything is audited – Planning receipts now include selection_audit, making it easy to see which offers were considered and why a specific one won.

Author Controls

Need

How to express it

Force a fresh instance

Set requirement_policy: CREATE on the role/setting.

Prefer scene-local reuse

Declare the affordance or template inside the scene/block so it is

 
                               in scope and has low proximity cost. |

| Share a template everywhere | Add scope: null to the template to mark it global. | | Diagnose unexpected selections | Inspect planning logs or use the debugger snippet below. |

Debugging Example

from tangl.vm.debug import PlanningDebugger

# After running a frame
receipt = next(r for r in frame.records if isinstance(r, PlanningReceipt)
PlanningDebugger.print_receipt(receipt)

The report lists every requirement, the offers considered, their cost/proximity, and the winning provider. Use it to confirm that your template scopes and requirement policies line up with your intent.

Best Practices

  • Declare generic NPCs/locations at the world or scene level so they can be reused cheaply.

  • Override requirement_policy only when you truly need bespoke instances.

  • Keep template names descriptive—receipts log template_ref, which shows up in debugging tools.

  • When troubleshooting, check selection_audit before changing YAML; the audit often reveals that the desired template was out of scope or more expensive than an existing option.