34d - AI 生成游戏资产

2D 精灵资产
├── 角色精灵（Character Sprites）
│   ├── 静态立绘（多方向：正面/背面/侧面）
│   ├── 行走动画帧（Walk Cycle：4-8 帧）
│   ├── 攻击动画帧（Attack Animation）
│   ├── 受伤/死亡动画帧
│   └── 特殊动作（跳跃、冲刺、施法）
├── 瓦片集（Tilesets）
│   ├── 地形瓦片（草地、石头、水面、沙地）
│   ├── 墙壁/建筑瓦片
│   ├── 装饰瓦片（花草、路灯、栅栏）
│   └── 自动瓦片（Auto-tile，含边角过渡）
├── UI 元素
│   ├── 按钮、面板、边框
│   ├── 血条、能量条、经验条
│   ├── 图标（技能、道具、状态）
│   └── 对话框、提示框
├── 道具与物品
│   ├── 武器（剑、弓、法杖）
│   ├── 防具（盔甲、盾牌）
│   ├── 消耗品（药水、食物）
│   └── 收集品（宝石、钥匙、卷轴）
└── 特效精灵
    ├── 粒子帧（火焰、烟雾、魔法）
    ├── 爆炸序列帧
    └── 光效/辉光

## 美术风格定义清单

### 基础参数
- 画风：[像素画 / 卡通 / 动漫 / 手绘 / 写实 / 低多边形]
- 分辨率：[16x16 / 32x32 / 64x64 / 128x128 / 256x256]
- 调色板：[限定色板（如 PICO-8 16色）/ 自由色彩]
- 视角：[正面 / 侧面 / 俯视 / 等距（Isometric）]
- 轮廓线：[有黑色轮廓 / 无轮廓 / 彩色轮廓]

### 角色规格
- 身体比例：[Q版 2-3 头身 / 正常 5-6 头身 / 写实 7-8 头身]
- 动画帧数：[行走 4帧 / 行走 8帧 / 攻击 6帧]
- 方向数：[1方向 / 4方向 / 8方向]
- 背景：[透明 / 纯色]

# Leonardo.AI 提示词模板 — 2D 游戏角色

## 基础角色生成
[character description], [art style] game sprite,
[view: front view / side view / top-down],
transparent background, game-ready asset,
[size: 32x32 pixel art / 64x64 / 128x128],
clean lines, consistent proportions

## 示例 — 像素风格骑士
pixel art knight character, 32x32 sprite,
blue armor with silver trim, holding sword and shield,
front view, transparent background,
retro game style, clean pixel art, limited color palette

## 示例 — 卡通风格法师
cartoon wizard character sprite, chibi style,
purple robe with golden stars, holding magic staff,
front view, transparent background,
2D game asset, cel-shaded, vibrant colors

## 示例 — 动漫风格弓箭手
anime style archer character, game sprite sheet,
green cloak with hood, wooden bow,
4 directional views (front, back, left, right),
transparent background, consistent style

# 使用参考图保持风格一致
1. 准备一张已确定风格的角色参考图
2. 在 Leonardo.AI 中使用 Image Guidance 功能
3. 设置 Guidance Strength 为 0.3-0.5（保持风格但允许变化）
4. 在提示词中描述新角色的差异点

# 提示词模板
same art style as reference, [new character description],
game sprite, transparent background,
matching color palette and proportions

PixelLab 功能矩阵
├── 角色生成
│   ├── 多方向视图（正面、背面、左、右）
│   ├── 行走动画（4-8 帧自动生成）
│   ├── 攻击动画序列
│   └── 自定义姿势
├── 瓦片集生成
│   ├── 地形瓦片（含自动边角过渡）
│   ├── 建筑瓦片
│   └── 装饰元素
├── 地图生成
│   ├── 最大 400x400 像素地图
│   ├── 基于瓦片的自动布局
│   └── 多层地图支持
└── API 集成
    ├── 程序化生成支持
    ├── 实时资产创建
    └── 动态游戏内容

# 1. 角色生成
- 输入文本描述："a brave knight with blue armor"
- 选择像素尺寸：16x16 / 32x32 / 64x64
- 选择方向数：1 / 4 / 8
- 生成并下载 PNG 精灵表

# 2. 动画生成
- 选择已生成的角色
- 选择动画类型：Walk / Run / Attack / Idle
- 设置帧数：4 / 6 / 8
- 自动生成动画精灵表

# 3. 瓦片集生成
- 描述地形风格："dark dungeon stone tiles"
- 选择瓦片尺寸：16x16 / 32x32
- 自动生成含边角过渡的完整瓦片集
- 导出为引擎兼容格式

# 1. 准备训练数据
- 收集 10-20 张目标风格的参考图
- 确保参考图风格一致（同一画师或同一游戏的资产）
- 图片分辨率建议 512x512 以上
- 包含不同类型的资产（角色、道具、场景元素）

# 2. 创建自定义生成器
- 登录 Scenario.gg → 点击 "Create Generator"
- 上传参考图集
- 设置训练参数：
  - Training Steps: 1000-2000（默认即可）
  - Learning Rate: 自动
  - 训练时间：约 15-30 分钟

# 3. 使用训练好的生成器
- 选择自定义生成器
- 输入描述新资产的提示词
- 生成的资产将自动匹配训练风格
- 批量生成保持风格一致性

# 4. 批量生成工作流
- 准备资产清单（所有需要的角色、道具、UI 元素）
- 使用相同的生成器 + 统一的提示词模板
- 批量生成 → 人工筛选 → 后处理

# 角色精灵
[character description], game sprite, [trained style name],
transparent background, [view direction],
consistent with existing game assets

# 道具图标
[item description], game icon, [trained style name],
64x64, transparent background, clean design,
matching game UI style

# 瓦片集
[terrain description], tileset piece, [trained style name],
seamless edges, [tile size], top-down view,
matching existing tileset style

# sprite_cutter.py — 将 AI 生成的精灵表切割为单帧
from PIL import Image
import os
import json
 
def cut_sprite_sheet(
    image_path: str,
    frame_width: int,
    frame_height: int,
    output_dir: str,
    prefix: str = "frame"
) -> list[str]:
    """
    将精灵表切割为单独的帧图片
    
    Args:
        image_path: 精灵表图片路径
        frame_width: 每帧宽度（像素）
        frame_height: 每帧高度（像素）
        output_dir: 输出目录
        prefix: 输出文件名前缀
    
    Returns:
        生成的文件路径列表
    """
    img = Image.open(image_path)
    sheet_width, sheet_height = img.size
    
    cols = sheet_width // frame_width
    rows = sheet_height // frame_height
    
    os.makedirs(output_dir, exist_ok=True)
    output_files = []
    
    for row in range(rows):
        for col in range(cols):
            left = col * frame_width
            top = row * frame_height
            right = left + frame_width
            bottom = top + frame_height
            
            frame = img.crop((left, top, right, bottom))
            
            # 跳过完全透明的帧
            if frame.getextrema()[3][1] == 0:  # Alpha 通道最大值为 0
                continue
            
            filename = f"{prefix}_{row}_{col}.png"
            filepath = os.path.join(output_dir, filename)
            frame.save(filepath)
            output_files.append(filepath)
    
    print(f"切割完成：{len(output_files)} 帧")
    return output_files
 
 
def generate_godot_sprite_frames(
    frames_dir: str,
    animation_name: str,
    fps: float = 10.0
) -> str:
    """
    生成 Godot SpriteFrames 资源文件（.tres）
    """
    frames = sorted([
        f for f in os.listdir(frames_dir) 
        if f.endswith('.png')
    ])
    
    tres_content = '[gd_resource type="SpriteFrames"]\n\n'
    tres_content += '[resource]\n'
    tres_content += 'animations = [{\n'
    tres_content += f'"name": &"{animation_name}",\n'
    tres_content += f'"speed": {fps},\n'
    tres_content += '"loop": true,\n'
    tres_content += '"frames": [\n'
    
    for frame in frames:
        tres_content += '{\n'
        tres_content += f'"texture": preload("res://{frames_dir}/{frame}"),\n'
        tres_content += '"duration": 1.0\n'
        tres_content += '},\n'
    
    tres_content += ']\n}]\n'
    
    return tres_content
 
 
def generate_unity_animation(
    frames_dir: str,
    animation_name: str,
    fps: float = 12.0
) -> dict:
    """
    生成 Unity 动画配置（JSON 格式，需在 Unity 中导入）
    """
    frames = sorted([
        f for f in os.listdir(frames_dir) 
        if f.endswith('.png')
    ])
    
    config = {
        "animation_name": animation_name,
        "fps": fps,
        "loop": True,
        "frames": [
            {
                "sprite": f"{frames_dir}/{frame}",
                "duration": 1.0 / fps
            }
            for frame in frames
        ]
    }
    
    return config
 
 
