prowl-animation
GitHub用于Prowl引擎中的角色、武器动画管理,涵盖模型导入、Rig配置、动画图构建、参数驱动及根运动处理。
Trigger Scenarios
Install
npx skills add ProwlEngine/Prowl --skill prowl-animation -g -y
SKILL.md
Frontmatter
{
"name": "prowl-animation",
"description": "Animating characters, arms and weapons in Prowl. Use when importing models or animation files, choosing Generic or Humanoid rigs, playing clips, building or editing .animgraph state machines and blends, driving Animator parameters from scripts, using root motion with a CharacterController, or attaching objects to bones."
}
Prowl animation
Prowl animation graphs are not Unity's Animator Controller. Transitions have no conditions of their own, states decide when they may be entered and left. Read the graph section before building one, or the graph never leaves its first state.
Importing
- A model file imports as a
PrefabAssetwith sub assets: meshes, materials, an Avatar named<model> Avatar, and oneAnimationClipper take, named after the take.asset info --path Models/Arms.fbxlists them. - Unless the rig type is None, the importer adds an
Animatorto the model's root with its Avatar and Clips filled in. importer Models/Arms.fbx --values '{"rigType": 2}'switches the rig. 0 none, 1 Generic (the default), 2 Humanoid.- A Generic clip plays on another model only where bone names match exactly. A Humanoid clip plays on any humanoid. Rigs that are only arms usually fail humanoid mapping, so keep first person arms and their gun animations Generic, with the same bone names.
- Per clip settings are keyed by the take name:
importer Models/Arms.fbx --values '{"clips.Fire.loop": false, "clips.Fire.name": "Shoot"}'. Keys areloop,name,trimStart,trimEnd,rootTravel,rootTurn,rootHeight. A take name containing a dot, such asmixamo.com, can not be written as a dotted key. Change that clip in the model inspector instead, since passing a wholeclipsobject replaces every clip's settings. - Root travel and root turn are extracted by default, so a walk clip plays in place and its movement becomes root motion. Set
rootTravelto false on clips whose movement should stay in the pose.
Animator
- It needs an
Avatar, or nothing animates. - Each frame it runs after every
Updateand beforeLateUpdate. Set parameters inUpdate. Override bones inLateUpdate. SetFloat,SetBool,SetInt,SetTrigger,ResetTrigger, and the matching getters. A parameter must be declared in the graph.- Without a graph:
Play(clip)orPlay("Fire")(by name fromClips),CrossFade(clip, seconds).PlayAutomaticallyplaysClips[0]. There is no separate legacy Animation component. - Assign a graph with
set /Arms:Animator Graph Anim/Arms.animgraph. - Call
Rebind()after adding or removing bones under it.
using Prowl.Runtime;
using Prowl.Vector;
public sealed class ArmsInput : Component
{
public Animator Arms;
public override void Update()
{
if (Arms.IsNotValid()) return;
Arms.SetFloat("Speed", Float2.Length(Input.GetWASD()));
if (Input.GetMouseButtonDown(0)) Arms.SetTrigger("Fire");
if (Input.GetKeyDown(KeyCode.R)) Arms.SetTrigger("Reload");
}
}
Root motion
ApplyRootMotion = truemoves the Animator's own Transform directly, through walls.- With a
CharacterController, leave it off and feed the delta intoMoveinLateUpdate. The delta is in the character's local space.
using Prowl.Runtime;
public sealed class RootMotionMover : Component
{
private Animator _animator;
private CharacterController _controller;
public override void OnEnable()
{
_animator = GetComponentInChildren<Animator>();
_controller = GetComponent<CharacterController>();
}
public override void LateUpdate()
{
var delta = _animator.RootMotionDelta;
_controller.Move(Transform.Rotation * delta.position);
Transform.Rotation = Transform.Rotation * delta.rotation;
}
}
Graphs
Create one with asset create --path Anim/Arms --type AnimationGraph, read it with graph Anim/Arms.animgraph, and edit it with graph Anim/Arms.animgraph --action edit --ops '<json>'. graph --action types lists every node with its pins and settings. Ops run in order as one undo step, and "as" names a result so later ops can use $name. A state named with "as": "fire" also gives $fire.output.
How a graph works:
- The first pose node added to the graph itself becomes the root. Usually that is a
motion.stateMachine. - A state is its own small graph. Nodes added with
"owner": "$state"belong to it, and its output node has three pins:Pose,EnterandExit. - A transition from A to B fires only when A's Exit and B's Enter are both true. A new state starts with Enter closed and Exit open. So with nothing wired to Enter, nothing ever transitions into that state.
- Open a gate permanently with
{"op": "gate", "state": "$idle", "enter": true}, or wire a flag into the pin to make it conditional. - Any State transitions ignore the source's Exit.
motion.stateFinishedis true once the state has played through (Threshold0.99). Wire it into Exit for one shot states like fire and reload, and set their clip node'sLoopingtoOnce.- A trigger is a flag parameter with
"trigger": true. It turns itself off when a transition fires on it. - An unwired required number pin reads 0, not the value shown in the editor. Feed constants with
motion.constFloatand itsValuesetting. motion.floatComparehas pinsAandBand anOpsetting that defaults toGreater.motion.blend1dhas aParameterpin, then one pose pin per input. Each pose input's threshold is its pin value, set with theinputop. They default to 1, so set every one.- Layers:
motion.layerBlendwith groups of Layer, Weight and Mask, andmotion.boneMaskwhoseBonessetting reads"Spine:1,LeftArm:0.5".
This builds idle, fire and reload for first person arms:
[
{"op": "param", "name": "Speed", "kind": "Number", "value": 0},
{"op": "param", "name": "Fire", "kind": "Flag", "trigger": true},
{"op": "param", "name": "Reload", "kind": "Flag", "trigger": true},
{"op": "add", "type": "motion.stateMachine", "as": "sm"},
{"op": "state", "machine": "$sm", "name": "Idle", "as": "idle"},
{"op": "state", "machine": "$sm", "name": "Fire", "as": "fire"},
{"op": "state", "machine": "$sm", "name": "Reload", "as": "reload"},
{"op": "add", "type": "motion.clip", "owner": "$idle", "as": "idleClip"},
{"op": "connect", "from": "$idleClip", "to": "$idle.output", "pin": "Pose"},
{"op": "gate", "state": "$idle", "enter": true},
{"op": "add", "type": "motion.clip", "owner": "$fire", "as": "fireClip"},
{"op": "set", "node": "$fireClip", "key": "Looping", "value": "Once"},
{"op": "connect", "from": "$fireClip", "to": "$fire.output", "pin": "Pose"},
{"op": "add", "type": "motion.parameter", "owner": "$fire", "as": "fireParam"},
{"op": "set", "node": "$fireParam", "key": "Name", "value": "Fire"},
{"op": "connect", "from": "$fireParam", "to": "$fire.output", "pin": "Enter"},
{"op": "add", "type": "motion.stateFinished", "owner": "$fire", "as": "fireDone"},
{"op": "connect", "from": "$fireDone", "to": "$fire.output", "pin": "Exit"},
{"op": "add", "type": "motion.clip", "owner": "$reload", "as": "reloadClip"},
{"op": "set", "node": "$reloadClip", "key": "Looping", "value": "Once"},
{"op": "connect", "from": "$reloadClip", "to": "$reload.output", "pin": "Pose"},
{"op": "add", "type": "motion.parameter", "owner": "$reload", "as": "reloadParam"},
{"op": "set", "node": "$reloadParam", "key": "Name", "value": "Reload"},
{"op": "connect", "from": "$reloadParam", "to": "$reload.output", "pin": "Enter"},
{"op": "add", "type": "motion.stateFinished", "owner": "$reload", "as": "reloadDone"},
{"op": "connect", "from": "$reloadDone", "to": "$reload.output", "pin": "Exit"},
{"op": "transition", "machine": "$sm", "from": "Idle", "to": "Fire", "duration": 0.05},
{"op": "transition", "machine": "$sm", "from": "Idle", "to": "Reload", "duration": 0.15},
{"op": "transition", "machine": "$sm", "from": "Fire", "to": "Idle", "duration": 0.1},
{"op": "transition", "machine": "$sm", "from": "Reload", "to": "Idle", "duration": 0.2}
]
Then set each clip, using the node ids the edit returned: {"op": "set", "node": "<id>", "key": "Clip", "value": "Models/Arms.fbx#Fire"}.
For a speed driven state, wire motion.parameter (Name Speed) into pin A of a motion.floatCompare, a motion.constFloat (Value 0.1) into pin B, and the compare into the state's Enter.
Bones and attachments
- Bones are ordinary GameObjects under the Animator, bound by name. Attach a gun by parenting it under the hand bone:
go parent --target /Gun --parent /Arms/Armature/Hand_R(find the real path withtree --root /Arms --depth 10 --filter Hand), then zero its local position withgo transform. - Never rename bones. The Animator and the
SkinnedMeshRendererfind them by name and path. - First person setup: the arms model under the camera, the gun under the hand bone, and one graph like the one above.
motion.ragdollandmotion.footGroundingexist for physical characters, seegraph --action types --filter ragdoll.
Look up Animator, AnimationGraph, AnimationClip, Avatar and AvatarMask with api --type.
Version History
- f68efb0 Current 2026-11-21 16:08


