krpgscript 0.1.0

Typed parser and runtime engine for tiny text RPG scripts

krpgscript

Русский | English

Typed parser for a small KRPG DSL.

What It Does

krpgscript parses a brace-based text format into a tree of Section and Command nodes. It is intentionally small and focused on syntax parsing, not on game runtime execution.

Core Concepts

• Section is a container node that can hold nested sections and commands
• Command is a leaf node with positional arguments
• TokenType describes tokenizer output: NEWLINE, BRACE, COMMAND
• parse_text() is the main entry point for parsing raw text into an AST

Example Syntax

See examples/story.krpg for a minimal demo.

game {
    title "Small Demo"
    version 1

    player "Aria" {
        hp 100
        mp 25
        skill "quick strike"
    }

    scene intro {
        say "You wake up in a quiet room."
        choice "Open the door" goto hall
        choice "Go back to sleep" goto sleep
    }
}

Usage

Parse text in Python

from pathlib import Path

from krpgscript import Command, Section, parse_text

root = parse_text(Path("examples/story.krpg").read_text(encoding="utf-8"))

game = root.get("game", command=False, section=True)
assert isinstance(game, Section)

for child in game.children:
    if isinstance(child, Command):
        print(child.name, child.args)
    else:
        print(child.name, child.args)

Run the demo example

uv run python examples/run_example.py

CLI

Validate syntax for a file, directory, or glob:

krpgscript check examples/story.krpg examples/

Format one or more files in place:

krpgscript format examples/**/*.krpg

Export the tree to JSON:

krpgscript json examples/story.krpg -o story.json

Development

Install dependencies:

uv sync --dev

Run tests:

just test

Run linting and type checks:

just check

Format code:

just fmt

Build release artifacts:

just build

Validate the release workflow:

just release-check

Project Layout

krpgscript/
  __init__.py
  main.py
  parser.py
examples/
  run_example.py
  story.krpg
tests/
  test_parser.py
justfile

Notes

• The package has no runtime dependencies
• The public API lives in krpgscript/init.py
• The current parser API is Section, Command, TokenType, tokenize, parse, and parse_text