Metadata-Version: 2.1
Name: starrail_damage_cal
Version: 4.2.0
Summary: For StarRail Role Damage Cal
Author-Email: qwerdvd <105906879+qwerdvd@users.noreply.github.com>, ilnli <220916405+ilnli@users.noreply.github.com>
License: MIT
Requires-Python: >=3.11
Requires-Dist: msgspec<1,>=0.20.0
Requires-Dist: httpx<1,>=0.28.1
Requires-Dist: aiohttp<4,>=3.13.4
Description-Content-Type: text/markdown

# StarRailDamageCal

`StarRailDamageCal` 是一个基于崩坏：星穹铁道角色面板数据的伤害计算库。

当前仓库主要提供三类能力：

- 将 Mihomo / 米游社角色数据转换为统一的内部模型
- 基于角色、光锥、遗器与命座信息计算技能伤害
- 更新本地 Excel / 映射资源文件

## 环境要求

- Python `3.11+`

## 安装

使用 `uv`：

```bash
uv sync --group test --group lint
```

使用 `pdm`：

```bash
pdm install -G test -G lint
```

## 快速使用

按 UID 读取公开展示柜并计算指定角色：

```python
import asyncio

from starrail_damage_cal import DamageCal


async def main() -> None:
    data = await DamageCal.get_damage_data_by_uid(
        uid="100086290",
        avatar_name="镜流",
    )
    print(data)


asyncio.run(main())
```

直接使用 Mihomo 原始数据：

```python
import asyncio
import json
from pathlib import Path

from starrail_damage_cal import DamageCal


async def main() -> None:
    mihomo_raw = json.loads(Path("test/test.json").read_text(encoding="utf-8"))
    data = await DamageCal.get_damage_data_by_mihomo_raw(
        mihomo_raw=mihomo_raw,
        avatar_name="镜流",
    )
    print(data)


asyncio.run(main())
```

## 更新资源文件

项目内置了资源更新接口，会将新版本数据覆盖到库包所在目录：

```python
import asyncio

from starrail_damage_cal.update import update_resource


async def main() -> None:
    print(await update_resource())


asyncio.run(main())
```

资源文件目录由 `starrail_damage_cal` 库包位置决定，不读取环境变量。

## 测试

```bash
python -m pytest
```

测试默认使用仓库内的离线样例数据，不依赖在线 UID。

## 当前限制

- 角色、光锥、遗器的部分条件性效果仍然采用静态假设，而不是完整战斗时序模拟
- 如果游戏新角色尚未接入对应伤害模型，会显式抛出 `UnsupportedAvatarError`
- 在线 UID 计算依赖外部数据源的可用性
