Metadata-Version: 2.4
Name: datapack-emulator
Version: 0.4.0
Summary: Run, profile and version-test Minecraft datapacks outside the game.
Author: Ancar
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/AnCarsenat/Datapack-Emulator
Project-URL: Repository, https://github.com/AnCarsenat/Datapack-Emulator
Project-URL: Issues, https://github.com/AnCarsenat/Datapack-Emulator/issues
Project-URL: Documentation, https://github.com/AnCarsenat/Datapack-Emulator/blob/main/docs/README.md
Keywords: minecraft,datapack,mcfunction,emulator,profiler,testing,ai-agents
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Environment :: X11 Applications :: Qt
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: gui
Requires-Dist: PySide6>=6.6; extra == "gui"
Requires-Dist: pyqtgraph>=0.13; extra == "gui"
Requires-Dist: numpy>=1.26; extra == "gui"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.12; extra == "dev"
Requires-Dist: coverage[toml]>=7; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=5; extra == "release"
Requires-Dist: pyinstaller>=6.6; extra == "release"
Dynamic: license-file

# Datapack Emulator

Load a Minecraft datapack, run its functions, see what they print, what they
cost and how they call each other — for **any Minecraft version you pick**,
checked against the real base game read out of a `client.jar`.

* emulates `#minecraft:load` / `#minecraft:tick`, scoreboards, selectors,
  `execute`, macros, schedules, storage, entity NBT, inventories and blocks
  (setblock, fill, clone, containers, block entity data), teams, game modes,
  experience, time, weather, the world border, random sequences, health,
  attributes, effects, riding, boss bars, item entities, predicates,
  advancements, and loot tables with their conditions and functions
* knows which commands exist in each version from 1.13 to 26.3, and which
  `pack.mcmeta` overlays apply
* prints Minecraft's own error messages, kept apart from the app's own logs
* shows the world as it runs — a scoreboard grid with each score's history,
  entities with their full NBT, command storage, placed blocks — and runs commands typed
  into it
* command tests at any tick, with checks on scores, storage, NBT, blocks and
  entity counts, in the window, during runs and across versions —
  and in CI: `datapack-emulator-cli test` exits non-zero on a failure and
  writes JUnit XML
* world snapshots: keep a world aside, rewind to it, and compare two to see
  what a tick changed
* a problems list for the whole pack, per version, worst first: what stops
  the world or the pack from loading at all (worldgen and dimension files
  missing a required field or using a removed kind, broken JSON there, an
  unreadable `pack.mcmeta`), then functions that do not
  load, unknown selector options, bad SNBT and ids, missing functions,
  broken loot tables and predicates, unused functions
* explains any command line: execute steps, selectors, references, version
  support and cost; your own notes on the project and its functions
* a function debugger: breakpoints (with conditions) on function lines, step
  into / over / out, the call stack, the command source and watched scores,
  storage and NBT — in the window and in the command-line shell
* profiler with per-function cost (from constants measured on a real server),
  dearest lines, a flame graph and
  before/after comparison of two runs, call-graph DAG, version matrix
* edits functions in the window: lines checked as you type, completion
  (Ctrl+Space) and renaming a function across the pack (F2)
* reads registries, tags and message strings straight from a `client.jar`

## Quick start

```sh
python -m venv .venv
.venv/bin/pip install -e ".[gui]"

.venv/bin/datapack-emulator          # the window; press F5 (it reopens the last project)
.venv/bin/datapack-emulator samples/hat   # or open this pack; --no-last-project for the sample
```

Or, from a checkout, `src/main.sh` (uses `.venv/` or `src/.venv/` if present,
no install needed beyond the requirements).

An installed copy (a wheel, or a folder built with PyInstaller) has no
`samples/`: it carries a starter pack inside the package, which the window
copies into your samples folder and opens on a cold start (the command line
does the same with `datapack-emulator-cli project samples --install`). See
[docs/releases.md](docs/releases.md) for building and publishing one.

