dgt
is a tool to assist in the development of interactive fiction
written in the Dialog language.
dgt
simplifies development, it allows you to specify the details of your project,
including what individual source files to use, and then provides commands to:
- run your project in the Dialog debugger
- run tests and identify failures
- review failed tests and "bless" updates
- build a compiled project for distribution
- more to come ...
Unlike many of my projects, this is really for personal use:
- OS X only
- Subject to breaking change at any time
- Written in Joker (the ultimate scripting language) which you almost certainly don't know
Run the command dgt help
for a list of commands; each command has a --help
option (abbreviated as -h
) that gives
specific details.
Your project must have a dialog.edn
file at the root.
EDN (Extensible Data Notation) is like JSON on steroids. It's the natural choice for Clojure or Joker programmers, but it's close enough to JSON that you should be able to figure it out.
This file identifies the sources in your project as well as other details needed to build, debug, and test your project.
An example dialog.edn
:
{:name "monty-haul"
:story-sources ["src/*.dg"]
:debug-sources ["debug/*.dg"
"/usr/local/share/dialog-if/stddebug.dg"]
:library-sources ["lib/*.dg"
"/usr/local/share/dialog-if/stdlib.dg"]}
Your dialog.edn
is merged on top of a default:
{:default-output :web
:name <directory name>
:debug-sources ["/usr/local/share/dialog-if/stddebug.dg"]
:library-sources ["/usr/local/share/dialog-if/stdlib.dg"]}
A very minimal dialog.edn
will just define :store-sources
.
You can override the default output format as the argument to dgt build
, e.g., dgt build c64
.
dgt
uses three sets of sources.
For each, you may specify any number of individual files, or glob matches.
You should be careful with glob matches, as Dialog can be sensitive to the order in which
source files are loaded.
:story-sources
- sources specific to your project:debug-sources
- used by thetest
,debug
andbuild --test
commands:library-sources
- additional libraries, including the standard library
You may optinally specify a numeric :seed
value, used to initialize the random number generator.
This can be very useful when writing tests where output text varies randomly; the same test script
with the same seed will result in stable, repeatable output.
When :seed
is omitted when running tests, a default seed value, based on a hash
of the path to the test input script, is supplied.
dgt
can download sources from GitHub repositories. Instead of a string path (as shown above), a remote source
is a map with the following structure:
{:github "hlship/threaded-conversation"
:version "v0.2"
:path "lib/tc.dg"}
This identifies the GitHub repository, the version, and the path within the GitHub repository.
On first execution, this map will be converted to a URL, which is downloaded, and saved to
the .cache
directory.
The :version
key may not be master
or main
.
Ideally it should be a published tag, though it can also
be a Git commit SHA.
Dialog makes it easy to code and test at the same time; the
dgdebug
command does a great job of updating in-place
when any of the source files change.
Testing is very simple with dgt
; under the tests
folder are .txt
files
and corresponding .out
files.
The .txt
file is a series of commands to execute, and the .out
file is the
expected game output from executing those commands.
The .txt
file may also include Dialog style comments (%%
), and
Dialog queries, including (now)
queries.
The dgt test
command finds each of these files, runs the debugger to execute
the game script, and captures the output.
If the output matches the .out
file, the test is successful.
Otherwise, the actual output is saved and the test is a failure; the
dgt bless
command allows you to review failed tests, using
a colorized side-by-side diff, and identify those where
the new output is correct.
dgt test
searches all directories under tests
for test files
which allows you to organize things as you like.
Once blessed, the blessed tests' output is saved with extension .out
.
From the debugger, the @save
command does a good job of saving just the input
to the game; although dgdebug
has additional commands (prefixed
with @
) and the ability to evaluate predicates, these
inputs are not saved to the input transcript file, which is
very convienient.
dgt test --force
will automatically bless all failed tests; you can then
use source code control to perform the diff, which works better for very long
transcripts.
brew install hlship/brew/dialog-tool
- Version numbers at start of game transcripts are problematic
and perhaps can be editted out by
dgt
to prevent false failures
Apache Software License 2.0