# 使用示例
if __name__ == "__main__":
    # 切割 AI 生成的精灵表
    cut_sprite_sheet(
        image_path="ai_generated_knight.png",
        frame_width=32,
        frame_height=32,
        output_dir="assets/sprites/knight/walk",
        prefix="knight_walk"
    )

// SpriteImportSettings.cs — Unity 自动配置 AI 生成精灵的导入设置
using UnityEditor;
using UnityEngine;
 
public class SpriteImportSettings : AssetPostprocessor
{
    void OnPreprocessTexture()
    {
        // 仅处理 sprites 目录下的图片
        if (!assetPath.Contains("sprites/")) return;
 
        TextureImporter importer = (TextureImporter)assetImporter;
        
        // 基础设置
        importer.textureType = TextureImporterType.Sprite;
        importer.spriteImportMode = SpriteImportMode.Single;
        importer.alphaIsTransparency = true;
        
        // 像素画设置（无抗锯齿）
        if (assetPath.Contains("pixel"))
        {
            importer.filterMode = FilterMode.Point;
            importer.textureCompression = TextureImporterCompression.Uncompressed;
            importer.spritePixelsPerUnit = 16; // 像素画通常 16 PPU
        }
        else
        {
            importer.filterMode = FilterMode.Bilinear;
            importer.textureCompression = TextureImporterCompression.Compressed;
            importer.spritePixelsPerUnit = 100; // 高清资产 100 PPU
        }
        
        // 精灵表自动切割
        if (assetPath.Contains("sheet"))
        {
            importer.spriteImportMode = SpriteImportMode.Multiple;
            // 需要在导入后手动设置切割参数
            // 或使用 SpriteEditorDataProvider API 自动切割
        }
        
        // 移动端优化
        var platformSettings = new TextureImporterPlatformSettings
        {
            name = "Android",
            overridden = true,
            maxTextureSize = 1024,
            format = TextureImporterFormat.ASTC_6x6,
            compressionQuality = 50
        };
        importer.SetPlatformTextureSettings(platformSettings);
    }
}

# sprite_import_helper.gd — Godot 精灵导入辅助工具
# 作为 @tool 脚本在编辑器中运行
 
@tool
extends EditorScript
 
func _run() -> void:
    """批量配置 AI 生成精灵的导入设置"""
    var dir = DirAccess.open("res://assets/sprites/")
    if dir == null:
        push_error("无法打开精灵目录")
        return
    
    dir.list_dir_begin()
    var file_name = dir.get_next()
    
    while file_name != "":
        if file_name.ends_with(".png"):
            _configure_sprite_import(
                "res://assets/sprites/" + file_name)
        file_name = dir.get_next()
    
    dir.list_dir_end()
    print("精灵导入配置完成")
 
func _configure_sprite_import(path: String) -> void:
    """配置单个精灵的导入设置"""
    # Godot 使用 .import 文件管理导入设置
    # 对于像素画，需要在 Import 面板中设置：
    # - Filter: Off（关闭抗锯齿）
    # - Compress Mode: Lossless
    # - Mipmaps: Off
    
    var import_path = path + ".import"
    if FileAccess.file_exists(import_path):
        var config = ConfigFile.new()
        config.load(import_path)
        
        # 像素画设置
        if "pixel" in path:
            config.set_value("params", "process/fix_alpha_border", false)
            config.set_value("params", "process/premult_alpha", false)
            config.set_value("params", "texture/filter", 0)  # Nearest
        
        config.save(import_path)

# PixelLab / Leonardo.AI
pixel art [character type] character,
[size]x[size] sprite, [color palette] palette,
[direction: front / back / left / right] view,
[equipment/clothing description],
transparent background, clean pixel art,
[game genre] game style,
no anti-aliasing, sharp pixels

# 示例
pixel art female warrior character,
32x32 sprite, fantasy color palette,
front view, red armor with golden trim,
wielding a flaming sword,
transparent background, clean pixel art,
action RPG game style,
no anti-aliasing, sharp pixels

# Leonardo.AI / Scenario.gg
[terrain type] tileset for [game type],
[size]x[size] tiles, seamless edges,
top-down view, [art style],
includes: ground, walls, corners, transitions,
game-ready tileset, consistent lighting,
[color mood: warm / cool / dark / vibrant]

# 示例
dark dungeon stone tileset for roguelike game,
32x32 tiles, seamless edges,
top-down view, pixel art style,
includes: floor tiles, wall tiles, corner pieces,
door frames, torch holders, cracks and moss,
game-ready tileset, dim torch lighting,
dark and moody color palette

# Leonardo.AI / DALL-E 3
game UI [element type], [art style],
[color scheme] color scheme,
transparent background, game-ready asset,
clean vector style, [size/aspect ratio]

# 示例 — 血条
game UI health bar, fantasy RPG style,
red and gold color scheme, ornate frame,
transparent background, game-ready asset,
horizontal bar with decorative end caps,
clean design, 256x32 pixels

# 示例 — 道具图标集
game item icons set, pixel art style,
fantasy RPG items: sword, shield, potion,
scroll, key, gem, ring, helmet,
64x64 each, transparent background,
consistent style, grid layout

# Leonardo.AI / Midjourney
[character description] sprite sheet,
[animation type: walk cycle / attack / idle],
[frame count] frames, [direction] facing,
[art style], transparent background,
evenly spaced frames, consistent proportions,
game animation sprite sheet

# 示例
knight character walk cycle sprite sheet,
8 frames, side view facing right,
pixel art 32x32 style, transparent background,
evenly spaced frames, consistent proportions,
smooth walking animation, blue armor

// Unity — AI 生成精灵的自动化集成管线
// AISpritePipeline.cs
 
using UnityEngine;
using UnityEditor;
using System.IO;
 
public static class AISpritePipeline
{
    /// <summary>
    /// 将 AI 生成的精灵表自动切割并创建动画
    /// </summary>
    [MenuItem("Tools/AI Sprites/Auto Slice Sprite Sheet")]
    public static void AutoSliceSpriteSheet()
    {
        // 获取选中的纹理
        var texture = Selection.activeObject as Texture2D;
        if (texture == null)
        {
            Debug.LogError("请先选中一个精灵表纹理");
            return;
        }
 
        string path = AssetDatabase.GetAssetPath(texture);
        var importer = AssetImporter.GetAtPath(path) as TextureImporter;
        
        if (importer == null) return;
 
        // 设置为多精灵模式
        importer.spriteImportMode = SpriteImportMode.Multiple;
        importer.filterMode = FilterMode.Point; // 像素画
        
        // 自动切割（假设均匀网格）
        int frameSize = 32; // 可配置
        int cols = texture.width / frameSize;
        int rows = texture.height / frameSize;
        
        var spriteSheet = new SpriteMetaData[cols * rows];
        
        for (int y = 0; y < rows; y++)
        {
            for (int x = 0; x < cols; x++)
            {
                int index = y * cols + x;
                spriteSheet[index] = new SpriteMetaData
                {
                    name = $"{texture.name}_{index}",
                    rect = new Rect(
                        x * frameSize,
                        (rows - 1 - y) * frameSize, // Unity Y 轴翻转
                        frameSize,
                        frameSize),
                    alignment = (int)SpriteAlignment.Center,
                    pivot = new Vector2(0.5f, 0.5f)
                };
            }
        }
        
        importer.spritesheet = spriteSheet;
        EditorUtility.SetDirty(importer);
        importer.SaveAndReimport();
        
        Debug.Log($"精灵表切割完成：{cols}x{rows} = {cols * rows} 帧");
    }
}

# godot_sprite_setup.gd — Godot AI 精灵自动化设置
# 在编辑器中作为工具脚本运行
 
@tool
extends Node
 
## 从 AI 生成的精灵表创建 AnimatedSprite2D
static func create_animated_sprite(
    sprite_sheet_path: String,
    frame_size: Vector2i,
    animations: Dictionary  # {"walk": {"row": 0, "frames": 8, "fps": 10}}
) -> AnimatedSprite2D:
    var sprite = AnimatedSprite2D.new()
    var frames = SpriteFrames.new()
    
    var texture: Texture2D = load(sprite_sheet_path)
    if texture == null:
        push_error("无法加载精灵表: " + sprite_sheet_path)
        return null
    
    var sheet_size = Vector2i(
        texture.get_width(), texture.get_height())
    var cols: int = sheet_size.x / frame_size.x
    
    for anim_name: String in animations:
        var anim_data: Dictionary = animations[anim_name]
        var row: int = anim_data.get("row", 0)
        var frame_count: int = anim_data.get("frames", 4)
        var fps: float = anim_data.get("fps", 10.0)
        var loop: bool = anim_data.get("loop", true)
        
        frames.add_animation(anim_name)
        frames.set_animation_speed(anim_name, fps)
        frames.set_animation_loop(anim_name, loop)
        
        for i in range(frame_count):
            # 创建 AtlasTexture 从精灵表中裁剪帧
            var atlas = AtlasTexture.new()
            atlas.atlas = texture
            atlas.region = Rect2(
                i * frame_size.x,
                row * frame_size.y,
                frame_size.x,
                frame_size.y
            )
            frames.add_frame(anim_name, atlas)
    
    # 删除默认动画
    if frames.has_animation("default"):
        frames.remove_animation("default")
    
    sprite.sprite_frames = frames
    return sprite
 
