MENU SCRIPT TUTORIAL - Part 1

Author: Jaeden "Sifo Dyas" al'Raec Ruiner (Fluffy)
Website: http://www.wayoftheleaf.net/
email: JaedenRuiner@wayoftheleaf.net

TABLE OF CONTENTS

1 - Discalimer
2 - Acknowledgements
3 - Basic Structure
4 - Syntax Diagrams
4a - Symbols
4b - Reserved Words (tags)
4c - uiScript Commands
5 - Usage
6 - Constants

--------------------------------------------------------------------------
1.	Discalaimer

  First of all, I'm a techy, not a a tech writer, so forgive me if I'm a tad
confusing at times.  Mostly, I like to play around with code and machines,
because I've always had a knack for working with either.  This tutorial is
INCOMPLETE, for there are several things I have no way of knowing what they
do without playing around horrendously with them.  As my own work has not
required the usage of such things, I don't know how to use them yet.

--------------------------------------------------------------------------
2.	Acknowledgements

LucasArts, Ravensoft, and the whole Jedi Knight Gaming community.  You all
Rock.  Really, these games have been more pure entertaining joy for may, than
any other game series.  I love games in and of themselves, but when it comes
the fun of wielding a lightsaber and hacking off pieces of enemies, nothing else
comes close.

--------------------------------------------------------------------------
3.	Basic Structure

  In all coding and Scripting formats, there is a standard structure for the
processing of the text.  The Menus are a scripted format, much like HTML.  They
execute no code based commands, but more are interpreted by an Engine.  HTML does
nothing on its own, but your internet browser "interprets" what the tags mean, and
does the code on your system to represent it.

First of all, much like C, C++, and Java, the .Menu scripts utilize the open and 
close brace " { } " for the declaration of a block of information.  All menus thus
start with a "{" and end with a "}".  

Example Menu:

{
   menuDef
    {
        itemDef
          {
          }
    }
}

Notice for each entry, one must have the Open and Close Brace to start and end the
block for the script.

The rest is just Syntax.

--------------------------------------------------------------------------
4.	Syntax Definitions

Here I will try to explain all the the little nuances I have discovered so far.  A little
vernacular help for those not in the coding lifestyle:
  Boolean, Bool  : 0 or 1, 0 = False, 1 = True
  Integer, Int   : Negative or Positive WHOLE numbers.  ie: -5, 3, 0, 1.  NOT:  -5.5
  String         : Quoted text.  ie:  "Hello". NOT: Hello, 
  STR            : Dereferenced String file Identifier.  ie: @MENUS_HEDI_HM
  Real           : Decimal number between -1 and 1, ie: 0.6 -0.5, 0, 1, -1.
  Coord          : Integer between 0 and 640 for X values, 0 and 480 for Y values.
  identifier     : Unquoted text referencing an identifer string, defined by NAME or GROUP.
  |              : Syntactically used to defined multpile possible parameters.  ie:  x [STRING] | [INT], thus X will take either a string or an integer as its parameter.
  []             : Used to signify the TYPE of the paramter entry, no brackets means direct TEXT.
  CONSTANT       : Constant defined in MENUDEF.H

-4a. Symbols

//                  - Remark, unparsed (unprocessed) line of text, usually to describe some information
/* */               - Start and End of a Remark block, usually for multiple lines of text to comment out of script processing.
{                   - Open Brace, start block of script code.
}                   - Close Brace, end block of script code.
@                   - At sign, derefencing tag for STRING files.  ie:  MENUS.STR, SP_INGAME.STR
"                   - Quote, Text delimiter, for names and other direct "strings" to use in script

-4b. Reserved Words (Tags)

=====Block Tags
  These require an Open and Close Brace for defining a series of tags and commands.

action              - Item Action block for "clickable" types.  Edit Fields, Buttons (mostly), Multi-lists, and Listboxes.
cvarStrList         - Item cvar String List for cvar names and values for MULTI types items.
  Syntax:        Either a BLOCK using { } or the 'feeder' command, which references the information provided by the specific feeder type decalared before the cvarStrList is defined.
