BeatSprite.cs

using Godot;
using System;

public partial class BeatSprite : AnimatedSprite2D
{
	private static readonly StringName DefaultSpriteAnimation = "default";

	[Export(PropertyHint.Range, "1,64,1")]
	public int QuarterBeatsPerFrame = 1;

	private StageManager _stageManager;

	public override void _Ready()
	{
		QuarterBeatsPerFrame = Math.Max(1, QuarterBeatsPerFrame);
		EnsureAnimationAndResetFrame();

		_stageManager = ResolveStageManagerFromRootChildren();
		if (_stageManager == null)
		{
			GD.PushWarning($"{nameof(BeatSprite)}: StageManager not found among root scene children.");
			return;
		}

		_stageManager.QuarterBeatTick += OnQuarterBeatTick;
	}

	public override void _ExitTree()
	{
		if (_stageManager == null)
		{
			return;
		}

		_stageManager.QuarterBeatTick -= OnQuarterBeatTick;
	}

	private StageManager ResolveStageManagerFromRootChildren()
	{
		SceneTree tree = GetTree();
		if (tree == null)
		{
			return null;
		}

		Node rootScene = tree.CurrentScene;
		if (rootScene == null)
		{
			return null;
		}

		for (int i = 0; i < rootScene.GetChildCount(); i++)
		{
			Node child = rootScene.GetChild(i);
			if (child is StageManager stageManager && GodotObject.IsInstanceValid(stageManager))
			{
				return stageManager;
			}
		}

		return null;
	}

	private void OnQuarterBeatTick(float totalBeatsAbsolute)
	{
		QuarterBeatsPerFrame = Math.Max(1, QuarterBeatsPerFrame);
		int quarterIndex = Mathf.FloorToInt(totalBeatsAbsolute * 4.0f);
		if (quarterIndex % QuarterBeatsPerFrame != 0)
		{
			return;
		}

		AdvanceFrame();
	}

	private void EnsureAnimationAndResetFrame()
	{
		if (!EnsureAnimation())
		{
			return;
		}

		Stop();
		SetFrameAndProgress(0, 0.0f);
	}

	private bool EnsureAnimation()
	{
		if (SpriteFrames == null)
		{
			return false;
		}

		StringName animationName = Animation;
		if (!SpriteFrames.HasAnimation(animationName))
		{
			if (!SpriteFrames.HasAnimation(DefaultSpriteAnimation))
			{
				return false;
			}

			animationName = DefaultSpriteAnimation;
			Animation = animationName;
		}

		return true;
	}

	private void AdvanceFrame()
	{
		if (!EnsureAnimation())
		{
			return;
		}

		int frameCount = SpriteFrames.GetFrameCount(Animation);
		if (frameCount <= 0)
		{
			return;
		}

		int nextFrame = (Frame + 1) % frameCount;
		SetFrameAndProgress(nextFrame, 0.0f);
	}
}