# 使用示例
# var animated_sprite = create_animated_sprite(
#     "res://assets/sprites/knight_sheet.png",
#     Vector2i(32, 32),
#     {
#         "idle": {"row": 0, "frames": 4, "fps": 8, "loop": true},
#         "walk": {"row": 1, "frames": 8, "fps": 12, "loop": true},
#         "attack": {"row": 2, "frames": 6, "fps": 15, "loop": false},
#         "hurt": {"row": 3, "frames": 3, "fps": 10, "loop": false},
#         "death": {"row": 4, "frames": 5, "fps": 8, "loop": false}
#     }
# )

3D 模型资产
├── 角色模型
│   ├── 玩家角色（高精度，含骨骼绑定）
│   ├── NPC（中精度）
│   ├── 敌人/怪物
│   └── 群众/背景角色（低精度）
├── 环境模型
│   ├── 建筑物（房屋、城堡、商店）
│   ├── 自然物（树木、岩石、植被）
│   ├── 地形装饰（路灯、栅栏、箱子）
│   └── 室内家具（桌椅、书架、床）
├── 道具模型
│   ├── 武器（剑、枪、法杖）
│   ├── 防具（盔甲、盾牌、头盔）
│   ├── 消耗品（药水瓶、食物）
│   └── 交互物品（宝箱、开关、门）
├── 载具模型
│   ├── 车辆（汽车、马车）
│   ├── 飞行器
│   └── 船只
└── 特效模型
    ├── 粒子网格
    ├── 投射物
    └── 环境特效（水面、熔岩）

# Tripo AI 工作流（推荐用于快速原型）

1. 准备概念图
   - 最佳：正面视图 + 干净背景
   - 可用：任意角度，但正面效果最好
   - 分辨率：512x512 以上
   - 背景：纯色或透明最佳

2. 上传到 Tripo AI
   - 选择 "Image to 3D"
   - 上传概念图
   - 等待生成（通常 10-30 秒）

3. 预览和调整
   - 在 3D 预览器中检查模型
   - 检查几何体完整性
   - 检查纹理映射质量

4. 导出设置
   - 格式选择：
     - FBX（Unity 推荐）
     - GLTF/GLB（Godot 推荐，Web 通用）
     - OBJ（通用，但不含动画）
   - 纹理导出：PBR 材质贴图（Albedo, Normal, Roughness）
   - 使用 Smart Retopology 优化拓扑

5. 后处理（在 Blender 中）
   - 检查并修复拓扑问题
   - 优化 UV 展开
   - 创建 LOD 层级
   - 调整材质参数

# Meshy 工作流（推荐用于高质量资产）

1. 文本转 3D（Text to 3D）
   - 输入详细的文本描述
   - 选择风格预设：
     - Realistic（写实）
     - Cartoon（卡通）
     - Low Poly（低多边形）
     - Voxel（体素）
   - 选择拓扑类型：
     - Quad（四边面，适合动画）
     - Triangle（三角面，适合静态）

2. 图片转 3D（Image to 3D）
   - 上传概念图
   - AI 自动推断 3D 形状
   - 支持多视角输入（提升质量）

3. AI 纹理重绘（Retexture）
   - 保持现有 3D 形状
   - 用 AI 重新生成纹理
   - 支持 PBR 材质贴图
   - 可以改变视觉风格而不改变几何体

4. 导出
   - FBX / GLTF / OBJ / USDZ
   - 含 PBR 纹理贴图
   - 可选自动减面

# 角色模型
a [character type] character, [art style],
[clothing/armor description],
[pose: T-pose / A-pose / action pose],
[detail level: high detail / medium detail / low poly],
game-ready 3D model

# 示例
a medieval knight character, stylized cartoon style,
silver plate armor with blue cape and golden trim,
T-pose for rigging, medium detail,
game-ready 3D model, clean topology

# 道具模型
a [item type], [art style],
[material description],
[size reference],
game prop, clean geometry

# 示例
a magical crystal sword, fantasy RPG style,
glowing blue blade with ornate golden hilt,
one-handed weapon size,
game prop, clean geometry, PBR materials

# 环境模型
a [structure type], [art style],
[material and color description],
[scale reference],
environment asset, optimized for games

# 示例
a medieval blacksmith shop, low poly stylized,
wooden walls with stone foundation, smoking chimney,
small building scale (about 5 meters tall),
environment asset, optimized for games

# Meshy 支持更详细的描述
Create a [object type] with the following details:
- Style: [realistic / cartoon / low poly / voxel]
- Material: [wood / metal / stone / fabric / crystal]
- Color: [primary color] with [accent color] details
- Size: [small prop / medium furniture / large building]
- Detail level: [high / medium / low]
- Special features: [glowing parts / transparent elements / animated parts]

# 示例 — 宝箱
Create a treasure chest with the following details:
- Style: cartoon fantasy
- Material: dark wood with iron bands and golden lock
- Color: brown wood with gold and iron gray accents
- Size: small prop (about 0.5 meters)
- Detail level: medium
- Special features: slightly open lid with golden glow inside

AI 生成 3D 模型后处理管线
│
├── 1. 拓扑检查与清理
│   ├── 检查面数（目标：移动端 <5K 面，PC <20K 面）
│   ├── 修复非流形几何体（Non-manifold geometry）
│   ├── 移除内部面和重叠面
│   ├── 合并距离过近的顶点
│   └── 确保法线方向一致
│
├── 2. 重拓扑（Retopology）
│   ├── 使用 Blender 的 Instant Meshes 或 QuadriFlow
│   ├── 角色模型：确保关节处有足够的边环（Edge Loop）
│   ├── 静态模型：优化为均匀的四边面
│   └── 目标面数根据平台和用途确定
│
├── 3. UV 展开优化
│   ├── 检查 AI 生成的 UV 是否合理
│   ├── 重新展开（如需要）：Smart UV Project 或手动
│   ├── 最大化 UV 空间利用率
│   ├── 确保接缝（Seam）在不显眼的位置
│   └── 打包多个模型到同一 UV 空间（Atlas）
│
├── 4. 材质和纹理优化
│   ├── 检查 PBR 贴图完整性（Albedo, Normal, Roughness, Metallic）
│   ├── 调整纹理分辨率（移动端 512x512，PC 1024x1024-2048x2048）
│   ├── 烘焙高模细节到低模法线贴图
│   ├── 创建 AO（环境光遮蔽）贴图
│   └── 压缩纹理格式（ASTC/ETC2 移动端，BC7 PC）
│
├── 5. LOD 生成
│   ├── LOD0：原始模型（近距离）
│   ├── LOD1：50% 面数（中距离）
│   ├── LOD2：25% 面数（远距离）
│   ├── LOD3：10% 面数或 Billboard（极远）
│   └── 使用 Blender Decimate 或引擎内置 LOD 工具
│
├── 6. 碰撞体生成
│   ├── 简化碰撞网格（Convex Hull 或基础形状组合）
│   ├── 角色：胶囊体或简化网格
│   ├── 环境：凸包或三角网格碰撞
│   └── 道具：基础形状（Box, Sphere, Capsule）
│
└── 7. 导出与引擎导入
    ├── 选择正确的导出格式和设置
    ├── 检查缩放和坐标系（Y-up vs Z-up）
    ├── 验证材质在引擎中的显示
    └── 配置引擎导入设置

# blender_post_process.py — Blender 3D 模型后处理自动化
# 在 Blender 中运行：Edit → Preferences → File Paths → Scripts
 
import bpy
import bmesh
 
