Hold Point Editor

Getting an axe to sit properly in a woodcutter's hand used to mean entering play mode and waiting for an agent to pick it up. The Hold Point Editor shows an agent in any pose from its animations, holding an item exactly as it would at runtime, and lets you move the points involved until it looks right.

BardTreeLtd/Civil AI/Hold Point Editor

Hold points

Two things decide where an item ends up in a hand.

Hold point	Lives on	Is a
Agent point	The agent	Slot
Item point	The item	Inventory point of interest (POI)

When an agent holds an item, the item is moved so that its item point sits exactly on the agent point, facing the same way. Moving either point changes the grip.

Both use the same types — Dominant Hand Handle, Non-Dominant Hand Handle and Storage by default. An agent point holds an item by the item point of the same type. If the item has none, either hand stands in for the other; if it has neither, the item is held by its own origin.

The short version

1. Open the editor and drag your agent prefab into Agent.
2. Drag your item prefab into Items.
3. Drag an animation, a model file or a folder of animations into Animations.
4. Scrub the timeline and watch the grip.
5. Select the item point the item is held by, set Gizmo > Edit to Item point and drag it until the item sits right.
6. 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.
• Agent hold points — the agent's slots. The selected one is the hand holding the item.
• Items — a list of items to flick between. The selected one is held.
• Item hold points — the selected item's inventory POIs, and Held by, which picks which one it is held by.
• Animations — a list of clips to flick between. The selected one plays on the timeline.
• Gizmo — what dragging in the viewport edits, and whether it moves or rotates.
• Display and View — which points are drawn, 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 holding hand, which is useful for close work while an animation plays.

Hover a point to see its name; click it to select it.

Agent hold points

Press + to add a hold point. A searchable list of the agent's bones opens, with the humanoid bones such as Right Hand and Left Hand first. A new point is a Dominant Hand Handle that takes any size of item.

Select a point to change its name, bone, type, size and Allow smaller, or type an exact position and rotation relative to the bone. − removes it.

To place it by eye, set Gizmo > Edit to Agent point and drag it in the viewport. The held item follows.

note

A slot added directly to a bone sits on the bone's pivot — usually the wrist. Move it and, when you save, the slot moves onto a new child of the bone so it can keep the offset. The save dialog tells you when this will happen. Anything that referenced the old Slot component directly will need pointing at the new one.

Item hold points

Press + and pick a type to add a hold point to the item. It is created where the item is currently gripped, so the item does not jump.

Select a point to rename it, change its type, or type an exact position and rotation. − removes it, and deletes its object from the item too unless something else still uses it.

With Gizmo > Edit set to Item point:

• dragging the point the item is held by moves the item in the hand, with the point staying on the hand. This is the quickest way to fix a grip.
• dragging any other point moves it within the item, and the item stays where it is.

Held by is Auto by default, which picks exactly as the runtime does. Choose a point instead to preview a different grip; a message explains when the runtime would pick differently.

Saving

Nothing is written to your prefab or scene until you save. Changed points are marked * and new ones (new), and each section shows unsaved changes.

• Save to agent and Save to item write that side's hold points.
• Revert throws away that side's unsaved changes.
• Every edit, including a whole gizmo drag, can be undone and redone.

Saving a scene object, or saving a prefab where points only moved or changed type, can itself be undone. Saving a prefab that adds or removes objects cannot; the save dialog says so before you confirm.

What the preview shows

• Items are placed by the runtime's own code, so what you see is what agents will do.
• Animations are not blended. Each frame shows one clip exactly; at runtime an agent crossfades into a new clip over a quarter of a second.
• Character scripts that move slots onto bones when play starts are allowed for. Some character packs keep slots and props in a separate group and re-parent them on Start. The preview does the same, so slots set up that way follow the animation.
• Lighting differs by render pipeline. If the preview is too dark or too bright, adjust View > Light.

Next step

Agent Inventory covers how slots, types and sizes behave at runtime, and Items covers setting up the items themselves.