                        ----------------------------
                        | THE WRATH OF SONA ENGINE |
                        |      ETX FILE FORMAT     |
                        ----------------------------
The ETX format is a special text format I invented to assist in the creation                        
of RPG dialog. ETX stands for Extended TeXt, and is much like HTML. It
consists of standard text within quotes, tags, and identifiers.

When the overhead engine receives a spacebar input and determines that an NPC
is next to the main character, the number is derived from the tile ID and the
proper array is called. A name is extracted, and the ETX file is opened. Then,
the ETX engine searches for the exact name specified. When it finds it, the
engine reads the ETX file contents from that point on. After the name, the
rest of the data is called the BODY of the document. Each ETX document has
several BODYs, one for each NPC encounter.

BODY-The body is composed of text and tags. Text is enclosed within quotes to
        maintain 'INPUT #1, TEXT$' compatibility with BASIC dialects. Other
        languages will have no problem working around the quotes-they can
        serve as markers. There is no longer a text limit, due to the variable
        width font routine. However, even with this, if there is too much
        text, it will be trimmed.
        Another thing-be careful about how much text you place if you use the
        WOS engine. The LINE LIMIT is 5, meaning that five lines of text are
        displayed at a time. When asking a question, keep it to one or two
        lines. Check out some of the current ETX files for examples.

CONTROL TAGS-
SYNTAX:
<EXAMPLE> This type of command is active.
<EXAMPLE>*This type of command is planned but not yet active.
<EXAMPLE>@This type of command is disabled for now.

<END> Signals the end of the conversation. MUST BE USED.
        EXAMPLE:
        "TEST"
        "This is a test."
        "<END>"
<MOVE> This tag allows screen movement of the character. It is followed by a
        text enclosed in quotes with a 100 character limit. Legal moves are
        L R U D for Left, Right, Up, and Down. The WOS engine supports moving
        in and out of buildings. In the WOS engine, the direction of the
        character is also built-in. If you need more than 100 moves, just use
        the tag again! The only problem with this tag is it is extremely
        direction-dependant, in that you can make the character move in a
        certain way if he's at one location...but if he's out of place, MOVE
        may not move him to where you want him! So, be careful...this tag is
        powerful...
        WARNING! DO NOT USE THIS TAG TO GO BETWEEN MAP FILES! You can corrupt
        the stack!
        EXAMPLE:
        "TEST"
        "This is a test move. Watch me now"
        " "
        " "
        " "
        " "
        "<MOVE>"
        "UUDLRRUUDDDLLR"
        "<TEXTBOX>"
        "Pretty neat, eh?"
        "<END>"
<EVNTnnn> This tag signals to set EVNT #nnn to 1.
        EXAMPLE:
        "TEST"
        "<EVNT010>"
        "I have set event 10 to TRUE."
        "<END>"
<KILLEVNTnnn> This tag signals to set EVNT #nnn to 0. Useful in dialogue!
        EXAMPLE:
        "TEST"
        "<KILLEVNT010>"
        "Now, I have set event 10 to FALSE."
        "<END>"