disableCvar         - item disable block for CVAR string values used directly following cvarTest.
hideCvar            - Item Hide Block for CVAR string Values used directly following cvarTest.
itemDef             - Item definition block for within a menu.
menuDef             - Main Menu definition block.
mouseEnter          - Item Mouse Over definition block.  Code happens when mouse enters the rect of the Item.  (usually for highlighting).
mouseExit           - Item Mouse Over Definition block.  Code happens when mouse exits the rect of the Item.  (usually for highlighting).
onClose             - Menu Close event Block.  Code happens when the menu is closed.
onESC               - Menu ESC event Block.  Code happens when the ESC key is pressed while in a menu, usually a termination or closing script.
onFocus             - Item Focus event block.  Code happens when an item recieves focus (clicked by mouse, or reached through arrow keys on the keyboard) 
onOpen              - Menu Open event block.  Code happens when the menu is first opened.
showCvar            - Item show block for CVAR string values used directly following cvarTest.

=====Single Line Tags

asset_model         - Item Tag, for declaring the cvar that contains the model name to display.
  Syntax:        asset_model [STRING] - The String is a CVAR containing the model name, ie: jedi_hm.

autowrapped         - Item Command., Used with ITEM_TYPE_TEXTSCROLL for auto wrapping text within the rect provided.
  Syntax:        autowrapped

backcolor           - Item Tag. for defining the background color of the item.
  Syntax:        backcolor [R REAL] [G REAL] [B REAL] [A REAL]  - R G B A meaning red green blue and alpha

background          - Item Tag. used with quotations to give the relative path and name of the image shader for the background of the item, sized to the rect provided.
  Syntax:        background [STRING] - string is relative path of the image to use as the background.

border              - Item Tag. border style to show.
  Syntax:        border [INT] - values found in MENUDEF.H

bordercolor         - Item Tag. color of the the border rectangle.
  Syntax:        bordercolor [R REAL] [G REAL] [B REAL] [A REAL]  - R G B A meaning red green blue and alpha

bordersize          - Item Tag. width of the line used for the border rectangle
  Syntax:        bordersize [INT]

close               - Item Command. Used to close specific internal items/menus/or keyworld "all".
  Syntax:        close [IDENTIFIER] | ALL

cvar                - Item Tag.  This is used in many occations.  With EDITFIELDS, it is the value that is contained within the field.  With MULTI's it is the cvar to recieve the values provided by cvarStrList
  Syntax:        cvar [STRING] - name of cvar.

cvarSubString       - Item Tag.  This is used to test for a "substring" within the cvar string.
  Syntax:        cvarSubString - placed at the END of the active cvar testing block.  

cvarTest            - Item Tag.  This is used to test the cvar provided for a value.  The results of the test is determined by the following block command.
  Syntax:        cvarTest [STRING] - cvar to test.

decoration          - Item Command.  This defines the item as purely a decoration with not actions or focusing capabilities.
  Syntax:        decoration

descAlignment       - Menu Tag.  This defines the alignment of the Description text as defined per item with "descText".
  Syntax:        descAlignment CONSTANT

descColor           - Menu Tag.  This defines the color of the description text.
  Syntax:        descColor [R REAL] [G REAL] [B REAL] [A REAL]  - R G B A meaning red green blue and alpha

descScale           - Menu Tag.  This defines the font scale of the description text.
  Syntax:        descScale [REAL]

descText            - Item Tag.  This defines the text to place in the description text area defined by the Menu Tags.
  Syntax:        descText [STRING] | [STR]

descTextStyle       - Menu Tag.  This defines the style of the description text.
  Syntax:        descTextStyle [INT] - 

descX               - Menu Tag.  This defines the X coordinates of the description text.
  Syntax:        descX [INT]

descY               - Menu Tag.  This defines the Y coordinates of the description text.
  Syntax:        descY [INT]

disableColor        - Menu tag.  This defines the color of any items text when it is disabled by cvarTest/disableCvar block.      
  Syntax:        disableColor [R REAL] [G REAL] [B REAL] [A REAL]  - R G B A meaning red green blue and alpha

elementheight       - Item Tag.  This is used in conjunction with the LISTBOX item type, to define the height of each element in the list box.
  Syntax:        elementheight [INT]

