# allien

**Repository Path**: remedo/allien

## Basic Information

- **Project Name**: allien
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-09
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RPG Framework — Godot 4 ECS 基础框架

> **引擎版本**：Godot 4.3+  **语言**：GDScript 2.0（全静态类型）  
> **架构原则**：组合优先 · 信号解耦 · Resource 数据驱动

---

## 📁 目录结构

```
rpg_framework/
├── autoloads/                    # 自动加载单例
│   ├── EventBus.gd               # 全局信号总线（所有跨系统通信）
│   ├── GameData.gd               # 数据注册表（物品/卡牌/技能/任务）
│   └── SaveManager.gd            # 存档系统
│
├── systems/
│   ├── character/                # 角色 & 属性系统
│   │   ├── CharacterStats.gd     # 属性组件（基础值 + 修改器叠加）
│   │   ├── HealthComponent.gd    # 生命值组件
│   │   ├── StatModifier.gd       # 属性修改器数据结构
│   │   └── StatusEffectComponent.gd  # Buff/Debuff 状态效果组件
│   │
│   ├── inventory/                # 背包 & 物品系统
│   │   ├── InventoryComponent.gd # 背包组件（格子/堆叠/整理）
│   │   └── EquipmentComponent.gd # 装备槽组件（自动应用 StatModifier）
│   │
│   ├── card/                     # 卡牌系统
│   │   ├── DeckComponent.gd      # 牌库（抽/弃/消耗堆）
│   │   ├── HandManager.gd        # 手牌管理（出牌/能量）
│   │   └── CardEffectProcessor.gd # 卡牌效果执行器
│   │
│   ├── quest/                    # 故事 & 任务系统
│   │   ├── QuestManager.gd       # 任务管理器（自动加载）
│   │   └── DialogueManager.gd    # 对话管理器（自动加载）
│   │
│   └── battle/                   # 战斗系统
│       ├── BattleManager.gd      # 战斗流程编排（自动加载）
│       ├── SkillComponent.gd     # 技能组件（主动/被动）
│       └── (SkillData 见 resources/skills/)
│
└── resources/                    # .tres 数据文件（设计师填写）
    ├── items/
    │   └── ItemData.gd           # 物品 Resource 基类
    ├── cards/
    │   └── CardData.gd           # 卡牌 Resource 基类
    ├── skills/
    │   ├── SkillData.gd          # 技能 Resource 基类
    │   └── StatusEffectData.gd   # 状态效果 Resource 基类
    └── quests/
        └── QuestData.gd          # 任务 Resource 基类
```

---

## 🏗️ 核心架构设计

### ECS 组合模式

每个**角色**是一个 `CharacterBody2D/3D` 根节点，行为由**组件子节点**组合实现：

```
Player (CharacterBody2D)  ← 根节点，仅处理物理移动
├── CharacterStats        ← 属性组件
├── HealthComponent       ← 生命值组件
├── StatusEffectComponent ← Buff/Debuff
├── InventoryComponent    ← 背包
├── EquipmentComponent    ← 装备槽
├── DeckComponent         ← 牌库（如有卡牌战斗）
├── HandManager           ← 手牌管理
└── SkillComponent        ← 技能
```

**原则**：组件通过**信号向上通信**，绝不 `get_parent()`；跨场景通信走 **EventBus**。

### 属性计算公式

```
最终属性 = (基础值 + Σ FLAT修改器) × (1 + Σ PERCENT_ADD修改器) × Π (1 + PERCENT_MUL修改器)
```

### 信号流向

```
组件内部信号
   ↓ (组件向父节点汇报)
EventBus 全局信号
   ↓ (跨系统广播)
UI / 其他系统监听
```

---

## ⚡ 快速上手

### 1. 配置自动加载

将 `project_autoload_config.txt` 中的 `[autoload]` 段合并到你的 `project.godot`，  
并把脚本路径指向项目实际路径。

> **顺序**：EventBus → GameData → SaveManager → QuestManager → DialogueManager → BattleManager

### 2. 创建物品数据

1. 在编辑器中右键 `res://resources/items/` → **新建资源**
2. 搜索 `ItemData`，创建 `.tres` 文件
3. 填写 `id`、`display_name`、`item_type`、`stat_modifiers` 等字段

### 3. 组装角色场景

```gdscript
# Player.gd 示例
class_name Player
extends CharacterBody2D

@onready var stats: CharacterStats        = $CharacterStats
@onready var health: HealthComponent      = $HealthComponent
@onready var inventory: InventoryComponent = $InventoryComponent
@onready var hand: HandManager            = $HandManager
@onready var skill_comp: SkillComponent   = $SkillComponent

func _ready() -> void:
    stats.character_id = "player_1"
    add_to_group("player")
    health.died.connect(_on_died)

func _on_died() -> void:
    EventBus.show_notification.emit("玩家死亡", "error")
```

### 4. 启动战斗

```gdscript
# 在场景中调用
BattleManager.start_battle(
    [player_node],           # 友方列表
    [goblin_node, orc_node]  # 敌方列表
)

# 玩家出牌
BattleManager.play_card("strike_card", [goblin_node])

# 玩家结束回合
BattleManager.end_player_turn()
```

### 5. 创建任务

1. 新建 `QuestData.tres`，填写 `id`/`objectives_config`/`reward_*`
2. `QuestManager.accept_quest("quest_id")` 接取任务
3. 杀怪/收集会**自动**更新进度（QuestManager 监听 EventBus）

### 6. 对话文件格式（JSON）

```json
[
  {"id":"start", "speaker":"老村长", "text":"你好冒险者！有任务想委托你。",
   "choices":[{"text":"说说看","next":"node2"},{"text":"改天吧","next":"end"}]},
  {"id":"node2", "speaker":"老村长", "text":"去帮我打5只哥布林！",
   "trigger":{"type":"quest_accept","quest_id":"quest_goblin_hunt"},
   "next":"end"}
]
```

---

## 🔧 扩展指南

| 需求 | 方案 |
|------|------|
| 新增属性（如 `luck`） | 在 `CharacterStats._get_base_value()` 添加 case |
| 新增卡牌效果类型 | 在 `CardEffectProcessor._execute_effect()` 添加 match 分支 |
| 敌方 AI 强化 | 替换 `BattleManager._run_enemy_turn()` 为行为树节点 |
| 多人联机 | 用 `MultiplayerSynchronizer` 同步 `CharacterStats` + EventBus 信号 |
| 新增存档字段 | 在对应组件实现 `save_data()`/`load_data()`，并向 `SaveManager.register()` 注册 |

---

## 📋 自动加载注册表

| 单例名 | 文件 | 职责 |
|--------|------|------|
| `EventBus` | autoloads/EventBus.gd | 所有跨系统信号 |
| `GameData` | autoloads/GameData.gd | 静态数据查表 |
| `SaveManager` | autoloads/SaveManager.gd | 存档/读档 |
| `QuestManager` | systems/quest/QuestManager.gd | 任务状态管理 |
| `DialogueManager` | systems/quest/DialogueManager.gd | 对话驱动 |
| `BattleManager` | systems/battle/BattleManager.gd | 战斗流程 |

---

## 🚨 开发规范

- **信号命名**：全部 `snake_case`，所有参数显式类型化
- **零无类型 var**：生产代码中不允许无类型 `var`
- **@onready 强制类型**：`@onready var x: HealthComponent = $HealthComponent`
- **组件不调用 get_parent()**：仅通过信号向上通信
- **每个场景可 F6 独立运行**：不依赖父节点上下文