Skip to content

Development

Jump to bottom
Linrane edited this page May 23, 2026 · 1 revision

开发 (Development)

项目概述

Abyssal Codex 是一款基于 Python 的 Roguelike 卡牌游戏，受《杀戮尖塔》启发，融合克苏鲁神话与深渊探索主题。

技术栈

技术 用途
Python 3.10+ 主要编程语言
pytest 单元测试框架
Git 版本控制
GitHub 代码托管

项目结构

Abyssal-Codex/
├── abyssal/                    # 核心游戏模块
│   ├── __init__.py
│   ├── game.py                 # 游戏主控制器
│   ├── entities/               # 游戏实体
│   │   ├── hero.py             # 英雄系统
│   │   ├── enemy.py            # 敌人系统
│   │   ├── boss.py             # Boss 系统
│   │   └── npc.py              # NPC 系统
│   ├── cards/                  # 卡牌系统
│   │   ├── card.py             # 卡牌基类
│   │   ├── attacks.py          # 攻击牌
│   │   ├── skills.py           # 技能牌
│   │   ├── powers.py           # 能力牌
│   │   └── curses.py           # 诅咒牌
│   ├── relics/                 # 遗物系统
│   │   ├── relic.py            # 遗物基类
│   │   └── relics.py           # 遗物实现
│   ├── events/                 # 事件系统
│   │   ├── event.py            # 事件基类
│   │   ├── event_runner.py     # 事件执行器
│   │   └── events.py           # 事件实现
│   ├── floors/                 # 楼层系统
│   │   ├── floor.py            # 楼层基类
│   │   └── floors.py           # 楼层实现
│   ├── dialogue/               # 对话系统
│   │   ├── engine.py           # 对话引擎
│   │   ├── node.py             # 对话节点
│   │   └── npcs.py             # NPC 实现
│   ├── endings/                # 结局系统
│   │   ├── ending.py           # 结局基类
│   │   └── endings.py          # 结局实现
│   └── utils/                  # 工具函数
│       ├── constants.py        # 游戏常量
│       └── helpers.py          # 辅助函数
├── data/                       # 游戏数据文件
│   ├── hero_data.json          # 英雄数据
│   ├── card_data.json          # 卡牌数据
│   ├── enemy_data.json         # 敌人数据
│   ├── relic_data.json         # 遗物数据
│   └── event_data.json         # 事件数据
├── saves/                      # 存档目录
├── tests/                      # 测试目录
│   ├── test_hero.py
│   ├── test_cards.py
│   ├── test_enemies.py
│   ├── test_events.py
│   ├── test_relics.py
│   ├── test_npc.py
│   └── test_endings.py
├── requirements.txt            # Python 依赖
├── README.md                   # 项目说明
└── .gitignore                  # Git 忽略文件

开发流程

环境搭建

# 克隆仓库
git clone https://github.com/Linrane/Abyssal-Codex.git
cd Abyssal-Codex

# 创建虚拟环境
python -m venv venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/macOS

# 安装依赖
pip install -r requirements.txt

运行游戏

python -m abyssal.game

运行测试

# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_hero.py

# 带覆盖率报告
pytest --cov=abyssal tests/

代码规范

命名约定

  • 类名：PascalCase（如 Hero, CardBase, EventRunner）
  • 函数/方法：snake_case（如 get_health, apply_effect, trigger_event）
  • 常量：UPPER_SNAKE_CASE（如 MAX_HP, DEFAULT_ENERGY）
  • 私有方法：前缀下划线（如 _internal_logic）

文档字符串

所有公共类和方法必须包含 docstring：

class Hero:
    """英雄基类，定义英雄的核心属性和行为。

    Attributes:
        name (str): 英雄名称
        current_hp (int): 当前生命值
        max_hp (int): 最大生命值
        energy (int): 当前能量
    """

    def take_damage(self, amount: int) -> None:
        """受到伤害。

        Args:
            amount: 伤害数值
        """

类型注解

所有函数和方法使用类型注解：

def calculate_damage(base: int, strength: int, vulnerable: bool) -> int:
    pass

贡献指南

提交规范

  • feat: 新功能
  • fix: 修复 bug
  • docs: 文档更新
  • refactor: 代码重构
  • test: 测试相关
  • chore: 其他维护

示例：feat: 添加 NPC 对话引擎

Pull Request 流程

  1. Fork 仓库
  2. 创建功能分支
  3. 编写代码和测试
  4. 确保所有测试通过
  5. 提交 Pull Request

版本发布流程

  1. 更新版本号
  2. 运行完整测试套件
  3. 更新 CHANGELOG
  4. 创建 annotated tag
  5. 推送到 GitHub
  6. 更新 Wiki

已知问题

当前版本 (v0.9.0)

  • 暂无已知严重问题

计划改进

  • 游戏 UI 完善
  • 存档系统增强
  • 多人模式探索
  • Steam Deck 适配

联系方式

Clone this wiki locally