souprune 0.5.1

//! # chapter.rs
//!
//! # chapter.rs 文件
//!
//! ## Module Overview
//!
//! ## 模块概述
//!
//! Chapter is the minimal unit of the linear sequence in the battle system.
//! It is an enum type representing different events in the battle.
//! For example, player choices, bullet pattern generation, dialogues, and nested Chapters.
//! Chapter itself does not contain definitions or implementations of bullet patterns or UI.
//!
//! Chapter 是 战斗系统中线性序列的最小单位。
//! 它是一个枚举类型，表示战斗中的不同事件。
//! 例如，玩家选择、弹幕生成、对话、以及 Chapter 的嵌套等。
//! Chapter 本身不包含 弹幕 或 UI 的定义与具体实现。

use bevy::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Deserialize, Serialize)]
pub enum Chapter {
    /// UI Interaction Chapter.
    ///
    /// The Chapter allows players to interact with the UI.
    /// Chapters involving UI interaction should apply this, such as player choices, dialogues, etc.
    ///
    /// UI 交互章节。
    ///
    /// 此章节允许玩家与 UI 交互。
    /// 涉及 UI 交互的章节都应应用此项，如 玩家选择、对话 等。
    UIInteraction { ui_layout: String },

    /// Danmaku Performance Chapter.
    ///
    /// The Chapter is responsible for playing a complete danmaku performance (timeline-based).
    ///
    /// 弹幕演出章节。
    ///
    /// 此章节负责播放完整的弹幕演出（基于时间轴）。
    DanmakuPerformance {
        /// Path to the performance file (e.g., "battle/performances/boss_attack.performance.ron")
        performance: String,
        /// Optional spawn position override (defaults to center of battle box)
        #[serde(default)]
        position: Option<(f32, f32)>,
    },

    /// Alight Motion Animation Performance Chapter.
    ///
    /// Plays an Alight Motion project (.amproj) as a battle animation.
    /// Layers with names starting with "#B" are treated as bullets (with collision).
    /// Layers with names starting with "#C" are treated as battle box boundaries.
    ///
    /// Alight Motion 动画演出章节。
    ///
    /// 播放 Alight Motion 项目 (.amproj) 作为战斗动画。
    /// 名称以 "#B" 开头的图层被视为弹幕（带碰撞体）。
    /// 名称以 "#C" 开头的图层被视为战斗框边界。
    AmPerformance {
        /// Path to the .amproj file (e.g., "demo_turn.amproj")
        amproj_path: String,
        /// Wait for animation to complete before continuing (default: true)
        #[serde(default = "default_true")]
        wait_for_completion: bool,
    },

    /// Simple Wait Chapter.
    ///
    /// 简单的等待章节。
    Wait(f32),

    /// Sequential Chapter Group.
    /// Chapters are executed one after another.
    ///
    /// 顺序执行的章节组。
    /// 章节会一个接一个地执行。
    Sequence(Vec<Chapter>),

    /// Parallel Chapter Group.
    /// All chapters start execution simultaneously.
    /// The group finishes when all child chapters are finished.
    ///
    /// 并行执行的章节组。
    /// 所有章节同时开始执行。
    /// 当所有子章节都完成时，该组才算完成。
    Parallel(Vec<Chapter>),

    /// Set Player State Chapter.
    /// Please note that in Battle, a player entity is not generated by default.
    /// If a player entity is needed to participate in the battle chapter,
    /// it must be generated through this chapter.
    ///
    /// 设置玩家状态的章节。
    /// 请注意，Battle 中，默认不会生成一个玩家实体。
    /// 如果需要玩家实体参与战斗章节，必须通过此章节进行生成。
    SetPlayer(PlayerAction),

    /// Set UI State Chapter.
    ///
    /// 设置 UI 状态的章节。
    SetUI(UIAction),
    /// Set Camera State Chapter.
    ///
    /// 设置 摄像机 状态的章节。
    SetCamera(CameraAction),
}

fn default_true() -> bool {
    true
}

/// Camera Action Enum.
///
/// 摄像机操作枚举。
#[derive(Debug, Clone, Deserialize, Serialize)]
pub enum CameraAction {
    /// Set Camera Position.
    ///
    /// 设置摄像机位置。
    SetPosition(Vec2),

    /// Set Camera Zoom Level.
    ///
    /// 设置摄像机缩放级别。
    SetZoom(f32),

    /// Start Camera Shake Effect.
    ///
    /// 开始摄像机震动效果。
    Shake { duration: f32, intensity: f32 },

    /// Set Camera to Follow Player.
    ///
    /// 设置摄像机跟随玩家。
    FollowPlayer(bool),
}

/// UI Action Enum.
///
/// UI 操作枚举。
#[derive(Debug, Clone, Deserialize, Serialize)]
pub enum UIAction {
    LoadLayout(String),
    Show(String),
    Hide(String),
    SetText { id: String, content: String },
    SetVariable { name: String, value: String },
    PlayAnimation { id: String, clip: String },
}

/// Player Action Enum.
///
/// 操作玩家的一系列枚举项。
#[derive(Debug, Clone, Deserialize, Serialize)]
pub enum PlayerAction {
    /// Set Mode for the player.
    /// Mode refers to different behavioral states defined in the Character Asset,
    /// such as "movable", "jumpable", "shootable", etc.
    /// The String references the mode names defined in the Character Asset.
    ///
    /// 设置玩家的模式。
    /// 模式 即 角色资产 中定义的 不同行为状态。
    /// 如“可移动”、“可跳跃”、“可射击”等。
    /// String 引用的是 角色资产 中定义的 模式 名称。
    SetMode(Vec<String>),

    /// Spawn a new player entity based on a config file.
    ///
    /// 根据配置文件生成一个新的玩家实体。
    Spawn { config_path: String, position: Vec2 },

    /// Teleport the player to a specified position.
    ///
    /// 将玩家传送到指定位置。
    Teleport(Vec2),

    /// Set the active state of the player.
    ///
    /// 设置玩家的激活状态。
    SetActive(bool),

    /// Despawn the player entity.
    ///
    /// 销毁玩家实体。
    Despawn,
}