排队动画精灵 Macroquad

queued_animated_sprites_macroquad Rust 库提供了一个围绕队列设计集中精力绘制动画精灵的简单接口。它建立在 macroquad 之上，并通过其动画效果系统提供灵活性，该系统可以增强精灵的绘制方式，而无需额外的工作。

特性

• 易于创建和管理精灵动画
• 支持每个精灵存储多个动画，使用泛型键类型存储，以简化项目集成（例如，使用您自己的枚举键）
• 序列化以轻松保存和加载精灵状态
• 基于队列的系统，动画根据持续时间自动连续播放，为高级动画组合提供良好接口
• 全面的动画效果系统，只需额外一行或两行代码即可应用独特的效果到您的精灵（淡入/淡出、滑动进入/退出、旋转、脉冲等）
• 可选的自定义效果（crate功能），允许任何人即时实现并使用他们自己的新效果

内置效果

库提供了一些内置效果，例如

• Blinking(EffectColor, u32)：使精灵以指定的颜色和闪烁次数闪烁（用于伤害或低血量效果）
• FadeIn 和 FadeOut：逐渐改变精灵的不透明度。
• SlideIn(SlideDirection) 和 SlideOut(SlideDirection)：将精灵移入或移出屏幕。
• Pulse(f32)：将精灵放大和缩小，以原点为中心。f32参数确定最大缩放因子。
• Shake(f32)：对精灵应用震动效果。f32参数确定震动的强度。
• Wobble(f32)：对精灵应用摇摆效果。f32参数确定摇摆的强度。
• Bounce(f32, u32)：使精灵弹跳。f32参数确定弹跳的高度，u32参数指定弹跳次数。
• BasicFlip(FlipDirection)：水平或垂直翻转精灵。
• Spin：旋转精灵。
• Glitch(f32)：对精灵应用故障效果。f32参数确定故障效果的强度。
• ShearLeft(f32)和ShearRight(f32)：对精灵应用剪切效果。f32参数确定剪切效果的强度。
• SquashFlipVertical(f32)和SquashFlipVertical(f32)：垂直或水平挤压+翻转精灵。f32参数确定挤压效果的强度。
• ColorCycle(Vec)：循环一组颜色。

基本用法

库的核心是AnimatedSprite结构体，其中包含此库的大部分功能。

以下是一个创建和使用动画精灵的快速示例

use queued_animated_sprites_macroquad::{AnimatedSprite, Animation, AnimationEffect, SlideFrom};
use macroquad::prelude::*;

#[macroquad::main("Queued Animated Sprites Demo")]
async fn main() {
    // Load the spritesheet
    let texture = Texture2D::from_file_with_format(
        include_bytes!("slime.png"),
        None
    );

    // Create the animated sprite
    let mut slime = AnimatedSprite::new(
        32.0,  // Width of each sprite on the spritesheet
        32.0,  // Height of each sprite on the spritesheet
        "idle", // Default key you want to have for your default animation
        Animation::new(0, 4, 6)  // Default animation, uses the first row on the spritesheet, with 4 sprites on the row, running at 6fps
    );

    // Add an attack animation
    slime.register_animation(
        "attack",
        Animation::new(1, 6, 12)  // Targets spritesheet's first row (1), takes the first 6 frames on the row, plays them at 12 fps
    );

    // Using the added attack animation, queue it up and set its duration for 1.5 seconds
    slime.add_animation_to_queue("attack", 1.5);

    loop {
        clear_background(WHITE);

        // Update and draw the sprite
        slime.update();
        slime.draw_animation(&texture, 400.0, 300.0, WHITE); // spritesheet texture, x, y, color

        next_frame().await
    }
}

此示例创建了一个粘液精灵，具有空闲动画和攻击动画。精灵执行攻击动画1.5秒后返回空闲（默认动画）。

动画效果

此库包含一个内置的动画效果系统，可以应用于您的精灵。这些允许您执行诸如在怪物生成时淡入，当精灵移动进出战斗时滑动屏幕，当UI元素需要被看到时进行脉冲，等等。

以下是如何使用动画效果的示例

use queued_animated_sprites_macroquad::{AnimatedSprite, Animation, AnimationEffect, SlideFrom};

// ... (previous setup code)

// Add a spawn animation with fade-in effects
slime.register_animation(
    "spawn",
    Animation::new(2, 4, 8)  // row 2, 4 frames, 8 fps
        .with_start_effect(AnimationEffect::FadeIn, 1) // fade in effect has a duration of 1s from the start of the spawn animation
);

// Add a despawn animation with fade-out
slime.register_animation(
    "despawn",
    Animation::new(3, 4, 8)  // row 3, 4 frames, 8 fps
        .with_end_effect(AnimationEffect::FadeOut, 0.5) // fade out effect has a duration starting 0.5s before the end of the despawn animation
);

// Queue the spawn animation which will play for 1 second
slime.add_animation_to_queue("spawn", 1.0);

在此示例中，我们添加了一个淡入的“生成”动画和一个淡出的“消失”动画。值得注意的是，您可以使用Animation::empty()使精灵完全不绘制。这意味着可以将空设置为默认值（对于在特定时刻触发的视觉效果很有用），或者将其添加到队列中暂时停止绘制精灵。

自定义效果（可选功能）

对于更复杂的使用案例，queued_animated_sprites_macroquad还支持自定义动画效果。这是一个可选功能，可以在您的Cargo.toml中启用。

[dependencies]
queued_animated_sprites_macroquad = { version = "0.1.0", features = ["custom_effects"] }

自定义效果允许您通过指定一个函数来定义自己的效果行为。唯一的缺点是自定义效果不可序列化（因此不太容易集成），所以这是一个为高级用户提供的可选功能。

以下是如何创建和使用自定义“颜色循环”效果的示例

use queued_animated_sprites_macroquad::{AnimatedSprite, Animation, AnimationEffect};
use macroquad::prelude::*;

// Define the color cycle effect
fn color_cycle_effect(
    progress: f32,
    color: &mut Color,
    _params: &mut DrawTextureParams,
    _x_pos: &mut f32,
    _y_pos: &mut f32,
    _tile_width: f32,
    _tile_height: f32,
) {
    color.r = (progress * std::f32::consts::PI * 2.0).sin() * 0.5 + 0.5;
    color.g = (progress * std::f32::consts::PI * 2.0 + 2.0).sin() * 0.5 + 0.5;
    color.b = (progress * std::f32::consts::PI * 2.0 + 4.0).sin() * 0.5 + 0.5;
}

// ... (previous setup code)

// Add an idle animation with the color cycle effect
let color_cycle_animation = Animation::new(0, 4, 6)
    .with_start_effect(AnimationEffect::new_custom(color_cycle_effect), 2.0);

slime.register_animation("idle_color_cycle", color_cycle_animation);

// Queue the color cycling idle animation, which will play for 3.0 seconds
slime.add_animation_to_queue("idle_color_cycle", 3.0);

此示例创建了一个自定义颜色循环效果，随着时间的推移改变精灵的颜色。此效果应用于持续3秒的“idle_color_cycle”动画。

许可证

此项目使用MIT许可证。有关详细信息，请参阅LICENSE文件。