nat20

KO | EN

gitlite — search

#editor #privacy #postgresql #terminal #rust #agents #typescript #computer-vision #devops #open-source

(★ 9)

D&D 5 Engine

파일 탐색기

ZIP 다운로드

- - ci.yml
  - docs.yml
  - provenance.yml
  - release.yml
- console-2026-08-21T22-45-13-314Z.log
- console-2026-08-21T22-47-16-507Z.log
- console-2026-08-21T22-51-05-936Z.log
- page-2026-08-21T22-45-14-166Z.yml
- page-2026-08-21T22-45-28-783Z.yml
- page-2026-08-21T22-45-35-211Z.yml
- page-2026-08-21T22-46-05-702Z.yml
- page-2026-08-21T22-46-24-116Z.yml
- page-2026-08-21T22-46-39-103Z.yml
- page-2026-08-21T22-46-47-586Z.yml
- page-2026-08-21T22-47-17-081Z.yml
- page-2026-08-21T22-47-32-795Z.yml
- page-2026-08-21T22-47-36-047Z.yml
- page-2026-08-21T22-47-53-431Z.yml
- page-2026-08-21T22-47-59-235Z.yml
- page-2026-08-21T22-48-05-379Z.yml
- page-2026-08-21T22-48-59-370Z.yml
- page-2026-08-21T22-51-06-407Z.yml
- page-2026-08-21T22-51-19-433Z.yml
- page-2026-08-21T22-51-26-253Z.yml
- page-2026-08-21T22-51-32-425Z.yml
- page-2026-08-21T22-51-38-843Z.yml
- page-2026-08-21T22-51-45-311Z.yml
- page-2026-08-21T22-51-52-165Z.yml
- page-2026-08-21T22-51-58-683Z.yml
- page-2026-08-21T22-52-06-060Z.yml
- page-2026-08-21T22-52-13-145Z.yml
- page-2026-08-21T22-52-19-385Z.yml
- page-2026-08-21T22-52-26-167Z.yml
- page-2026-08-21T22-52-31-891Z.yml
- page-2026-08-21T22-52-38-565Z.yml
- page-2026-08-21T22-52-47-974Z.yml
- page-2026-08-21T22-52-54-230Z.yml
- page-2026-08-21T22-53-01-117Z.yml
- page-2026-08-21T22-53-07-792Z.yml
- page-2026-08-21T22-53-14-161Z.yml
- page-2026-08-21T22-53-24-260Z.yml
- page-2026-08-21T22-53-30-284Z.yml
- page-2026-08-21T22-53-38-626Z.yml
- page-2026-08-21T22-53-48-476Z.yml
- - Makefile
  - pyproject.toml
  - README.md
- - activities.md
  - combat.md
  - effects.md
  - grid.md
  - monsters.md
  - reactions.md
- - 2026-08-17-demo-webapp-design.md
  - 2026-08-17-demo-webapp-plan.md
  - passive-projection.md
  - reaction-queue.md
  - spatial-geometry.md
- - v0.1-to-v0.2.md
  - v0.2-to-v0.3.md
  - v0.3-to-v0.4.md
  - v0.4-to-v0.5.md
  - v0.5-to-v0.6.md
- api.md
- bridge.md
- capabilities.md
- comparison.md
- index.md
- llms.txt
- quickstart.md
- build_party_member.py
- grid_combat.py
- README.md
- skill_check.py
- - CHANGELOG.md
  - LICENSE
  - Makefile
  - NOTICE
  - pyproject.toml
  - README.md
- - .gitignore
  - CHANGELOG.md
  - LICENSE
  - Makefile
  - NOTICE
  - pyproject.toml
  - README.md
- - LICENSE
  - Makefile
  - pyproject.toml
  - README.md
.gitignore
BACKLOG.md
CONTRIBUTING.md
LICENSE
LICENSES.md
Makefile
mkdocs.yml
NOTICE
pyproject.toml
README.md
uv.lock

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

# 프로젝트 배지

Engine: MIT 바로가기
Data: CC-BY-4.0 바로가기
Python: 3.12+ 바로가기

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**Nat20** is an open-source, host-agnostic, zero-I/O **D&D 5e SRD 5.2 (CC-BY-4.0)**
rules engine for Python. Deterministic combat, skill checks, saving throws, effects,
and grid or zone-graph movement — driven by a typed, bundled SRD dataset. No network,
no database, no game host required.

## What is Nat20

Nat20 is a `uv` workspace of two complementary packages:

| Package | What it is | License |
|---------|-----------|---------|
| [`dnd5e-engine`](packages/dnd5e-engine) | Pure-Python 5e SRD rules engine — combat, checks, effects, grid/zone movement. Ships no rules data; reads the dataset at runtime. | **MIT** (code) |
| [`dnd5e-srd-data`](packages/dnd5e-srd-data) | The typed, canonical SRD 5.2 dataset the engine consumes via `BundledAssetLoader`. | **CC-BY-4.0** (data) |
| [`nat20-bridge`](packages/nat20-bridge) | Localhost FastAPI sidecar that exposes the engine over HTTP — rolls, checks, rests, party validation, full combat lifecycle, SRD browsing, and homebrew content. | **MIT** (code) |

The engine is edition-agnostic: it resolves whatever typed content it is handed —
install your own loader with `set_asset_loader` to drive it from a different corpus.
The shipped dataset is the 2024 SRD (5.2) corpus.

