Multi-file stories

As a story grows, split it across files. A .story file imports a .chord fragment, and the compiler splices that fragment in at the import line, exactly as if you had pasted its contents there.

story "Harbor" by "You"
  id: harbor

create the Lighthouse
  a room

  A tall lighthouse by the sea.

import "regions/harbor"

The fragment lives beside the story as regions/harbor.chord:

## Harbor's rooms, kept in their own file.

create the pier
  a room
  north to the Lighthouse

  A wooden pier over cold water.

You write import "regions/harbor" with no extension: .chord is assumed, so the file on disk is regions/harbor.chord. Paths resolve relative to the importing .story file.

An import is a paste

Splicing happens before anything is checked, so a fragment shares one namespace with the main story. The pier's north to the Lighthouse exit reaches a room declared in the main file; a fragment freely references anything the story defines, and the story references anything the fragment adds. The import's position is the arbitration position for anything order-sensitive: the fragment behaves as if written on the import line.

Because it is a plain paste, there are no new rules to learn: ordering, name collisions, and cross-references all work exactly as they would in one file.

What a fragment may hold

A .chord fragment holds any complete declaration the story does (rooms, people, sequences, define phrasebook blocks, ## comments) — including grammar alterations, so a story can keep its extend action and remove from action blocks in a grammar-tweaks.chord of their own — with two exceptions:

• No story header. The story block lives only in the main .story file.
• No import of its own. Imports are flat: only the main file imports, one level deep, so a cycle can never form.

A fragment must hold whole declarations: you cannot split a single room or rule across two files.

Diagnostics

The import-fragment-* messages point into the fragment file (prefixed with its name); import-unresolved points at the import line in your main story.