{"id":50029809,"url":"https://github.com/phiat/rpg-quint","last_synced_at":"2026-05-20T19:17:30.240Z","repository":{"id":350704809,"uuid":"1207793200","full_name":"phiat/rpg-quint","owner":"phiat","description":"Formal RPG system specs in Quint with model-based testing for Odin implementations","archived":false,"fork":false,"pushed_at":"2026-04-11T18:09:32.000Z","size":243,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T18:11:05.294Z","etag":null,"topics":["model-based-testing","odin","quint","raylib","rpg"],"latest_commit_sha":null,"homepage":"","language":"Odin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phiat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-11T12:11:40.000Z","updated_at":"2026-04-11T17:45:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/phiat/rpg-quint","commit_stats":null,"previous_names":["phiat/rpg-quint"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/phiat/rpg-quint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phiat%2Frpg-quint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phiat%2Frpg-quint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phiat%2Frpg-quint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phiat%2Frpg-quint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phiat","download_url":"https://codeload.github.com/phiat/rpg-quint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phiat%2Frpg-quint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33271856,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-20T15:12:43.734Z","status":"ssl_error","status_checked_at":"2026-05-20T15:12:42.300Z","response_time":356,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["model-based-testing","odin","quint","raylib","rpg"],"created_at":"2026-05-20T19:17:29.604Z","updated_at":"2026-05-20T19:17:30.228Z","avatar_url":"https://github.com/phiat.png","language":"Odin","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Odin](https://img.shields.io/badge/Odin-lang-blue)\n![Quint](https://img.shields.io/badge/Quint-formal%20spec-purple)\n![Raylib](https://img.shields.io/badge/raylib-5.5-green)\n![License](https://img.shields.io/badge/license-MIT-blue)\n\n# Quint Crawl — Formally Verified RPG\n\nA raylib RPG game built on formally verified game logic. Every game rule is specified in [Quint](https://quint-lang.org/), tested via Model-Based Testing (MBT), and implemented in [Odin](https://odin-lang.org/).\n\nInspired by: [Model-Based Testing for D\u0026D](https://www.loskutoff.com/blog/model-based-testing-dnd/)\n\n![Title Screen](screenshots/title.png)\n![Map Exploration](screenshots/map.png)\n![Combat](screenshots/combat.png)\n![Inventory](screenshots/inventory.png)\n\n## The Game\n\n**Quint Crawl** is a turn-based RPG rendered with raylib. Explore a 9x9 world grid (81 zones across 5 difficulty levels), fight enemies, gather resources, craft gear, and level up to conquer the Castle.\n\n```bash\njust play             # build and run the game\n```\n\nThe game logic in `quint_crawl/` is the single source of truth — shared by both the raylib game and the MBT test harness. Every state transition is formally specified and verified.\n\n## Controls\n\n### Movement\n\n| Key | Action |\n|-----|--------|\n| WASD | Move between zones |\n| J | Fast travel (between unlocked village waypoints) |\n\n### Combat — Sword\n\n| Key | Action |\n|-----|--------|\n| E | Initiate fight |\n| A | Basic attack |\n| K | Combo (3-hit chain: Slash → Thrust → Finisher) |\n| H | Heavy strike (2x damage, cooldown) |\n\n### Combat — Actions \u0026 Skills\n\n| Key | Action |\n|-----|--------|\n| Y | Battle cry (ATK buff) |\n| Z | Shield block |\n| N | Counter-attack (block + retaliatory hit) |\n| I | Fortify (extended DEF buff) |\n| F | Flee |\n\n### Combat — Tactical\n\n| Key | Action |\n|-----|--------|\n| P | Use potion |\n| V | Apply poison (venom sac) |\n| X | Antidote |\n| B | Throw bomb (flat damage, bypasses DEF) |\n| M | Smoke bomb (guaranteed escape) |\n| INS | Use holy water (full heal) |\n\n### Exploration\n\n| Key | Action |\n|-----|--------|\n| R | Rest (restore stamina) |\n| G | Gather wood |\n| M | Mine iron |\n| Z | Open treasure chest (chest zones only) |\n| - | Eat ration (restore stamina) |\n| I | Open inventory (ESC to close) |\n\n### Village\n\n| Key | Action |\n|-----|--------|\n| B | Buy potions |\n| F | Buy bombs |\n| / | Buy smoke bombs |\n| ' | Buy rations |\n| C | Craft sword (Level 2+) (Shift+C: batch 3) |\n| Q | Equip |\n| T | Repair sword |\n| O | Craft venom sac |\n| U | Respec skills |\n| \\ | Salvage sword |\n| = | Upgrade salvage level |\n| 1–7 | Unlock skill (when points available) |\n| 8–0 | Enchant sword slots 1–3 |\n| F1 | Recycle 3 wood → ration |\n| F2 | Recycle 3 iron → battery |\n| F3 | Recycle 3 potion → holy water |\n| L | Claim victory (at Level 5 Castle, after the Boss) |\n\n### Companions\n\n| Key | Action |\n|-----|--------|\n| , | Adopt local companion |\n| . | Feed companion |\n| ; | Dismiss companion |\n| ' | Companion command (in combat) |\n\n### System\n\n| Key | Action |\n|-----|--------|\n| F5 | Save |\n| F9 | Load |\n\nSee the HUD sidebar for zone-specific actions.\n\n## Features\n\n- **World** — 9x9 grid, 5 difficulty levels, biome tiling (3x3 pattern repeats across regions), fog of war, HUD minimap, mouse hover tooltips, per-zone weather (Clear/Rain/Fog/Storm) affecting combat/gathering/movement, village waypoints with fast travel, one-time treasure chests with tier-scaled gold rewards.\n- **Combat** — turn-based, stamina-gated actions, 3-hit combo chain with damage multipliers, cooldown abilities (heavy strike, battle cry, fortify, counter-attack), status effects (poison, ATK/DEF buffs) with turn-based ticking, enemy respawn timer (5-turn cooldown after a kill), four weapon types (sword / dagger / battery pistol / staff; `weapon_type` gates combat actions — sword and dagger share blade-combat paths with per-weapon stamina + attack tuning).\n- **Bestiary** — data-driven catalog of 200 named enemies across 20 archetypes (4 per tier, 5 tiers), 6 trait tags (Undead/Beast/Elemental/Construct/Humanoid/Aberration), trait-keyed secondary loot drops.\n- **Elemental system** — 4-element cycle (Fire \u003e Ice \u003e Lightning \u003e Earth \u003e Fire) with 2x/1x/0.5x damage multipliers.\n- **Companions** — data-driven species catalog (Wolf/Hawk/Turtle/Fox/Bear/Owl/Lynx/Sprite) with biome-gated adoption, trait affinities (Attacker/Defender/Scout/Support), rarity tiers (Common/Rare/Legendary), species-specific perks (HP regen / mana regen / stamina vigor / loyalty bond), loyalty-on-combat loop (inactive below LOW_LOYALTY until fed), in-combat command, village training to raise rarity, and a 3-stage companion quest chain. The spec verifies the abstract (trait × rarity) effect space; Odin grows the catalog freely without code changes.\n- **Progression** — XP/level-up, skill tree with 3 branches (Offense/Defense/Utility), 1 point per level, respec at village, 3 prerequisite-gated quests (Slime Slayer → Venture Forth → Castle Conqueror) tracked in the HUD, Castle Boss encounter gates the final victory claim.\n- **Items \u0026 crafting** — resource gathering (wood, iron), level-gated sword crafting (Lv2+, batch-of-3 option), sword durability with village repair, salvage system (upgradeable 1–3), 3-slot weapon enchantment (fire/ice/vampiric/lightning; fire/ice mutually exclusive), venom sac crafting, holy water crafting (holy_dust + wood → out-of-combat full heal), fire scrolls (bypass mana gate), loot drops with pity-counter guarantee, zone-tiered sword rarity drops (Common/Rare/Legendary with ATK scaling), per-tier unique archetype trophies (5 collectible drops that grant a permanent ATK bonus), village recycling (3-for-1 wood/iron/potion conversion), full-screen inventory overlay ([I] to open), inventory capacity (30 items) enforced across gathering/shopping/loot.\n- **Persistence \u0026 polish** — save/load snapshot with full state round-trip; post-processing effects (zone tint, chromatic aberration, low-HP pulse, level-up bloom, poison overlay).\n\n## How MBT works\n\n```\nspecs/*.qnt  ──[quint run --mbt]──▶  traces/*.itf.json  ──[odin test]──▶  pass/fail\n                                          │\n                 Odin implementation  ◀───┘\n                 (*_mbt/*.odin)        replayed against spec expectations\n```\n\n1. **Write a Quint spec** — state variables, actions (state transitions), invariants (properties that must always hold)\n2. **Generate traces** — Quint explores the state space nondeterministically and records execution traces in ITF (Intermediate Trace Format)\n3. **Write Odin glue** — a step handler (dispatches action names to your code) and a state getter (reads your implementation's state back for comparison)\n4. **Replay** — the MBT runner walks each trace step, mutates your implementation, and checks that every state variable matches the spec's expectation\n\n## Project structure\n\n```\nquint_crawl/           Shared game logic (Game_State, all action procs, constants)\nquint_crawl_game/      Raylib game executable (rendering, input, UI, shaders)\n  assets/              GLSL shaders (effects.fs)\nquint_mbt/             Shared Odin library: ITF parser + trace replayer\nquint_crawl_mbt/       MBT harness for the integrated game spec\nspecs/                 Quint formal specifications\n  core/                Character fundamentals (rpg, healing, leveling, stamina)\n  combat/              Combat systems (combat, combat_full, status, cooldown, elemental)\n  items/               Equipment \u0026 crafting (equip, durability, enchantment, crafting, salvage, ...)\n  economy/             Trade \u0026 loot (shop, dynamic_shop, trade, loot)\n  world/               Exploration (world_grid, trap, respawn, companion)\n  social/              Progression \u0026 social (party, quest, skill_tree, reputation, summoning)\n  quint_crawl.qnt      Integrated game spec\nmbt/                   Per-module Odin MBT test harnesses (mirroring specs/ layout)\n  core/                ...\n  combat/              ...\n  items/               ...\n  economy/             ...\n  world/               ...\n  social/              ...\ntraces/                Generated ITF trace files (.itf.json)\ndocs/                  Design documents (asset specs, etc.)\njustfile               Task runner for common workflows\n```\n\n## Modules\n\nThe integrated game spec lives at `specs/quint_crawl.qnt` — 7 record-typed state vars, ~50 actions, ~46 invariants covering HP/gold/level/position/inventory bounds, level gates, skill prerequisites, quest counters, cooldowns, status effects, enchantment slots, companion loyalty, and victory conditions.\n\nAlongside it, `specs/{core,combat,items,economy,world,social}/` holds 38 standalone spec modules (rpg, combat, equip, healing, stacking, shop, status, crafting, party, leveling, cooldown, quest, durability, loot, respawn, dynamic_shop, combat_full, capacity_craft, gated_craft, stamina, skill_tree, reputation, summoning, world_grid, elemental, enchantment, trap, companion, salvage, auction, faction, fast_travel, dialogue, fog_of_war, permadeath, bounty, trade) that each verify one subsystem in isolation — useful as unit tests for the underlying mechanics before integration.\n\n## Quick start\n\n```bash\njust play            # build and run the game\njust build-game      # build without running\n\njust check           # typecheck all specs\njust traces          # generate MBT traces for all specs\njust test            # run all Odin MBT tests\njust all             # check + traces + test\njust retest          # traces + test\n\njust check-one rpg             # typecheck one spec\njust test-one rpg              # test one module\njust trace rpg rpg_run         # regenerate one trace\njust trace-crawl               # regenerate quint_crawl traces (5x, 100k samples)\njust test-crawl                # regen traces + run crawl MBT tests\njust verify NAME MAIN INVARIANT # run invariant check (100k traces, 20 steps)\n```\n\n## Prerequisites\n\n- [Odin](https://odin-lang.org/) (with vendor:raylib)\n- [Quint](https://quint-lang.org/) (tested with 0.32.0)\n- [just](https://github.com/casey/just) (task runner)\n- X server or WSLg (if running on WSL)\n\n## Docs\n\n- [Asset Design Guide](docs/assets-design.md) — sprite specs for V2 visual upgrade (91 required assets)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphiat%2Frpg-quint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphiat%2Frpg-quint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphiat%2Frpg-quint/lists"}