ZoneBuilder/Documents/usdf11.txt

===============================================================================
Universal Strife Dialog Format Specification v1.1 - 01/29/09

Written by Braden "Blzut3" Obrzut - admin@maniacsvault.net

Defined with input from:

CodeImp
Gez
Graf Zahl
Quasar
et al.

    Copyright (c) 2009 Braden Obrzut.
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.2
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

===============================================================================

=======================================
I. Grammar / Syntax
=======================================

The grammar and syntax is similar to that of UDMF.  A compliant UDMF parser 
should be applyable to the USDF.  However, it will need to be capable of 
handling sub-blocks.  Unknown sub-blocks should be skipped.

=======================================
II. Implementation Semantics
=======================================

------------------------------------
II.A : Storage and Retrieval of Data
------------------------------------

This is the same as in UDMF.

-----------------------------------
II.B : Storage Within Archive Files
-----------------------------------

There are two options for the USDF lump placement.  This can either be a part 
of the UDMF lump list or standalone.  If used stand alone the lump name 
DIALOGXY is used corresponding with MAPXY.  For UDMF the lump shall be called 
"DIALOG".

--------------------------------
II.C : Implementation Dependence
--------------------------------

USDF also implements the namespace statement.  This has all the same 
requirements as UDMF.

=======================================
III. Standardized Fields
=======================================

The following are required for all USDF complient implementations.  Like UDMF, 
any unknown field/function should be ignored and not treated as an error.

NOTE: "mobj" refers to Strife's conversationIDs and not doom editor numbers or 
      Hexen's spawnids.

---------------------
III.A : Conversations
---------------------

Conversations are groups of pages that can be assigned to a particular object.
Implementors should preserve the IDs to allow for dynamic reassignment through 
scripting although this is not a requirement.  Section III.B covers static 
assignments.

conversation // Starts a dialog.
{
    actor = <integer>; // mobj for this conversation's actor.  If previously 
                       // used, this will override the previous conversation.

    page // Starts a new page.  Pages are automatically numbered starting at 0.
    {
        name   = <string>; // Name that goes in the upper left hand corner
        panel  = <string>; // Name of lump to render as the background.
        voice  = <string>; // Narration sound lump.
        dialog = <string>; // Dialog of the page.

        // jumps to the specified page if the chater has the specified amount 
        // or more of item in their inventory.  This can be repeated as many
        // times as the author wants, but only the first one to evaluate as
        // true takes effect.
        ifitem
        {
            item   = <integer>; // mobj of item to check.
            amount = <integer>; // amount required to be in inventory.
            page   = <integer>; // page to jump to.
        }

        // Choices shall be automatically numbered.
        choice
        {
            text            = <string>;  // Name of the choice.

            // The amount of an item needed to successfully pick this option.
            // This can be repeated, but only the first will be shown (provided 
            // diaplaycost is true).  First to evaluate to true determines 
            // success.
            cost
            {
                item   = <integer>; // Item that is required for this option.
                amount = <integer>; // Minimum amount of the item needed.
            }

            displaycost     = <bool>;    // Weather the cost should be
                                         // displayed with the option.
                                         // Default: true
            yesmessage      = <string>;  // Text to add to console when choice
                                         // is accepted.
            nomessage       = <string>;  // Text to add to console when choice
                                         // is denied.

            log             = <string>;  // LOG entry to use on success.
            giveitem        = <integer>; // Gives the specified item upon
                                         // success.
            // The following are the same as the special for linedefs in UDMF.
            // They are executed on success.
            special         = <integer>;
            arg0            = <integer>;
            arg1            = <integer>;
            arg2            = <integer>;
            arg3            = <integer>;
            arg4            = <integer>;

            nextpage        = <integer>; // Sets the next page.
            closedialog     = <bool>;    // Should the dialog be closed upon
                                         // selecting this choice?
                                         // Default: false
        }
    }
}

-------------------------------
III.B : Including Other Dialogs
-------------------------------

Unlike the original Strife dialog format.  The lump "SCRIPT00" should not be 
included automatically.  Instead the user must specify this behavior by using 
the include function, which takes the name of a lump to include.  Include only 
needs to be available in the global scope and for compatibility reasons, must 
include the result of the script and not act like a preprocessor statement.

include = <string>;

===============================================================================
EOF
===============================================================================