elementwidth        - Item Tag.  This is used in conjunction with the LISTBOX item type, to define the width of each element in the list box.
  Syntax:        elementwidth [INT]

elementtype         - Item Tag.  This is used in conjunction with the LISTBOX item type, to define the type the listbox entries will be.  ie: Image, Text, etc.
  Syntax:        elementtype [INT] - values found in MENUDEF.H

exec                - Item Command.  Execute console command.  Usually this is used as a "vstr [cvar]" methodology, so that one cvar can effectively control many desired effects, and the action taken at the end is to execute that CVARs internal command.
  Syntax:        exec [STRING]

fadeAmount          - Menu Tag.  Amount to adjust alpha per cycle
  Syntax:        fadeAmount [REAL]

fadeClamp           - Menu Tag.  Sets the fadeup alpha.
  Syntax:        fadeClamp [REAL]

fadeCycle           - How Often fade happens in milliseconds.
  Syntax:        fadeCycle [INT]

fadeIn              - Item/Menu Command. Executes alpha fadein. 
  Syntax:        fadeIn [IDENTIFIER]

feeder              - Item Tag.  This is used in conjunction with the MENUDEF.H file, utilized for MULTI's and LISTBOX's where internal JKA code provides the "list" within the feeder.  The values are predefinied constants.
  Syntax:        feeder [INT] - Values found in MENUDEF.H

focusColor          - Item Tag.  This is the foreground color given to the item when it retains the focus from mouse clicks or keyboard entry.
  Syntax:        focusColor [R REAL] [G REAL] [B REAL] [A REAL]  - R G B A meaning red green blue and alpha

font                - Item Tag.  This is the font used to display the item's text.
  Syntax:        font [INT] - Unknown what the values are, play with them, and find the fonts you like.

forecolor           - Item Tag.  Current Foreground color of the item.
  Syntax:        forecolor [R REAL] [G REAL] [B REAL] [A REAL]  - R G B A meaning red green blue and alpha

fullscreen          - Menu Tag.  Boolean setting for if the menu is a full screen menu, or if it is just a window superimposed on the current screen.
  Syntax:        fullscreen [BOOL]

group               - Item Tag.  Defines the group of items this item belongs to.
  Syntax:        group [IDENTIFIER]

hide                - Item Command.  Hides a specific Item(s) by name or by group identifier.
  Syntax:        hide [IDENTIFIER]

horizontalscroll    - item Tag.  Used in conjunction with LISTBOX's to defined a visible horizontal scroll bar.
  Syntax:        horizontalscroll

isCharacter         - Item Tag.  Used with model display windows,  NO real understanding why it exists, just that in the Character menu, it is used to say the current model "is the character".
  Syntax:        isCharacter [BOOL]

model_angle         - Item Tag.  360 Degree angle definition for a model display window.
  Syntax:        model_angle [INT]

model_fovx          - Item Tag.  Field of View via the X axis of the model, for model display windows.
  Syntax:        model_fovx [INT]

model_fovy          - Item Tag.  Field of View via the Y axis of the model, for model display windows.
  Syntax:        model_fovy [INT]

model_g2anim        - Item Tag.  Animation String for the display of the model, in a model display window.
  Syntax:        model_g2anim [STRING] - the animation tag, like "BOTH_WALK1".

model_g2mins        - Item Tag.  Have no idea, but it is used in model display windows.
  Syntax:        model_g2mins [INT] [INT] [INT] - no idea what these are for, play with them.  If you find out, let me know.

model_g2maxs        - Item Tag.  Have no idea, but it is used in model display windows.
  Syntax:        model_g2maxs [INT] [INT] [INT] - no idea what these are for, play with them.  if you find out, let me know.

model_rotation      - Item Tag.  Model Rotation speed, for model display windows.
  Syntax:        model_rotation [INT]

name                - Item/Menu Tag.  Identifer of the current Item for use with HIDE, SHOW, OPEN, CLOSE commands.
  Syntax:        name [IDENTIFIER]

open                - Item Command.  Opens a menu, as defined by the menuDefs NAME tag.
  Syntax:        open [IDENTIFIER]