<DOEVNTnn> This tag signals the start of a hardcoded sequence or a special
        battle. This is how you can add "boss" monsters to the game easily, or
        this could be an easier way to show animations. The actual sequences
        MUST be hardcoded into a SUB (if you're smart! and I know you are).
        See SUB doevent (eventnumber) in WOS-4.BAS for an example.
        EXAMPLE:
        "TEST"
        "I will now start hardcoded event"
        "number 5. Watch me!"
        " "
        " "
        " "
        "<DOEVNT05>"
        "<END>"
<TREASUREnn> This tag works with <EVNTnn> to work with treasure boxes and such
        in RPGs. nn is a custom number from 00-99 that denotes the nature of
        the treasure. So, you could have 100 possible types of treasure using
        this format. However, if you increase the nn to nnn, you'll have 1000
        possible treasures. Any more than that is probably a waste of code,
        especially when you can have 800 placings of treasure type 05, for
        example. Also, if you want to place infinite treasure, don't use the
        <EVNTnn> tag and the treasure placed will be always available! This
        works well with special things in RPG games, like healing orbs and
        such that are permanantly active.
        EXAMPLE:
        "TEST"
        "<TREASURE06>"
        "I just gave you treasure #6!"
        "<END>"
<COLORnnn> Changes the current text color. Useful for when changing character
        text in dialogue. Use a different color for each character! If COLOR
        is not specified, a default color will be used. As of beta 0.15, this
        tag has no effect in the WOS engine, due to the bitmapped font.
        However, I am leaving this tag in the official format.
        no example, command not used in WOS
<PAY> Signals a pay box to appear during conversation. It is linked with <YES>
        and <NO>. <PAY> can do a <JUMP> only, it will never do a <JUMPBACK>,
        so the <YES> and <NO> have to follow the <PAY>. You can, however, get
        extremely sneaky with this tag because it will land on the first-found
        tag it's calling for...so you bury the tags deep inside the document,
        possibly skipping many lines of text on the way there! The <PAY> tag
        will, by the way, default to <NO> even if the answer was <YES>...if
        the character doesn't have the cash for the payment...also, directly
        after the <PAY> tag, on the next line, MUST be an actual amount to
        pay! This number MUST be an integer (short or long).
        EXAMPLE:
        "TEST"
        "Can you give me 1000 moolah?"
        "<PAY>"
        1000
        "<YES>"
        "Yay! I got your money!"
        "<END>"
        "<NO>"
        "What, you're not gonna pay me what"
        "I ask for? Well fine then!"
        "<END>"
<QUESTION> Like <PAY>, but functions only to ask a question.
        EXAMPLE:
        "TEST"
        "Are you going to vote WOS as the"
        "best QBRPG ever made?"
        "<QUESTION>"
        "<YES>"
        "Alrighty then! I'll send you a bowl"
        "of frosted flakes as payment!"
        "<END>"
        "<NO>"
        "What!! No! What are you smoking?!"
        "<END>"
BRANCHING TAGS-
<YES> This is <JUMP>ed to when the payment is made or a question is answered
        'yes'. In the future, this will also be used with <CHECKnnEVNT>.
<NO> This is <JUMP>ed to when the payment is not made or the player has 
        answered 'no' to a question. It is possible to have many <YES> and
        <PAY> or <QUESTION> tags, but only one 'default' <NO> tag. In the
        future, this will also be used with <CHECKnnEVNT>.
<CUSTnn> This is a custom tag. The nn is a number from 00 to 99, specially
        called by <JUMP> or <JUMPBACK>.
<JUMPnn> This jumps forward in the document, and looks for a custom tag.
<JUMPBACKnn> The <JUMP> tag jumps forward only-the <JUMPBACK> tag will close
        the ETX file, re-open it, and search for the custom tag from the very
        start of the document. Although at first this appears to be a useless
        tag, couple this with <NEWETX> for some interesting effects!
<ONEVNTnnnJUMPxx> This tag will <JUMP> to CUSTxx when EVNT nn=1.
<ONEVNTnnnJUMPBACKxx> Like the last tag, but with the <JUMPBACK> command.
<CHECKnnEVNT>*This upcoming tag verifies the TRUTH of several event flags.
        nn denotes the number of events to check. After the tag, the next
        lines must contain the event numbers to verify. If any of the events
        are FALSE, the program will go to the next found <NO> tag. If they
        are all TRUE, it will go to the next found <YES> tag. If the program
        cannot find the total number of events to check, it may error out, so
        you must be careful with this tag.

NON-OFFICIAL EXTENSIONS USED IN THE WRATH OF SONA-
<SCROLLY_D> This is the first of the planned scrolly functions. It takes two
        GIF images and scrolls them downward. When using this, you need to
        give three strings: The name of the GIF for the Top, the one for the
        Bottom, and the PAL1030 file that will be used for the fade-in. And
        remember to use BLACKIMG.EXE to kill the GIF palette so you have an
        invisible load...
        EXAMPLE:
        "<SCROLLY_D>"
        "SCREENS\SONASCRL.GIF"
        "SCREENS\SONASCR2.GIF"
        "PALETTES\666"
        Remember to leave out the .PAL extension, and to add the path!
<SHOWFACE> Loads a face file and places it on the screen. The type (A or B)
        plus the index number (0000-????) must be a string on the next line.
        The types (A or B) are detailed in the file 021A021B.TXT. The index
        number must be four bytes long regardless of the amount. Starting with
        beta 0.21, you are also required to use FACEBOX if you want it,
        because it is no longer automatically called.
<SHOWCHARn>@Like SHOWFACE, but specifically loads the face file of character
        n (n being 1-4).
<FACEBOX> Creates a new face border. This command is no longer automatic and
        MUST be used if you plan to show the face border.
<LOADMUSIC> This command will load a new soundtrack when in conversation.
        Useful for talking with important people. The next line after this tag
        should be the filename (like "MUSIC\WOS-SNG1.GDM") like that...see
        TRATH in PASS1.ETX for an example.
<RESTOREMUSIC> This command will restore the default map music.
<FADEMUSIC> This command will fade out the currently playing music.
<FADEMUSICFAST> This command will fade out the currently playing music FAST.
<WARP> This is like the old LITEWARP and DARKWARP, but this can now do any
        color fade. Just enter the RGB values after the X and Y.
<BLEND> Blends two palettes. This must be done due to a DashX error, plus it
        makes it a lot simpler on code to have one command instead of six for
        the same basic concept! Must specify source and destination palettes.
<CHANGETILE> This command instantly changes any tile to another ID. X, Y,
        Layer, and ID must be specified. Also, EVNT can be specified next, but
        if not setting an event then just place a 0. This is like the
        TILECHANGE command in the MAP specs, but the EVNT comes last instead
        of first. This command immediately updates the screen after executing.
<CHANGEID> Like <CHANGETILE> but does not update the screen. Can be used with
        <CHANGETILE> to give the appearance of several tiles changing at once.
<TEXTBOX> Displays a textbox =)
        EXAMPLE:
        See the <MOVE> command