def auto_cleanup(obj_name: str):
    """自动清理 AI 生成的 3D 模型"""
    obj = bpy.data.objects.get(obj_name)
    if obj is None or obj.type != 'MESH':
        print(f"对象 {obj_name} 不存在或不是网格")
        return
    
    # 选择对象
    bpy.context.view_layer.objects.active = obj
    obj.select_set(True)
    
    # 进入编辑模式
    bpy.ops.object.mode_set(mode='EDIT')
    
    # 1. 合并距离过近的顶点
    bpy.ops.mesh.select_all(action='SELECT')
    bpy.ops.mesh.remove_doubles(threshold=0.001)
    
    # 2. 修复法线
    bpy.ops.mesh.normals_make_consistent(inside=False)
    
    # 3. 删除松散顶点和边
    bpy.ops.mesh.select_all(action='SELECT')
    bpy.ops.mesh.delete_loose(
        use_verts=True, use_edges=True, use_faces=False)
    
    # 4. 填充非流形边界
    bpy.ops.mesh.select_non_manifold()
    # 注意：自动填充可能不总是正确，需要人工检查
    
    # 返回对象模式
    bpy.ops.object.mode_set(mode='OBJECT')
    
    print(f"清理完成：{obj_name}")
    print(f"  顶点数：{len(obj.data.vertices)}")
    print(f"  面数：{len(obj.data.polygons)}")
 
 
def generate_lods(
    obj_name: str, 
    ratios: list = [0.5, 0.25, 0.1]
):
    """为模型生成 LOD 层级"""
    obj = bpy.data.objects.get(obj_name)
    if obj is None:
        return
    
    original_faces = len(obj.data.polygons)
    
    for i, ratio in enumerate(ratios):
        # 复制对象
        lod_obj = obj.copy()
        lod_obj.data = obj.data.copy()
        lod_obj.name = f"{obj_name}_LOD{i + 1}"
        bpy.context.collection.objects.link(lod_obj)
        
        # 应用 Decimate 修改器
        modifier = lod_obj.modifiers.new(
            name="Decimate", type='DECIMATE')
        modifier.ratio = ratio
        
        # 应用修改器
        bpy.context.view_layer.objects.active = lod_obj
        bpy.ops.object.modifier_apply(modifier="Decimate")
        
        lod_faces = len(lod_obj.data.polygons)
        print(f"LOD{i + 1}：{lod_faces} 面 "
              f"（原始的 {lod_faces/original_faces*100:.1f}%）")
 
 
def export_for_engine(
    obj_name: str,
    output_path: str,
    engine: str = "godot"  # "godot" | "unity" | "unreal"
):
    """导出模型为引擎兼容格式"""
    obj = bpy.data.objects.get(obj_name)
    if obj is None:
        return
    
    # 选择对象
    bpy.ops.object.select_all(action='DESELECT')
    obj.select_set(True)
    bpy.context.view_layer.objects.active = obj
    
    if engine == "godot":
        # Godot 推荐 GLTF 格式
        bpy.ops.export_scene.gltf(
            filepath=output_path + ".glb",
            use_selection=True,
            export_format='GLB',
            export_apply=True,
            export_texcoords=True,
            export_normals=True,
            export_materials='EXPORT'
        )
    elif engine == "unity":
        # Unity 推荐 FBX 格式
        bpy.ops.export_scene.fbx(
            filepath=output_path + ".fbx",
            use_selection=True,
            apply_scale_options='FBX_SCALE_ALL',
            axis_forward='-Z',
            axis_up='Y',
            use_mesh_modifiers=True,
            mesh_smooth_type='FACE'
        )
    elif engine == "unreal":
        # Unreal 推荐 FBX 格式
        bpy.ops.export_scene.fbx(
            filepath=output_path + ".fbx",
            use_selection=True,
            apply_scale_options='FBX_SCALE_ALL',
            axis_forward='X',
            axis_up='Z',
            use_mesh_modifiers=True
        )
    
    print(f"导出完成：{output_path}")
 
 
# 使用示例
# auto_cleanup("AI_Generated_Model")
# generate_lods("AI_Generated_Model", [0.5, 0.25, 0.1])
# export_for_engine("AI_Generated_Model", "/output/model", "godot")

# Tripo AI / Meshy — 角色模型
a [character archetype] character for [game genre] game,
[art style: realistic / stylized / low poly / cartoon],
[clothing/armor description with materials],
[pose: T-pose for rigging / A-pose / action pose],
[body type and proportions],
game-ready 3D model, clean topology,
PBR materials, [polygon budget]

# 示例 — 卡通风格战士
a barbarian warrior character for action RPG game,
stylized cartoon style with exaggerated proportions,
fur-lined leather armor with iron shoulder pads,
large battle axe strapped to back,
T-pose for rigging, muscular build,
game-ready 3D model, clean quad topology,
PBR materials, under 10000 polygons

# Tripo AI / Sloyd — 环境道具
a [object type] for [game setting],
[art style], [material description],
[size/scale reference],
game environment prop, optimized geometry,
[texture detail level]

# 示例 — 中世纪铁匠铺道具
a medieval anvil on wooden stump,
stylized fantasy style, dark iron with hammer marks,
waist-height scale, game environment prop,
optimized geometry under 2000 polygons,
hand-painted texture style

# Meshy / Tripo AI — 武器装备
a [weapon/equipment type], [fantasy/sci-fi/realistic] style,
[material details: blade material, handle material, decorations],
[size: one-handed / two-handed / small accessory],
game weapon prop, clean geometry,
PBR materials with [special effects: glow / runes / enchantment]

# 示例 — 魔法法杖
a wizard's staff with crystal orb on top,
high fantasy style, dark wood shaft with silver vine wrapping,
glowing purple crystal orb emitting magical particles,
two-handed weapon size, game weapon prop,
clean geometry under 3000 polygons,
PBR materials with emissive crystal

// Unity — AI 生成 3D 模型的自动导入配置
// ModelImportSettings.cs
 
using UnityEditor;
using UnityEngine;
 
public class AIModelImportSettings : AssetPostprocessor
{
    void OnPreprocessModel()
    {
        // 仅处理 AI 生成模型目录
        if (!assetPath.Contains("Models/AI_Generated/")) return;
 
        ModelImporter importer = (ModelImporter)assetImporter;
 
        // 基础设置
        importer.globalScale = 1.0f;
        importer.useFileUnits = true;
        importer.importBlendShapes = false; // AI 模型通常无 BlendShape
        importer.importVisibility = false;
        importer.importCameras = false;
        importer.importLights = false;
 
        // 网格设置
        importer.meshCompression = ModelImporterMeshCompression.Medium;
        importer.isReadable = false; // 节省内存
        importer.optimizeMeshPolygons = true;
        importer.optimizeMeshVertices = true;
        importer.addCollider = false; // 手动添加碰撞体
 
        // 法线和切线
        importer.importNormals = ModelImporterNormals.Import;
        importer.importTangents = ModelImporterTangents.CalculateMikk;
 
        // 材质设置
        importer.materialImportMode = ModelImporterMaterialImportMode.ImportViaMaterialDescription;
        importer.materialLocation = ModelImporterMaterialLocation.InPrefab;
 
        // 动画设置（AI 模型通常无动画）
        importer.importAnimation = false;
 
        // LOD 设置（如果模型包含 LOD 组）
        if (assetPath.Contains("_LOD"))
        {
            importer.importAnimation = false;
            importer.addCollider = false;
        }
    }
 
    void OnPostprocessModel(GameObject gameObject)
    {
        // 自动设置材质
        var renderers = gameObject.GetComponentsInChildren<Renderer>();
        foreach (var renderer in renderers)
        {
            foreach (var material in renderer.sharedMaterials)
            {
                if (material == null) continue;
 
                // 确保使用 URP Lit Shader
                material.shader = Shader.Find(
                    "Universal Render Pipeline/Lit");
            }
        }
    }
}

# godot_3d_import.gd — Godot AI 3D 模型导入辅助
# 用于配置 AI 生成的 GLTF/GLB 模型
 
@tool
extends EditorScript
 
func _run() -> void:
    """配置 AI 生成 3D 模型的导入设置"""
    # Godot 4.4 使用 .import 文件管理 3D 模型导入
    # GLTF 模型导入时的推荐设置：
    
    print("=== AI 3D 模型导入指南 ===")
    print("")
    print("1. 将 .glb/.gltf 文件放入 res://assets/models/")
    print("2. 在 Import 面板中配置：")
    print("   - Root Type: StaticBody3D（静态）或 CharacterBody3D（角色）")
    print("   - Root Name: 使用有意义的名称")
    print("   - Generate Tangents: 启用（法线贴图需要）")
    print("   - Generate LODs: 启用（自动 LOD）")
    print("   - LOD Min Distance: 根据模型大小调整")
    print("   - Create Shadow Meshes: 启用（阴影优化）")
    print("")
    print("3. 材质配置：")
    print("   - 检查 PBR 贴图是否正确映射")
    print("   - Albedo → Base Color")
    print("   - Normal → Normal Map")
    print("   - Roughness → Roughness")
    print("   - Metallic → Metallic")
    print("")
    print("4. 碰撞体：")
    print("   - 静态模型：Mesh → Create Trimesh Static Body")
    print("   - 动态模型：手动添加简化碰撞形状")
    print("   - 道具：使用 ConvexPolygonShape3D")
 
 
