Syntax guide

A Turberfield scene script file represents a sequence of dramatic action. A single file contains one or more scenes, each of which is composed of separate shots. A shot can contain dialogue, audio effects and other directives.

A Scene script adopts the reStructuredText syntax. By using a defined subset of that syntax, along with custom extensions, Turberfield defines a format which visually resembles a traditional screenplay, yet which conforms to a formal data model.

A key feature of the format is that it allows roles to be cast dynamically, such that objects must match the declared criteria for a role. It is nonetheless possible for dialogue to refer to personal attributes such as names, using a mechanism of substitution references.

Naming convention

The file name should contain lower case characters only. It should contain no whitespace or punctuation characters. Underscores should be used to represent spaces.

The file must have a suffix of .rst. If you’d like to distinguish between dialogue text and regular reStructuredText, then give your scene script file a .dlg.rst suffix.

Structure

  1. The file should begin with a comment identifying it as a Turberfield scene script.

  2. The file should contain metadata identifying the author(s) in a field list. The following fields are recommended:

    • author

    • date

    • copyright

  3. The file must contain at least one entity declaration before any scene is defined.

  4. The file must contain at least one scene section which is created by a top-level heading.

  5. Each scene must contain at least one shot section which is created by a second-level heading.

  6. Dialogue is defined by a citation in a shot section. The name given in the citation must match an entity declaration. Dialogue may contain inline markup and substitution references.

  7. Shot sections may also contain one or more of these elements:

Elements

Entity declaration

.. entity:: NAME

The name of an entity should be in upper case.

:roles:

A whitespace separated sequence of other entities. A match for this entity will be considered for those roles. Optional.

:states:

A whitespace separated sequence of dotted paths. Each path must resolve to a Python Enum class member. In addition, a single integer value is also allowed.

The resolution rules allow for hierarchical states, eg:
  • 3 matches integer states 301, 38 and 3.

  • Location.pub matches Location.pub and Location.pub_carpark.

A candidate for this entity must match all these state criteria. Optional.

:types:

A whitespace separated sequence of dotted paths. Each path must resolve to a Python type. A candidate for this entity must be an instance of at least one of these types. Optional.

Property directive

.. property:: ATTRIBUTE [VALUE]

This directive takes no other options.

The property directive acts in two modes.

  • With a single argument it is a getter; it returns the attribute value. This is the mode to use when defining a substitution reference.

  • With two arguments it is a setter; it sets the attribute value. This allows you to modify entities during the delivery of dialogue.

FX directive

.. fx:: PACKAGE RESOURCE

The FX (effects) directive calls up a visual cue or a sound effect. The first argument is the dotted name of the package which contains the asset file. The second argument is the path of the file relative to the package location.

:duration:

Sets the duration (audio playback, display of still image). This value is in milliseconds. Optional.

:loop:

The number of times to play the audio or display a still image.

:offset:

Sets the point in an audio file at which playback begins. This value is in milliseconds.

:label:

A text label for the resource. May contain substitution references.

Condition directive

.. condition:: ATTRIBUTE VALUE

This directive takes no other options.

The condition directive specifies that a comparison be evaluated. If VALUE is supplied in parentheses, it is used as a Regular Expression. Otherwise, it is treated as a plain string, though it may contain substitution references.

The intended purpose of this directive is to mask off sections of dialogue which do not satisfy certain criteria.

Memory directive

.. memory:: STATE

The Memory directive saves a record to the dialogue database. STATE is the dotted path to a Python Enum class value, or else an integer.

This directive lets you capture relationships between entities and store them with a timestamp and a note of explanation.

:subject:

The name of an entity which is primarily associated with STATE. With no object (see below) the interpretation is that the subject is assigned the state. If object is defined, the relationship between subject, object and state is application-specific.

:object:

The name of an entity which is the object of the relationship (subject, state, object). Optional.

Any paragraphs of inline content to this directive are used as a note which accompanies the record in the database. Such paragraphs may contain inline markup and substitution references.