Latest Additions

Terrain Following Objects

You can use the TERRAINFOLLOW tag to allow objects to align themselves to the terrain.

New Script Functions

You can now use the Sort function to sort a generic array, and the FindStringInArray function to search for an array entry based on a string element.

//sort the array by the elementName entry (which must be an integer).  If direction included, 0 is ascending (the default), 1 is descending.
Sort(elementName, array, count, [direction])

//returns the index of the first array item containing and element called elementName which is the search string.  elementName is a string entry, array is the variable array itself
FindStringInArray(string, elementName, array)

An example would be

struct TTest
{
  char name[32] ;
  int value ;
}
...
TTest array[2][32] ;

  Sort("value", array[1], 32) ;

AddVizUnitFormation Command

This command allows to you trigger and wait for a formation change.

//do a call to the unit placement function (potentially calling the FORMATION_CALLBACK) and wait until all the men are in position and facing the correct way.
AddVizUnitFormation(id)

Formation Facing Control

Use the new command SetFormationFacing in the FORMATION_CALLBACK function to set the facing of the nth man in the unit. Use -1 to just have the man face in the default direction of the unit as a whole, as was the previous behaviour.

//set the facing of the nth man in the unit.  Use -1 to just have the man face in the default direction of the unit as a whole.  Only relevant in FORMATION_CALLBACK
SetFormationFacing(n, facing)

Scrollable Text Controls

Text controls can now be made scrollable. Add

SCROLLING <control texture> 

to the control definition and the control will (if the text is too large to fit in the control) add a scrollbar to allow for scrolling to view the ful text. Note that this will not work correctly when combined with rescaling text boxes. You can also use BARSIZE to control the size of the scrollbar.

String Manipulation and Creation

You can allow the user to create string entries (expected in the editor) via script. The new functions are:

//places the contents of the edit box into the first UI string.
GetUIEditbox(objectName)

//creates a string of the form IDS_<tagBody>_<number> finding the first empty slot in the string table, and fills it with the contents of the first UI string
AddUserString(tagBody)

//remove the denoted user string from the temporary store.  Has no effect if the string has already been written out to the file.
RemoveUserString(tag)

//flush out any user strings to the TEXT9.TXT file.  NOTE: this is done automatically at map save and editor exit.
FlushUserStrings()

//returns the highest N for which a string exists with the form IDS_<tagBody>_<N>, up to a max of 100000. Returns -1 if none exist.
GetHighestStringIndex(tagBody)

//return 1 if the string exists, 0 otherwise
DoesStringExist(tag)

//get the denoted string into the first UI string if it exists.  Empty otherwise
GetString(tag)

So users can type in strings which are then added to the list of strings available to use ingame.

Script Updates

1 - the break directive to trigger the debugger has changed to DebugBreak ; to prevent confusion with the C break statement.

2 - while loops are now supported. Note that the test cannot be an operation, so

while(i--)

will not work, as the scripting does not treat the left hand of an expression as a value in the same way as C.

Custom UI Object Rendering (inc Listbox Items)

Individual UI objects can now have their own scripts attached, including their own rendering callbacks. As before the rendering callback is of the form

FUNCTION UI_OBJ_RENDER(x,y,width,height,pass)

Where pass is 0/1 for pre/post normal control rendering.

Listboxes can also include

FUNCTION UI_OBJ_RENDER_ITEM(x,y,width,height,pass,flags, item, name)

which operates in the same way but for each listbox item. The flags param has bits set for selection (bit 0) and mouseover (bit 1), item is the index of the item in the listbox, name is the UI object name.

Listboxes: Multiple Selection

You can enable multiple selection for listboxes with the MULTISELECT tag in their UI definition. Then use

//return 1 if the specified item is selected, zero otherwise
IsUIListboxItemSelected(object, index)

//returns the number of items in a listbox
GetUIListboxCount(object)

to interrogate the listbox.

Note: This means that it is possible to get UI script triggers from listboxes which are actually a CTRL+ event which unselects the item.

Scripting: GetWorkString

You can now use GetWorkString on the RHS of an assignment expression, e.g.

char myString[32] ;
myString = GetWorkString() ;

The contents will be safely truncated to the source string's size.

3DVIEW UI Control

Creates a 3D viewport into which you can load 3D models for viewing. The COLOUR tag for this control sets the background clear colour (use zero for a transparent background, FF000000 for black).

Script commands to control this are:

//if filename starts with # then defaults to standard unit loading paths.
UIObject3DLoad(objectName, filename, [texturePath])

//automatically set the zoom and camera origin to the size of the currently loaded object
UIObject3DAuto(objectName)

//set the origin position and vertical angle of the camera.
SetUIObject3DCamera(objectName, x,y,z,angle,[zoom])

//set the options for the view.  0 for off, nonzero for on.
SetUIObject3DOptions(objectName, allowZoom, allowHorizontalRotate, allowVerticalRotate)