## 3D 模型场景设置辅助函数
static func setup_ai_model_scene(
    model_path: String,
    model_type: String = "static"  # "static" | "character" | "prop"
) -> Node3D:
    """
    将 AI 生成的 3D 模型设置为游戏可用的场景
    """
    var packed_scene: PackedScene = load(model_path)
    if packed_scene == null:
        push_error("无法加载模型: " + model_path)
        return null
    
    var model: Node3D = packed_scene.instantiate()
    
    match model_type:
        "static":
            # 静态环境模型：添加碰撞体
            var static_body = StaticBody3D.new()
            static_body.name = "StaticBody"
            
            # 从网格生成碰撞形状
            for child in model.get_children():
                if child is MeshInstance3D:
                    var mesh_instance: MeshInstance3D = child
                    mesh_instance.create_trimesh_collision()
            
            return model
        
        "prop":
            # 可交互道具：添加 RigidBody3D
            var rigid_body = RigidBody3D.new()
            rigid_body.name = model.name + "_RigidBody"
            
            # 使用凸包碰撞
            for child in model.get_children():
                if child is MeshInstance3D:
                    var mesh_instance: MeshInstance3D = child
                    mesh_instance.create_convex_collision()
            
            rigid_body.add_child(model)
            return rigid_body
        
        "character":
            # 角色模型：添加 CharacterBody3D 框架
            var character = CharacterBody3D.new()
            character.name = model.name + "_Character"
            
            # 添加胶囊碰撞体
            var collision = CollisionShape3D.new()
            var capsule = CapsuleShape3D.new()
            capsule.radius = 0.4
            capsule.height = 1.8
            collision.shape = capsule
            collision.position.y = 0.9
            
            character.add_child(model)
            character.add_child(collision)
            return character
    
    return model

游戏音效
├── 角色音效
│   ├── 脚步声（不同地面材质：石头、木头、草地、金属）
│   ├── 攻击音效（挥剑、射箭、施法、拳击）
│   ├── 受伤音效（被击中、倒地、死亡）
│   ├── 角色语音（呼喊、喘息、欢呼）
│   └── 装备音效（穿戴盔甲、拔剑、开弓）
├── 环境音效
│   ├── 自然环境（风声、雨声、雷声、鸟鸣、虫鸣）
│   ├── 室内环境（壁炉、钟摆、水滴）
│   ├── 城市环境（人群、马车、铁匠铺）
│   └── 地牢环境（回声、铁链、怪物低吼）
├── UI 音效
│   ├── 按钮点击、悬停
│   ├── 菜单打开/关闭
│   ├── 物品拾取/丢弃
│   ├── 任务完成/升级
│   └── 错误/警告提示
├── 战斗音效
│   ├── 武器碰撞（金属对金属、金属对木头）
│   ├── 魔法效果（火球、冰冻、治疗、传送）
│   ├── 爆炸（小型、中型、大型）
│   └── 护盾/格挡
└── 特殊音效
    ├── 传送门/空间扭曲
    ├── 时间减速/加速
    ├── 隐身/显形
    └── Boss 登场/阶段转换

# 1. 登录 ElevenLabs → Sound Effects
# 2. 输入音效描述（越详细越好）
# 3. 设置参数：
#    - Duration: 根据需要（UI 音效 0.5-2s，环境音 5-20s）
#    - Quality: High（48kHz）
#    - Loop: 启用（环境音效）
# 4. 生成并试听
# 5. 下载 WAV/MP3 格式

# 角色脚步声
footsteps on [surface: stone / wood / grass / metal / gravel],
[speed: slow walking / normal walking / running / sprinting],
[weight: light / medium / heavy],
[environment: indoor / outdoor / cave / castle],
[number] steps, game sound effect

# 示例
footsteps on stone floor, normal walking speed,
heavy armored boots, indoor castle hallway,
8 steps with slight echo, game sound effect

# 武器音效
[weapon type] [action: swing / hit / draw / sheathe],
[material: steel / wood / crystal / bone],
[impact surface: metal / flesh / stone / wood],
[intensity: light / medium / heavy],
sharp and impactful, game combat sound effect

# 示例
steel sword slash through air followed by metal shield impact,
heavy strike, sharp metallic ring with slight reverb,
game combat sound effect, punchy and satisfying

# 魔法音效
[magic type: fire / ice / lightning / healing / dark / arcane] spell,
[phase: charging / casting / impact / dissipating],
[intensity: subtle / moderate / powerful / devastating],
[mood: mystical / aggressive / serene / ominous],
fantasy game magic sound effect

# 示例
ice spell casting, crystalline formation sound,
crackling frost spreading outward,
moderate intensity, cold and sharp,
fantasy RPG game magic sound effect, 3 seconds

# UI 音效
[UI action: button click / menu open / item pickup / 
level up / error / notification / achievement],
[style: clean / retro / fantasy / sci-fi / minimal],
[mood: positive / neutral / negative / exciting],
short and responsive, game UI sound effect

# 示例
item pickup sound, fantasy RPG style,
bright magical chime with sparkle,
positive and rewarding, 0.5 seconds,
game UI sound effect

# 环境音效
[environment type] ambient sound,
[specific elements: wind, water, fire, creatures, machinery],
[mood: peaceful / tense / mysterious / dangerous],
[time: day / night / dawn / dusk],
seamless loop, game ambient sound effect

# 示例
dark dungeon ambient sound,
distant water dripping, occasional chain rattling,
faint monster growls in the distance,
tense and mysterious mood,
seamless loop, 15 seconds, game ambient sound effect

# Stable Audio 工作流

1. 访问 stableaudio.com 或使用 API
2. 输入音效描述
3. 设置参数：
   - Duration: 0.5s - 47s
   - Steps: 100-200（质量 vs 速度）
   - CFG Scale: 7-12（提示词遵循度）
4. 生成多个变体，选择最佳
5. 下载 WAV 格式

# Stable Audio 提示词技巧
- 使用具体的声音描述词汇
- 指定音频特征：频率范围、动态范围
- 添加 "game sound effect" 或 "game audio" 标签
- 指定时长和循环需求

# audio_processor.py — 游戏音效后处理工具
# 依赖：pip install pydub numpy
 
from pydub import AudioSegment
from pydub.effects import normalize, compress_dynamic_range
import numpy as np
import os
 
def process_game_sfx(
    input_path: str,
    output_path: str,
    target_sample_rate: int = 44100,
    target_format: str = "wav",
    normalize_audio: bool = True,
    trim_silence: bool = True,
    fade_in_ms: int = 0,
    fade_out_ms: int = 10,
    make_loop: bool = False
) -> None:
    """
    处理 AI 生成的音效，使其适合游戏使用
    
    Args:
        input_path: 输入音频文件路径
        output_path: 输出音频文件路径
        target_sample_rate: 目标采样率
        target_format: 输出格式（wav/ogg/mp3）
        normalize_audio: 是否标准化音量
        trim_silence: 是否裁剪首尾静音
        fade_in_ms: 淡入时长（毫秒）
        fade_out_ms: 淡出时长（毫秒）
        make_loop: 是否处理为无缝循环
    """
    # 加载音频
    audio = AudioSegment.from_file(input_path)
    
    # 转换采样率
    audio = audio.set_frame_rate(target_sample_rate)
    
    # 转换为单声道（游戏音效通常使用单声道以节省内存）
    # 环境音效保持立体声
    if not make_loop:
        audio = audio.set_channels(1)
    
    # 裁剪首尾静音
    if trim_silence:
        audio = _trim_silence(audio, silence_thresh=-50)
    
    # 标准化音量
    if normalize_audio:
        audio = normalize(audio)
    
    # 动态范围压缩（使音效更"有力"）
    audio = compress_dynamic_range(
        audio, threshold=-20.0, ratio=4.0, attack=5.0, release=50.0)
    
    # 淡入淡出
    if fade_in_ms > 0:
        audio = audio.fade_in(fade_in_ms)
    if fade_out_ms > 0:
        audio = audio.fade_out(fade_out_ms)
    
    # 无缝循环处理
    if make_loop:
        audio = _make_seamless_loop(audio)
    
    # 导出
    os.makedirs(os.path.dirname(output_path), exist_ok=True)
    audio.export(output_path, format=target_format)
    
    # 输出信息
    duration = len(audio) / 1000.0
    file_size = os.path.getsize(output_path) / 1024
    print(f"处理完成: {output_path}")
    print(f"  时长: {duration:.2f}s | 大小: {file_size:.1f}KB | "
          f"采样率: {target_sample_rate}Hz")
 
 