play                - Item Command.  Plays a sound file, the string parameter is in PK3 relative path information, with no extension on the filename.
  Syntax:        play [STRING]

rect                - Item/Menu Tag.  Defines the Rectangle coordinates of the item/menu.  Set in X Y Width Height format.
  Syntax:        rect [X COORD] [Y COORD] [W COORD] [H COORD] - X Y W H respectively X,Y Coords, Width and Height.

setCvar             - Item/Menu Command.  Must be within an active block, like a mouse enter, onClose, or Action block, to set a cvar to a specific value.
  Syntax:        setCvar [NAME STRING] [VALUE STRING]

setFocus            - Item/Menu Command.  Must be within an active block.  Sets the current Item control to have the focus.  Naturally, triggering the items onFocus event if it has one defined.
  Syntax:        setFocus [IDENTIFIER]

setItemBackground   - Item Command.  Sets by name a specific Item's background.
  Syntax:        setItemBackground [ITEM IDENTIFIER] [BG STRING] - BG being the background.

setItemColor        - Item Command.  Sets by name a specific Item's foreground color.
  Syntax:        setItemColor [ITEM IDENTIFIER] [R REAL] [G REAL] [B REAL] [A REAL]  - R G B A meaning red green blue and alpha

setItemRect         - Item Command.  Sets by name a specific Item's rectangle.  Most helpful in button glow highlight shaders.
  Syntax:        setItemRect [ITEM IDENTIFIER] [X COORD] [Y COORD] [W COORD] [H COORD] - X,Y,W,H resepctively X,Y coords, Width and Height

setItemText         - Item Command.  Sets by name a specific Item's display text.
  Syntax:        setItemText [ITEM IDENTIFIER] [STRING | STR]

show                - Item/Menu Command.  Must be within an active block, and makes visible an Item by Name.
  Syntax:        show [IDENTIFIER]

style               - Item Tag.  Defines the Item's Window Style.
  Syntax:        style [CONSTANT] - values found in MENUDEF.H  WINDOW_STYLE_*

text                - Item Tag.  Defines the Item's display text.
  Syntax:        text [STRING | STR]

textAlign           - Item Tag.  Defines the alignment style of the item's display text.
  Syntax:        textAlign [CONSTANT] - Values found in MENUDEF.H

textAlignx          - Item Tag.  Defines the display text's X alignment relative to the Alignment style.
  Syntax:        textAlignx [INT]

textAligny          - Item Tag.  Defines the dispaly text's Y alignment relative...to what I am not sure.
  Syntax:        textAligny [INT]

textScale           - Item Tag.  Defines the Scale of the display text in reference to the font type of the item.
  Syntax:        textScale [REAL]

textStyle           - Item Tag.  Defines the style of the display text.  What this is, i do not know.
  Syntax:        textStyle [INT] - Unknown, possibly found in MENUDEF.H

type                - Item Tag.  Defines the TYPE of the Item, be it a button, listbox, editfield, multi, etc.
  Syntax:        type [CONSTANT] - Values found in MENUDEF.H  ITEM_TYPE_*

uiScript            - Item/Menu Command.  Must exist within an active block, and executes a predetermined script within the JKA code.  UNEDITABLE!!!!
  Syntax:        uiscript [STRING] - list of commands and function in next chapter.

visible             - Item Tag.  Boolen that defines whether or not the item is defaultly visible or not.
  Syntax:        visible [BOOL]

-4c. uiScript Commands
I'm listing these because I have found out the basics of what they do.  Not to say we can do a damn thing about this functionality, it is just helpful
to know they exist.

