Questmark is a hypertext fiction and conversation tree language, compiler, interpreter, and TypeScript library. It supports both conversation trees (like in games such as Star Control 2) and quests, hypertext fiction, text adventures, and visual novels (like in games such as Space Rangers 2).
Questmark is based heavily on Markdown, and compiles to Tzo bytecode. If you can write Markdown, you can write Questmark: every properly-structured Markdown document with headers and in-document links is already a Questmark document. Behaviour and side-effects are added with small, backticked code snippets where needed.
The docs follow the Diátaxis framework and are also rendered as a hosted website:
- Tutorials — start here if you're new. Write and play your first conversation in about ten minutes, then continue through context, choices, randomness, text output, a branching dialogue, and a full text adventure. Every complete document has Code and Play tabs when the docs are served as a website.
- How-to guides — play a document, compile it to bytecode, debug it, organize a larger work, and embed Questmark in your own application.
- Reference — the language, the CLI, and the API, described precisely and completely.
- Explanation — why Questmark exists, how it works under the hood, the design principles and mental model, the trust model, how it is tested, open design problems, the wider questmark/Tzo ecosystem, and an FAQ/comparison.
- Integrator guides — porting and conformance, save/load, sandboxing untrusted documents, and CI validation.
- Playground — edit and play a document in your browser, no installation required.
npm install
# Play an example conversation
npm start -- --input examples/space_alien.md
# Compile a document to Tzo bytecode without running it
npm start -- --input examples/space_alien.md --output vmstate.json --no-run
# Run the test suite
npm testYou can also use the published CLI with npx questmark (see the
how-to guide).
# Build, then run the full suite
npm test
# Same suite with a coverage report and 80% line/branch/function thresholds
npm run test:coverage
# Only the portable conformance cases
npm run conformanceThe suite covers the compiler, the VM, the CLI, the browser bundle, every
playable documentation example, and a portable conformance corpus
that other Questmark runtimes can reuse. See
test/conformance/README.md for the case format.
The examples folder contains playable documents. Notably,
self-describing.md is a text adventure written
in Questmark that explains how the language works, and
space_alien.md demonstrates preconditions,
@once options, and context-driven branching.
Questmark is a working proof of concept implemented in TypeScript, with a compiler, an interpreter, a CLI, and a test suite. The spec is still informal and the supported feature set is still evolving.
Open questions being worked on:
- How should inline HTML be treated?
- How can the compiler be modified to add custom directives and macros?
- How can a document be translated to another language, whilst keeping the scripting logic intact and easy to modify?
Questmark is part of a small ecosystem. Tagged repositories are listed on GitHub under the questmark and tzo topics.
- Tzo — the bytecode and VM Questmark compiles to.
- questmark-webrenderer — write and play Questmark documents in your web browser.
- questmark-rust — a Questmark runtime VM written in Rust.
- tzo-rust — a Rust implementation of Tzo.
- tzo-c — a C implementation of the Tzo VM and a QuestMark runtime interpreter.
- tzo-godot — an experimental Godot extension for Tzo and QuestVM.
- tzo-wat — compiles Tzo's standard representation to WebAssembly Text Format.
- tzo-analyze — a Tzo code analyzer.
- questmark-yarn — an experimental Yarn Spinner 2.0 to QuestMark compiler.
- questmark-ide — a work-in-progress IDE for Questmark and Questmark-Yarn.
- tzo-concisetext-language-support — VS Code language support for Tzo ConciseText.
- tzo-powered-uqm-comm-test — a Tzo-powered rendering test for Star Control 2-style comm graphics.
MIT