{"id":35098467,"url":"https://github.com/katelouie/bardic","last_synced_at":"2026-03-12T04:05:01.782Z","repository":{"id":317303962,"uuid":"1066843153","full_name":"katelouie/bardic","owner":"katelouie","description":"A Python-first interactive fiction engine and authoring system. Frontend-agnostic and portable.","archived":false,"fork":false,"pushed_at":"2026-03-09T13:47:16.000Z","size":26541,"stargazers_count":23,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-09T16:24:16.551Z","etag":null,"topics":["bardic","domain-specific-language","dsl","game-development","game-engine","if","interactive-fiction","markup-language","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/katelouie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"2025-09-30T03:22:06.000Z","updated_at":"2026-02-16T09:44:41.000Z","dependencies_parsed_at":"2025-10-24T00:12:09.845Z","dependency_job_id":"af277d5d-cb62-4fc7-869c-6602a21430ee","html_url":"https://github.com/katelouie/bardic","commit_stats":null,"previous_names":["katelouie/bardic"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/katelouie/bardic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katelouie%2Fbardic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katelouie%2Fbardic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katelouie%2Fbardic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katelouie%2Fbardic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/katelouie","download_url":"https://codeload.github.com/katelouie/bardic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katelouie%2Fbardic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30415042,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T00:40:14.898Z","status":"online","status_checked_at":"2026-03-12T02:00:07.260Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["bardic","domain-specific-language","dsl","game-development","game-engine","if","interactive-fiction","markup-language","python","python3"],"created_at":"2025-12-27T16:07:58.860Z","updated_at":"2026-03-12T04:05:01.777Z","avatar_url":"https://github.com/katelouie.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bardic\n\n[![PyPI version](https://badge.fury.io/py/bardic.svg)](https://badge.fury.io/py/bardic)\n[![Python Version](https://img.shields.io/pypi/pyversions/bardic.svg)](https://pypi.org/project/bardic/)\n[![VSCode Marketplace](https://img.shields.io/visual-studio-marketplace/v/katelouie.bardic)](https://marketplace.visualstudio.com/items?itemName=katelouie.bardic)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/katelouie/bardic)\n[![Tests](https://github.com/katelouie/bardic/actions/workflows/test.yml/badge.svg)](https://github.com/katelouie/bardic/actions/workflows/test.yml)\n\u003c!-- [![Coverage](https://codecov.io/gh/YOUR_USERNAME/bardic/branch/main/graph/badge.svg)](https://codecov.io/gh/YOUR_USERNAME/bardic) --\u003e\n\n**Bardic is a Python-first interactive fiction engine that lets you import your own classes and use real Python in your stories.**\n\nWrite your branching narrative in a clean, simple syntax (inspired by Ink), and when you need complex logic, just use Python. Bardic is designed to be the \"story layer\" for games that need rich data models, complex state, and custom UIs. Bardic is frontend-agnostic and works with NiceGUI, Reflex, React+FastAPI, or any other frontend layer you want to build with. It compiles stories to JSON and is portable and versatile.\n\n## Bardic in Action (with VSCode Extension)\n\n![Split View Screenshot](images/split_graph_view_2.png)\n\n![Live Preview Screenshot](images/livepreview.png)\n\n## A Quick Example\n\nBardic syntax is designed to be simple and stay out of your way. Here's a small story that shows off the core features:\n\n```bard\n# Import your own Python classes, just like in a .py file\nfrom my_game.character import Player\n\n:: Start\n# Create a new Player object\n~ hero = Player(\"Hero\")\n\nWelcome to your adventure, {hero.name}!\nYou have {hero.health} health.\n\n+ [Look around] -\u003e Forest\n+ [Check your bag] -\u003e Inventory\n\n:: Forest\nThe forest is dark and spooky.\n~ hero.sprint() # Call a method on your object\nYou feel a bit tired.\n\n+ [Go back] -\u003e Start\n\n:: Inventory\n# Use Python blocks for complex logic\n@py:\nif not hero.inventory:\n  bag_contents = \"Your bag is empty.\"\nelse:\n  # Use list comprehensions, f-strings...\n  item_names = [item.name for item in hero.inventory]\n  bag_contents = f\"You have: {', '.join(item_names)}\"\n@endpy\n\n{bag_contents}\n\n+ [Go back] -\u003e Start\n```\n\n## Why Bardic? A New Choice for Writers and Developers\n\nYou have great tools like Twine, Ink, and Ren'Py. So, why did I create Bardic?\n\nBardic is built for stories that get *complex*.\n\n- **Twine** and **Ink** are both excellent authoring systems with large communities. If you like them, use them!\n- **Bardic** is for when your \"state\" isn't just a number or a string, but a complex object. It's for when you want to write:\n  - \"I want this character to have an inventory, which is a **list of `Item` objects**.\"\n  - \"I need to **import my `Player` class** and call `player.take_damage(10)`.\"\n  - \"I want to simulate a full tarot deck, with 78 **`Card` objects**, each with its own properties and methods.\"\n\nHave you ever been writing and thought, \"I wish I could just `import` my custom class and use it\"? **That's what Bardic does.**\n\nIt bridges the gap between simple, text-based branching logic and the full power of a programming language, letting you use both in the same file.\n\n## Quick Start\n\n**Install:**\n\n```bash\npip install bardic\n\n# With a UI framework (pick one):\npip install bardic[nicegui]    # Pure Python, single-file games\npip install bardic[web]        # FastAPI + React\npip install bardic[reflex]     # Python-to-React compilation\n```\n\n**Create a project and run it:**\n\n```bash\nbardic init my-game          # Creates a project from template\ncd my-game\npip install -r requirements.txt\nbardic compile example.bard -o compiled_stories/example.json\npython player.py             # Opens at http://localhost:8080\n```\n\nOr skip the project template and just write a `.bard` file:\n\n```bash\nbardic play my_story.bard    # Auto-compiles and plays in terminal\n```\n\n### Installation Options\n\nBardic supports multiple UI frameworks. Choose the one you prefer:\n\n| Framework | Install Command | Best For |\n|-----------|----------------|----------|\n| NiceGUI | `pip install bardic[nicegui]` | Pure Python, single-file games |\n| FastAPI + React | `pip install bardic[web]` | Production web apps |\n| Reflex | `pip install bardic[reflex]` | Python → React compilation |\n\nOr install the core engine and add dependencies manually:\n\n```bash\nbardic init my-game\ncd my-game\npip install -r requirements.txt\n```\n\n## Core Features\n\n- **Write Python, Natively:** Use `~` for simple variable assignments or drop into full `@py:` blocks for complex logic.\n- **Use Your Own Objects:** `import` your custom Python classes (like `Player`, `Card`, or `Client`) and use them directly in your story.\n- **Passage Parameters:** Pass data between passages like function arguments: `:: Shop(item) -\u003e BuyItem(item)`. Perfect for shops, NPC conversations, and dynamic content!\n- **Complex State, Solved:** Bardic's engine can save and load your *entire game state*, including all your custom Python objects, right out of the box.\n- **You Write the Story, Not the UI:** Bardic doesn't care if you use React, NiceGUI, or a terminal. It produces structured data for any UI.\n  - Use the **NiceGUI** template for a pure-Python, single-file game.\n  - Use the **Web** template (FastAPI + React) for a production-ready, highly custom web game.\n- **Clean, Writer-First Syntax:** Focus on your story with a minimal, line-based syntax for passages (`::`), choices (`+`), and text.\n- **Visualize Your Story:** Automatically generate a flowchart of your entire story to find highlighted dead ends or orphaned passages with the `bardic graph` command.\n- **Catch Bugs Before Players Do:** `bardic lint` analyzes your compiled story for broken jump targets, orphaned passages, dead ends, and attribute consistency issues. Extend it with [project-specific plugins](docs/lint-plugins.md) for your own game mechanics.\n- **Instant Start-Up:** Get a working game in 60 seconds with `bardic init`. It comes with a browser-based frontend pre-configured and ready to run with a single command. (NiceGUI, Reflex, or React -- take your pick.)\n- **Browser distribution.** `bardic bundle` packages your game for itch.io with a full Python runtime (Pyodide). No server required.\n- **VS Code Integration:** Syntax highlighting, snippets, code folding, live preview, and graph-based navigation. Install \"Bardic\" from the marketplace or run `code --install-extension katelouie.bardic`.\n\n## Batteries Included: Standard Library\n\nBardic ships with pre-built modules for common game mechanics — no need to write them from scratch.\n\n```bard\nfrom bardic.stdlib.inventory import Inventory\nfrom bardic.stdlib.economy import Wallet, Shop\nfrom bardic.stdlib.quest import QuestJournal\nfrom bardic.stdlib.relationship import Relationship\nfrom bardic.stdlib.dice import roll, skill_check\n```\n\n| Module | What it does |\n|--------|-------------|\n| **`inventory`** | Weight-limited item management with add/remove/filter |\n| **`economy`** | Wallets, shops, buying/selling with automatic refunds |\n| **`quest`** | Quest tracking with custom stages, journal entries, completion |\n| **`relationship`** | NPC trust/comfort/openness with threshold events |\n| **`dice`** | Dice rolls (`3d6+5`), skill checks, advantage/disadvantage |\n\nPlus built-in special variables — `_visits` tracks how many times each passage has been entered, and `_turns` counts player choices.\n\n```bard\n:: Tavern\n@if _visits.get(\"Tavern\", 0) == 1:\n    You push open the tavern door for the first time.\n@else:\n    The bartender nods. \"The usual?\"\n@endif\n\n+ {_turns \u003e= 10} [I've been here a while...] -\u003e Leave\n```\n\n## CLI Reference\n\n| Command | Description |\n| ------- | ----------- |\n| `bardic init my-game` | Create a new project from template (nicegui, web, or reflex) |\n| `bardic compile story.bard` | Compile `.bard` source to `.json` |\n| `bardic play story.bard` | Play a story in the terminal (accepts `.bard` or `.json`) |\n| `bardic graph story.json` | Generate a visual flowchart (`.png`, `.svg`, or `.pdf`) |\n| `bardic lint story.bard` | Analyze story for structural issues (broken jumps, dead ends, attribute bugs) |\n| `bardic bundle story.bard` | Package for browser distribution (itch.io, static hosting) |\n| `bardic serve` | Start the web runtime (FastAPI backend + React frontend) |\n\n## Syntax At a Glance\n\n| Syntax | Meaning |\n| ------ | ------- |\n| `:: Name` | Passage header |\n| `+ [Text] -\u003e Target` | Choice (persistent) |\n| `* [Text] -\u003e Target` | Choice (one-time, disappears after use) |\n| `~ variable = value` | Variable assignment |\n| `{variable}` | Display a variable or expression |\n| `@if condition:` ... `@endif` | Conditional block |\n| `@for item in list:` ... `@endfor` | Loop |\n| `@py:` ... `@endpy` | Python code block |\n| `@include file.bard` | Include another file |\n| `@render component(data)` | Send data to a UI component |\n| `@input name=\"x\" label=\"Y\"` | Request player input |\n\n## Browser Distribution (itch.io)\n\nWant to share your game on itch.io or any web hosting? Bardic can bundle your entire game into a self-contained package that runs in the browser:\n\n```bash\n# Create a browser-ready bundle\nbardic bundle my-story.bard --zip\n\n# With options\nbardic bundle my-story.bard -o ./release -n \"My Epic Adventure\" --theme dark --zip\n```\n\nThis creates a ZIP file containing:\n\n- Your compiled story\n- The Bardic engine (browser version)\n- A complete Python runtime (Pyodide)\n- Pre-installed packages: numpy, pillow, networkx, pyyaml, regex, jinja2, nltk, and more\n\n**Bundle sizes:**\n\n- Full bundle: ~17 MB (all packages included)\n- Minimal bundle: ~5 MB (use `--minimal` flag for stories that don't need extra packages)\n\n**No server required** - everything runs in the browser via WebAssembly.\n\n### Options\n\n| Option | Description |\n| ------- | ------------ |\n| `-o, --output` | Output directory (default: `./dist`) |\n| `-n, --name` | Game title (uses story metadata if not specified) |\n| `-t, --theme` | Visual theme: `dark`, `light`, or `retro` |\n| `-z, --zip` | Create a ZIP file ready for upload |\n| `-m, --minimal` | Smaller bundle (~5 MB) with only core Pyodide |\n\n### Uploading to itch.io\n\n1. Run `bardic bundle my-story.bard --zip`\n2. Go to [itch.io](https://itch.io) and create a new project\n3. Upload the generated ZIP file\n4. Check \"This file will be played in the browser\"\n5. Publish!\n\n### Testing Locally\n\n```bash\nbardic bundle my-story.bard -o ./dist\ncd dist\npython -m http.server 8000\n# Open http://localhost:8000 in your browser\n```\n\n## Example Game: *Arcanum*\n\nNeed to see a large-scale project? The [Arcanum](https://github.com/katelouie/arcanum-game) cozy tarot reading game is built with Bardic. It's an example of using Bardic with custom Python classes, complex state, and a NiceGUI frontend.\n\n## Editor Support\n\n**VSCode Extension:**\n\nGet syntax highlighting, code snippets, code folding, graph node navigation and debugging, and live preview from any point in the story with variable injection:\n\n1. Open VSCode\n2. Search \"Bardic\" in Extensions\n3. Install\n\nOr install from command line:\n\n```bash\ncode --install-extension katelouie.bardic\n```\n\n[View on VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=katelouie.bardic)\n\n## Where to Go Next?\n\n- **New to Bardic?** I've put together a short [tutorial course](docs/tutorials/README.md) that walks you through all of the syntax and features of Bardic, from beginner to advanced.\n- **Want to see all the syntax?** Check out the [Language Specification](https://github.com/katelouie/bardic/blob/main/docs/spec.md) for the full list of features, from loops to render directives.\n- **Want to lint your story?** Use `bardic lint` for structural analysis, and write your own [lint plugins](docs/lint-plugins.md) for game-specific checks.\n- **Want to build the engine?** See our [`CONTRIBUTING.md`](CONTRIBUTING.md) for details on the architecture and development setup.\n- **Want VS Code integration?** Download the [Bardic VS Code extension](https://github.com/katelouie/bardic-vscode) with full syntax highlighting, snippets and code folding. Also has live passage preview and graph-based navigation of your source file.\n- See the [DeepWiki detailed documentation](https://deepwiki.com/katelouie/bardic) generated from AI code indexing. It includes a *lot* of technical implementation details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatelouie%2Fbardic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkatelouie%2Fbardic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatelouie%2Fbardic/lists"}