Skip to content

README_CN.md

Latest commit

 

History

History
165 lines (121 loc) · 4.25 KB

README_CN.md

File metadata and controls

165 lines (121 loc) · 4.25 KB

ZZZ模拟器

English | 中文

项目介绍

ZZZ模拟器是一款《绝区零》的伤害计算器。

本工具支持全自动模拟，无需手动设置技能释放序列（如需序列模式可以提issue）

您只需配置代理人装备，选择合适的APL（行动优先级列表），点击运行即可。

该工具提供友好的用户界面，可计算队伍整体伤害输出。基于预设的APL自动模拟队伍行动，触发buff，记录并分析结果，最终生成可视化图表报告。

功能特性

  • 基于队伍配置计算总伤害
  • 生成可视化图表
  • 提供各角色详细伤害数据
  • 编辑代理人装备
  • 编写APL代码

安装指南

从发布页面下载最新打包源码或使用 git clone

安装UV（如未安装）

在任意终端中执行：

# 使用pip安装：
pip install uv
# macOS/Linux：
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows11 24H2及以上：
winget install --id=astral-sh.uv -e
# 旧版Windows：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

或参考官方安装指南：https://docs.astral.sh/uv/getting-started/installation/

安装并运行ZZZ模拟器

在项目目录中执行：

uv sync

uv run zsim run

开发

主要组件

  1. 模拟引擎 - zsim/simulator/ 中的核心逻辑处理战斗模拟
  2. Web API - zsim/api_src/ 中基于FastAPI的REST API，提供程序化访问
  3. Web UI - zsim/webui.py 中基于Streamlit的界面以及 electron-app/ 中的Vue.js + Electron桌面应用
  4. CLI - 通过 zsim/run.py 的命令行接口
  5. 数据库 - 基于SQLite的角色/敌人配置存储
  6. Electron应用 - 使用Vue.js和Electron构建的桌面应用，与FastAPI后端通信

构建系统

项目使用基于 Make 的综合构建系统来管理开发、构建和发布流程。

可用的 Make 目标

# 构建组件
make build              # 完整构建（清理 + 后端 + Electron）
make backend            # 仅构建后端API
make electron-build     # 仅构建Electron桌面应用

# 开发
make dev                # 启动前端开发服务器
make clean              # 清理所有构建文件
make check              # 检查依赖

# 工具
make help                # 显示帮助信息

设置和安装

# 首先安装UV包管理器
uv sync

# WebUI开发
uv run zsim run 
# FastAPI后端
uv run zsim api

# Electron应用开发，还需安装Node.js依赖
cd electron-app
pnpm install

运行应用

快速启动（推荐）

# 一键启动开发服务器，包含前端和后端
cd electron-app
pnpm dev

单独组件

# Streamlit WebUI
uv run zsim run

# FastAPI后端
uv run zsim api

# Electron桌面应用（生产构建）
cd electron-app
pnpm build

注意：pnpm dev 命令提供了最便捷的开发体验：

  • 自动启动Vue.js前端和FastAPI后端
  • 将所有后端控制台输出转发到开发终端
  • 提供前端热重载功能
  • 启用完整的调试能力

测试结构

  • 单元测试位于 tests/ 目录
  • API测试位于 tests/api/
  • 测试固件在 tests/conftest.py 中定义
  • 使用pytest并支持asyncio
# 运行测试
uv run pytest
# 运行测试并生成覆盖率报告
uv run pytest -v --cov=zsim --cov-report=html

待办事项

详见贡献指南获取最新开发计划。

环境变量

FastAPI后端

  • ZSIM_DISABLE_ROUTES - 设置为"1"以禁用API路由（默认：启用）
  • ZSIM_IPC_MODE - IPC通信模式："auto"、"uds"或"http"（默认："auto"）
  • ZSIM_UDS_PATH - 使用UDS模式时的socket文件路径（默认："/tmp/zsim_api.sock"）
  • ZSIM_API_PORT - API服务器端口，设置为0可自动选择端口（默认：0）
  • ZSIM_API_HOST - API服务器主机地址（默认："127.0.0.1"）

IPC模式行为

  • auto：在类Unix操作系统上使用uds，在Windows上使用http
  • uds：使用Unix域套接字进行本地通信（仅适用于类Unix系统）
  • http：使用HTTP/TCP进行通信（默认模式）