MyBevy 是一个基于 Rust 和 Bevy 的游戏项目仓库。仓库根目录用于协作文档、脚本和平台工程，实际游戏工程位于 project/。
当前工程使用 Rust stable、bevy = "0.18.1"，同一套 Bevy 代码支持桌面开发运行，并通过 android/ Gradle 壳工程打包 Android APK。
- Bevy 游戏工程：桌面入口在
project/src/main.rs，共享 App 入口在project/src/lib.rs。 - Touch Ripple：单界面触控/鼠标互动玩法，通过 authority 帧同步回放
ui_touch输入，支持按下圆形反馈、拖动水波纹拖尾和松开淡出。 - Robot Sync：
arena.robot_sync3D 场景，用于验证机器人移动的 authority 帧同步、坐标映射、双客户端一致性和 HUD 诊断。 - 场景框架：
project/src/framework/scene/提供场景命令、事件、生命周期、首包 RON manifest、Loading、根实体、相机、spawn/anchor、trigger、streaming 元数据和 debug 配置。 - UI 框架：
project/src/framework/ui/提供页面模式、面板层级、输入路由、焦点、通用控件、覆盖层、主题和国际化。 - 音频框架：
project/src/framework/audio/提供音频 catalog、cue、group、bus、scope、音乐、空间音频、场景音频 adapter、lazy bank 和调试快照。 - 网络框架：
project/src/framework/network/提供 HTTP、TCP 和 KCP 的 Bevy 消息接口。 - Authority 会话：
project/src/game/authority/提供本地控制机、局域网控制机和远端 MyServer 控制机的统一命令/事件接口。 - Android 打包：
android/会加载 Rust 产出的libproject.so，并把project/assets打包进 APK assets。
mybevy/
|-- android/ # Android Gradle 壳工程
|-- docs/ # 项目文档
| |-- audio/ # 音频框架说明
| |-- gameplay/ # 玩法系统设计
| |-- scene/ # 场景框架说明
| |-- ui/ # UI 框架说明
| `-- 世界观/ # 世界观和长期玩法设定
|-- project/ # Rust / Bevy 游戏工程根目录
| |-- assets/ # 首包资源
| |-- src/
| | |-- framework/ # UI、audio、network、scene、fight 等横向能力
| | |-- game/ # 游戏层插件、页面、玩法、场景和协议适配
| | |-- lib.rs # 共享 Bevy App 入口
| | `-- main.rs # 桌面入口
| `-- Cargo.toml
|-- scripts/ # 仓库级开发脚本
|-- summary/ # 开发中 checklist，完成后归档到 docs
|-- CLAUDE.md # 协作和开发约定
`-- README.md
基础开发需要：
- Rust stable
- Git LFS
- Windows PowerShell
首次克隆或换新机器开发时建议执行：
git lfs install
rustc --version
cargo --version当前 project/Cargo.toml 依赖本地 MyServer 仓库中的 ../../MyServer/packages/authority-core。如果编译时报找不到该路径，需要先确认同级 MyServer 仓库存在，或按你的本地环境调整依赖路径。
Android 打包还需要：
- Android SDK / NDK
cargo-ndk- JDK 17 或更新版本
所有 Rust 和 Bevy 命令默认在 project/ 目录执行：
Set-Location project
cargo run仓库根 .cargo/config.toml 会让游戏工程和独立工具共享根 target/ 构建缓存，因此从 project/ 执行游戏命令时二进制仍输出到 target/debug/。通常不要设置 CARGO_TARGET_DIR；脚本或 CI 必须显式设置时，只能将它指向仓库根 target/，避免重新产生清单本地缓存。
共享缓存的三个 Cargo 根仍各自保留 Cargo.toml 和 Cargo.lock，但在当前根 .cargo/config.toml 配置下，从其中任一目录执行 cargo clean 都会清除仓库根 target/，从而影响其他两个根的后续构建。不要把 cargo clean 当作单个工具的局部操作。
运行中的游戏客户端、cargo/rustc、UI 生成或视觉审计工具、测试，以及 Android 的 Gradle/Java/ADB 进程都可能使用共享缓存。停止这些进程后，先执行默认预演，再在人工确认后清理：
pwsh -File scripts/clear-shared-cargo-target.ps1
pwsh -File scripts/clear-shared-cargo-target.ps1 -IncrementalOnly
pwsh -File scripts/clear-shared-cargo-target.ps1 -IncrementalOnly -Execute -ConfirmSharedTargetCleanup
pwsh -File scripts/clear-shared-cargo-target.ps1 -Execute -ConfirmSharedTargetCleanup前两条命令不会删除文件；-IncrementalOnly 只针对 target/debug/incremental。建议仅在根 target/ 超过 35 GiB、磁盘空间紧张，或完成一个发布/大型分支后进行人工检查，优先清理由本脚本控制的 stale incremental 缓存。不要在每次构建前自动清理完整缓存，否则会失去依赖复用并延长构建时间。
共享目录上的 Blocking waiting for file lock 通常表示另一个 Cargo 正在正常排队。先观察对应 Cargo 命令是否仍有 CPU、磁盘或编译日志进展；若没有进展，使用任务管理器或 Get-CimInstance Win32_Process 查找遗留的 cargo、rustc、link、游戏或 UI 工具进程并让其正常退出。只有在相关进程均已结束、等待持续且无任何产物或日志变化时，才把它按可能死锁处理；先保留终端输出和进程信息，再重新启动构建，不要直接删除共享缓存。
回滚共享缓存配置时，不需要修改 Rust 源码、任何 Cargo.lock，或 UI 工具与正式包的依赖方向：移除根 .cargo/config.toml，恢复 .gitignore、脚本和当前文档中的原本地 target/ 路径约定，确认旧路径不再被当成共享缓存后删除根 target/，再分别在 project/、tools/ui-generation/ 和 tools/ui-visual-audit/ 运行各自的构建或测试命令以重建本地缓存。
格式化和检查：
Set-Location project
cargo fmt
cargo check只改文档时，至少确认 diff 没有空白问题：
git diff --check桌面端可以用窗口 profile 模拟移动设备分辨率：
Set-Location project
cargo run -- --window-profile phone-landscape
cargo run -- --window-profile phone-1080p-landscape
cargo run -- --window-profile tablet-landscape
cargo run -- --window-size 1600x720
cargo run -- --window-profile phone-landscape --window-scale 50%这些参数只影响桌面开发窗口。Android 真机 Activity 固定为横屏；旧竖屏 profile 仍保留给历史兼容性回归。
直接启动样板场景：
Set-Location project
$env:MYBEVY_START_SCENE="sample.dungeon_room"
cargo run直接启动 Robot Sync 场景：
Set-Location project
$env:MYBEVY_START_SCENE="arena.robot_sync"
cargo run -- --window-profile phone-landscape --window-scale 50%Robot Sync 手动输入模式：
Set-Location project
$env:MYBEVY_START_SCENE="arena.robot_sync"
$env:ROBOT_SYNC_INPUT_MODE="manual"
cargo run -- --window-profile phone-landscape --window-scale 50%音频监控和音频测试页：
Set-Location project
$env:TOUCH_START_SCREEN="audio_monitor"
cargo run
$env:TOUCH_START_SCREEN="audio_gallery"
cargo run一键启动两个 Touch Ripple 客户端：
.\scripts\start-two-clients.ps1一键启动两个 Robot Sync 客户端：
.\scripts\start-robot-sync-two-clients.ps1 -DryRun -SkipBuild
.\scripts\start-robot-sync-two-clients.ps1 -Mode lan -SkipBuild安装 Android target 和 cargo-ndk：
rustup target add aarch64-linux-android
cargo install cargo-ndk构建 Rust 动态库：
Set-Location project
cargo ndk -t arm64-v8a -P 26 -o ..\android\app\src\main\jniLibs rustc --release --lib --crate-type cdylib打包 Debug APK：
Set-Location ..\android
.\gradlew.bat assembleDebug如果 JAVA_HOME 指向 JDK 8，先在当前终端切到 JDK 17 或更新版本：
$env:JAVA_HOME="C:\Program Files\Java\jdk-21"Debug APK 通常输出到：
android/app/build/outputs/apk/debug/app-debug.apk
首包资源统一放在 project/assets/。代码中引用资源时，从 project/assets/ 下一级开始写：
ui/fonts/MyBevyUiCjk-Regular.otf
audio/ui/click_wood_01.wav
scenes/sample_dungeon_room/scene.ron
不要写成：
project/assets/ui/fonts/MyBevyUiCjk-Regular.otf
图片、字体、音频、二进制模型和源工程类资源通过 Git LFS 提交；RON、JSON、TXT、授权说明等文本资源保持普通 Git 提交。
后续下载资源不要放入 project/assets/。相关设计见 docs/assets-workflow.md。
- 新增游戏功能优先放入
project/src/下的模块，不持续堆在main.rs。 - UI 页面结构放在
project/src/game/screens/。 - 具体玩法放在
project/src/game/features/。 - 具体游戏场景注册和适配放在
project/src/game/scenes/。 - UI 框架能力放在
project/src/framework/ui/。 - UI 通用控件放在
project/src/framework/ui/widgets/。 - 颜色、字号、间距、圆角等主题参数集中放在
project/src/framework/ui/style/theme.rs。 - 修改项目结构、初始化方式、Bevy 版本、资源目录约定或新成员上手流程时，同步检查相关文档。
涉及 Rust 代码时至少执行：
Set-Location project
cargo fmt
cargo check只涉及文档或资源时，至少确认变更路径和内容正确：
git status --short
git diff --check提交信息建议使用：
<type>(<scope>): <summary>
示例：
docs: add project overview readme
feat(scene): add robot sync arena entry
fix(ui): correct lobby route button state