Organizing Your Sources

dialog.json sits at the root of your project folder and tells the extension which files make up the project. This chapter covers the parts of it you touch most: the name, the sources object, and binDir. The exports, dialogcOptions, and feelies fields are covered in Building and Releasing Your Project.

The file is plain JSON. When the extension edits it for you — adding a source, adding a feelie — it preserves your existing formatting and key order.

The four source categories

sources is an object with up to four keys. Each key’s value is a list, and each item in that list is either a directory or a single file.

Category What it holds When it is compiled

Category	What it holds	When it is compiled
`main`	Your story sources. This is the default category and the only one that is required.	Always.
`library`	Shared library code, including the Dialog standard library.	Always.
`debug`	Extra sources for use under the interactive debugger — debugging helpers, layout tweaks.	Skein sessions, Debug in Terminal, and Run Tests.
`test`	Unit-test sources: the objects that drive `(test $)` / `(assert $)` checks.	Run Tests and `dgbuild test` only. A running Skein never loads them.

main

Your story sources. This is the default category and the only one that is required.

Always.

library

Shared library code, including the Dialog standard library.

Always.

debug

Extra sources for use under the interactive debugger — debugging helpers, layout tweaks.

Skein sessions, Debug in Terminal, and Run Tests.

test

Unit-test sources: the objects that drive (test $) / (assert $) checks.

Run Tests and dgbuild test only. A running Skein never loads them.

The Dialog IDE: Add File to dialog.json… command shows these same one-line descriptions when it asks which category a file belongs in.

Directory entries and file entries

A directory entry contributes every .dg file that sits directly inside that directory. It does not descend into subdirectories, and the files come in sorted (lexical) order.

A file entry contributes exactly that one file, in the position you list it.

Because a directory’s files arrive in sorted order, you do not have fine control over their sequence. When the order between two files matters — and in Dialog it often does — list those files individually, in the order you need them, rather than relying on a directory entry.

A path that does not exist on disk is skipped quietly; it is not an error.

a realistic dialog.json with several files across the four categories

Why order matters

The extension hands the compiler one flat list of files, built by concatenating the categories in a fixed order: main, then test, then debug, then library.

Dialog resolves rules from the top of that list down, and the first matching rule wins. So put your exceptions before the default rules they override, and put any file that needs to override library behaviour before the library itself.

Live source tracking

The extension watches your project’s files the whole time it is running. Editing a .dg file, adding a new one, deleting one, or renaming one is picked up automatically — there is no "refresh sources" or "reload project" action, and you never need to restart a Skein session because the source changed.

Because a directory entry in dialog.json is re-expanded every time the project is compiled, a file you drop into main/ (or debug/, or any watched directory) is part of the very next build, and a file you delete is gone from it, with no edit to dialog.json.

A running Skein always compiles against the current files on disk. The next command you send, and the next Replay or Replay All, use the latest source. The uncovered-source and duplicate-source warnings described below also re-evaluate live as files and dialog.json change.

Per-format source suffixes

A file whose name ends .<format>.dg is included only when building for that format:

colors.zblorb.dg is compiled into a .zblorb export and nowhere else.
layout.dgdebug.dg is loaded only when running against dgdebug — a Skein session, Debug in Terminal, or Run Tests.

The recognised formats are zblorb, z8, aa, and dgdebug. A file with no such suffix, or with a suffix that does not match any format the extension builds for, is always included.

Use this to keep per-target tweaks — colours, screen layout, debugging shortcuts — from leaking into builds where they do not belong.

The uncovered-source warning

If you create a .dg file that no category covers, the extension flags it two ways: a dismissible notification, and a badge on the file in the Explorer. Both offer a one-click Add to dialog.json fix that prompts for a category and edits the file for you.

Turn this off with the dialog-ide.warnOnUncoveredSource setting if it gets in your way.

The duplicate-source warning

If a file appears in more than one category — or twice in one category, through overlapping directory entries — the extension flags it. Because order matters, a file compiled twice is rarely harmless. Turn this off with dialog-ide.warnOnDuplicateSource.

Adding a file from the Command Palette

Run Dialog IDE: Add File to dialog.json…. It offers the file currently open in the editor, or lets you browse for one, then asks which category to add it to and edits dialog.json in place.

the category QuickPick showing the four categories and their descriptions

Pointing at a specific toolchain (binDir)

Add a binDir field whose value is a directory containing dgdebug, dialogc, and (if you use the web export) aambundle:

{
  "name": "my-project",
  "binDir": "/opt/dialog/bin",
  "sources": { "main": ["src"] }
}

A relative path is resolved against the project root; an absolute path is used as-is. binDir takes priority over everything else — the extension’s bundled toolchain and anything on your PATH. Use it for a locally built dgdebug, or on a platform the extension does not bundle a toolchain for (see Installing the Dialog IDE Extension).

What’s next

How the Skein Works: Time Travel and the Tree of Timelines — the ideas behind the Skein, before you start using it.