The project opened most recently comes back on startup (the first sample pack
when there is none). The [command line](docs/cli.md) does what the window does — run, test,
profile, inspect, explain, search, complete, rename, the fields a version's
own files hold, the call graph, the
world, an interactive console with a debugger and project editing — on packs or saved projects:

```sh
.venv/bin/datapack-emulator-cli run    samples/hat_v2 --version 1.21.4 --vanilla
.venv/bin/datapack-emulator-cli matrix samples/hat_v2 --declared --boundaries
.venv/bin/datapack-emulator-cli test   projects/hat.dpemu --junit generated/tests.xml
.venv/bin/datapack-emulator-cli shell  samples/hat          # type commands, .step, .scores, .help
.venv/bin/datapack-emulator-cli shell  samples/hat --break hat:tick:2 --watch "score Player1 hat"   # debug
.venv/bin/datapack-emulator-cli world  samples/hat --ticks 5 --scores
.venv/bin/datapack-emulator-cli check  samples/hat --declared --boundaries
src/main.sh --cli run samples/hat_v2 --version 26.3      # same runner through the script
```

## For scripts and AI agents

The core installs with no dependencies (`pip install datapack-emulator`) and
answers in JSON, from Python or the command line:

```python
from datapack_emulator import agent

agent.check("my_pack", version="1.21.4")              # what the version refuses to load
agent.run("my_pack", version="1.21.4", ticks=40,      # tick it, then ask the world
          commands=["scoreboard players get #game timer"])
agent.test("my_pack", ["5:"], checks=["score #game timer = 5"])
agent.matrix("my_pack", declared=True, boundaries=True)
```

```sh
datapack-emulator-cli --quiet run my_pack --version 1.21.4 --json
```

Every result has `ok` and a one-line `summary`; `ok` is false for the silent
failures a real server only warns about (a function that does not parse,
`functions/` folders on 1.21+). See [docs/agents.md](docs/agents.md). The
[minecode-mcp](https://github.com/AnCarsenat/minecode-mcp) server exposes it
as MCP tools.

## Documentation

Everything is in [`docs/`](docs/README.md):

* [getting started](docs/getting-started.md) · [the window](docs/ui.md) ·
  [projects](docs/projects.md) · [command line](docs/cli.md) ·
  [scripts and AI agents](docs/agents.md)
* [versions & overlays](docs/versions.md) ·
  [base game from client.jar](docs/vanilla-assets.md) ·
  [what is emulated](docs/emulation.md) · [version engine](docs/engine.md) ·
  [cost model](docs/costs.md)
* [architecture](docs/architecture.md)

Timings come from a cost model whose constants were **measured on a real
Minecraft server** — a lower bound and a ranking, not a tick-time
prediction. For real timings of your own pack, `datapack-emulator-cli
server-profile` reads a server's `/perf` report; `calibrate` measures the
model on your machine. See [costs.md](docs/costs.md).

## Layout

```
src/datapack_emulator/emulator/   model, commands, runtime, analysis, version engine (no Qt)
src/datapack_emulator/window/     window.ui, engine.ui, download.ui, and the code that wires them
src/datapack_emulator/cli/       the command line: datapack-emulator-cli (no Qt)
src/datapack_emulator/project.py  .dpemu project files
src/main.sh     starts the window (or --cli) from a checkout
tests/          pytest suite (no network, no Minecraft install needed)
tools/          generate_version_data.py
docs/           documentation
samples/        example datapacks
projects/       your saved .dpemu projects (git-ignored)
generated/      reports and .dot files   (git-ignored)
.cache/         downloaded client jars   (git-ignored)
```

## Contributing

Bug reports, command handlers, UI work and docs are welcome — see
[CONTRIBUTING.md](CONTRIBUTING.md) for setup, ground rules and the checks CI
runs.

## License

GPL-3.0 — see [LICENSE](LICENSE).