getcharscvars                  - Transfers values from the G_CHAR_* cvars to the UI_CHAR_* cvars.
character                      - Dunno.
resetsabercvardefaults         - Resets the UI_SABER_* cvar values to their defaults.
getsabercvars                  - Transfers values from the G_SABER_* cvars to the UI_SABER_* cvars.
updatefightingstylechoices     - Updates the ingame fighting style values, found in UI_FIGHTINGSTYLESALLOWED and UI_CURRENTFIGHTINGSTYLE
saber_hilt                     - Updates the current saber hilt model, for use with Model display windows.
saber_color                    - Updates the current saber blade color, for use with model display windows.
saber2_hilt                    - Updates the current saber2 hilt model, for use with Model display windows.
saber2_color                   - Updates the current saber2 blade color, for use with model display windows.
updatesabercvars               - Transfers the values back from the UI_SABER_* cvars to the G_SABER_* cvars.  (for use between saving the game)
closesabermenu                 - Closes Saber menu.  Dont' know why this is used instead of "close all".
saber_type                     - Updates the current saber type, for model dispaly windows.
startgame                      - Starts the game, intro text and movie, landing you a map yavin1b
startmap [ID]                  - Starts a map provided by the [MAPNAME IDENTIFIER] following.  
load_auto                      - Loads the auto save file.
load_quick                     - Loads the quick save file.
decrementforcepowerlevel       - Decrements the last force power incremented.
initallocforepower [STRING]    - Initializes the visual HEX diagrams of the forcepower previded by the [STRING], ie: "absorb", "jump", etc.
showforceleveldesc             - Activates the current force powers RANK description, for Jump level 1,2,3, etc.
affectforcepowerlevel [STRING] - Affects force power provided by the [STRING] by one point.  Handles the visual HEX diagram display as well.
loadcontrols                   - Loads the current control set for visual referencing in the controls menu.
savecontrols                   - Saves the current control set.
closeingame                    - CLoses the ingame menu.  Again don't know why they don't use "close all"
update [ID]                    - Updates specific control based items, based off of the [IDENTIFER], used for mouse pitch, force feedback, etc.
quit                           - Quits the game.

--------------------------------------------------------------------------
5.	Usage


Basically I plan to try and give some help with the Menu declarations so you can understand my syntax diagrams more clearly.  
Primarily this is for the events and the cvar tests.


EXAMPLE: cvarTest 

name        A
cvarTest    "new_cvar"
showCvar    { "0" }

   The item will show ONLY when new_cvar equals "0", and yes these are all STRING values, there are no "byte" or numerics 
here.  If you don't understand don't worry, it simply means you cannot do "math" with these values.

name        B
cvarTest    "new_cvar"
hideCvar    { "0" }
 
   Unlike the first example, this one will only show when new_cvar DOES NOT equal "0"

name        C
cvarTest    "new_cvar"
hideCvar
{
  "0"
  "1"
  "2"
}

   This one shows that you can have multpile values for any effect, thus this one will hide if the value of new_cvar is 0, 1, or 2.  
however, for anything else the item will become visible.

EXAMPLE: ITEM_TYPE_MULTI

name MULTI
type ITEM_TYPE_MULTI
cvar "new_cvar"
cvarStrList
{
   "Hello" "2"
   "Boo"   "1"
   "Goodbye" "0"
   "A brave new world "4"
}

  With an item like this on the menu, you can click it and it will cycle from top to bottom through that list.  YOu will see on the screen
the text HELLO, BOO, GOODBYE, and A BRAVE NEW WORLD.  However, the cvar "new_cvar" will be set to the values respectively, 2, 1, 0, and 4.  
In the this whole menu definition, while cycling through this MULTI, if GoodBye is showed, B and C will be hidden, while A is visible.  if 
Hello and Boo are showed, A and C will be hidden.  And if "A Brave New world" is visible, B and C will be visible.

Also using the same name with cvarTest can be quite powerful.

name A
cvarTest "new"
showCvar { "0" }

name A
cvarTest "new"
showCvar { "1" }

name A
cvarTest "new"
showCvar { "2" }

name Button
action
{
  show A
}

  Now when you click on the button, it's action will show the item A, which happens to be three items.  Yet, the cvar "New" will control which one 
is actually displayed.

EXAMPLE: exec

  This is by far the most poweful command you will have at your disposal unless you do actual code modifications, and rewrite the interface scripting.

name Multi
type ITEM_TYPE_MULTI
cvar "new_cvar"
cvarStrList
{
   "Hello" "echo hello; helpusobi 1; wait 25; setforcejump 3; wait 25; helpusobi 0"
   "Boo"   "echo Boo"
}

name button
type ITEM_TYPE_BUTTON
action
{
  exec "vstr new_cvar"
}

  Now when the button is clicked, it will try to execute console command "vstr new_cvar"  if Hello is visible, this 