<DELAY> Adds a delay factor. Useful when used with CHANGETILE or similar
        commands. You must specify the delay in 1/60ths of a second.
<CHANGEALLID> Similar in nature to the CHANGEID tag, but instead of acting on
        a single tile, it acts on ALL of a certain tile. Specify Layer, Tile
        ID to change, and Tile ID to change to.
<CHANGEALLTILE> Like CHANGEALLID, but also updates the screen afterwards.
<UPDATE> Updates the screen. Useful for showing normal animations during a
        dialogue session.
<NEGATIVE> This uses DashX's VSNegative command to negative the palette.
<LOOP>*This upcoming tag allows many commands to be executed without having
        to type them all out again and again. You must specify the number of
        times the loop will take place. This number can be no lower than 2,
        and no higher than 32767 (for now).
<ENDLOOP>*Ends an active loop.
<NEWETX> Changes the default ETX file. All future dialogues will use the new
        file. Couple this with <JUMPBACK> and...
<CHANGESPRITE> A very cool command, this changes the default character sprite!
        This can be used during ETX-controlled cinemas. You must specify the
        filename of the PUT file to use. See the MAP command "SPRITECHANGE".
<EFFECTnn>*An upcoming command, this activates one of a number of prebuilt
        special effects. The planned effects are:
               -01- Mosaic Fade
               -02- Ripple
               -03- Ripple Fadeout
               -04- Ripple Fadein
               -05- FuzzIt (tm)

SHOP EXTENSIONS (NON-OFFICIAL)-
<WEAPONSHOP> Adds a weapon shop to the game. Followed by 5 integers, these
        will be the weapons to sell. Everything else is handled by the engine.
<ITEMSHOP> Like WEAPONSHOP, but for items instead. Same rules apply.
<ARMORSHOP> Same.
<SHIELDSHOP> Same.
<HEADGEARSHOP> Same.
<SPELLSHOP> Same.

CHARACTER EXTENSIONS (NON-OFFICIAL)-
<ADDCHAR> This HIGHLY TECHNICAL ETX command adds a character to the party. If
        a character slot is opened, the data you feed the ETX engine adds a
        character to fit the data. This tag is followed by a grand total of
        57 pieces of information, describing the character. Use the YES and NO
        tags with this command. Also, make use of the event schedule for this,
        because to keep codesize down, we forwent any types of error checking
        and adding the same character twice is a possibility, so use the EVNT
        tags to prevent this from taking place!
        ORDER OF DATA ENTRY:
        Array NStat (28 pieces of data) INTEGER
        Array Nbig (2 pieces of data) LONG INTEGER
        Arrat Nst (7 pieces of data) STRING
        Array Spl (20 pieces of data) INTEGER
        Note that the format for this command is temporary, future versions
        will be a little more dynamic and will not require as much data. I
        will set up a database that contains all this info, and all you'll
        have to do is <ADDCHARnn> and the rest will be handled automatically,
        I did it the way it is now because of time constraints!
<REMOVECHARnn> Removes character ID nn from the current party, frees the slot,
        and reorganizes the slots if needed. Use the <YES> and <NO> tags for
        this command as well. Actually, because of time constraints, I have
        not yet added the reorganizing routine yet, so if like say you have
        three characters and character 2 leaves, you have character 1 and
        character 3...I'll change this for the next version!
<ADDEXPnnnnn>*Adds nnnnn experience points to the party (even no matter how
        many chars). If any chars break their XP limit for their level, they
        will gain a level upon the next battle. This number is an integer, so
        keep in mind that the limit is 32767! I may expand on this command in
        the future to support long integers, but seriously...what is worth
        such a large number of experience points?!

By using the ETX file format, you can cut the amount of internal code down
drastically. Of course, writing ETX documents and making an engine to read
them are two wholly different things. You should be familiar with the basic
concepts of variables, flags, and events of an RPG. The WOS ETX reader has
been specially designed to work with the game-it's the first game I've used
the format in. You can take the reader code and implement it into your own
games if you wish, or use the code as a basis for building your own ETX
reader. If you have any additions to the ETX format, you are encouraged to
make them. If you wish to add them to the 'official' ETX format, just send
your suggestions our way-

        kaddash@rocketmail.com

