# ZSim: an automatic battle simulator and damage calculator for Zenless Zone Zero

> ZSim turns a team composition, a set of agent equipment and a preset action priority list into a simulated fight with damage breakdowns and charts. The interesting part is that the simulation is automatic, and the second interesting part is the three front ends it ships.

**ZSim-Dev/ZSim** — Advanced Automated Battle Simulator for ZZZ 绝区零进阶全自动战斗模拟器

- Repository: https://github.com/ZSim-Dev/ZSim
- Website: https://zsim.com.cn
- Stars: 770 · Forks: 53
- Language: Python
- License: GPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/zsim-dev-zsim

## What the simulator replaces: a spreadsheet of expected damage

ZSim is a battle simulator and damage calculator for Zenless Zone Zero, the action game from Hoyoverse. The problem it addresses is narrow and real: working out how much damage a team composition actually produces once weapon stats, equipment and buff stacking are taken into account. The project's documentation describes the flow as editing the equipment of your agents, selecting a proper APL, then clicking run. The output is total damage for the team, a detailed breakdown per character, and visual charts rather than a single number.

The notable design choice is that the fight is not scripted by hand. The documentation states that the simulator is fully automatic and that there is no need to set a skill sequence manually, and it points out that a sequence mode can be requested. That distinction matters for the workflow. If you need a specific rotation, this project does not currently provide the mechanism for it. If you want an estimate of what a team produces given its gear and a priority order, that is exactly the case it covers.

## The APL is the only thing you actually author

APL means Action Priority List, and it is the input that stands in for a player. Based on a preset APL, ZSim automatically simulates the actions in the team, triggers buffs, records the results, and analyses them. The APL is edited inside the tool as code, so the list of actions and their priority order is the part you write, while the sequencing of buffs and follow-up hits is the part the simulator handles.

That division of labour is the core mechanism, and it is why the project calls itself a simulator rather than a calculator. A calculator would take your numbers and add them up. Here, a character acting triggers a buff, the buff changes what the next character does, and the outcome is recorded per character and rolled up to the team total. The feature list is short and matches this: calculate total damage based on team composition, generate visual charts, provide detailed damage information for each character, edit agents equipment, and edit APL code.

## Install with uv, then run one simulation

The project is installed from a source checkout, either by downloading the latest source from the release page or by cloning the repository. The package manager it expects is uv, and the documentation gives options for every major platform. Installing uv with pip is the shortest route if you already have Python.

```bash
# Using pip if you have python installed:
pip install uv
```

On macOS or Linux the shell installer is used instead.

```bash
# On macOS or Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
```

With uv in place, open a terminal in the project directory and sync the environment, then start the app.

```bash
uv sync
```

```bash
uv run zsim run
```

The second command starts the Streamlit web interface. Python 3.12 or later is required, which the project configuration states directly, and the dependency set is large enough that uv resolves it for you rather than asking you to assemble it by hand.

## One simulator, three front ends, two IPC modes

The architecture is a single core with several ways to reach it. The simulation engine lives in zsim/simulator/. A FastAPI based REST API sits in zsim/api_src/ for programmatic access. The Streamlit interface is in zsim/webui.py, a command line entry point is in zsim/run.py, and a new Vue.js plus Electron desktop application lives in electron-app/. Character and enemy configuration is stored in SQLite, and the Electron shell talks to the FastAPI backend rather than duplicating the logic.

That split is why there are two ways to launch the backend. The web UI and the API can run as separate processes, which is what the Electron application needs, while `uv run zsim run` is enough for the web interface alone. The desktop application is a client of the API, so anyone embedding ZSim in another tool can follow the same path and use HTTP directly.

## IPC mode decides how the desktop app reaches the backend

The communication layer between the front ends and the API is controlled by environment variables, and the default is to pick a sensible transport per platform. The mode variable accepts auto, uds or http. In auto mode, a Unix domain socket is used on Unix like systems and HTTP on Windows. The uds mode is Unix only, and http uses HTTP over TCP.

Three related variables complete the picture. The API port defaults to 0, which means the server selects a port automatically, and the API host defaults to 127.0.0.1. The socket path in uds mode defaults to a file under /tmp. There is also a switch to disable the API routes entirely, which is useful when you only want the local interface. Note the mismatch in defaults worth keeping in mind: the mode variable documents http as the default mode while the mode list describes auto as the behaviour used on Unix like systems, so setting the mode explicitly is clearer than relying on the fallback.

