Add animation node extension

godotengine · Nov 17, 2024 · 8baefdb · 8baefdb
1 parent cb411fa
commit 8baefdb
Show file tree

Hide file tree

Showing 4 changed files with 199 additions and 0 deletions.
diff --git a/doc/classes/AnimationNodeExtension.xml b/doc/classes/AnimationNodeExtension.xml
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="AnimationNodeExtension" inherits="AnimationRootNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+        Base class for extending [AnimationRootNode]s from GDScript, C# or C++.
+	</brief_description>
+	<description>
+        [AnimationNodeExtension] exposes the APIs of [AnimationRootNode] to allow users to extend it from GDScript, C# or C++. This class is not meant to be used directly, but to be extended by other classes. It is used to create custom nodes for the [AnimationTree] system.
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="_process" qualifiers="virtual">
+			<return type="PackedFloat32Array" />
+			<param index="0" name="playback_info" type="PackedFloat64Array" />
+			<param index="1" name="test_only" type="bool" />
+			<description>
+                A version of the [method AnimationRootNode._process] method that is meant to be overridden by custom nodes. It returns a [PackedFloat32Array] with the processed animation data. 
+                The [PackedFloat64Array] parameter contains the playback information, containing the following values (in order): playback time and delta, start and end times, whether a seek was requested, whether the seek request was externally requested, the current [enum Animation.LoopedFlag] (encoded as a float), and the current blend weight.
+                The function must return a [PackedFloat32Array] of the node's time info, containing the following values (in order): animation length, time position, delta, [enum Animation.LoopMode] (encoded as a float), whether the animation is about to end and whether the animation is infinite. All values must be included in the returned array.
+            </description>
+		</method>
+		<method name="get_process_tree" qualifiers="const">
+			<return type="AnimationTree" />
+			<description>
+                Returns the [AnimationTree] that owns this node. This method should only be called from within the [method AnimationNodeExtension._process] method, and will return null otherwise.
+            </description>
+			</description>
+		</method>
+		<method name="get_remain" qualifiers="static">
+			<return type="float" />
+			<param index="0" name="node_info" type="PackedFloat32Array" />
+			<param index="1" name="break_loop" type="bool" />
+			<description>
+                Returns the remaining time of the animation for a given node time info [PackedFloat32Array].
+			</description>
+		</method>
+		<method name="is_looping" qualifiers="static">
+			<return type="bool" />
+			<param index="0" name="node_info" type="PackedFloat32Array" />
+			<description>
+                Returns whether the animation is looping for a given node time info [PackedFloat32Array].
+			</description>
+		</method>
+	</methods>
+</class>
diff --git a/scene/animation/animation_node_extension.cpp b/scene/animation/animation_node_extension.cpp
@@ -0,0 +1,92 @@
+/**************************************************************************/
+/*  animation_node_extension.cpp                                          */
+/**************************************************************************/
+/*                         This file is part of:                          */
+/*                             GODOT ENGINE                               */
+/*                        https://godotengine.org                         */
+/**************************************************************************/
+/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
+/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur.                  */
+/*                                                                        */
+/* Permission is hereby granted, free of charge, to any person obtaining  */
+/* a copy of this software and associated documentation files (the        */
+/* "Software"), to deal in the Software without restriction, including    */
+/* without limitation the rights to use, copy, modify, merge, publish,    */
+/* distribute, sublicense, and/or sell copies of the Software, and to     */
+/* permit persons to whom the Software is furnished to do so, subject to  */
+/* the following conditions:                                              */
+/*                                                                        */
+/* The above copyright notice and this permission notice shall be         */
+/* included in all copies or substantial portions of the Software.        */
+/*                                                                        */
+/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,        */
+/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF     */
+/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
+/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY   */
+/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,   */
+/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE      */
+/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
+/**************************************************************************/
+
+#include "animation_node_extension.h"
+
+AnimationNodeExtension::AnimationNodeExtension() {
+}
+
+AnimationNode::NodeTimeInfo AnimationNodeExtension::_process(const AnimationMixer::PlaybackInfo p_playback_info, bool p_test_only) {
+	PackedFloat32Array r_ret;
+
+	GDVIRTUAL_CALL(
+			_process,
+			_playback_info_to_array(p_playback_info),
+			p_test_only,
+			r_ret);
+
+	return _array_to_node_time_info(r_ret);
+}
+
+AnimationTree *AnimationNodeExtension::get_process_tree() const {
+	ERR_FAIL_NULL_V(process_state, nullptr);
+	return process_state->tree;
+}
+
+bool AnimationNodeExtension::is_looping(const PackedFloat32Array &p_node_info) {
+	return _array_to_node_time_info(p_node_info).is_looping();
+}
+
+double AnimationNodeExtension::get_remain(const PackedFloat32Array &p_node_info, bool p_break_loop) {
+	return _array_to_node_time_info(p_node_info).get_remain(p_break_loop);
+}
+
+void AnimationNodeExtension::_bind_methods() {
+	ClassDB::bind_method(D_METHOD("get_process_tree"), &AnimationNodeExtension::get_process_tree);
+	ClassDB::bind_static_method("AnimationNodeExtension", D_METHOD("is_looping", "node_info"), &AnimationNodeExtension::is_looping);
+	ClassDB::bind_static_method("AnimationNodeExtension", D_METHOD("get_remain", "node_info", "break_loop"), &AnimationNodeExtension::get_remain);
+	GDVIRTUAL_BIND(_process, "playback_info", "test_only");
+}
+
+AnimationNode::NodeTimeInfo AnimationNodeExtension::_array_to_node_time_info(const PackedFloat32Array &p_node_info) {
+	ERR_FAIL_COND_V_MSG(p_node_info.size() != 6, AnimationNode::NodeTimeInfo(), "Invalid node info.");
+	AnimationNode::NodeTimeInfo ret_val;
+	ret_val.length = p_node_info[0];
+	ret_val.position = p_node_info[1];
+	ret_val.delta = p_node_info[2];
+	ret_val.loop_mode = static_cast<Animation::LoopMode>(p_node_info[3]);
+	ret_val.will_end = p_node_info[4] > 0.0;
+	ret_val.is_infinity = p_node_info[5] > 0.0;
+	return ret_val;
+}
+
+PackedFloat64Array AnimationNodeExtension::_playback_info_to_array(const AnimationMixer::PlaybackInfo &p_playback_info) {
+	PackedFloat64Array playback_info_array;
+	playback_info_array.push_back(p_playback_info.time);
+	playback_info_array.push_back(p_playback_info.delta);
+	playback_info_array.push_back(p_playback_info.start);
+	playback_info_array.push_back(p_playback_info.end);
+	playback_info_array.push_back(p_playback_info.seeked);
+	playback_info_array.push_back(p_playback_info.is_external_seeking);
+	playback_info_array.push_back(p_playback_info.looped_flag);
+	playback_info_array.push_back(p_playback_info.weight);
+
+	return playback_info_array;
+}
diff --git a/scene/animation/animation_node_extension.h b/scene/animation/animation_node_extension.h
@@ -0,0 +1,60 @@
+/**************************************************************************/
+/*  animation_node_extension.h                                            */
+/**************************************************************************/
+/*                         This file is part of:                          */
+/*                             GODOT ENGINE                               */
+/*                        https://godotengine.org                         */
+/**************************************************************************/
+/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
+/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur.                  */
+/*                                                                        */
+/* Permission is hereby granted, free of charge, to any person obtaining  */
+/* a copy of this software and associated documentation files (the        */
+/* "Software"), to deal in the Software without restriction, including    */
+/* without limitation the rights to use, copy, modify, merge, publish,    */
+/* distribute, sublicense, and/or sell copies of the Software, and to     */
+/* permit persons to whom the Software is furnished to do so, subject to  */
+/* the following conditions:                                              */
+/*                                                                        */
+/* The above copyright notice and this permission notice shall be         */
+/* included in all copies or substantial portions of the Software.        */
+/*                                                                        */
+/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,        */
+/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF     */
+/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
+/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY   */
+/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,   */
+/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE      */
+/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
+/**************************************************************************/
+
+#ifndef ANIMATION_NODE_EXTENSION_H
+#define ANIMATION_NODE_EXTENSION_H
+
+#include "scene/animation/animation_tree.h"
+
+class AnimationNodeExtension : public AnimationRootNode {
+	GDCLASS(AnimationNodeExtension, AnimationRootNode);
+
+public:
+	AnimationNodeExtension();
+	virtual ~AnimationNodeExtension() = default;
+
+	virtual NodeTimeInfo _process(const AnimationMixer::PlaybackInfo p_playback_info, bool p_test_only = false) override;
+
+	AnimationTree *get_process_tree() const;
+
+	static bool is_looping(const PackedFloat32Array &p_node_info);
+	static double get_remain(const PackedFloat32Array &p_node_info, bool p_break_loop = false);
+
+protected:
+	static void _bind_methods();
+
+	GDVIRTUAL2R(PackedFloat32Array, _process, PackedFloat64Array, bool);
+
+private:
+	static AnimationNode::NodeTimeInfo _array_to_node_time_info(const PackedFloat32Array &p_array);
+	static PackedFloat64Array _playback_info_to_array(const AnimationMixer::PlaybackInfo &p_playback_info);
+};
+
+#endif // ANIMATION_NODE_EXTENSION_H
diff --git a/scene/register_scene_types.cpp b/scene/register_scene_types.cpp
@@ -37,6 +37,7 @@
 #include "scene/animation/animation_blend_space_2d.h"
 #include "scene/animation/animation_blend_tree.h"
 #include "scene/animation/animation_mixer.h"
+#include "scene/animation/animation_node_extension.h"
 #include "scene/animation/animation_node_state_machine.h"
 #include "scene/animation/animation_player.h"
 #include "scene/animation/animation_tree.h"
@@ -512,6 +513,7 @@ void register_scene_types() {
 	GDREGISTER_CLASS(AnimationNodeBlendSpace2D);
 	GDREGISTER_CLASS(AnimationNodeStateMachine);
 	GDREGISTER_CLASS(AnimationNodeStateMachinePlayback);
+	GDREGISTER_CLASS(AnimationNodeExtension);
 
 	GDREGISTER_INTERNAL_CLASS(AnimationNodeStartState);
 	GDREGISTER_INTERNAL_CLASS(AnimationNodeEndState);