def _trim_silence(
    audio: AudioSegment, 
    silence_thresh: float = -50,
    chunk_size: int = 10
) -> AudioSegment:
    """裁剪音频首尾的静音部分"""
    # 找到第一个非静音位置
    start = 0
    for i in range(0, len(audio), chunk_size):
        if audio[i:i+chunk_size].dBFS > silence_thresh:
            start = max(0, i - chunk_size)
            break
    
    # 找到最后一个非静音位置
    end = len(audio)
    for i in range(len(audio), 0, -chunk_size):
        if audio[i-chunk_size:i].dBFS > silence_thresh:
            end = min(len(audio), i + chunk_size)
            break
    
    return audio[start:end]
 
 
def _make_seamless_loop(
    audio: AudioSegment, 
    crossfade_ms: int = 100
) -> AudioSegment:
    """将音频处理为无缝循环"""
    if len(audio) < crossfade_ms * 2:
        return audio
    
    # 交叉淡化首尾
    end_part = audio[-crossfade_ms:]
    start_part = audio[:crossfade_ms]
    
    # 简单的交叉淡化
    middle = audio[crossfade_ms:-crossfade_ms]
    result = end_part.fade_in(crossfade_ms)
    result = result + middle
    result = result + start_part.fade_out(crossfade_ms)
    
    return result
 
 
def batch_process_sfx(
    input_dir: str,
    output_dir: str,
    config: dict
) -> None:
    """批量处理音效文件"""
    supported_formats = {'.wav', '.mp3', '.ogg', '.flac', '.m4a'}
    
    for filename in os.listdir(input_dir):
        ext = os.path.splitext(filename)[1].lower()
        if ext not in supported_formats:
            continue
        
        input_path = os.path.join(input_dir, filename)
        output_name = os.path.splitext(filename)[0] + "." + config.get(
            "target_format", "wav")
        output_path = os.path.join(output_dir, output_name)
        
        try:
            process_game_sfx(input_path, output_path, **config)
        except Exception as e:
            print(f"处理失败: {filename} - {e}")
 
 
# 使用示例
if __name__ == "__main__":
    # 处理 UI 音效（短、单声道、高压缩）
    batch_process_sfx(
        input_dir="ai_generated/ui_sfx/",
        output_dir="game/assets/audio/sfx/ui/",
        config={
            "target_sample_rate": 22050,  # UI 音效可用较低采样率
            "target_format": "ogg",
            "normalize_audio": True,
            "trim_silence": True,
            "fade_out_ms": 5,
            "make_loop": False
        }
    )
    
    # 处理环境音效（长、立体声、循环）
    batch_process_sfx(
        input_dir="ai_generated/ambient/",
        output_dir="game/assets/audio/ambient/",
        config={
            "target_sample_rate": 44100,
            "target_format": "ogg",
            "normalize_audio": True,
            "trim_silence": False,
            "fade_in_ms": 500,
            "fade_out_ms": 500,
            "make_loop": True
        }
    )

// Unity — AI 生成音效的管理系统
// GameAudioManager.cs
 
using UnityEngine;
using System.Collections.Generic;
 
/// <summary>
/// 游戏音效管理器 — 管理 AI 生成的音效资产
/// 使用对象池避免频繁创建/销毁 AudioSource
/// </summary>
public class GameAudioManager : MonoBehaviour
{
    public static GameAudioManager Instance { get; private set; }
 
    [Header("音效配置")]
    [SerializeField] private AudioClip[] _uiSounds;
    [SerializeField] private AudioClip[] _combatSounds;
    [SerializeField] private AudioClip[] _ambientSounds;
    [SerializeField] private AudioClip[] _footstepSounds;
 
    [Header("音频源池")]
    [SerializeField] private int _poolSize = 16;
    [SerializeField] private GameObject _audioSourcePrefab;
 
    private Queue<AudioSource> _audioPool = new();
    private List<AudioSource> _activeAudio = new();
    private AudioSource _ambientSource;
 
    private void Awake()
    {
        if (Instance != null)
        {
            Destroy(gameObject);
            return;
        }
        Instance = this;
        DontDestroyOnLoad(gameObject);
        InitializePool();
    }
 
    private void InitializePool()
    {
        for (int i = 0; i < _poolSize; i++)
        {
            var go = new GameObject($"AudioSource_{i}");
            go.transform.SetParent(transform);
            var source = go.AddComponent<AudioSource>();
            source.playOnAwake = false;
            go.SetActive(false);
            _audioPool.Enqueue(source);
        }
 
        // 专用环境音源
        var ambientGo = new GameObject("AmbientSource");
        ambientGo.transform.SetParent(transform);
        _ambientSource = ambientGo.AddComponent<AudioSource>();
        _ambientSource.loop = true;
        _ambientSource.playOnAwake = false;
    }
 
    /// <summary>
    /// 播放一次性音效（UI、战斗等）
    /// </summary>
    public void PlaySFX(
        AudioClip clip,
        Vector3 position = default,
        float volume = 1f,
        float pitch = 1f,
        float spatialBlend = 0f)
    {
        if (clip == null) return;
 
        var source = GetPooledSource();
        if (source == null) return;
 
        source.transform.position = position;
        source.clip = clip;
        source.volume = volume;
        source.pitch = pitch;
        source.spatialBlend = spatialBlend;
        source.Play();
 
        StartCoroutine(ReturnToPool(source, clip.length / pitch));
    }
 
    /// <summary>
    /// 播放随机变体音效（脚步声等需要变化的音效）
    /// </summary>
    public void PlayRandomSFX(
        AudioClip[] clips,
        Vector3 position = default,
        float volume = 1f,
        float pitchVariation = 0.1f)
    {
        if (clips == null || clips.Length == 0) return;
 
        var clip = clips[Random.Range(0, clips.Length)];
        float pitch = 1f + Random.Range(-pitchVariation, pitchVariation);
        PlaySFX(clip, position, volume, pitch);
    }
 
    /// <summary>
    /// 切换环境音效（带淡入淡出）
    /// </summary>
    public void SetAmbient(AudioClip clip, float fadeTime = 1f)
    {
        StartCoroutine(CrossfadeAmbient(clip, fadeTime));
    }
 
    private System.Collections.IEnumerator CrossfadeAmbient(
        AudioClip newClip, float fadeTime)
    {
        // 淡出当前环境音
        float startVolume = _ambientSource.volume;
        for (float t = 0; t < fadeTime; t += Time.deltaTime)
        {
            _ambientSource.volume = Mathf.Lerp(
                startVolume, 0, t / fadeTime);
            yield return null;
        }
 
        // 切换并淡入
        _ambientSource.clip = newClip;
        _ambientSource.Play();
        for (float t = 0; t < fadeTime; t += Time.deltaTime)
        {
            _ambientSource.volume = Mathf.Lerp(
                0, startVolume, t / fadeTime);
            yield return null;
        }
    }
 
    private AudioSource GetPooledSource()
    {
        if (_audioPool.Count == 0) return null;
        var source = _audioPool.Dequeue();
        source.gameObject.SetActive(true);
        return source;
    }
 
    private System.Collections.IEnumerator ReturnToPool(
        AudioSource source, float delay)
    {
        yield return new WaitForSeconds(delay + 0.1f);
        source.Stop();
        source.clip = null;
        source.gameObject.SetActive(false);
        _audioPool.Enqueue(source);
    }
}

# audio_manager.gd — Godot AI 音效管理器
# 注册为 Autoload: AudioManager
 
class_name AudioManagerClass
extends Node
 
## 音效音量（0.0 - 1.0）
@export var sfx_volume: float = 1.0
## 环境音量
@export var ambient_volume: float = 0.7
## 音效池大小
@export var pool_size: int = 16
 
# 音效播放器池
var _sfx_pool: Array[AudioStreamPlayer] = []
var _sfx_pool_index: int = 0
 
# 2D 音效播放器池（空间音效）
var _sfx_2d_pool: Array[AudioStreamPlayer2D] = []
var _sfx_2d_pool_index: int = 0
 
# 环境音播放器
var _ambient_player: AudioStreamPlayer
var _ambient_tween: Tween
 
func _ready() -> void:
    _init_pools()
 
func _init_pools() -> void:
    # 初始化非空间音效池（UI、全局音效）
    for i in range(pool_size):
        var player = AudioStreamPlayer.new()
        player.bus = &"SFX"
        add_child(player)
        _sfx_pool.append(player)
    
    # 初始化 2D 空间音效池（战斗、脚步等）
    for i in range(pool_size / 2):
        var player = AudioStreamPlayer2D.new()
        player.bus = &"SFX"
        player.max_distance = 1000.0
        add_child(player)
        _sfx_2d_pool.append(player)
    
    # 环境音播放器
    _ambient_player = AudioStreamPlayer.new()
    _ambient_player.bus = &"Ambient"
    _ambient_player.volume_db = linear_to_db(ambient_volume)
    add_child(_ambient_player)
 
