Item Setup Editor

Setting up a bench used to mean adding an Action POI in the inspector, adding a Mount and a Seat, nudging transforms in the scene, then entering play mode and waiting for an agent to come and sit on it. Item Setup shows an agent at the item, standing or seated, playing the animation it would play at runtime, and lets you move everything involved until it looks right.

BardTreeLtd/Civil AI/Item Setup

The window has two tabs:

Tab	Sets up	Guide
Hold	Where the agent holds the item, and where the item is held	Hold Point Editor
Actions	What the agent does at the item, and where it sits to do it	This page

What the Actions tab edits

Two things on an item decide what an agent does when it arrives.

In the editor	On the item	Decides
Action point	An Action POI	Where the agent stands for one action type, and what it plays when it arrives
Seat	A Seat beneath the item's Mount	Where the agent sits, how it gets on and off, and whether it drives

An action point's type is what an Action node's POI Action names. When an action with that POI action reaches the item, the agent goes to the point and plays its animation. Use Spots covers how the point's position is chosen over the item's own use spot, and Behaviour Actions covers the nodes that drive it.

A seat makes the item a mount. On an item with a seat, action points are performed sitting down unless they are marked Performed Standing. Mounts and Seats covers how a seat is chosen, entered and left, and the Mount setting on action nodes that overrides it.

The editor writes the same components the inspector does. Anything set up here can be read and changed in the inspector afterwards, and anything already on the item appears here.

The short version

1. Open the editor, pick the Actions tab and drag your agent prefab into Agent.
2. Drag your item prefab into Items.
3. Under Action points press + and pick an action type. The point appears at the item's use spot.
4. Set Stands at, drag the point where the agent should be, and drop clips into Animation.
5. For something agents sit on, press + under Seats and move the seat onto it.
6. Press Play on the timeline and watch the agent do it.
7. Press Save to item.

The window

The sidebar sets up what is shown; the viewport on the right shows it.

• Agent — a prefab or a scene object. It is copied into the preview, so the original is never posed.
• Items — a list of items to flick between. The selected one is set up.
• Action points — the selected item's Action POIs.
• Seats — the selected item's seats.
• Carried — items to show in the agent's hands while it plays.
• Preview — what the timeline plays, and which clip set.
• Gizmo — whether dragging moves or rotates, and in which space.
• View — preview light brightness and the floor grid.

In the viewport, left-drag orbits, middle- or right-drag pans, scroll zooms and F frames the agent. Follow in the toolbar keeps the camera on the selected point or seat.

Every point and seat is drawn as a marker with an arrow for the way it faces. Hover one to see its name; click it to select it, and the gizmo moves to it.

Colour	Marks
Orange	An action point
Green	A seat
Blue	A seat's mount location
Pink	A seat's dismount location

A line joins each location to its seat, so the path the agent slides along while mounting is visible.

Action points

Press + and pick an action type to add a point. The list is the Action POI types from Civil AI module settings, with New action type… at the bottom. The point is created at the item's use spot, facing the same way, so the agent starts somewhere sensible.

Select a point to edit it.

Field	What it does
Action	The Action POI type. New… beside it creates a type and gives it to this point
Stands at	Its own point, which you place, or The item's use spot. Either way a seated action is played in the seat
Performed Standing	On an item with a seat, the agent does this action on its feet beside the mount rather than sitting down. Only shown when the item has a mount, or a seat is being added
Name	The name of the point's object in the item
Local position	Where the point is, relative to the item. Type an exact value, or drag the gizmo
Local rotation	Which way the agent faces there
Animation	What the agent plays at the point, standing or seated

The Animation foldout is the item's endpoint behaviour, the same thing the Action POI inspector and behaviour tree nodes edit.

Field	What it does
Length	Free plays the clips once. Exact length and Length range repeat the middle clip to fill the time
Clip order	Order always plays the first clip set. Random picks a set each time
Rigid sets	Keep a set's start, middle and end together rather than mixing clips across sets
Hold last pose	Leave the last clip's pose showing, for an action that ends where the agent stays
Layer	The animation profile layer the clips play on. Empty uses the profile's first layer
Clip set	A start, middle and end clip. Add clip set adds another for variety

See Animation Layers for layers and profiles.

note

A point whose position is the item itself, or an object outside the item, can only be moved in the scene or prefab, and Stands at is greyed out. A point that shares its settings with another point on the same item is given its own copy when you save a change to it.

New action types

New action type… in the + menu, or New… beside the Action dropdown, asks for a name and adds it to the Action POI types in module settings. The new type takes the next free id, so every existing POI and every Action node keeps its meaning, and a Behaviour Tree Editor that is open refreshes its POI Action dropdowns at once.

The name must not be blank or already in use.

Seats

