Note
This page explains Balladeer's classic syntax, which is no longer maintained.
Refer to a more recent article for its replacement, Balladeer lite.
Interactions
The top-level object in Balladeer is the Story. And whether game, prose or poetry, a Story always has one active Drama object. That object specifies where to find the corresponding Dialogue files.
What's shared between Drama and Dialogue is the Ensemble. That's simply a container for all characters and objects currently in context. Both Drama and Dialogue can modify the state of objects in the Ensemble.
Operation
Your Drama may define an interlude function. That is called every time Balladeer generates output to display. In that function you can put any logic which is invariant to user action.
Then comes the process of casting. The Ensemble is offered to the Dialogue scripts. They specify which objects and characters they use, and which states those must have.
When suitable Dialogue is found, a Presenter object is created. The Presenter animates the dialogue, calculating how long the text will take to read, and when it must appear.
The Presenter also carries out any instructions in the Dialogue which change state of Ensemble objects while the scene is played out. This is reaction.
Control now passes to the Story, which renders the scene. Out of the box, Balladeer can render to a character terminal, or in HTML5 for the browser experience. The Dialogue format supports images, and playing audio and video. You have complete freedom to restyle the display using CSS3.
User input can come in the form of free text, or web GUI forms and buttons. That input is passed to the Drama to interpret and act upon.
Balladeer's text parser system is innovative and very flexible. Drama objects can recognize commands of any complexity. You can enable or disable those commands on the fly as required.