Add FrameAnimator3D for animated texture support on Blockbench models

Scripts/Interactables/FrameAnimator3D.cs

@@ -0,0 +1,94 @@
+using Godot;
+
+namespace Cirno.Scripts.Interactables;
+
+/// <summary>
+/// Animates a tiled texture by shifting the UV1 vertical offset on a mesh surface material.
+/// Designed for Blockbench-exported meshes whose texture is a vertical sprite sheet
+/// (e.g. 16×64 with 4 frames stacked top-to-bottom).
+///
+/// Usage:
+///  1. Attach this node as a child of (or sibling to) the MeshInstance3D you want to animate.
+///  2. Optionally assign <see cref="TargetMesh"/> in the inspector; if left empty the node
+///     will search its parent for the first MeshInstance3D automatically.
+///  3. Set <see cref="FrameCount"/> to the number of frames in the sprite sheet.
+///  4. Drive <see cref="CurrentFrame"/> from an AnimationPlayer track — the script handles
+///     the UV offset calculation.
+/// </summary>
+[Tool]
+public partial class FrameAnimator3D : Node3D
+{
+    /// <summary>
+    /// The mesh whose surface_0 material UV offset will be updated.
+    /// If null, the node searches its parent for the first MeshInstance3D on _Ready.
+    /// </summary>
+    [Export] public MeshInstance3D TargetMesh { get; set; }
+
+    /// <summary>
+    /// Total number of animation frames stacked vertically in the texture.
+    /// </summary>
+    [Export] public int FrameCount { get; set; } = 4;
+
+    /// <summary>
+    /// Surface index on the mesh to apply the UV offset to.
+    /// Defaults to 0, matching Blockbench's typical single-surface export.
+    /// </summary>
+    [Export] public int SurfaceIndex { get; set; } = 0;
+
+    private int _currentFrame;
+
+    /// <summary>
+    /// The active frame index (0-based). Set this from an AnimationPlayer track to animate.
+    /// Clamped to [0, <see cref="FrameCount"/> - 1].
+    /// </summary>
+    [Export]
+    public int CurrentFrame
+    {
+        get => _currentFrame;
+        set
+        {
+            _currentFrame = Mathf.Clamp(value, 0, Mathf.Max(0, FrameCount - 1));
+            ApplyFrame();
+        }
+    }
+
+    public override void _Ready()
+    {
+        // Auto-discover the mesh from the parent if none was assigned in the inspector.
+        if (TargetMesh is null)
+        {
+            TargetMesh = GetParent() as MeshInstance3D
+                         ?? GetParentOrNull<Node>()?.FindChild("*", recursive: false, owned: false) as MeshInstance3D;
+        }
+
+        ApplyFrame();
+    }
+
+    /// <summary>
+    /// Calculates the normalised V offset for <see cref="CurrentFrame"/> and writes it to the
+    /// override material on <see cref="TargetMesh"/>'s surface.
+    /// Each frame occupies an equal vertical slice: offset = frame / frameCount.
+    /// </summary>
+    private void ApplyFrame()
+    {
+        if (TargetMesh is null || FrameCount <= 0) return;
+
+        // Ensure we have an override material to write to so we don't mutate shared resources.
+        if (TargetMesh.GetSurfaceOverrideMaterial(SurfaceIndex) is not StandardMaterial3D mat)
+        {
+            var baseMat = TargetMesh.GetActiveMaterial(SurfaceIndex);
+
+            // Duplicate the base material so sibling nodes keep their own state.
+            mat = baseMat?.Duplicate() as StandardMaterial3D;
+            if (mat is null) return;
+
+            TargetMesh.SetSurfaceOverrideMaterial(SurfaceIndex, mat);
+        }
+
+        // Each frame is a 1/FrameCount slice; V offset moves down one slice per frame.
+        float vOffset = (float)_currentFrame / FrameCount;
+        mat.Uv1Offset = new Vector3(mat.Uv1Offset.X, vOffset, mat.Uv1Offset.Z);
+    }
+}
+
+

Scripts/Interactables/FrameAnimator3D.cs.uid

@@ -0,0 +1 @@
+uid://b46e1ft1scvwt