## 播放全局音效（UI、系统音效）
func play_sfx(stream: AudioStream, volume: float = 1.0, 
              pitch: float = 1.0) -> void:
    if stream == null:
        return
    
    var player: AudioStreamPlayer = _get_next_sfx_player()
    player.stream = stream
    player.volume_db = linear_to_db(volume * sfx_volume)
    player.pitch_scale = pitch
    player.play()
 
## 播放空间音效（在指定位置）
func play_sfx_at(stream: AudioStream, position: Vector2,
                 volume: float = 1.0, pitch: float = 1.0) -> void:
    if stream == null:
        return
    
    var player: AudioStreamPlayer2D = _get_next_sfx_2d_player()
    player.stream = stream
    player.global_position = position
    player.volume_db = linear_to_db(volume * sfx_volume)
    player.pitch_scale = pitch
    player.play()
 
## 播放随机变体音效（脚步声等）
func play_random_sfx(streams: Array[AudioStream], 
                     position: Vector2 = Vector2.ZERO,
                     volume: float = 1.0,
                     pitch_variation: float = 0.1,
                     spatial: bool = false) -> void:
    if streams.is_empty():
        return
    
    var stream: AudioStream = streams.pick_random()
    var pitch: float = 1.0 + randf_range(
        -pitch_variation, pitch_variation)
    
    if spatial:
        play_sfx_at(stream, position, volume, pitch)
    else:
        play_sfx(stream, volume, pitch)
 
## 设置环境音效（带交叉淡化）
func set_ambient(stream: AudioStream, 
                 fade_time: float = 1.0) -> void:
    if _ambient_tween:
        _ambient_tween.kill()
    
    _ambient_tween = create_tween()
    
    # 淡出当前环境音
    _ambient_tween.tween_property(
        _ambient_player, "volume_db", -80.0, fade_time * 0.5)
    
    # 切换并淡入
    _ambient_tween.tween_callback(func():
        _ambient_player.stream = stream
        _ambient_player.play()
    )
    _ambient_tween.tween_property(
        _ambient_player, "volume_db", 
        linear_to_db(ambient_volume), fade_time * 0.5)
 
## 停止环境音效
func stop_ambient(fade_time: float = 1.0) -> void:
    if _ambient_tween:
        _ambient_tween.kill()
    
    _ambient_tween = create_tween()
    _ambient_tween.tween_property(
        _ambient_player, "volume_db", -80.0, fade_time)
    _ambient_tween.tween_callback(_ambient_player.stop)
 
func _get_next_sfx_player() -> AudioStreamPlayer:
    var player = _sfx_pool[_sfx_pool_index]
    _sfx_pool_index = (_sfx_pool_index + 1) % _sfx_pool.size()
    return player
 
func _get_next_sfx_2d_player() -> AudioStreamPlayer2D:
    var player = _sfx_2d_pool[_sfx_2d_pool_index]
    _sfx_2d_pool_index = (
        _sfx_2d_pool_index + 1) % _sfx_2d_pool.size()
    return player

游戏音乐
├── 背景音乐（BGM）
│   ├── 主菜单音乐（大气、引人入胜）
│   ├── 探索音乐（轻松、环境感）
│   ├── 战斗音乐（紧张、节奏快）
│   ├── Boss 战音乐（史诗、压迫感）
│   ├── 商店/安全区音乐（温馨、放松）
│   ├── 地牢/危险区音乐（阴暗、紧张）
│   └── 胜利/失败音乐（短曲，情感明确）
├── 自适应音乐（Adaptive Music）
│   ├── 层级系统（根据战斗强度叠加乐器层）
│   ├── 分支系统（根据游戏状态切换音乐段落）
│   └── 过渡系统（平滑的音乐状态转换）
├── 音乐短曲（Stingers/Jingles）
│   ├── 升级音效（2-5 秒）
│   ├── 任务完成（3-8 秒）
│   ├── 发现秘密（2-4 秒）
│   ├── 死亡/Game Over（3-6 秒）
│   └── 成就解锁（2-4 秒）
└── 特殊音乐
    ├── 过场动画配乐
    ├── 片尾曲
    └── 预告片音乐

# 通用游戏 BGM 模板
[genre] game soundtrack, [mood/emotion],
[tempo] BPM, [key instruments],
[specific scene/context],
instrumental, loopable,
[additional style descriptors]

# === 按场景分类的提示词 ===

# 主菜单音乐
epic orchestral game menu theme,
majestic and inviting, 100 BPM,
full orchestra with choir,
main title screen music,
instrumental, cinematic,
building from soft strings to full ensemble

# 探索/开放世界
ambient exploration music for open world RPG,
peaceful and wonder-filled, 80 BPM,
acoustic guitar, flute, soft strings, light percussion,
wandering through meadows and forests,
instrumental, loopable, gentle and flowing

# 战斗音乐
intense battle music for action RPG,
aggressive and driving, 140 BPM,
heavy drums, electric guitar, brass section,
combat encounter theme,
instrumental, loopable,
powerful and adrenaline-pumping

# Boss 战音乐
epic boss battle theme, dark fantasy RPG,
ominous and overwhelming, 150 BPM,
full orchestra, heavy percussion, dark choir,
final boss confrontation,
instrumental, dramatic build-ups and drops,
latin chanting, pipe organ

# 商店/安全区
cozy shop music for fantasy RPG,
warm and welcoming, 90 BPM,
lute, accordion, light bells, wooden flute,
medieval tavern atmosphere,
instrumental, loopable,
cheerful and relaxing

# 地牢/恐怖
dark dungeon ambient music,
eerie and unsettling, 60 BPM,
deep drones, distant whispers, metallic scrapes,
exploring dangerous underground,
instrumental, loopable,
minimal and atmospheric, tension building

# 胜利短曲
victory fanfare jingle, fantasy RPG,
triumphant and celebratory, 120 BPM,
brass fanfare, strings, timpani,
level complete celebration,
instrumental, 5 seconds,
bright and uplifting

# 像素风/复古
8-bit chiptune adventure theme,
energetic and nostalgic, 130 BPM,
square wave, triangle wave, noise channel,
retro platformer game music,
instrumental, loopable,
catchy melody, NES style

# 1. 生成初始曲目
- 登录 Suno → Create
- 选择 "Instrumental"（游戏 BGM 通常不需要人声）
- 输入提示词（使用上方模板）
- 生成 2-4 个变体
- 试听并选择最佳版本

# 2. 扩展和调整
- 使用 "Extend" 功能延长曲目到目标时长
- 使用 "Remaster" 提升音质
- 如需要，使用 Stem 分离获取独立乐器轨道

# 3. 后处理（在 DAW 或 Audacity 中）
- 裁剪到合适的循环点
- 添加淡入淡出
- 标准化音量
- 导出为游戏引擎兼容格式

# 4. 循环处理
- 找到自然的循环点（通常在小节线上）
- 确保循环点处的波形平滑过渡
- 测试循环播放是否有明显的"接缝"

# AIVA 工作流

1. 选择风格预设
   - Cinematic（电影配乐）
   - Fantasy（奇幻）
   - Electronic（电子）
   - Rock（摇滚）
   - Jazz（爵士）
   - 或上传参考曲目

2. 配置参数
   - 时长：30s - 5min
   - 情感：Happy / Sad / Epic / Tense / Peaceful
   - 乐器编制：Full Orchestra / Chamber / Solo Piano / Custom
   - 节奏：Slow / Medium / Fast
   - 调性：Major / Minor / Custom

3. 生成并编辑
   - AIVA 生成 MIDI + 音频
   - 可在编辑器中调整：
     - 修改乐器分配
     - 调整段落结构
     - 改变和弦进行
     - 添加/删除乐器层

4. 导出
   - MP3 / WAV / MIDI
   - MIDI 导出允许在 DAW 中进一步编辑
   - Pro 计划拥有完整版权

# music_loop_processor.py — 游戏 BGM 循环处理工具
# 依赖：pip install pydub librosa numpy
 
from pydub import AudioSegment
import numpy as np
import os
 