Also, feel free to contact us if you need any help implementing ETX in your
games!

ETX Format is public domain.

Contributions so far:
        19day
        hydroXide

THE WRATH OF SONA, WOS, Sona, and all names contained within are all copyright
1997,1998 Dave Perry

All examples in this text file, and all specifications, are subject to change
without notice. Because the ETX format is public domain, several different
versions of ETX may someday exist, and not all ETX files are guaranteed to
work with all ETX readers. The 'official' ETX format should be supported by
all ETX readers. If you have a new idea, PLEASE let me know so I can add it to
the official format and all users of ETX can be informed of updates!

Any extensions added by personal users of ETX are perfectly normal... :)

And finally...heheh...I am also working on an integrity tester. It will scan
through an ETX file and attempt to find flaws. Kewl, eh? It cannot find all
flaws because of the flexible and sneaky ETX nature, but it can detect missing
commands, like a missing <NO> tag after a <PAY> tag.
==============================================================================
MORE EXAMPLES OF ETX FORMAT-
This example is a treasure example. When a treasure box is opened, a check is
made for event 67. If event 67 is TRUE (treasure is taken) jump to 53. If not,
then the player has not yet gotten the treasure. It will then be procured.

"TREASURE045"
"<ONEVNT67JUMP53>" 
"<TREASURE06>" 
"<EVNT67>" 
"You find blablabla..." 
"<END>" 
"<CUST53>" 
"The treasure chest is empty."
"<END>" 

This is like the last example, but instead of automatically taking the
treasure, the player is asked if they want it or not. Note that the tag for
the treasure must precede any text. Also, unlike the last example, you MUST
place the treasure tag after the YES, because when the engine reads the
treasure tag, it credits the treasure. The EVNT tag will prevent any future
takings of this treasure. However, if you use CHANGEID or CHANGETILE on the
treasure on the map, then the treasure tile can be turned into a nonobject,
making future takings impossible anyways =)

"TREASURE045"
"<ONEVNT67JUMP53>" 
"You find blablabla..." 
"Do you take it?"
"<QUESTION>" 
"<YES>"
"<TREASURE06>" 
"<EVNT67>" 
"Treasure blablabla taken."
"<END>"
"<NO>"
"You leave the treasure alone."
"<END>" 
"<CUST53>" 
"The treasure chest is empty."
"<END>" 

This is a simple example of infinite treasure. A lot easier, eh?

"TREASURE045"
"<TREASURE09>"
"You find blablabla thingie"
"<END>"

When a crucial treasure is found, you could warp the character back to the
beginning of a dungeon...
"TREASURE045"
"<TREASURE12>"
"You find the blabla vital thingie..."
" "
" "
" "
" "
"<WARP>"
4,7
"Back to the beginning.."
"<END>"

Note the four " " quotes...

Testing several events quickly:
"CHECKINGEVENTS"
"<CHECK04EVNT>"
34
56
41
12
"<YES>"
"All events verified."
"<END>"
"<NO>"
"One or more events false."
"<END>"

This can also be written as:
"CHECKINGEVENTS"
"<CHECK04EVNT>"
34,56,41,12
"<YES>"
"All events verified."
"<END>"
"<NO>"
"One or more events false."
"<END>"

The interpreter doesn't care as long as the commas are present; a space does
not work, for it will cause an error or an incorrect interpretation.

Interesting PAY use:
"PAYDUDE"
"Do you want some money?"
"<PAY>"
-1000
"<YES>"
"You get 1000 moolah!"
"<END>"
"<NO>"
"You get the shaft!"
"<END>"

PAY can be used to GIVE you money! Because we use a signed integer (actually,
we have no choice =), a negative amount creates an addition to your money
pool. Remember from Algebra..."a positive minus a negative is a positive"...

A certain sequence in the current build has you finding a treasure chest and
going back and talking to someone else to gain a "reward". Linking events
among many ETX files becomes very complex, but is extremely cool when used
properly. Try searching for secrets in the Southern Pass...

One drawback of the ETX system involves going to battle and returning without
possibility of instant text. However, there is a most sneaky way to simulate
this effect. By using <KILLEVNT001> before a major battle, you can place a
"BEGIN" character in your ETX file and have it automatically open when the
battle has been won. Be careful in this however-you cannot have more than one
"BEGIN" in any ETX file, but by careful use of control tags (like CHECKEVNT)
you can use multiple BEGIN sequences in one ETX file. ETX is so sneaky!!!