## The build targets assume pyinstaller and pnpm

Development is driven by a Make based build system, and the targets assume you have a working uv environment plus Node tooling for the desktop app. The build targets produce a backend API bundle through pyinstaller using the zsim_api.spec file, and there are separate targets for Windows, Linux and macOS plus a target that builds all three. The release build for the desktop application is a separate step in the electron-app directory, which needs pnpm.

For day to day work the individual commands are simpler. The web UI and the API each have a command, and the combined development server is started from the electron-app directory with pnpm dev, which starts the Vue.js frontend and the FastAPI backend together, forwards backend console output to the terminal, and gives the frontend hot reload. For the desktop app you install Node dependencies with pnpm install first. Tests live in tests/, with API tests in tests/api/ and shared fixtures in tests/conftest.py, and they run under pytest with asyncio support.

## Where ZSim is the wrong tool

Two boundaries are visible in the project itself. The first is the missing sequence mode. The documentation says the simulation is fully automatic and that a skill sequence does not need to be set, and it invites requests for sequence mode. Until that exists, anyone whose question is which specific rotation gives the best result has to encode that rotation as an APL and accept the simulator's own action logic.

The second boundary is operational weight. Even the lightest path needs Python 3.12 or later, uv, and a dependency set that includes pandas, numpy, polars, FastAPI, uvicorn, SQLAlchemy, alembic and Streamlit. The desktop application adds Node.js, pnpm and Electron on top. For a single team calculation that is a heavy install, and a hand written spreadsheet still wins for a rough estimate where gear bonuses do not interact. The project earns its weight when you are iterating on a composition repeatedly, or when you want the same simulation exposed as an API for other tools.

## Licence, releases and where the documentation stops

ZSim is distributed under the GPL-3.0 licence, which carries obligations around redistribution and derivative works, so read the LICENSE file in the repository before you embed it in a closed product. The releases move in small steps. The listed versions are v0.3.4a1, v0.3.4a2 and v0.3.5, with v0.3.5 dated 2025-09-23. The last push to the repository was on 2026-07-08, and the version in the project configuration matches the v0.3.5 release.

The documentation has clear edges. There is a TODO list that points to a develop guide hosted on the project's wiki, and the README does not walk through data entry for characters and enemies in detail, so how character and enemy data reaches the SQLite store is something you learn from the wiki rather than from the readme. The homepage is zsim.com.cn, and an English and Chinese documentation pair exists under docs/. The project is not archived, and behaviour after 2026-07-08 is not something the repository itself confirms.

## Conclusion

ZSim fits players and analysts who want team damage numbers for Zenless Zone Zero without hand-calculating every hit, and it fits developers who want a REST API to drive the same simulation. It does not fit you if you need a scripted skill sequence, since the project says sequence mode is not available yet, or if you are not willing to install Python 3.12 or later and the uv toolchain. Before you rely on a report, check the APL you pasted and the equipment values you entered, since those inputs decide the output, and read the licence file because the project is distributed under GPL-3.0.

## FAQ

### What does ZSim do for Zenless Zone Zero?

ZSim is a battle simulator and damage calculator that estimates the total damage of a team composition while taking weapon and equipment characteristics into account. It produces a per character damage breakdown and visual charts from a preset action priority list.

### How do I install and run ZSim?

Install uv, download the source from the release page or clone the repository, then run uv sync followed by uv run zsim run in the project directory. Python 3.12 or later is required.

### Does ZSim have a desktop application and an API?

Yes. A Vue.js and Electron desktop app in electron-app/ talks to a FastAPI REST API in zsim/api_src/, and the Streamlit interface in zsim/webui.py is the third front end. The API can be launched on its own with uv run zsim api.

### Can ZSim simulate a specific skill sequence instead of an APL?

Not currently. The documentation describes the simulator as fully automatic with no need to set a skill sequence manually, and it invites requests for a sequence mode.

### Under which licence is ZSim released?

ZSim is released under the GPL-3.0 licence, and the repository includes a LICENSE file at the top level alongside the source directories.

## Sources

- [License: GPL-3.0](https://github.com/ZSim-Dev/ZSim/blob/main/LICENSE)
- [Project website](https://zsim.com.cn)
- [README](https://github.com/ZSim-Dev/ZSim/blob/main/README.md)
- [Releases](https://github.com/ZSim-Dev/ZSim/releases)
- [ZSim-Dev/ZSim on GitHub](https://github.com/ZSim-Dev/ZSim)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zsim-dev-zsim