{"id":17244854,"url":"https://github.com/hlship/dialog-tool","last_synced_at":"2026-05-26T01:06:32.702Z","repository":{"id":66810305,"uuid":"234830403","full_name":"hlship/dialog-tool","owner":"hlship","description":"Tool to assist in testing and building interactive fiction using Dialog","archived":false,"fork":false,"pushed_at":"2026-05-22T22:31:49.000Z","size":11013,"stargazers_count":14,"open_issues_count":5,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-05-22T22:54:41.619Z","etag":null,"topics":["cli","dialog","interactive-fiction"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hlship.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"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":"2020-01-19T02:50:29.000Z","updated_at":"2026-05-22T22:31:53.000Z","dependencies_parsed_at":"2025-01-25T23:28:23.271Z","dependency_job_id":"f7158cd8-559f-45f6-8e53-50cd10672fc9","html_url":"https://github.com/hlship/dialog-tool","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/hlship/dialog-tool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hlship%2Fdialog-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hlship%2Fdialog-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hlship%2Fdialog-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hlship%2Fdialog-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hlship","download_url":"https://codeload.github.com/hlship/dialog-tool/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hlship%2Fdialog-tool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33499287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T14:31:05.219Z","status":"ssl_error","status_checked_at":"2026-05-25T14:31:02.878Z","response_time":57,"last_error":"SSL_read: 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":["cli","dialog","interactive-fiction"],"created_at":"2024-10-15T06:27:46.829Z","updated_at":"2026-05-26T01:06:32.687Z","avatar_url":"https://github.com/hlship.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dgt - Dialog Tool\n\n`dgt` is a tool to assist in the development of interactive fiction\nwritten in the [Dialog](https://github.com/dialog-if/dialog) language. Not every work of IF is a \"game\" so we use the term \"project\".\n\n`dgt` simplifies Dialog development, it allows you to specify the details of your project,\nincluding what individual source files to use, and then provides commands to:\n\n- run your project in the Dialog debugger\n- run the web-based Skein UI\n- run tests derived from your skein files\n- package your project for release\n\n\u003e [!WARNING]\n\u003e `dgt` can be sensitive to the exact version of Dialog; this release is based on Dialog 1b/02. If you have\n\u003e a different version of Dialog installed, you may encounter problems.\n\n## Installing\n\n### Homebrew (macOS)\n\nThe easiest way to install `dgt` on macOS is via [Homebrew](https://brew.sh/), which handles all dependencies automatically:\n\n```\nbrew install hlship/brew/dialog-tool\n```\n\nThis installs `dgt` along with all required tools: the Dialog compiler and debugger, Frotz, ImageMagick, and Java.\n\nOnce `dgt` is installed, `brew upgrade` will keep it up-to date with the latest version.\n\nThe Homebrew installation also sets up zsh command completions for `dgt`.  Type `dgt \u003cTAB\u003e` to get started.\n\n### Manual install\n\nDownload the latest release zip from the [GitHub releases page](https://github.com/hlship/dialog-tool/releases).\nThe zip contains two files you need:\n\n- `dgt` — the launcher script\n- `dialog-tool-\u003cversion\u003e.jar` — the uberjar containing all Clojure dependencies\n\nExtract both files into the same directory, then add that directory to your `PATH`,\nor symlink `dgt` into a directory already on your `PATH`.\n\nJava 21 or later is required, though Java 24 or better is preferred.\n\nThe following external tools must also be installed and on your `PATH`:\n\n- [Dialog](https://github.com/dialog-if/dialog) — provides `dialogc` (compiler) and `dgdebug` (debugger)\n- [AAMachine](https://github.com/dialog-if/aamachine) — provides `aambundle`, for `dgt bundle`\n- [Frotz](https://gitlab.com/DavidGriffith/frotz) — for `dgt run`\n- [ImageMagick](https://imagemagick.org/) — for `dgt bundle`\n\n---\n\nRun `dgt help` for a list of commands; each command has a `--help` option (abbreviated as `-h`) for\nspecific details.\n\n## Creating a new project\n\nThe command `dgt new` creates a new directory and a new project within it:\n\n```\n\u003e dgt new magnum-opus\nCreating magnum-opus ...\n  dialog.edn\n  src/meta.dg\n  src/magnum-opus.dg\n  lib/dialog/stdlib.dg\n  lib/dialog/debug/stddebug.dg\n  lib/dialog/test/unit.dg\n  cover.png\n  bundle/index.html\n  bundle/play.css\n  bundle/style.css\n  \nChange to directory magnum-opus to begin work\ndgt debug to run the project in the Dialog debugger\ndgt skein new to open a web browser to the Skein UI\ndgt help for other options\n```\n\nThe exact files created by `dgt new` may change over time.\n\nThe directory must not already exist.\n\nWith the `--flat` option, library files are placed directly in `lib/` (instead of subdirectories)\nand `dialog.edn` lists individual source files rather than directories.\n\n`dgt new` will create a unique [IFID](https://linusakesson.net/dialog/docs/beyondprg.html) for your project; it\nwill be part of the content in the `meta.dg` file. \n\n## dialog.edn\n\nYour project must have a `dialog.edn` file at the root.\n\n\u003e [EDN (Extensible Data Notation)](https://github.com/edn-format/edn) is like JSON on steroids. It's the natural\n  choice for Clojure programmers, but it's close enough to JSON that you should be able to figure it out.\n\nThis file identifies the sources in your project as well as other details needed to build, debug, and test your project.\n\nA minimal example `dialog.edn` (as created by `dgt new`):\n \n```\n{:name \"magnum-opus\"\n :target :zblorb\n :build\n {:zblorb\n  {:options [\"--cover\"     \"cover.png\" \n             \"--cover-alt\" \"Magnum-opus\"]}}\n :sources\n {:main    [\"src\"]\n  :test    [\"lib/dialog/test\"]\n  :debug   [\"lib/dialog/debug\"]\n  :library [\"lib/dialog\"]}}\n```                   \n\n### Source Paths\n\nThe primary (but not only) use of `dialog.edn` is to tell `dgt` where the sources for your project are,\nand _in what order_ they should apply (which is very critical to how Dialog operates).\nFurther, during development and testing you will often include extra \"debug\" sources that should not \nbe included when building and packaging your project for release.\n\n`dgt` uses four categories of sources.  For each category, you may specify a number of directories, relative\nto your project, in which to locate source files. All Dialog source files _directly_ in each directory\nare included.\n\n* :main - sources specific to your project\n* :test - unit test sources, loaded when running `dgt test`\n* :debug - used by the commands `skein test`, `debug`, `skein run`, etc.\n* :library - additional libraries, including the Dialog standard library\n\n\u003e [!WARNING]\n\u003e The order in which files in a source directory are loaded is unspecified. If it ever makes a difference,\n\u003e don't rely on ordering; split files across directories and use the load order of directories, which is\n\u003e under your control, or list the individual files in the directory in the appropriate order.\n\nGenerally, source code that is specific to your project goes in :main; reusable code goes in :library and :debug; \nthis may include code obtained from others, including the standard library.\n\nIt is a common practice to modify libraries as necessary, even the standard library!  Another\ngood practice is to try and split out reusable code (code that could reasonably be used in an entirely different\nproject) under :library (and :debug).\n\nAlternately, a source may be a specific file, which is simply added to the list of source files.\nIf you are coming to `dgt` from a different approach, it may be easier to just list all the files, in order,\nin your `dialog.edn`, but if you are starting from scratch, the directory-based approach is easier.\n\n### Target\n\nThe :target key defines the output when the project is built. It may be a single keyword\n(e.g., `:target :zblorb`) or a vector of keywords (e.g., `:target [:zblorb :z8]`).\n:zblorb is a good general choice.\nIn specific situations you may want to build for :z5, :z8, or :aa.  The differences between\nthese targets are described in [the Dialog manual](https://dialog-if.github.io/manual/dialog/1a01/software.html).\n\n`dgt build` builds all targets defined in the project; use the `--target` option to build\na single specific target instead.\n\n### Build Config\n\nThe :build key contains build configuration for each target. When bundling, all project targets\nare built, plus :aa (for the web player) if not already included.\n\nThe :options key is used to specify additional options to add to the `dialogc` command line.\nThis is typically used to set the heap size information.\n\nUnder :build, the :default key contains defaults for building (any target); the specific build map (:zblorb, in our example)\nis merged on top of the :default map, if present.\n\n### Bin Dir\n\nNormally, `dgt` expects the Dialog commands it uses (`dgdebug`, `dialogc`, and `aambundle`) to be on the\ndefault command search path (as specified in the `$PATH` environment variable).\n\nIf your `dialog.edn` contains a :bin-dir key, its value is used as the directory containing these commands. \n\nThis is a rarely used option, such as when testing a project against a new version of Dialog without installing that new version.\n\n## Running your project\n\n`dgt debug` will run your project using `dgdebug` so you can explore your creation interactively at the console.\n\n```\n\u003e dgt debug\nDialog Interactive Debugger (dgdebug) version 0m/03.\nType @help at the game prompt for a brief introduction.\n\n\nThe Featureless Space\nAn interactive fiction by The Intrepid Author.\nRelease 0. Serial number DEBUG.\nDialog Interactive Debugger (dgdebug) version 0m/03. Library version 0.46.\nDebugging extension 1.1.\n\nEndless Featureless Space\nYou are in an endless, featureless space. Just what will you create within it?\n\n\u003e\n```\n\nAgain, the title, author, release number, and other details can be configured by editing `meta.dg`.\nThe file `magnum-opus.dg` generated by the template \ncontains the room and player and not anything else.  From here, it is all about\nyour imagination.\n\nHowever, you are likely to spend very little time directly running the debugger; instead, you'll run the debugger indirectly, via the Skein.\n\nYou can also run your project using [frotz](https://gitlab.com/DavidGriffith/frotz) with `dgt run`.  \nThis will compile your project first.\nBy default, debug sources are excluded, but you can run with the `--debug` switch to include them as well.\n\nNeither the debugger nor the Skein can present all the possible Dialog screen effects, such\nas status bar updates; to verify these, you must run using Frotz.\n\n## Running unit tests\n\n`dgt test` runs your project's unit tests, using all sources (:main, :debug, :test, and :library). \nThe exit status of the command is 0 if all unit test pass, or 1 if any tests fail.\n\nA new project includes a sample unit test that you can run:\n\n```text\n$ dgt test\nAttempting 1 test.\nTesting #sample-unit-test: Passed!\n1 test passed successfully.\n```\n\n## Running the Skein\n\nThe [Skein](doc/skein.md) is an interactive web interface for running, debugging, and\ntesting your project.\n\n`dgt skein new` will open up the skein UI for a new skein file.\nBy default, the file is named `default.skein`, or you can provide a different\nname, as you may want to have multiple skein files. \n\nThe Skein UI is an alternate way of running your project in the Dialog debugger; you interact through\na web-based user interface.\n\nThe Skein represents your project as a tree of \"knots\"; each knot is a command. You can\nadd new commands beneath any knot, and you can also rerun the project to any knot\nand the skein will identify any text that has changed.  You can even run *all* possible branches\nto completion.\n\n`dgt skein run` will open an existing skein. When launched, the Skein automatically\nreplays all branches to ensure responses and dynamic state are up to date.\n\n## Building and Bundling\n\nThe `dgt build` command is used to build your project; the :target key of `dialog.edn` determines how it\nwill be built; the default is :zblorb; The [ZBlorb format](https://en.wikipedia.org/wiki/Blorb) can contain not only the compiled output of your project, but\nalso sounds and images.\n\n```\n\u003e dgt build\nBuilding out/release/magnum-opus.zblorb ...\n```\n\nZBlorb files also include a cover image; the file `cover.png` is used for this.  A boring placeholder `cover.png` is\ncreated by `dgt new`.\n\nThis image can be used by an application that runs your compiled project,\nsuch as [Spatterlight](https://github.com/angstsmurf/spatterlight):\n\n![Spatterlight Screen](images/splatterlight.png)\n\nYou can see that some of the game's metadata is also presented, such as the title, and the \"blurb\". This is all customized in the `meta.dg` file.\n\nYou can upload your zblorb file to the [Interactive Fiction Database](https://ifdb.org/).\nIf you want to self-host your project, you can bundle it:\n\n```\n\u003e dgt bundle\nBuilding out/release/magnum-opus.zblorb ...\nBuilding out/release/magnum-opus.aastory ...\n  out/web/resources/...\n  out/web/resources/style.css\n  out/web/introduction-to-if.pdf\n  out/web/style.css\n  out/web/magnum-opus.zblorb\n  out/web/cover.png\n  out/web/cover-small.jpg\n  out/web/index.html\n  out/magnum-opus-0.zip\n```\nThe `bundle` command creates a directory and populates it with a custom page for your project.\nIt also creates a `.zip` file of the contents of `out/web` (the name is based on the project's name, and the version number inside `src/meta.dg`)\n\nIf you open `out/web/index.html` in a web browser, you'll be provided with an option to download the game file, or play the game in-browser:\n\n![Bundled Web Page](images/web-bundle-loaded.png)\n\n### Walkthrough\n\nIf the project's default skein contains a knot labeled \"WALKTHROUGH\", then `dgt bundle` will extract a walkthrough (the text from the start\nto that specific knot), and include a link to the walkthrough in the bundled `index.html` page.\n\nIf you like, you may have a secondary skein for the walkthrough; add a :walkthrough-skein key to `dialog.edn` to specify which skein should be used for the walkthrough.\n\n## License\n\nApache Software License 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhlship%2Fdialog-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhlship%2Fdialog-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhlship%2Fdialog-tool/lists"}