def find_loop_points(
    audio_path: str,
    min_loop_duration: float = 30.0,
    max_loop_duration: float = 120.0
) -> list[tuple[float, float, float]]:
    """
    自动检测音乐中的最佳循环点
    
    Returns:
        列表 [(start_ms, end_ms, similarity_score), ...]
        按相似度排序，分数越高越好
    """
    try:
        import librosa
    except ImportError:
        print("需要安装 librosa: pip install librosa")
        return []
    
    # 加载音频
    y, sr = librosa.load(audio_path, sr=22050)
    
    # 检测节拍
    tempo, beat_frames = librosa.beat.beat_track(y=y, sr=sr)
    beat_times = librosa.frames_to_time(beat_frames, sr=sr)
    
    # 计算色度特征（用于比较音乐段落的相似度）
    chroma = librosa.feature.chroma_cqt(y=y, sr=sr)
    
    candidates = []
    duration = len(y) / sr
    
    # 在节拍点上搜索循环点
    for i, start_time in enumerate(beat_times):
        for j, end_time in enumerate(beat_times):
            loop_duration = end_time - start_time
            
            if loop_duration < min_loop_duration:
                continue
            if loop_duration > max_loop_duration:
                break
            
            # 比较循环起点和终点附近的音乐特征
            start_frame = librosa.time_to_frames(start_time, sr=sr)
            end_frame = librosa.time_to_frames(end_time, sr=sr)
            
            # 取前后各 1 秒的特征进行比较
            window = int(sr / 512)  # 约 1 秒的帧数
            
            if start_frame + window >= chroma.shape[1]:
                continue
            if end_frame + window >= chroma.shape[1]:
                continue
            
            start_chroma = chroma[:, start_frame:start_frame + window]
            end_chroma = chroma[:, end_frame:end_frame + window]
            
            # 计算余弦相似度
            similarity = np.mean([
                np.dot(start_chroma[:, k], end_chroma[:, k]) / (
                    np.linalg.norm(start_chroma[:, k]) * 
                    np.linalg.norm(end_chroma[:, k]) + 1e-8
                )
                for k in range(min(
                    start_chroma.shape[1], end_chroma.shape[1]))
            ])
            
            candidates.append((
                start_time * 1000,  # 转换为毫秒
                end_time * 1000,
                similarity
            ))
    
    # 按相似度排序
    candidates.sort(key=lambda x: x[2], reverse=True)
    return candidates[:5]  # 返回前 5 个最佳候选
 
 
def create_loopable_bgm(
    input_path: str,
    output_path: str,
    loop_start_ms: float = None,
    loop_end_ms: float = None,
    crossfade_ms: int = 2000,
    intro_path: str = None
) -> None:
    """
    将 AI 生成的音乐处理为可循环的游戏 BGM
    
    Args:
        input_path: 输入音乐文件
        output_path: 输出文件路径
        loop_start_ms: 循环起点（毫秒），None 则自动检测
        loop_end_ms: 循环终点（毫秒），None 则自动检测
        crossfade_ms: 交叉淡化时长
        intro_path: 可选的独立前奏文件路径
    """
    audio = AudioSegment.from_file(input_path)
    
    # 自动检测循环点
    if loop_start_ms is None or loop_end_ms is None:
        candidates = find_loop_points(input_path)
        if candidates:
            loop_start_ms, loop_end_ms, score = candidates[0]
            print(f"自动检测循环点: {loop_start_ms:.0f}ms - "
                  f"{loop_end_ms:.0f}ms (相似度: {score:.3f})")
        else:
            # 默认使用整首曲目
            loop_start_ms = 0
            loop_end_ms = len(audio)
    
    # 提取循环段落
    loop_section = audio[loop_start_ms:loop_end_ms]
    
    # 交叉淡化处理
    if crossfade_ms > 0 and len(loop_section) > crossfade_ms * 2:
        # 取结尾部分
        end_part = loop_section[-crossfade_ms:]
        # 取开头部分
        start_part = loop_section[:crossfade_ms]
        
        # 交叉淡化
        end_faded = end_part.fade_out(crossfade_ms)
        start_faded = start_part.fade_in(crossfade_ms)
        
        # 混合
        crossfaded = end_faded.overlay(start_faded)
        
        # 重组：开头交叉部分 + 中间 + 结尾交叉部分
        loop_section = (
            crossfaded + 
            loop_section[crossfade_ms:-crossfade_ms]
        )
    
    # 如果有独立前奏
    if intro_path:
        intro = AudioSegment.from_file(intro_path)
        # 前奏 + 循环段落
        final = intro + loop_section
    else:
        final = loop_section
    
    # 标准化音量
    target_dbfs = -14.0  # 游戏音乐标准响度
    change_in_dbfs = target_dbfs - final.dBFS
    final = final.apply_gain(change_in_dbfs)
    
    # 导出
    os.makedirs(os.path.dirname(output_path), exist_ok=True)
    final.export(output_path, format="ogg", 
                 parameters=["-q:a", "6"])  # OGG 质量 6（高质量）
    
    duration = len(final) / 1000.0
    file_size = os.path.getsize(output_path) / 1024 / 1024
    print(f"BGM 处理完成: {output_path}")
    print(f"  时长: {duration:.1f}s | 大小: {file_size:.2f}MB")
 
 
# 使用示例
if __name__ == "__main__":
    # 处理探索音乐
    create_loopable_bgm(
        input_path="ai_music/exploration_theme.mp3",
        output_path="game/assets/audio/music/exploration.ogg",
        crossfade_ms=3000
    )
    
    # 处理战斗音乐（手动指定循环点）
    create_loopable_bgm(
        input_path="ai_music/battle_theme.mp3",
        output_path="game/assets/audio/music/battle.ogg",
        loop_start_ms=4000,   # 跳过前奏
        loop_end_ms=64000,    # 在 64 秒处循环
        crossfade_ms=2000
    )

// Unity — 游戏音乐管理器（支持自适应音乐）
// MusicManager.cs
 
using UnityEngine;
using System.Collections;
using System.Collections.Generic;
 
/// <summary>
/// 游戏音乐管理器
/// 支持 BGM 切换、交叉淡化、自适应音乐层级
/// </summary>
public class MusicManager : MonoBehaviour
{
    public static MusicManager Instance { get; private set; }
 
    [Header("音乐配置")]
    [SerializeField] private MusicTrack[] _tracks;
    [SerializeField] private float _crossfadeDuration = 2f;
    [SerializeField] private float _masterVolume = 0.7f;
 
    private AudioSource _sourceA;
    private AudioSource _sourceB;
    private AudioSource _activeSource;
    private Coroutine _crossfadeCoroutine;
 
    // 自适应音乐层级
    private List<AudioSource> _layers = new();
    private float[] _layerTargetVolumes;
 
    private void Awake()
    {
        if (Instance != null) { Destroy(gameObject); return; }
        Instance = this;
        DontDestroyOnLoad(gameObject);
 
        _sourceA = gameObject.AddComponent<AudioSource>();
        _sourceB = gameObject.AddComponent<AudioSource>();
        _sourceA.loop = true;
        _sourceB.loop = true;
        _activeSource = _sourceA;
    }
 
    /// <summary>
    /// 播放指定 BGM（带交叉淡化）
    /// </summary>
    public void PlayTrack(string trackName)
    {
        var track = System.Array.Find(
            _tracks, t => t.name == trackName);
        if (track == null) return;
 
        if (_crossfadeCoroutine != null)
            StopCoroutine(_crossfadeCoroutine);
 
        _crossfadeCoroutine = StartCoroutine(
            CrossfadeTo(track.clip));
    }
 
    /// <summary>
    /// 设置自适应音乐层级的音量
    /// 例如：战斗强度增加时，逐渐加入更多乐器层
    /// </summary>
    public void SetLayerIntensity(float intensity)
    {
        // intensity: 0.0 = 平静, 1.0 = 最大强度
        intensity = Mathf.Clamp01(intensity);
 
        for (int i = 0; i < _layers.Count; i++)
        {
            // 每层在不同的强度阈值激活
            float threshold = (float)i / _layers.Count;
            float targetVolume = intensity > threshold
                ? _masterVolume
                : 0f;
 
            _layers[i].volume = Mathf.Lerp(
                _layers[i].volume, targetVolume,
                Time.deltaTime * 3f);
        }
    }
 
    private IEnumerator CrossfadeTo(AudioClip newClip)
    {
        var fadeOut = _activeSource;
        var fadeIn = _activeSource == _sourceA
            ? _sourceB : _sourceA;
 
        fadeIn.clip = newClip;
        fadeIn.volume = 0;
        fadeIn.Play();
 
        float elapsed = 0;
        float startVolume = fadeOut.volume;
 
        while (elapsed < _crossfadeDuration)
        {
            elapsed += Time.deltaTime;
            float t = elapsed / _crossfadeDuration;
 
            fadeOut.volume = Mathf.Lerp(
                startVolume, 0, t);
            fadeIn.volume = Mathf.Lerp(
                0, _masterVolume, t);
 
            yield return null;
        }
 
        fadeOut.Stop();
        fadeOut.volume = 0;
        fadeIn.volume = _masterVolume;
        _activeSource = fadeIn;
    }
}
 
[System.Serializable]
public class MusicTrack
{
    public string name;
    public AudioClip clip;
    [Range(0, 1)] public float volume = 1f;
}