AnimationNodeAnimation Dynamic animation parameter for programmatic control

[Jhappy77]

Describe the project you are working on

3D sandbox adventure game with UGC

Describe the problem or limitation you are having in your project

I have characters with nearly 100 animations, and that will expand to more in the future. I also will support UGC where users can upload their own animations to existing characters.

I'd like to simplify my animation graphs to not require every possible animation to be added to the graph as a separate node. Many animations fill similar niches that in theory don't require explicit alternative nodes in the animation tree.

This would help:

• Simplify creating AnimationTrees - create a node per animation niche, not a node for every possible occupant of that niche
• Reusing animationtree structure for entities which have the same body but different expected animations for the same role (ex: a zombie and a human might share the same model and animationtree but via code the zombie requests a different idle animation or different death animation, instead of needing to create new nodes for them we can reuse the existing ones)
• (probably, haven't validated this yet) enable UGC animations to be played in animationtree without modifying tree

Describe the feature / enhancement and how it helps to overcome the problem or limitation

AnimationNodeAnimation could expose a new parameter animation to the AnimationTree that lets code change which animation it outputs.

Alternatively, if we don't want to change AnimationNodeAnimation, we could make a new node, something like AnimationNodeDynamicAnimation.

That way, if you have dozens of animations that fill a similar role, instead of needing to create separate animation nodes for each one, you can use a single node in the graph, which represents a niche, and you can use code to dynamically set the animation in this niche as required.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

something along the lines of

// AnimationTree.cpp

StringName animation_param = PNAME("animation");

// helper
inline StringName _effective_animation() const {
	Variant v = get_parameter(animation_param);
	if (v.get_type() == Variant::STRING_NAME) {
		const StringName n = v;
		if (n != StringName()) {
			return n;
		}
	}
	return animation; // fallback to the shared property
}

AnimationNode::NodeTimeInfo AnimationNodeAnimation::get_node_time_info() const {
	NodeTimeInfo nti;
	const StringName anim_name = _effective_animation();
	if (!process_state->tree->has_animation(anim_name)) {
		return nti;
	}

	if (use_custom_timeline) {
		nti.length = timeline_length;
		nti.loop_mode = loop_mode;
	} else {
		Ref<Animation> anim = process_state->tree->get_animation(anim_name);
		nti.length = (double)anim->get_length();
		nti.loop_mode = anim->get_loop_mode();
	}
	nti.position = get_parameter(current_position);
	return nti;
}

// etc, other places where animation is needed also use _effective_animation() helper

If this enhancement will not be used often, can it be worked around with a few lines of script?

If you don't use it, you can ignore it entirely

Is there a reason why this should be core and not an add-on in the asset library?

Important and useful functionality that makes animation trees more flexible and controllable via code.

[TokageItLab]

There have already been several requests of this thing like #8818 #7121, and I have mentioned to them; Currently, the behavior of the AnimationBlendTree is heavily dependent on the length of the AnimationNodeAnimation. Therefore, simple implementation for changing the animation in AnimationNodeAnimation could potentially break the transitions within the animation tree. Also since AnimationNodeAnimation has internal states for pingpong loops and reverse playback, it may break playback state. So implementing that must be avoided.

I suggest the safe approach as current workaround is to include all potentially changeable animations within a StateMachine in Nested mode, functioning as an AnyState https://godotengine.org/article/migrating-animations-from-godot-4-0-to-4-3/#nested.

---

Also, we need to consider interactions with BlendSpaceCyclicSync proposal #13307.

If we want to combine it with BlendSpaceCyclicSync proposed by #13307 --if we extend AnimationNodeAnimation, we would need an implementation that manages time position as a progress (0-1) or performs a conversion that preserves progress when changing animations (or BlendSpaceCyclicSync must subscribe a signal for detecting animation changed). Also other internal states must be properly initialized.

---

Assuming it cannot be placed in the BlendSpaceCyclicSync proposed by #13307 --if not extending AnimationNodeAnimation, it might be possible to extend AnimationNodeStateMachine and implement a read-only StateMachine that simulates the AnyState described above.

If making it read-only proves difficult, simply extending AnimationRootNode should suffice. However, in either case, please keep in mind that this AnyState approach might not be able to be placed into the BlendSpaceCyclicSync in the future.

[Jhappy77]

Thanks for the reply. A new node that uses AnimationNodeStateMachine as a basis that lets you use any animation without needing to explicitly define it would be sufficient for my use case and probably most others.

I think a documented limitation of not working with BlendSpaceCyclicSync would be acceptable since they seem to be conceptually opposed - the goal here is to make an animation node as flexible and non-specific as possible whereas the cyclic sync blendspace is about blending specific animations to work better together. But since that isn't implemented yet I can't comment too much further on it but maybe it is possible to get them working together down the line as a followup task.

I can potentially work on it this month, it's higher priority for me than the other issue I opened #13386

[nonchip]

i'm a bit confused here, AnimationNodeAnimation already has an animation property. as far as i can tell, all you'd need to do is add the animation to the library used by the AnimationPlayer and then set that property to its name you defined there.

assuming you dont want to reconfigure this during an entity's lifetime (which might be needed in some kind of animation editor or such, but not during gameplay), you can simply have the entity create an animationlibrary for anything custom it needs, and then add it to its player which gets its "default/shared" animations from its main library.

[TokageItLab]

AnimationNodeAnimation already has an animation property.

@nonchip What you need to know to avoid confusion is that properties and parameters are different.

Properties are members of the resource. If multiple instances containing an AnimationTree with the same BlendTree exist in a scene, they will all change simultaneously. Therefore, properties are generally static.

Conversely, parameters are members of the AnimationTree node, making them controllable per instance. Even if multiple instances containing an AnimationTree with the same BlendTree exist in a scene, they can have different States.

[nonchip]

@TokageItLab ah yes, my approach would require each "type" of entity to have a copy of the resource, which depending on complexity is gonna make this pretty memory inefficient.