will use cheats to set your force jump to level 3 as an example.  I use this to set multiple cvars and other control functions, as well
as the defaults using them to start the approprate map after mission selection.  The mission selection screen sets the tier_mapname, and 
the weapon selection begin game button, executes the command "vstr tier_mapname".

EXAMPLE: MULTI Decoration

  This is simply a helpful tool to realize that the Cvar used in a multi will determine what is INITIALLY visible as well as what you select.
Thus if you declare a MULTI control to be a DECORATION, you cannot change the value, but you can control internally what is displayed via the 
cvar present.

name MULTI
text "Current Style:"
type ITEM_TYPE_MULTI
cvar "ui_currentfightingstyle"
cvarStrList
{
   "FAST" "0"
   "MEDIUM" "1"
   "STRONG" "2"
   "DUAL"  "3"
   "STAFF" "4"
}
decoration

Now when the menu is opened, and this item is visible, whatever value is in ui_currentfightingstyle will show up as the respective string name.

--------------------------------------------------------------------------
6.	Constants

These are the Primary constants that are used in the Menu Script files.

TAG:  type

ITEM_TYPE_TEXT                          - simple text
ITEM_TYPE_BUTTON                        - button, basically text with a border 
ITEM_TYPE_RADIOBUTTON                   - toggle button, may be grouped 
ITEM_TYPE_CHECKBOX                      - check box
ITEM_TYPE_EDITFIELD                     - editable text, associated with a cvar
ITEM_TYPE_COMBO                         - drop down list
ITEM_TYPE_LISTBOX                       - scrollable list  
ITEM_TYPE_MODEL                         - model
ITEM_TYPE_OWNERDRAW                     - owner draw, name specs what it is
ITEM_TYPE_NUMERICFIELD                  - editable text, associated with a cvar
ITEM_TYPE_SLIDER                        - mouse speed, volume, etc.
ITEM_TYPE_YESNO                         - yes no cvar setting
ITEM_TYPE_MULTI                         - multiple list setting, enumerated
ITEM_TYPE_BIND                          - multiple list setting, enumerated
ITEM_TYPE_TEXTSCROLL                    - scrolls text

TAG:  textAlign
    
ITEM_ALIGN_LEFT                         - left alignment
ITEM_ALIGN_CENTER                       - center alignment
ITEM_ALIGN_RIGH                         - right alignment

TAG:  textstyle

ITEM_TEXTSTYLE_NORMAL                   - normal text
ITEM_TEXTSTYLE_BLINK                    - fast blinking
ITEM_TEXTSTYLE_PULSE                    - slow pulsing
ITEM_TEXTSTYLE_SHADOWED                 - drop shadow ( need a color for this )
ITEM_TEXTSTYLE_OUTLINED                 - drop shadow ( need a color for this )
ITEM_TEXTSTYLE_OUTLINESHADOWED          - drop shadow ( need a color for this )
ITEM_TEXTSTYLE_SHADOWEDMORE             - drop shadow ( need a color for this )
                          
TAG:  border

WINDOW_BORDER_NONE                      - no border
WINDOW_BORDER_FULL                      - full border based on border color ( single pixel )
WINDOW_BORDER_HORZ                      -  horizontal borders only
WINDOW_BORDER_VERT                      - vertical borders only 
WINDOW_BORDER_KCGRADIENT                - horizontal border using the gradient bars

TAG:  style
  
WINDOW_STYLE_EMPTY                      - no background
WINDOW_STYLE_FILLED                     - filled with background color
WINDOW_STYLE_GRADIENT                   - gradient bar based on background color 
WINDOW_STYLE_SHADER                     - gradient bar based on background color 
WINDOW_STYLE_TEAMCOLOR                  - team color
WINDOW_STYLE_CINEMATIC                  - cinematic

--------------------------------------------------------------------------
7.	Credits and Whatever

I hope this helps, I give all the kudos in the world to those before me who have trudged their way through this stuff as much as I have and possibly more.
so, good luck to anyone else who wishes to continue with their own work in menu scripting.  *chuckle*  (it's a LOT of hair pulling trust me.)