Nat20 implements much, but not all, of SRD 5.2. The
**[capability matrix](https://tapestria.github.io/nat20/capabilities/)** is the
honest per-mechanic inventory of what resolves and what does not; read it before
depending on a specific rule.

## SillyTavern bridge

`nat20-bridge` is a small localhost HTTP host that puts the engine behind a REST API,
so a non-Python client can drive combat, checks, and rests without embedding Python.
It's the server half of the [SillyTavern-nat20](https://github.com/tapestria/SillyTavern-nat20)
extension, which lets a SillyTavern chat run 5e SRD combat and skill resolution through
the bridge instead of freeform narration.

```bash
uvx nat20-bridge  # or: uv run nat20-bridge (in-repo)
```

`nat20-bridge` isn't published on PyPI yet — until then, `uvx nat20-bridge` won't
resolve; run `uv run nat20-bridge` from a checkout of this repo instead.

See [`docs/bridge.md`](docs/bridge.md) for the full endpoint table, quickstart, and
homebrew-content notes.

## Quickstart

Install the engine (the dataset comes along as a dependency):

```bash
uv add dnd5e-engine
```

Run a tiny grid combat end-to-end. Every name below comes from the engine's public
surface (`dnd5e_engine.__all__`):

```python
import asyncio

from dnd5e_engine import (
    EncounterMemberSpec,
    GridScene,
    PartyMemberSpec,
    PlayerIntent,
    cell_id,
    end_combat,
    start_combat,
    submit_player_intent,
)

async def main() -> None:
    # One Hero at cell (0,0), one Foe at (5,0), on a 10x10 grid. rng_seed makes
    # the dice deterministic; cell_id(col, row) encodes the "col,row" position.
    start = await start_combat(
        session_id="example",
        party=[
            PartyMemberSpec(
                entity_id="char:hero",
                name="Hero",
                initiative=20,  # high initiative => the Hero acts first
                hp_current=12,
                hp_max=12,
                ac=12,
                zone_id=cell_id(0, 0),
            )
        ],
        encounter=[
            EncounterMemberSpec(
                entity_id="mon:foe",
                entity_type="Monster",
                name="Foe",
                initiative=1,
                hp_current=7,
                hp_max=7,
                zone_id=cell_id(5, 0),
            )
        ],
        grid_scene=GridScene(width=10, height=10),
        rng_seed=1,
    )

# The Hero takes one diagonal step toward the Foe.
    await submit_player_intent(
        start.handle,
        actor_id="char:hero",
        intent=PlayerIntent(intent_type="move", target_zone_id=cell_id(1, 1)),
    )

# Close the encounter; the result carries the projected outcome.
    result = await end_combat(start.handle)
    print(f"Combat ended ({result.outcome.ended_reason}).")
    print(f"Residual HP: {result.outcome.residual_hp}")

asyncio.run(main())
```

The full, verified-runnable version lives in [`examples/grid_combat.py`](examples/grid_combat.py),
which also resolves an attack and prints the resulting `CombatEvent` stream.

## Live demo

[`apps/demo`](apps/demo) is a small playable HTMX web app built on top of the public
engine API — pick a scenario, take a turn, watch the engine's event tape fill in. The
server is stateless: every fight is replayed from a seed, so any combat is a shareable
permalink that reproduces the same dice.

Run it locally (from the repo root, after `uv sync --all-packages --all-extras`):

```bash
uv run nat20-demo
```

then open <http://127.0.0.1:8000>. The [demo README](apps/demo/README.md) covers the
scenarios, the replay architecture, and development. The repo ships no deployment
logic — the demo is a plain ASGI app any host can run.

## Documentation

📖 **[tapestria.github.io/nat20](https://tapestria.github.io/nat20/)** — concepts, the
[capability matrix](https://tapestria.github.io/nat20/capabilities/), the public API
reference, and a feature comparison.

The site is built with MkDocs from [`docs/`](docs/). Build and browse it locally:

```bash
uv run --group docs mkdocs serve
```

The published site is generated from the same sources (`mkdocs build --strict`).

## Licensing & provenance

- **Engine code** (`dnd5e-engine`): **MIT** — see [`packages/dnd5e-engine/LICENSE`](packages/dnd5e-engine/LICENSE).
  The engine ships no SRD data.
- **Dataset** (`dnd5e-srd-data`): **CC-BY-4.0** — see [`packages/dnd5e-srd-data/LICENSE`](packages/dnd5e-srd-data/LICENSE).
  Portions derived from the [Foundry VTT dnd5e](https://github.com/foundryvtt/dnd5e)
  system (CC-BY-4.0), cross-checked against [open5e](https://open5e.com) (CC-BY-4.0)
  and the [5e-bits/5e-database](https://github.com/5e-bits/5e-database) project (MIT).
- **Original source**: System Reference Document 5.1 and 5.2 by Wizards of the Coast
  LLC, distributed under CC-BY-4.0.

See [`NOTICE`](NOTICE) for the consolidated attribution.

## Disclaimer

Nat20 implements rules from the **D&D 5e System Reference Document (SRD 5.2)**, which
is published by Wizards of the Coast LLC under the Creative Commons Attribution 4.0
International License (CC-BY-4.0). Nat20 is an independent, unofficial project. It is
**not affiliated with or endorsed by Wizards of the Coast**. "Dungeons & Dragons" and
"D&D" are trademarks of Wizards of the Coast LLC; their use here is nominative, to
identify the SRD ruleset this project implements.

---

Built by the [Tapestria](https://github.com/tapestria) team. Nat20 is the deterministic
rules oracle behind [tapestria.quest](https://tapestria.quest), an AI-driven MUD TTRPG.

nat20

파일 탐색기

# CDN으로 사용하기

# 프로젝트 배지

Was this content helpful?

Recent Feedback

Download README