Latest Additions

CUSTOM_UNIT_ANIM_CALLBACK

Tile. You can intercept and change requests by the game to change the animation. The format of the function is

FUNCTION CUSTOM_UNIT_ANIM_CALLBACK(me, flags, currentRand, currentIndex)

Where me is the unit, flags is various helper flags (see below), currentRand is the random animation value, and currentIndex is the animation variation of the currently playing animation. The string tags for the upcoming and current animations are in work strings 0 and 1 respectively.

If you wish to change the animation that gets played, put the new tag into work string 0, and return the new random index value (or the incoming currentRand if you wish to leave it as is).

Note that this function can be called almost every frame with the same animation, depending on the internal unit state, not just when animations finish or are triggered.

Zoom Speed Option

Allows zoom speed to be altered between 25% and 500%. Requires options screen controls OptionsZoomSpeedLabel and OptionsZoomSpeedButton (works in the same way as scroll speed). Also IDS_ZOOMSPEED string for descriptor.

Key Mapping

You can map keys in the options. It requires a listbox named OptionsKeyList. This gets a list of the remappable keys (these are defined in code). The user can then remap them and the remapping is saved in the options file. Note that ESC cannot be used as a remapped key.

You need to define strings for each of the remappable keys in the form IDS_KEYDESC_<keyname>, so examples would be IDS_KEYDESC_W and IDS_KEYDESC_LEFT.

Please speak to us if you desire other keys to be remappable.

SetMusicFile

Allows you to point to a music file which is used.

//set a music file to be loaded and used. Looks in local then core files. A ? as filename means leave the existing music entry.
SetMusicFile(filename)

Hexadecimal Values and Colour Strings

You can now use hex values in script as integer literals. So

var = 0xFF8800FF ;

is now a valid script line.

As part of this change, most script functions which take a colour string can now also take integer values. So these are both valid and equivalent

SetUITooltipColour( "FFFF00FF" ) ;
SetUITooltipColour( 0xFFFF00FF ) ;

NOTE: one caveat is that due to the fact you can pass strings around as integers (for historical reasons) you should note that passing a string into a user function that takes a parameter can strip the type information from the value, meaning you get an incorrect result.

FUNCTION SetTT(colourString)
{
  SetUITooltipColour( colourString ) ;
}
...
  SetTT( "FFFF00FF" ) ;

This will set the colour incorrectly (SetUITooltipColour will treat colourString as an integer value and set the colour to whatever the internal string pointer value happens to be). To prevent this, type your functions appropriately:

FUNCTION SetTT(char colourString[32])
{
  SetUITooltipColour( colourString ) ;
}
...
  SetTT( "FFFF00FF" ) ;

SetShowAIMoves

Tile. New script command.

//if state is 0 then automatic viewing of AI moves is disabled, otherwise it is enabled (default).  Note this resets at the start of each turn.
SetShowAIMoves(state)

PlayUIAnimation

Tile. New script command.

//play the animation on the denoted UI screen (the objectName must be the root object of the screen).
PlayUIAnimation(objectName, animationName)

LoadVariableFromParserFile

This command loads data from a parser file into a variable. The chunks should be named [0], [1], etc for each element in the array.

//read a parser file to the named var (must be an array of structs). Only int values currently supported. Numbered chunks (base 0) are read to the corresponding array element in the named array. Each value is read to corresponding item in the structure.  See wiki for details.
LoadVariableFromParserFile(variableName, filename)

An example input file might be of the form:

[0]
side 10
data[0] 89
data[2] 5

[3]
side 33

And would be used as such:

struct TLoad
{
  int side ;
  int data[4] ;
}
TLoad gLoad[256] ;
...
  LoadVariableFromParserFile("gLoad", "MapData") ;

SetCameraPositionPrecise & StopSFX

Tile. New script commands.

//set the camera to instantly point to the given point (defined in 100ths), centering it on the screen
SetCameraPositionPrecise(x, y)

//stop a playing sample using a playback ID.  Has no effect if the sample is over, or has been stopped by the system.
StopSFX(playbackID)

Note that the playbackID is newly returned from SFX playback functions.

Object Terrain Priority

Tile. You can add a tag to an object PRIORITY. The default value is 0. Of the objects on a tile, the object with the highest priority value will denote the terrain (assuming it has a terrain override set). PRIORITY value must be [0,255].

Unit Scaling

Tile. You can add an attrib UnitScaling which allows for scaling of unit sizes. The value is in 1000ths, a value of zero is ignored.

Textbox Rescale and Scrolling

You can now have rescaling text boxes which will convert to scrolling if they exceed a given height, set using the RESCALEMAX tag. So an object can have the RESCALE and SCROLLING tags both set, and will rescale up to the height set by RESCALEMAX, and then stay at that size and use scrolling to allow access to the full text.

Force Selection Script Additions

Tile. Additional script commands to allow for custom force controls.

//set the selected state of a given unit on tile x,y on the deployment map.  If select is 0 then the unit is unselected, otherwise selected. Note can fail if unit is fixed or not enough points.
SetForceControlSelected(objectName, x, y, select)

//returns 0 if the unit on x,y is unselected, 1 if selected, 2 if fixed, (-1 if no unit is on the tile)
GetForceControlSelected(objectName, x, y)

//set the zoom level for the camera in battle
SetZoom(zoom)

There is now an additional tag for ForceSelection UI objects. HIDEBUTTONS will entirely hide the display of the normal force control buttons.

OBJ_UI_RENDER/HANDLE Change

The UI script callback functions UI_OBJ_RENDER and UI_OBJ_HANDLE now also has a name parameter containing the name of the rendering object.

FUNCTION UI_OBJ_RENDER(x,y,width,height,pass, name)
FUNCTION UI_OBJ_HANDLE(data, event, id, name)

Water

1st pass water implemented. You can now add a SKYDOME <name> line to a lighting file. The name should not include the type extension. Note that only the skydome texture from the daytime lighting file is used by the system when loading the skydome. This texture should be in the DATA/BATTLE/TEXTURES folder (either main or campaign local). It is available in the shaders in sampler 7.

Flying Units

Tile. You now tag objects with FLYHEIGHT values. These are used to generate a per-tile max height. Then, if your squads file has a FlyingFollow attrib, then any unit with a non-zero value will remain above the ground by a value made up of the per-tile max height plus the value of the FlyingFollow attribute for the unit.

GetPositionDistance Script Command

Takes two positions (in 100ths) and returns the distance between them.

//return the distance in 100ths between two points that are also in 100ths
GetPositionDistance(x1,y1,x2,y2)

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. Note that the facing is specified relative to the facing of the unit, not in terms of absolute facing. So to make a man face 45 degrees anticlockwise from the facing of the unit, the facing would be 45.

//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)