Press + to add a seat. It is created at the item's use spot, or at the item's origin when there is no use spot. Adding the first seat makes the item mountable: saving adds a Mount to the item for you.

Select a seat to edit it.

Field	What it does
Name	The name of the seat's object
Local position	Where the agent is held while mounted. It faces the seat's forward
Local rotation	Which way the seated agent faces
Mount location	Tick to give the seat somewhere the agent walks to before mounting. Without one it walks to the seat. Edit puts the gizmo on it
Dismount location	Tick to give the seat somewhere the agent ends up after dismounting. Without one it uses the mount location
Control seat	The agent here drives the mount, as a cart's driver does. A free control seat is always filled first
Arrive within	How close to the mount location counts as there. 0 uses the ordinary arrival check
Transition	Blend slides the agent from the location to the seat while the clip plays. Snap plays the clip in place, then seats it
Lead-in	Seconds at the start of a blend before the agent starts sliding, while the animator crossfades into the clip
Mount animation	Played while getting on. Set up like an action point's Animation
Dismount animation	Played while getting off

The Seat component explains what each of these does at runtime, and Transition style which transition a clip needs.

note

A seat added here is a passenger seat. Tick Control seat on the one that drives. The seat list's order matters for which control seat is filled first, so a cart's driving seat should be first in it.

A seat on the item's own root moves with the item and cannot be moved on its own. A mount or dismount location that is the seat itself, or outside the item, can only be moved in the scene or prefab.

Previewing

The timeline plays what Preview > Play says, using the selected action point and seat.

Play	Shows
Action, standing at its point	The agent at the point, or at the use spot, playing the action
Action, in the selected seat	The agent in the seat, playing the action
Mount, action, dismount	The agent walks up to the mount location, gets on, plays the action, gets off and ends at the dismount location
Mount	Getting on only
Dismount	Getting off only

The agent is placed as it is at runtime: a Blend seat slides it from the mount location to the seat over the clip, after the Lead-in, and a Snap seat puts it in the seat when the clip ends. Anything but the first option needs a seat selected; until then the action plays standing and the sidebar says so.

Clip set appears when the action has more than one set, and picks which one plays. Each clip plays once in the preview, whatever Length says, and a seat's mount and dismount animations preview their first set.

The timeline has first, previous, play, next and last frame buttons, a Speed and a Loop toggle. Playback pauses while the window is hidden behind another tab.

Carried items

Carried lists one field for each hold point on the agent, labelled by its type, so a Dominant Hand Handle and a Non-Dominant Hand Handle each get one. Drop an item in and it is shown in that hand, placed by its own hold points exactly as the runtime places it, and it follows the hand through the pose, standing, seated and while mounting.

Carried items are display only. Nothing about them is saved, Save and Revert ignore them, and their hold points are edited on the Hold tab. The choice is remembered per project, so switching to another agent with the same hold points keeps it.

Saving

Nothing is written to your prefab or scene until you save. Changed points and seats are marked * and new ones (new), and the sidebar shows Unsaved changes.

• Save to item writes the item's action points and seats.
• Revert throws away the item's unsaved action and seat changes.
• Every edit, including a whole gizmo drag, can be undone and redone.

Removing a point or seat deletes its object from the item too, unless something else still uses it. Saving a scene object, or saving a prefab where points and seats only moved or changed their settings, can itself be undone. Saving a prefab that adds or removes objects cannot; the save dialog says so before you confirm.

When to use this instead of the inspector

The inspector is fine for changing one field on a point you can already see. Use the editor when you are placing something by eye, when you want to check an animation against the point or seat it plays at, or when you are setting up a seat's transition, since the blend between mount location and seat is hard to judge without watching it.

Both write the same components, so there is no cost to switching between them.

note

The Item Setup section of Civil AI module settings is a different thing: it holds the item name, type and size collections. Action POI types live in the same settings and are what the Action dropdown here lists.

Common problems

Symptom	Cause
+ is greyed out	No item is selected under Items
Performed Standing is not shown	The item has no mount and no seat is being added, so there is nothing to stand beside
Stands at is greyed out	The point's position is the item itself or an object outside it. Move it in the scene or prefab
The preview plays standing though a seated option is chosen	No seat is selected. Click one under Seats or in the viewport
A new action type is refused	The name is blank or already exists, or module settings have no Action POI type collection
Carried says to pick an agent with hold points	The agent has no slots. Add them on the Hold tab and save
The agent sits down for an action meant to be done beside it	Tick Performed Standing on that point
The agent slides into the seat before the animation starts	Lead-in is lower than the layer's fade in. See Transition lead in

Next step

Mounts and Seats covers how seats behave at runtime, Use Spots covers where agents stand, and the Hold Point Editor covers the window's other tab.