# godot-ppt

**Repository Path**: CodeTang01/godot-ppt

## Basic Information

- **Project Name**: godot-ppt
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: art/ninja-adventure
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-07
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Godot PPT (Godot AI Battle Project)

本项目是一个基于 **Godot Engine 4** 开发的原生游戏项目，包含完整的多人大厅、战斗、社交及商城系统。  
同时，本项目深度集成了 **[godot_ai](addons/godot_ai)** 插件，提供了一套基于 MCP (Model Context Protocol) 的 AI 自动化开发环境，支持通过自然语言或外部 AI IDE（如 Cursor, Windsurf, Cline）控制引擎进行开发。

## 核心特性

### 🎮 游戏功能
- **大厅系统 (Hall):** 完整的用户登录、大厅展示、任务奖励、每日签到系统。
- **社交生态 (Social):** 好友添加、聊天系统、组队房间 (TeamRoom)、快速匹配 (QuickMatch)。
- **战斗系统 (Battle):** 基于帧同步逻辑的战斗场景，包含地图网格系统、角色动画状态机、实时伤害结算。
- **商业系统:** 商城购物、角色皮肤 (Skin) 购买与更换、排行榜 (Rank)。
- **UI 框架:** 高度复用的 `BasePanel` 弹窗架构和通用 UI 组件库。

### 🤖 AI 集成 (Godot AI)
- **多客户端兼容:** 支持连接主流 AI 编程工具，通过 MCP 协议与 Godot 编辑器交互。
- **自动化操作:** 支持通过 AI 生成代码、修改场景节点、自动化测试和资源管理。
- **视觉辅助:** 提供编辑器内的截图、场景解析和日志诊断能力。

## 项目结构

- **`scenes/`**: 存放所有游戏场景文件（`.tscn`），包括主场景、大厅、战斗及各类 UI 面板。
- **`scripts/`**: 游戏的业务逻辑代码。
  - `battle/`: 战斗核心逻辑与同步机制。
  - `hall/`: 大厅界面的交互逻辑。
  - `core/`: 网络请求 (HttpClient)、数据存储 (DataStore)、音效管理 (SoundManager) 等基础库。
  - `panels/`: 游戏内各个功能面板的具体实现。
  - `game/sync/`: 战斗同步相关的数学库和帧驱动代码。
- **`addons/godot_ai/`**: AI 插件的核心代码与工具定义。
- **`assets/`**: 游戏的音频、字体及大量的纹理资源（按模块分为 battle, hall, auth 等）。
- **`tools/`**: 开发辅助的 Python/JS 脚本，如资产生成与地图生成 (`gen_battle_maps.js`)。

## 快速开始

1. **环境要求:**
   - 安装 [Godot Engine 4.x](https://godotengine.org/download)（本项目使用 **4.7.2** 开发与验证；纯 GDScript，标准版即可，无需 .NET 版）。
   - 安装 Python 3.x 与 Pillow（用于运行 `tools/` 目录下的辅助脚本）。

2. **导入项目:**
   - 克隆本仓库。
   - 打开 Godot，点击 **Import** 并选择项目根目录下的 `project.godot` 文件。

3. **运行游戏:**
   - 在 Godot 编辑器中按 `F5` 或点击 **Run** 按钮启动游戏。

4. **启用 AI 功能 (可选):**
   - 在 Godot 编辑器中激活 `godot_ai` 插件。
   - 在对应的 AI 客户端（Cursor/Windsurf）中配置 MCP 端口连接到 Godot 编辑器。

## 开发工具

项目根目录下的 `tools/` 包含了一系列开发辅助脚本：

- **资产生成:** 自动将 CC0 素材批量生成为项目贴图：
  - `gen_na_art.py` — 角色/炸弹/道具/皮肤立绘（来源 [Ninja Adventure](https://pixel-boy.itch.io/ninja-adventure-asset-pack)，CC0）
  - `gen_map_art.py` — 四主题地图瓦片（来源 [Bombman 2D Resources](https://opengameart.org/content/bombman-2d-resources)，CC0）
  - `audit_unused_images.py` — 未引用图片审计清理
- **测试脚本:** `test_battle_sim.gd`（9000 tick 逐帧一致性）、`test_battle_scene.gd`、`test_fixedmath.gd` 等测试用例，以及 `probe_trial_skin.gd` 等数据流探针。

详细使用方法请查阅各脚本文件或 `addons/godot_ai/README.md`。

## 素材版权声明

**战斗相关美术已 100% 替换为 CC0（公有领域）素材**，可自由使用、修改与再分发：

| 素材 | 来源 | 许可 |
|---|---|---|
| 角色/炸弹/爆炸/道具/皮肤立绘 | [Ninja Adventure Asset Pack](https://pixel-boy.itch.io/ninja-adventure-asset-pack)（pixel-boy） | CC0 |
| 地图瓦片/墙体/木箱（四主题） | [Bombman 2D Resources](https://opengameart.org/content/bombman-2d-resources)（drummyfish） | CC0 |
| 爆炸音效 | Ninja Adventure Asset Pack | CC0 |

来源与再生成方法详见 [`assets/textures/NA_ART_SOURCE.md`](assets/textures/NA_ART_SOURCE.md)。

**部分界面素材来源于网络公开渠道**（主要为部分大厅按钮类 UI和背景音乐），**经合理检索仍无法完全确认原始授权状态**，其著作权依法归原作者或原始发布方所有。

- **权利人联络**：若您认为本项目使用的某项素材侵犯了您的权益，请通过以下方式联系，并提供涉嫌侵权的素材名称、权属证明及您的联系方式。我们承诺在收到有效通知后 **7 个工作日内** 核实并移除相关内容。
  - **邮件**（推荐，适合提交权属证明等敏感材料）：[tzq2008wd@163.com](mailto:tzq2008wd@163.com)
  - **Issue**（公开透明，便于追踪）：[新建 Issue](../../issues/new/choose)

- **使用者风险提示**：本项目代码部分采用 MIT 许可证开源，但**上述少量待确认素材不包含在 MIT 授权范围内**。若您计划将本项目用于商业用途、二次分发或衍生开发，请务必自行核实并获取相关素材的合法授权。项目作者已尽合理注意义务，但不对素材部分的版权完整性作任何保证。

## 代码许可证

本项目源代码以 [MIT License](./LICENSE) 开源。

代码由 Kimi Code 辅助生成，并经项目作者人工审查、修改与整合。

## 免责声明

本项目旨在促进技术研究与交流，不构成任何商业建议或法律意见。使用者应结合自身情况独立评估使用风险。除法律明确规定不得免除的责任外，项目作者对因使用本项目产生的直接或间接损失不承担赔偿责任。