Let an agent edit your scene

An agent changes your scene with the same editor you use. It creates entities with entity_create, changes them with entity_update, and reaches any other control by its field id with fields_set. Every change goes through the editor's own handlers, so it lands in your undo history.

You'll need an editor tab paired with your agent, and a key with the Edit projects permission. This page is step 2 of the build loop. The board game maker page shows the kinds of scenes people build this way.

Look first#

Before it touches anything, the agent should read the scene. scene_tree lists the Hierarchy: entities, folders, seats, zones and snap points. entity_get reads one entity in detail, and describe_panel reads a whole panel as text.

The agent also needs the project lease, the editor's lock that lets one tab at a time change a project. project_status reports whether this tab holds it. Without the lease, every write fails with read-only-lease, the same as it would for you.

Place entities#

entity_create places a new entity of a given kind, such as a board, token, die, card, deck, bag or custom model. The agent can start from a preset, give a position and rotation, and put it under a parent. The tool returns the new entity's id, which every later call uses to find it.

Then the agent shapes it:

• entity_update patches the transform, physics, appearance and metadata.
• entity_duplicate makes copies, offset by a set distance. It's handy for a row of pieces.
• entity_reparent moves an entity under another one, or back to the top level.
• material_create and material_set handle colors and surfaces.
• component_add and component_set add and tune a light or camera component.

The render, rigidbody and collision components are built into every entity. The agent sets them through entity_update's physics fields instead. Scripts attach with script_attach, covered in Write game scripts with an agent.

Units. Lengths are in feet, DiceyTable's world unit. Angles are in degrees. A tool never quietly trims a value that is out of range. It refuses the call and reports the range, so the agent can fix it.

Set up seats, zones and snap points#

These three tools shape how people play:

• seats_configure sets the number of seats, up to 10, or applies a seat template. It also sets each seat's label and color.
• zone_upsert creates or changes a zone, such as a hand zone or a discard area. Leave out the id to make a new one.
• snap_points_set lays out table snap points, one by one or as a grid. Snap points that belong to one entity are set in its Prefab tab instead.

Player zones and seats explains what each one does at the table.

What if there's no tool for a setting?#

Every form control in the editor has a field id, so the agent can still reach it. fields_list finds fields by panel or by id prefix. fields_get reads their values. fields_set sets them through each control's own change handler, in a batch. With autoOpen: true, it selects the entity and opens the right panel first.

Buttons and menu commands work the same way: actions_list finds them and actions_invoke presses them. A button that deletes or publishes still needs confirm: true or your click. The field catalogue lists every field id by panel. For what each panel does, see the editor docs.

Can the agent delete things?#

Yes, but carefully. entity_delete is a destructive tool, so the agent must pass confirm: true. The first destructive call in a session saves a restore point and returns its id. If you chose Ask me each time for Destructive edits when you approved the agent, you answer each delete yourself.

undo and redo use the same history as you do. If the agent makes a mess, you can step back with the usual undo. Actions that need your click lists what else is guarded.

Save and check#

After a batch of edits, the agent calls project_save, then project_validate, then diagnostics_get. That order catches problems while they are still small. Then it's time to play-test the game.

Next steps#

• Build a deck of cards with an agent: the next step for card games.
• Scene tools reference: every argument for the tools on this page.
• Example prompts: ready-made requests for scene work.