Latest Additions: Difference between revisions

From Archon Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(52 intermediate revisions by the same user not shown)
Line 1: Line 1:
= UI Updates =
= Achievement Values =
* Clicking away from a dropdown listbox will now close it
You can now get and set values for a campaign that are saved in the achievements file.  New script commands
* New script commands TriggerUICommand (allows direct triggering of custom UI commands), and DisableUIAll.
SetAchievementValue, 2, 2, "(name, value) set the value of the named achievementvalue.  If doesn't exist will be created.")  
  <nowiki>//trigger a UI custom command.  These are numeric values which vary on a per-flavour basis.
  GetAchievementValue, 1, 1, "(name) get the value of the named achievementvalue.  If doesn't exist, returns 0.")
TriggerUICommand(command)


//disable all UI screens (you should follow this with some enabled UI screens!)
= Region Map Highlights =
DisableUIAll()</nowiki>
You can now enable dynamic highlights as the mouse moves over a region map.  See [[UI#REGIONMAP]].


= IsDebugMode Script Command =
= String File Naming =
New script command to determine if DebugMode is set in the USER.TXT file.  E.g. for adding additional tooltip info for debug users.
You can now name string files with additional descriptive information.  The filenames must be of the form:
  <nowiki>//returns 1 if debug mode is on, otherwise 0
Text<number><string>.TXT
IsDebugMode()</nowiki>
Or
Text<number><string>_<tag>.TXT
Where tag is the standard 3 character language tag. Note that the string entries do not need to be the same for all the members of a given text file group.  E.g. the follow would be valid
Text2General.txt
Text2_FRE.txt
  Text2German_GER.txt
Restrictions are: you cannot start the description string with a number (can lead to ambiguous filenames).  You cannot duplicate the _??? pattern at the end of a non-localised text filename.


= BASELOCK added for edging =
= Stricter String File Checking =
Tile. You can use a BASELOCK_<X>_<Y> tag to pass in a value to the base tile edging shader. This is passed in to the z ordinate of the appropriate positions array.  Is zero when not user set, otherwise is 1+ the user value.
There is now stricter string checking to determine that lines are either of the form
TAG,"string",
or
// comment
By default these check failures are shown as warnings, but you can enable error throwing by using the line
  MAXDEBUG 2
in the USER.TXT file.  Note that comments can still follow a correctly formatted string line.


= NoBorderDraw Behaviour Update =
= ELO Reroll Allows =
Tile. When the NoBorderDraw tweak is set the shroud edging is changed to prevent the "into the border' shroud edging that was previously shown.
If there is a checkbox named LobbyAllowRerolls in the MP challenge setup screen, then an allow rerolls bool will be set in the misc data.  This is passed into the MP lobby tooltip callbacks as an ALLOWREROLLS param.


= Tooltip Update =
There is a new callback in battle RESIGN_BATTLE_CALLBACK.  This should return -1 to do nothing.  If it returns 1, then the skip rating flag will be set when sending the turn. To facilitate this, there are new script commands:
Fixed a bug where tooltip window borders were not being scaled with resolution.  The size of the tooltip window border can be controlled in the SYSTEM/UIDEFAULTS.TXT file using the tag
  GameAllowsRerolls
  <nowiki>TOOLTIPBORDER <borderSize></nowiki>
IsRanked
The default value is 8.


= GetCampaignEntry Addition =
= UI and Font Scaling =
GetCampaignEntry now returns a set of flags for the campaign.  Currently sets bit zero if the campaign is locked (protected content which has not been purchased, and bit 1 if the campaign is a core (non-user) campaign.
See: [[UI#UI_and_Font_Scaling]]


= HasBeenOrdered Commands =
= Copy + Paste in Edit Boxes =
Tile. Added new Reset and Get commands to manipulate the flag used internally to show units which has been ordered.
You can now copy and paste in Edit boxes. There is a new tag SELECTIONCOLOUR which allows you to alter the colour of the selection box displayed when selecting for copy.
<nowiki>//set the flag on the denoted unit which tells the system whether it should be shown when using the 'show next unordered unit' shortcut.
SetHasBeenOrdered(id)


//reset the has been ordered flag for the given unit
You cannot copy from a password box.  You cannot paste over text (e.g. paste into a selection thus replacing it).
ResetHasBeenOrdered(id)


//returns 0 if the has been ordered flag is not set, 1 if the flag is set
You can also copy from textmode listboxes (as used by the MP chat box).  This is only possible if you add an ALLOWCOPY tag to the UI control.  There is also a TEXTSELECTIONCOLOUR tag which can be set on these controls.
GetHasBeenOrdered(id)</nowiki>


= 3DView Lighting and Shader Script Commands =
= 4:3 Ratio UI overrides =
Allows scripts to control the lighting of 3DView controls.
In the rare case where a UI file needs special formatting for 4:3 ratio screens, you can define a different UI file to be loaded where appropriate.  Simply create a folder called 43 in the same folder as the UI files.  Any file in the 43 folder, which has the same name as a file in the parent folder, will be loaded instead, when running at a resolution with a 4:3 aspect ratio or lower.
  <nowiki>// set the lighting direction xyz and the light colour and ambient colour for the control.
SetUIObject3DLighting(objectName, x, y, z, colour, ambient)</nowiki>
Also allows setting the custom shader values.
<nowiki>//set the 4 shader values for register 30 (random uvs etc), in 100ths.
SetUIObject3DShaderValues(objectName, a, b, c ,d)</nowiki>


= Rescale UI Direction Locking =
= Pick Callback =
The new tag RESCALELOCK allows control over which direction a RESCALE-set text control will grow.  A value of 0 means center as usual, 1 means grown downward from the base position only, 2 means grow upward from the base position only.
Tile. Use the following HELPERS.BSF callback to control picking/selection in battle.
PICK_CALLBACK(blocking)
Where blocking is set to 1 when the mouse is over any UI block set with BlockUIArea during a render call.  Return 0 to pick normally, 1 to prevent picking/selection.


= Array Search =
= Custom Mouse Handling =
FindStringInArray now optionally takes an isSorted parameter to indicate that the array is already sorted in ascending order by the requested element, in which case a binary search will be used.  A similar command, FindInArray has also been added which can search for either int or string elements.
Tile. Callbacks exist for custom mouse handling.  These are
MOUSE_CLICK_HANDLER(action, tilex, tiley)    // in HELPERS.BSF
DEBUG_MOUSE_CLICK_HANDLER(action, tilex, tiley) // in DEBUG_HELPERS.BSF when enabled
They are triggered on mouse up.  action is 0 for LMB, 1 for RMB.  Return non-zero in MOUSE_CLICK_HANDLER to prevent normal mouse handling.


  <nowiki>//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, if isSorted is != 0 the array is assumed to already be sorted in ascending order by elementName
= User Folder Redirection =
FindStringInArray(string, elementName, array, [isSorted])
If the user places a REDIRECT.TXT file in their local folder (e.g. Documents/My Games/<game>) which contains the line
  FOLDER <fullpath>
Then the game will treat the provided folder as the user folder for this game.


//returns the index of the first array item containing and element called elementName which equals the search value.  elementName is the name of the struct element as a string, array is the variable array itself, if isSorted is != 0 the array is assumed to already be sorted in ascending order by elementName
= Hotkey Tooltips =
FindInArray(value, elementName, array, [isSorted])</nowiki>
You can now enable automatic hotkey tooltips.  See the UI button documentation.


= Text Centering Tags =
= Hotkey Modifiers =
You can now use a <a></a> pair to horizontally center text in its text bounds.  See [[UI#Strings]]
Can now have UI control hotkeys with SHIFT and/or CTRL modifiers.  See the UI documentation.


= Campaign and Battle Enumeration Enhancements =
= New Tile Callbacks =
Tile. You can now interrogate a campaign without having to start it by passing in the pathname (as provided back to you by GetCampaignEntry).
Tile. New callbacks
<nowiki>//return the number of scenarios in the current campaign, or in the campaign at the provided path if passed in.
GetBattleCount([campaignPath])


//set the first work string with the scenario name for the given battle, and the first UI string with IDS_SCENARIO_<name> if it exists.  If campaignPath is set use it, otherwise the current campaign.
// Allows for additional text to be added to skirmish descriptions in the MP creation screen.
GetBattleEntry(index, [campaignPath])</nowiki>
// Place any string to be added in the first UI string
This allows (e.g.) a single list of all campaigns and missions in a single list. Note that this can be somewhat slow (thanks to local strings needing to be loaded for each campaign) and so should not happen every frame.
  FUNCTION SKIRMISH_COMMENT_CALLBACK()


= UI Shader Enhancements =
// Called immediately after loading the userdata when a game is loaded
For Image and Button controls, the system will now try and load another texture if it exists (with an _N postfix).  If this texture is loaded, then an alternate shader is used (CORE/SHADERS/SCREENRGBA_NORMAL.TXT).  This can be used for special effects etc.  To aid in this, the current mouse position onscreen is now available in the wz components of c0 in both the vertex and pixel shaders when rendering UI elements.  E.g. if you have a control loading MyTexture.TGA then if MyTexture_N.TGA exists it will be loaded and available in texture sampler 1, along with the main texture in sampler 0 as normal, and the SCREENRGBA_NORMAL shader will be used.
// skirmish param is zero or one.  Userdata is in the first work array.
  FUNCTION LOAD_USERDATA_CALLBACK(skirmish)


Obviously as this is all in screen space, there is no actual 3D positioning for the UI elements, so the shader must be built purely to give an appropriate effect.
= StartCampaign & ReplaceUnit Script Commands =
Tile. StartCampaign can now take no params at which point it loads the ||SKIRMISH campaign as per skirmish battles.  ReplaceUnit replaces one unit with another.  In order to handle any custom setup (esp anything which is used in animation callbacks) there is a REPLACE_CALLBACK(me) callback where any required data can be set up after the new replacement unit has been initialized but before we try and sync up animations etc.  So you will need to save out any specific attribs from the unit that you care about and then reset then in the callback (if needed) or after the ReplaceUnit call returns.


= Campaign and Battle Enumeration Commands =
= Screenshot/Movie Capture =
Tile. New commands to allow custom access to campaign and battle information.  NOTE: you still need most of the standard UI controls to exist, but they can be offscreen or have zero dimensions as required.
Updates:  there is now an onscreen flash when capturing a screenshot. You can also place entries for SCREENSHOTSFX and MOVIESFX into the UIDefaults.txt file in System.  These should be numeric index values into the sfx list for sounds to be played when screenshotting, and when beginning a movie capture respectively.
<nowiki>//switch to a given campaign.  Searches in local campaigns, then in campaigns.  Also accepts a full path using / as seperator.
StartCampaign(campaignName)


//return the number of campaigns available currently (takes any campaign filtering into account, only useful on or after the campaign selection screen
= Global saves =
GetCampaignCount()
You can now pass an empty string into Load/SaveVariableData and it will load and save from a GLOBAL_DATA.TXT file in (e.g.) My Documents/My Games/FieldOfGlory2.  This can be used to set up a global structure for persistent data across the game, e.g. hi scores or battles won.


//set the first work string with the pathname of the given campaign, and the first UI string with the campaign name IDS_CAMPAIGN_NAME, if it exists.  Also places the base campaign name into the 2nd work string (stripped of path).
= Load Sequence Function =
GetCampaignEntry(index)
Tile. If the script CORE/LOADINIT.BSF exists then the function LoadInit from within it will be called at the very start of the main loading sequence, immediately after the first loadbar frame is shown.


//return the number of scenarios in the current campaign
= Progress Bars Accept KEEPSQUARE =
GetBattleCount()
You can now use a KEEPSQUARE tag for progress bars if desired.


//set the first work string with the scenario name for the given battle, and the first UI string with IDS_SCENARIO_<name> if it exists
= Global Orders =
GetBattleEntry(index)</nowiki>
Tile. You can now include global orders which do not require a unit to be selected.  These are defined in the CORE.BSF script, and should follow the template for standard unit orders (i.e. CHECK_, UIBUTTON_, etc functions must exist).  These orders use a CORE_ prefix, rather than TILE_, UNIT_, or ALL_.


= Exit to Main Menu =
= Gamma Adjustment =
Tile.  Triggering a custom command with the value 200 will return you to the main menu.
Two new commands allow for adjusting the gamma values when in fullscreen.  To allow for saving of the gamma value (or others) there are 3 additional Custom* options values available.  Custom1, Custom2, Custom3.  All default to zero.  Suggested values for gamma would be 0.5 to 2.0 or so, depending on the variation you wish to allow.
  COMMAND CUSTOM 200
<nowiki>//set the gamma value, if possible.  gamma is in 1000ths.
If adding to the options screen to complement the Quit Game option, you should make the button a child of the OptionsExitGame control to ensure it gets hidden along with it.
SetGamma(gamma)


= SetUIObject3DTilt =
//returns 1 if the current setup allows for gamma adjustment (e.g. driver support, or because gamma requires fullscreen).
Allows control of the tilt of the object in the control.
AllowsGamma()</nowiki>
<nowiki>//set the per-axis tilts for the model, in 100ths of degrees. Note the rotations are applied in xyz order.
SetUIObject3DTilt(objectName, x, y ,z)</nowiki>


= PRESTARTBATTLE_CONTROL =
= Get/SetUnitString Script Commands =
Tile. By default PreStartBattle is not called for MP games.  You can over-ride this by returning non-zero from a PreStartBattle_Control callback.  This can exist in both the CORE.BSF and the scenario script, with the scenario script callback taking precedence.
Tile. New commands to allow a custom unicode string to be attached to a unit.
  <nowiki> FUNCTION PreStartBattle_Control(mode)</nowiki>
  //place the contents of the first UI string as a custom string for the unit.  
  SetUnitString(me)


= Gameview Control (Campaign Screen) Additions =
  //place the contents of the unit custom string into the first UI string.  Returns 0 if there is no custom string, 1 otherwise
Tile. The files below can now have $ versions (e.g. rather than BACKDROP.TGA you would name the file BACKDROP$.TGA) to turn on rendering of the texture as if it were a control tagged as BACKDROP in the UI (that is, keeps the aspect on screens up to 21:9). The effected files are:
  GetUnitString(me)
<nowiki>BACKDROP.TGA // the optional custom backdrop per campaign
DATA/UI/TEXTURES/WORLD_BACKGROUND.DDS  // the default system backdrop
DATA/UI/TEXTURES/GENERIC_MISSION_BACKGROUND.TGA // default mission background
ICON.TGA  // the optional custom campaign image
DATA/UI/TEXTURES/GENERIC_CAMPAIGN_OVERLAY.TGA  // default campaign image
DATA/UI/TEXTURES/CAMPAIGNBACK.TGA // the campaign background image</nowiki>
This naming convention will also work for mission backdrops in SCENARIOS.


= Tournament Updates =
= User Content Debugging =
Tile. Additions to the scoring callbacks, as detailed in [[Multiplayer#Scoring]].  New command IsTournament
Tile. When in DEBUGMODE is set to 2, the system will additionally load list_debug.txt into the user content list from the server.  This is to allow for simpler testing of user content from the server without polluting the release list.
<nowiki>//returns 1 if the current game is MP and is a tournament game.
IsTournament()</nowiki>


= HELPER_SELECT_UNIT_CALLBACK =
= GetSkirmishPoints & GetCurrentMod =
If the function is defined in HELPERS.BSF it will be called each time that the unit selection is changed, whether by code or via user interaction.  Clearly you should not call SetCurrentSelectedUnit from inside this callback...
Tile. New script commands to fetch the currently set skirmish points, and to query the current mod.
  <nowiki>FUNCTION HELPER_SELECT_UNIT_CALLBACK()</nowiki>
  <nowiki>//sets the first 4 values in the first work array with the current skirmish points values (fixed0, fixed1, select0, select1)
GetSkirmishPoints()


= DeleteUnit Script Command =
//if a mod is selected, place the name of the current mod into the first UI string and return its index, otherwise return -1.  Always returns -1 in multiplayer.
Tile.
GetCurrentMod()</nowiki>
<nowiki>//delete a unit from the side.  This will remove the unit entirely, unlike RemoveUnit etc.  This command can change the ids of other units in the side.
DeleteUnit(side, index)</nowiki>
 
= Progress Bar Nubs =
You can now have a draggable nub on a progress bar to allow the user to change its value.
<nowiki>NUB <nub image file>
NUBWIDTH <width>  // defaults to 32</nowiki>
The nub is always the full height of the progress bar control.
 
= SkipForceSelection Change =
Tile. SkipForceSelection can now take some flags.  Currently only valid value is 1, which forces even non-fixed units to be deployed on the map.
<nowiki>//tell the game to skip force selection.  Only useful in the PreStartBattle callback. flags can be combination of: 1 (prevent unfixed units from being removed on deployment)
SkipForceSelection([flags])</nowiki>
 
= UI_OBJ_UPDATE Addition =
There is another optional param for UI_OBJ_UPDATE.  This is Data.  Data is per-control data passed back to the script.  Currently only listboxes use this value, passing the index of the item that the mouse is over, or -1 if none.
 
= SkipForceSelection =
Tile. New script command to skip over force selection for a mission.
<nowiki>//tell the game to skip force selection.  Only useful in the PreStartBattle callback.
SkipForceSelection()</nowiki>
 
= UI Image Control SLICED Tag =
You can now add a SLICED entry to Image UI controls.  See [[UI#IMAGE]].
 
= Additional 3DView UI Commands =
Note that animation data is loaded automatically with the mesh.  The system will automatically remove any _0 from the end of a filename when searching for the anim .TXT file.
<nowiki>//set the rotation angle for the 3D view
SetUIObject3DRotation(objectName, angle)
 
//set the zoom for the given 3D view
SetUIObject3DZoom(objectName, zoom)
 
//play an animation, which must be set up in the standard text file. If index then it will play a specific anim (if it exists) otherwise random. Loops if loop is != 0, defaults on
SetUIObject3DAnim(objectName, animName, [loop, index])</nowiki>
Also fixed a bug where the zoom param in SetUIObject3DCamera was inoperative.
 
= RegionMapGetByteData =
Added new data to the RegionMap control.  16 byte values, so must be 0 to 255 inclusive.  So the data for a map region now can have the form (e.g.):
<nowiki>[77]  // the region number
DATA 0 0 0 0  // 4 int values
BYTEDATA 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0  // 16 byte values</nowiki>
 
= Banner Height =
Tile. If there is a BannerHeight attrib it is used to raise any banner.  BannerHeight is in 10ths.
 
= Skinning/Global Mod Support =
Tile. See [[Modding#Creating_a_Mod]]
 
Note that there must be a MainMenuMods listbox on the main menu screen to show the mod list.  This object is disabled when no mods are available.
 
= PrintTo and PrintCat =
New script commands for UI strings
<nowiki>//same as Print other than takes an index to the UI string to print to.
PrintTo(index, formatString, [...])
 
//same as Print other than take an index to the UI string AND also adds the printed string to the end of the existing UI string, whatever it may be.
PrintCat(index, formatString, [...])</nowiki>
 
= FromFileFindString =
New command for interrogating text files.
<nowiki>//search for a tagged string in the chunk where the start of the string matches the given searchString, and place the remainder of the string into workstring[index].  Return 1 if successful.
FromFileFindString(fileID, chunk, tag, search, [index])</nowiki>
 
= Dropdown Listboxes =
You can now define a listbox as being a dropdown list.  To do this add a DROPDOWN tag to the UI definition.  Note that you still define the positioning of the listbox by the listbox size <i>when open</i>.  When the listbox is closed up, it shows the selected item at the position where the first item in the open listbox would be.
 
= Tournament Documentation =
See [[Multiplayer#Tournaments]] for details.
 
= RenderString Script Command Change =
Tile. A negative width value will cause rendering to be a single line, clipping off any text past the abs(width).
 
= Listbox Item Render Flags =
The flags parameter passed into listbox item rendering functions will now have bit 2 set (value 4) when scrollbars are active.
 
= GetScenarioName Command =
Tile.
<nowiki>//places the scenario name for the currently running scenario into the first work string.  Behaviour if called outside a battle is undefined.
GetScenarioName()</nowiki>
 
= Scripting Documentation Change Notification =
When in debug mode, if the autodocs for the scripting have changed, a notice will be displayed on running the game, and the changes are saved to SCRIPTCHANGES.TXT in the autodocs file.
 
= SetAutosaveString & Autosaving =
Tile. Allows you to set an info string that is added to carryover campaign autosaves to better describe the state of the save.
<nowiki>//use the current UI string as an additional string to display in the name of the autosave for the current campaign.  So, e.g. set to the name of the current mission.
SetAutosaveString()</nowiki>
Also, in single player, there is now an autosave at the start of each player turn.
 
= Unit Icon Change =
Tile. If you call SetUnitIconMask with the bottom 24 bits set, then the top 8 bit denote a single icon on the icon page to use.
<nowiki>SetUnitIconMask(me, 0x04FFFFFF) ;  // use just the 5th icon on the page</nowiki>
Remember to use ClearUnitIconMask, as SetUnitIconMask ORs the values together.
 
= Version Reporting Change =
V.TXT no longer just contains the matching EXE version (to ensure data and EXE match up) but also a cosmetic version number which is displayed to the player.  The format of the file should be
<nowiki><EXE Version>
<Game Version></nowiki>
For example
<nowiki>00010006
00010002</nowiki>
Would display the game version number as 1.0.2 while the build number would be 10006.
 
= New Checkbox Mode for UI Buttons =
You can now flag a button as being a checkbox.  Simply add the two lines
<nowiki>CHECKBOX
CHECKBOXTICK MyTickImage.tga</nowiki>
You can then use the SetUICheckbox script command to control the state of the checkbox.
 
= Non-Square & Power of 2 Restrictions Removed =
You can now use non-square and non-power of 2 sized textures without restriction.  NOTE: this relies upon the video card supporting arbitrary texture sizes (which any card almost certainly will).  If the game encounters a card which cannot, then it will resize the textures to a valid size.  Authors should bear this in mind in case they utilise any functionality which relies upon exact sizes.
 
= Clickable Link Display Strings =
You can now show a different display string to the clickable link URL when setting up clickable link strings.  So rather than
<nowiki><html>http://www.slitherine.com</html></nowiki>
you could use
<nowiki><html>http://www.slitherine.com|Click this link</html></nowiki>
To show just the text "Click this link" onscreen.  See [[Latest_Additions#Clickable_Links|Here]] for more information.
 
= CAMPAIGN_VICTORY_CALLBACK =
You can define a new callback in the campaign script to tell the system that the user has won the campaign, by returning a non-zero value.
<nowiki>FUNCTION CAMPAIGN_VICTORY_CALLBACK(winner)</nowiki>
The winner value is 0 for the player and 1 for the AI as the result of the last battle (the callback is only called after a battle completes).  Note that this should only be used by campaigns with custom campaign UI.
 
= Documented Tutorial Popup Functionality =
See [[UI#Tutorial_Popups|Here]]
 
= Additional MapView Script Commands =
New commands to return additional data from the map.  The user string is defined by the author of the data.
<nowiki>//places the ID string for the area into the first work string.
MapViewGetAreaString(objectName, areaIndex)
 
//places the connections data into the first work array.  The first array item is the count, followed by the IDs of the connected regions.
MapViewGetAreaConnections(objectName, areaIndex)
 
//returns the areaIndex when passed an ID.  Returns -1 if invalid.
MapViewGetIndexFromID(objectName, ID)</nowiki>
 
= Sort Script Command Update =
You can now sort by strings (char arrays) when using the Sort script command
<nowiki>//sort the array by the elementName entry (which must be an integer or a char array).  If direction included, 0 is ascending (the default), 1 is descending.
Sort(elementName, array, count, [direction])</nowiki>
 
= MODULATE Blend Mode for UI Images =
You can now add a MODULATE tag to a UI control of type IMAGE which causes it to use a modulate (multiply) blend when rendering.  Note that any alpha values passed in (e.g. via a FADE UI animation) will work as expected, with smaller alpha values reducing the visibility of the image.
 
= Campaign Screen List Changes =
The main campaign listbox has changed slightly.  It no longer defaults to right-aligned text (it will obey RIGHT and CENTER tags in the UI object definition).  You can also disable the vertical centering of the items in the object bounds by setting user value 0 to non-zero, e.g:
<nowiki>VALUE0 1</nowiki>
This allows for easier customisation of the look of the screen.
 
= Smallcaps Support =
You now enable Smallcaps support by enclosing the text with a <c> </c> pair.  Smallcaps renders all lowercase letters using smaller versions of their uppercase versions.  See this image for an example [http://www.micropress-inc.com/texdocs/smallc1.gif Smallcaps]
 
= AddVizWaitOnTurnAll Script command =
You can delay viz queue processing until all the men in a unit have turned to their desired facings.  This would generally be used after turning a unit, or after setting a formation.  Note that depending upon the internal logic, it may be necessary to delay for a tick or so to allow formation facings to propogate to the units before waiting for the turn to happen, so be aware that this may be necessary.
<nowiki>//wait until all the men in the denoted unit are at or reach their desired facing
AddVizWaitOnTurnAll(id)</nowiki>
 
= SetUnitIconDisplayState =
Tile. New script command for controlling how the unit icons are shown/faded/etc.
<nowiki>//determine how/if unit icons are shown.  1 for on all the time, 0 for off all the time, -1 for default behaviour.  Defaults to -1.
SetUnitIconDisplayState(state)</nowiki>
 
= SetUnitShaderStyle =
Tile. Sets the shader style for a unit, allowing different visuals for a unit (beyond conditionals from SetShaderValue).
<nowiki>//set the shader style for the rendering on a unit. Use -1 to use the style defined in the model.
SetUnitShaderStyle(id, style)</nowiki>
 
= More UI Strings =
The number of available UI Strings (StartString, etc.) is being increased from 4 to 16.
 
= UI Screen Edge Attachment =
The ATTACH tag can now be used to have a UI object attach to a screen edge.  The data for ATTACH is in the form of a string, with valid values being L, R, T, B for left, right, top, and bottom edges respectively.  So, e.g:
<nowiki>ATTACH TL</nowiki>
would position a control at the top left of the screen in all resolutions.  ATTACH can be used (for example with SQUAREASPECT or the DX/DY tags) on a parent object to build a control panel which is in a given position onscreen irrespective of it's actual size and positioning.
 
= UI Square Aspect =
You can now denote controls to maintain their aspect, along with all their children.  This differs from the KEEPSQUARE logic in that the actual positioning of child objects will retain a constant aspect (rather than just their control dimensions, as with KEEPSQUARE).  Effectively, setting SQUAREASPECT on a control will cause it to be centered around it's usual position, with all its children positions as they would have been in their 1024x768 defined coordinates.  So a popup (for example) will have the same look and layout all screen resolutions, but will scale uniformly to the appropriate size.  Note that while it is possible to turn off SQUAREASPECT on child objects of SQUAREASPECT parents, the results will likely be undesired.
 
= Script Command Update: GetUnitAssetFilename =
Can now be used without requiring an existing unit, by setting bit 16 in the id value.
<nowiki>//puts the base asset filename for the unit in the workString requested, default 0. If bit 16 is set (+65536) then id is assumed to be the type index of the unit type, allowing this to be used when no unit exists.
GetUnitAssetFilename(id, [workString])</nowiki>
 
= Multiple Variable Definitions Per Line =
You can now declare multiple variable definitions per line, e.g.
<nowiki>int x,y,z ;</nowiki>
Note that you cannot have multiple variables per line in structure definitions, nor if you are setting up static data in a global variable.
 
= Updated Unit Texture Functions =
Tile. Updated SetUnitTexture and added CheckUnitTextureFile.  You can now set a texture in any of the 4 texture paths on a model, or reset back to the model default. Note that (as before) when looking for a texture in either function it first checks the campaign, and then the main data folder, and if no path is set it uses DATA/BATTLE/UNITTEXTURES.
<nowiki>//set the unit to use a new texture.  A unit can only have a single texture on all its men.  If path is omitted or empty uses DATA/BATTLE/UNITTEXTURES (either local or main). index [0,3]. Empty filename means reset.
SetUnitTexture(me, filename [,path][,index])
 
//return 1 if the given texture exists, 0 otherwise.  The type on the filename is optional and success is returned if any valid texture file type exists.
CheckTextureFile(filename [,path])</nowiki>
 
= Skirmish Map Size Scripting =
Tile. The function RandomMap_MapSize can now take a 7th parameter, which is the skirmish type index.  As before the parameters for this function need to be in order in the definition.
<nowiki>FUNCTION RandomMap_MapSize(mapSize, width, height, mapType, points0, points1, scenarioType)</nowiki>
 
= User Data for MP Games =
Tile. You can now add user data to MP games which can then by parsed by your game setup, and shown as tooltips.  To do this you need two functions inside the UI script for the lobby (lobby.txt):
<nowiki>FUNCTION MULTIPLAYER_USERDATA_CALLBACK()
{
// this should fill the work array with up to 16 values
// generally this would be driven by custom UI
}
 
FUNCTION MULTIPLAYER_USERDATA_TOOLTIP_CALLBACK()
{
// this is called with the user data in the work array, and should fill the UI string with the appropriate tooltip
// only adds a tooltip if it returns != 0
return 1 ;
}</nowiki>
The user data is available in the work array at the start of the battle (e.g. in the initial StartTurn calls etc).  Note that this data can be overwritten by user code and should thus be extracted and stored as soon as possible.  Also note that because the logic for the userdata is part of the UI script it cannot be customised on a per-campaign basis (this is because loading custom scripts for all campaigns (including possibly ones that the user does not have installed) would be prohibitive.
<b>NOTE: The current limit for the number of user data integers is 16.</b>
 
= ConfirmEndTurn =
Tile. A new option ConfirmEndTurn pops up a confirmation when you try and end the turn.  This requires a new string IDS_ENDTURN_CONF.  The confirmation only occurs when ConfirmEndTurn has the value 1.  The default value is 2, and zero is also a valid value.  This allows games to tell whether the option is in default or has been set by the user (so a game could turn it to 1 if it wished at start if the default is set).


= ClearUIListbox Update =
= Modding Updates =
This script command now allows for an optional value which sets the size of the listbox. This aids performance with adding large numbers of items to a list. Note that the list can still grow beyond this size as needed.
Tile.  Mods can now override S4F and their animation files for units. They can also override scripts for AI, unit, HELPERS, and CORE BSF files.  NOTE: to package global mods, you need a ModsPackage named button on the mod UI panel.
  <nowiki>//clear a listbox UI object and reset its selection. numberOfItems pre-allocates space for that many items, speeding up large list filling.
ClearUIListbox(objectName, [numberOfItems])</nowiki>


= Clickable Links =
= Lobby Colouring Tweak =
It is now possible to include clickable links in text controls by using correct markup. See [[UI#Strings|Here]] for details. Note that if you include DATA/UI/MOUSE/LINK.TGA (or DDS of course) cursor image then it will be used when over a clickable link.
Tile. You can now use the VALUE5 entry for the accept games list to define the RGB value for disabled games (where you do not have the necessary campaign etc). Alpha is set to 0xFF by the game. Zero uses the default colouring.


= ShaderValue Attrib =
= String Attribs =
Tile. If an attrib exists named ShaderValue then the value for a given unit is passed in as the .w component of c30 (which is usually filled with pseudo-random values when rendering units) to the vertex and pixel shaders. This can allow for conditional shader code to be executed based on either static (from the squads file) or dynamic values in the attrib.
Tile. You can have up to 8 read-only strings attached to a squad template.  These must be defined in the squads file using tags ##0 to ##7.  The string data for each element must have 27 characters or less, and spaces are not permitted.  You can then retrieve these using the new command
<nowiki>//place the given attrib string into the first work string.  typeIndex is the index of the unit type. index is currently [0,7].
GetAttribString(typeIndex, index)</nowiki>
Note that the string returned will have been converted into upper case.


= New UI Animation Commands =
= UpdateUserStringFromUI and GetUIEditboxToInt Script Commands =
New commands SCALE and ROTATE.  Format is:
  <nowiki>//take the UI string from an editbox object and update it if it has changed (or is new).  Return 1 if a change has been made, zero otherwise.
  <nowiki>ANIM SCALE <object> <frame> <startScaleX> <startScaleY> <endScaleX> <endScaleY> <ticks>
UpdateUserStringFromUI(objectName, tag)
ANIM ROTATE <object> <frame> <startRot> <endRot> <ticks> <loop></nowiki>


= Antialias Support =
//takes the contents of the UI editbox and converts them to a string.  If there are any non-numeric characters in the string, then the return value is invalidValue.  Skips leading and trailing whitespace.
Tile. You can enable AA support in the options panel by providing a listbox (OptionsAAList) and the appropriate strings (IDS_AA_NONE and IDS_AA_SAMPLES).  Note that IDS_AA_SAMPLES expects to be a formatted string which takes the number of samples to be used.
GetUIEditboxToInt(objectName, invalidValue)</nowiki>
<nowiki>IDS_AA_SAMPLES,"%d samples",</nowiki>


= Per-Man Status Display =
= Review Battlefield After Battle =
Tile. You can display status information over the selected and moused-over units.  This is in the form of a bar over each man. To use it you need a callback of the form
Tile. You can now set up the UI to allow the user to review the battlefield after a battle ends. To do this you should:
<nowiki>FUNCTION STATUS_BAR_CALLBACK(me, man)</nowiki>
* Add a button the the EndBattle control called EndBattleReview
Which returns the percentage value for the bar.  Returning -1 hides the bar for that man.  The positioning and appearance can be controlled by optional per-unit attributes
* Create a new UI screen to allow the user to exit after they have finished reviewing.  This screen should be called EndReview, and should include a button named EndReviewOK.  EndReview should not be modal, but should have the same HANDLER as EndBattle (DeployHandler).
<nowiki>StatusOffset // the percentage of the IconHeight attribute to position the bar at (in 100ths), defaults to 80
This should allow the player to review the battlefield, with all units shown.
StatusSize // height of the bar in 100ths, defaults to 50
StatusWidth // multiple of the height for the width of the bar, in 16ths. Cannot be larger than 255.</nowiki>
The default shader uses the center 50% of the texture (DECALBAR0 and 1 in UI/DATA/TEXTURES) for the area around the percentage position, and repeats the outer 25% on each side along the remaining bar.  The decalbar.txt shader can be customised as desired.


= ShowConfirm Script Command =
= ShowUIListboxItem =
You can show a confirm popup using the new command
New script command which moves the viewable area (if needed) to show the given item.
  <nowiki>//show a confirm popup using UI string 0, and callback the given function with the result (see wiki for details) empty string for no callback. flags denote the buttons to show, zero for off, 1 for on, for OK and Cancel buttons for bits 0 and 1 respectively
  //move the UI listbox to show the given item index. Scrolls unless immediate is non-zero, in which case it instantly changes the view
ShowConfirm(callbackFunction, [flags])</nowiki>
ShowUIListboxItem(objectName, index, [immediate])
The callback function should be of the form
<nowiki>FUNCTION MyCallback(ok)</nowiki>
Where ok will be 1 or 0 depending upon the choice the user makes.  Note that you cannot use Get/SetGlobal calls in this callback function.


= Reaction Display =
= GetString Control Change =
Tile. The reaction display was failing to display.  This has now been fixed, but there is also a new tweak DISPLAYREACTION which allows it to be disabled as desired.  This defaults to 1, but a value of zero disables display of the reaction ring.
If the UI object GetStringTitle exists, then the title text for the system GetString control will be placed there, rather than in the title of the GetString object window as per default.


= CUSTOM_UNIT_ANIM_CALLBACK =
= DEPLOY_DRAG_CALLBACK =
Tile. You can intercept and change requests by the game to change the animation. The format of the function is
Tile. Unit script function that is called each time a unit is moved by dragging when in deployment.
  <nowiki>FUNCTION CUSTOM_UNIT_ANIM_CALLBACK(me, man, flags, currentRand, currentIndex)</nowiki>
  FUNCTION DEPLOY_DRAG_CALLBACK(me, tilex, tiley)
Where me is the unit, man is the index in the unit of the specific man, 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).
= Multiline for UI Edit Controls =
Adding a CHATMODE tag to edit controls will now allow them to contain more than one line.


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.
= Further INCLUDE Functionality for UI Files =
You can now use a prefix to rename included UI file components, allowing reuse of UI fragments. See here:[[UI]]


Additionally, you can now add a FLAGS byte to animation definitions.  If you wish for an animation to act like a MOVE or DIE animation, you need to set bits 0 and 1 respectively in a FLAGS value.  E.g.
= User Music Control =
  <nowiki>[MOVE_CUSTOM00]
Tile.  You can alter the music that is playing using the new script command
FLAGS 1
  <nowiki>//switch to the denoted music track.  Must be [0,5] currently as per the MUSIC.TXT file order.
...</nowiki>
SwitchMusic(track)</nowiki>
Can be combined with the new tweak DisableDefaultMusic, which stops all hardcoded changes of music (NOTE: other than the initial playing of the main menu music, and some other changes back to the main menu music when internal code takes the UI back to the main menu).


flags bit values:
It is also worth reminding of the existence of the SetMusicFile command
1 - attempting to change from a move animation to wait after movement finishes
 
= 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.
  <nowiki>//set a music file to be loaded and used. Looks in local then core files. A ? as filename means leave the existing music entry.
  <nowiki>//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)</nowiki>
SetMusicFile(filename)</nowiki>


= Hexadecimal Values and Colour Strings =
= New Script Commands: GetMapStyle & DeleteUserCampaign =
You can now use hex values in script as integer literals.  So
Tile.
<nowiki>var = 0xFF8800FF ;</nowiki>
  <nowiki>//place the current map style string into the first work string.
is now a valid script line.
GetMapStyle()
 
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
<nowiki>SetUITooltipColour( "FFFF00FF" ) ;
SetUITooltipColour( 0xFFFF00FF ) ;</nowiki>
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.
<nowiki>FUNCTION SetTT(colourString)
{
  SetUITooltipColour( colourString ) ;
}
...
  SetTT( "FFFF00FF" ) ;</nowiki>
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:
<nowiki>FUNCTION SetTT(char colourString[32])
{
  SetUITooltipColour( colourString ) ;
}
...
  SetTT( "FFFF00FF" ) ;</nowiki>
 
= SetShowAIMoves =
Tile. New script command.
<nowiki>//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)</nowiki>
 
= PlayUIAnimation =
Tile. New script command.
<nowiki>//play the animation on the denoted UI screen (the objectName must be the root object of the screen).
PlayUIAnimation(objectName, animationName)</nowiki>
 
= 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.
<nowiki>//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)</nowiki>
An example input file might be of the form:
<nowiki>[0]
side 10
data[0] 89
data[2] 5
 
[3]
side 33</nowiki>
And would be used as such:
<nowiki>struct TLoad
{
  int side ;
  int data[4] ;
}
TLoad gLoad[256] ;
...
  LoadVariableFromParserFile("gLoad", "MapData") ;</nowiki>
 
= SetCameraPositionPrecise & StopSFX =
Tile. New script commands.
<nowiki>//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)</nowiki>
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.
<nowiki>//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)</nowiki>
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.
<nowiki>FUNCTION UI_OBJ_RENDER(x,y,width,height,pass, name)
FUNCTION UI_OBJ_HANDLE(data, event, id, name)</nowiki>
 
= 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.
<nowiki>//return the distance in 100ths between two points that are also in 100ths
GetPositionDistance(x1,y1,x2,y2)</nowiki>
 
= 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.
<nowiki>//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)</nowiki>
 
An example would be
<nowiki>struct TTest
{
  char name[32] ;
  int value ;
}
...
TTest array[2][32] ;
 
  Sort("value", array[1], 32) ;</nowiki>
 
= AddVizUnitFormation Command =
This command allows to you trigger and wait for a formation change.
 
  <nowiki>//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)</nowiki>
 
=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.
 
<nowiki>//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)</nowiki>
 
= Scrollable Text Controls =
Text controls can now be made scrollable.  Add
 
<nowiki>SCROLLING <control texture> </nowiki>
 
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:
 
<nowiki>//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)</nowiki>
 
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
<code>while(i--)</code>
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
 
<code>FUNCTION UI_OBJ_RENDER(x,y,width,height,pass)</code>
 
Where pass is 0/1 for pre/post normal control rendering.
 
Listboxes can also include
 
<code>FUNCTION UI_OBJ_RENDER_ITEM(x,y,width,height,pass,flags, item, name)</code>
 
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
 
<nowiki>//return 1 if the specified item is selected, zero otherwise
IsUIListboxItemSelected(object, index)
 
//returns the number of items in a listbox
GetUIListboxCount(object)</nowiki>
 
to interrogate the listbox. 
 
<i>Note: This means that it is possible to get UI script triggers from listboxes which are actually a CTRL+ event which unselects the item.</i>
 
= Scripting: GetWorkString =
You can now use GetWorkString on the RHS of an assignment expression, e.g.
<code>char myString[32] ;
myString = GetWorkString() ;</code>
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).
//delete a user campaign.  The filename is expected to include the CAMPAIGNS or MULTIPLAYER path element depending upon where the campaign is.  E.g. MULTIPLAYER/MYCAMPAIGN.  NOTE: it is good practice to prompt the user to confirm deletion.
DeleteUserCampaign(filename)</nowiki>


Script commands to control this are:
= Including Templates in UI Files =
You can now include other files in UI files.  Note this should be used with care as objects with the same names are still prohibited.  All includes must be the first thing in the UI file.  Lines must be of the form
#include "file.txt"
or
include "file.txt"
The template files must be in DATA/UI/TEMPLATES


  <nowiki>
= AreNewDownloads Script Command =
//if filename starts with # then defaults to standard unit loading paths.
  //returns 1 if there are new user content downloads available, 0 otherwise
UIObject3DLoad(objectName, filename, [texturePath])
AreNewDownloads()


//automatically set the zoom and camera origin to the size of the currently loaded object
= Button Text Colour Updates =
UIObject3DAuto(objectName)
You can now define different colours for buttons to use when they are being actioned.  These colours can be set globally in the UIDEFAULTS.TXT file using
BUTTONOVERCOLOUR <hex>
BUTTONDOWNCOLOUR <hex>
BUTTONDISABLEDCOLOUR <hex>
You can also over-ride these values on a per-button basis in the UI text file using
OVERCOLOUR <hex>
DOWNCOLOUR <hex>
DISABLEDCOLOUR <hex>


//set the origin position and vertical angle of the camera.
= PRESTARTEDITOR Callback =
SetUIObject3DCamera(objectName, x,y,z,angle,[zoom])
Tile. There is now a callback when the editor starts.  This can be located in either or both the CORE.BSF and scenario scripts.  The function is of the same form as PRESTARTBATTLE:
<nowiki>FUNCTION PreStartEditor(mode)</nowiki>


//set the options for the view.  0 for off, nonzero for on.
= Older Entries =
SetUIObject3DOptions(objectName, allowZoom, allowHorizontalRotate, allowVerticalRotate)
[[Archive_1]]
</nowiki>

Latest revision as of 21:58, 4 November 2024

Achievement Values

You can now get and set values for a campaign that are saved in the achievements file. New script commands 

SetAchievementValue, 2, 2, "(name, value) set the value of the named achievementvalue.  If doesn't exist will be created.") 
GetAchievementValue, 1, 1, "(name) get the value of the named achievementvalue.  If doesn't exist, returns 0.")

Region Map Highlights

You can now enable dynamic highlights as the mouse moves over a region map. See UI#REGIONMAP.

String File Naming

You can now name string files with additional descriptive information. The filenames must be of the form: 

Text<number><string>.TXT

Or 

Text<number><string>_<tag>.TXT

Where tag is the standard 3 character language tag. Note that the string entries do not need to be the same for all the members of a given text file group. E.g. the follow would be valid 

Text2General.txt
Text2_FRE.txt
Text2German_GER.txt

Restrictions are: you cannot start the description string with a number (can lead to ambiguous filenames). You cannot duplicate the _??? pattern at the end of a non-localised text filename.

Stricter String File Checking

There is now stricter string checking to determine that lines are either of the form 

TAG,"string",

or 

// comment

By default these check failures are shown as warnings, but you can enable error throwing by using the line 

MAXDEBUG 2

in the USER.TXT file. Note that comments can still follow a correctly formatted string line.

ELO Reroll Allows

If there is a checkbox named LobbyAllowRerolls in the MP challenge setup screen, then an allow rerolls bool will be set in the misc data. This is passed into the MP lobby tooltip callbacks as an ALLOWREROLLS param.

There is a new callback in battle RESIGN_BATTLE_CALLBACK. This should return -1 to do nothing. If it returns 1, then the skip rating flag will be set when sending the turn. To facilitate this, there are new script commands: 

GameAllowsRerolls
IsRanked

UI and Font Scaling

See: UI#UI_and_Font_Scaling

Copy + Paste in Edit Boxes

You can now copy and paste in Edit boxes. There is a new tag SELECTIONCOLOUR which allows you to alter the colour of the selection box displayed when selecting for copy.

You cannot copy from a password box. You cannot paste over text (e.g. paste into a selection thus replacing it).

You can also copy from textmode listboxes (as used by the MP chat box). This is only possible if you add an ALLOWCOPY tag to the UI control. There is also a TEXTSELECTIONCOLOUR tag which can be set on these controls.

4:3 Ratio UI overrides

In the rare case where a UI file needs special formatting for 4:3 ratio screens, you can define a different UI file to be loaded where appropriate. Simply create a folder called 43 in the same folder as the UI files. Any file in the 43 folder, which has the same name as a file in the parent folder, will be loaded instead, when running at a resolution with a 4:3 aspect ratio or lower.

Pick Callback

Tile. Use the following HELPERS.BSF callback to control picking/selection in battle. 

PICK_CALLBACK(blocking)

Where blocking is set to 1 when the mouse is over any UI block set with BlockUIArea during a render call. Return 0 to pick normally, 1 to prevent picking/selection.

Custom Mouse Handling

Tile. Callbacks exist for custom mouse handling. These are 

MOUSE_CLICK_HANDLER(action, tilex, tiley)    // in HELPERS.BSF
DEBUG_MOUSE_CLICK_HANDLER(action, tilex, tiley) // in DEBUG_HELPERS.BSF when enabled

They are triggered on mouse up. action is 0 for LMB, 1 for RMB. Return non-zero in MOUSE_CLICK_HANDLER to prevent normal mouse handling.

User Folder Redirection

If the user places a REDIRECT.TXT file in their local folder (e.g. Documents/My Games/<game>) which contains the line 

FOLDER <fullpath>

Then the game will treat the provided folder as the user folder for this game.

Hotkey Tooltips

You can now enable automatic hotkey tooltips. See the UI button documentation.

Hotkey Modifiers

Can now have UI control hotkeys with SHIFT and/or CTRL modifiers. See the UI documentation.

New Tile Callbacks

Tile. New callbacks 

// Allows for additional text to be added to skirmish descriptions in the MP creation screen.
// Place any string to be added in the first UI string
FUNCTION SKIRMISH_COMMENT_CALLBACK()

// Called immediately after loading the userdata when a game is loaded
// skirmish param is zero or one.  Userdata is in the first work array.
FUNCTION LOAD_USERDATA_CALLBACK(skirmish)

StartCampaign & ReplaceUnit Script Commands

Tile. StartCampaign can now take no params at which point it loads the ||SKIRMISH campaign as per skirmish battles. ReplaceUnit replaces one unit with another. In order to handle any custom setup (esp anything which is used in animation callbacks) there is a REPLACE_CALLBACK(me) callback where any required data can be set up after the new replacement unit has been initialized but before we try and sync up animations etc. So you will need to save out any specific attribs from the unit that you care about and then reset then in the callback (if needed) or after the ReplaceUnit call returns.

Screenshot/Movie Capture

Updates: there is now an onscreen flash when capturing a screenshot. You can also place entries for SCREENSHOTSFX and MOVIESFX into the UIDefaults.txt file in System. These should be numeric index values into the sfx list for sounds to be played when screenshotting, and when beginning a movie capture respectively.

Global saves

You can now pass an empty string into Load/SaveVariableData and it will load and save from a GLOBAL_DATA.TXT file in (e.g.) My Documents/My Games/FieldOfGlory2. This can be used to set up a global structure for persistent data across the game, e.g. hi scores or battles won.

Load Sequence Function

Tile. If the script CORE/LOADINIT.BSF exists then the function LoadInit from within it will be called at the very start of the main loading sequence, immediately after the first loadbar frame is shown.

Progress Bars Accept KEEPSQUARE

You can now use a KEEPSQUARE tag for progress bars if desired.

Global Orders

Tile. You can now include global orders which do not require a unit to be selected. These are defined in the CORE.BSF script, and should follow the template for standard unit orders (i.e. CHECK_, UIBUTTON_, etc functions must exist). These orders use a CORE_ prefix, rather than TILE_, UNIT_, or ALL_.

Gamma Adjustment

Two new commands allow for adjusting the gamma values when in fullscreen. To allow for saving of the gamma value (or others) there are 3 additional Custom* options values available. Custom1, Custom2, Custom3. All default to zero. Suggested values for gamma would be 0.5 to 2.0 or so, depending on the variation you wish to allow. 

//set the gamma value, if possible.  gamma is in 1000ths.
SetGamma(gamma)

//returns 1 if the current setup allows for gamma adjustment (e.g. driver support, or because gamma requires fullscreen).
AllowsGamma()

Get/SetUnitString Script Commands

Tile. New commands to allow a custom unicode string to be attached to a unit. 

//place the contents of the first UI string as a custom string for the unit. 
SetUnitString(me)

//place the contents of the unit custom string into the first UI string.  Returns 0 if there is no custom string, 1 otherwise
GetUnitString(me)

User Content Debugging

Tile. When in DEBUGMODE is set to 2, the system will additionally load list_debug.txt into the user content list from the server. This is to allow for simpler testing of user content from the server without polluting the release list.

GetSkirmishPoints & GetCurrentMod

Tile. New script commands to fetch the currently set skirmish points, and to query the current mod. 

//sets the first 4 values in the first work array with the current skirmish points values (fixed0, fixed1, select0, select1)
GetSkirmishPoints()

//if a mod is selected, place the name of the current mod into the first UI string and return its index, otherwise return -1.  Always returns -1 in multiplayer.
GetCurrentMod()

Modding Updates

Tile. Mods can now override S4F and their animation files for units. They can also override scripts for AI, unit, HELPERS, and CORE BSF files. NOTE: to package global mods, you need a ModsPackage named button on the mod UI panel.

Lobby Colouring Tweak

Tile. You can now use the VALUE5 entry for the accept games list to define the RGB value for disabled games (where you do not have the necessary campaign etc). Alpha is set to 0xFF by the game. Zero uses the default colouring.

String Attribs

Tile. You can have up to 8 read-only strings attached to a squad template. These must be defined in the squads file using tags ##0 to ##7. The string data for each element must have 27 characters or less, and spaces are not permitted. You can then retrieve these using the new command 

//place the given attrib string into the first work string.  typeIndex is the index of the unit type. index is currently [0,7].
GetAttribString(typeIndex, index)

Note that the string returned will have been converted into upper case.

UpdateUserStringFromUI and GetUIEditboxToInt Script Commands

//take the UI string from an editbox object and update it if it has changed (or is new).  Return 1 if a change has been made, zero otherwise.
UpdateUserStringFromUI(objectName, tag)

//takes the contents of the UI editbox and converts them to a string.  If there are any non-numeric characters in the string, then the return value is invalidValue.  Skips leading and trailing whitespace.
GetUIEditboxToInt(objectName, invalidValue)

Review Battlefield After Battle

Tile. You can now set up the UI to allow the user to review the battlefield after a battle ends. To do this you should:

  • Add a button the the EndBattle control called EndBattleReview
  • Create a new UI screen to allow the user to exit after they have finished reviewing. This screen should be called EndReview, and should include a button named EndReviewOK. EndReview should not be modal, but should have the same HANDLER as EndBattle (DeployHandler).

This should allow the player to review the battlefield, with all units shown.

ShowUIListboxItem

New script command which moves the viewable area (if needed) to show the given item. 

//move the UI listbox to show the given item index.  Scrolls unless immediate is non-zero, in which case it instantly changes the view
ShowUIListboxItem(objectName, index, [immediate])

GetString Control Change

If the UI object GetStringTitle exists, then the title text for the system GetString control will be placed there, rather than in the title of the GetString object window as per default.

DEPLOY_DRAG_CALLBACK

Tile. Unit script function that is called each time a unit is moved by dragging when in deployment. 

FUNCTION DEPLOY_DRAG_CALLBACK(me, tilex, tiley)

Multiline for UI Edit Controls

Adding a CHATMODE tag to edit controls will now allow them to contain more than one line.

Further INCLUDE Functionality for UI Files

You can now use a prefix to rename included UI file components, allowing reuse of UI fragments. See here:UI

User Music Control

Tile. You can alter the music that is playing using the new script command 

//switch to the denoted music track.  Must be [0,5] currently as per the MUSIC.TXT file order.
SwitchMusic(track)

Can be combined with the new tweak DisableDefaultMusic, which stops all hardcoded changes of music (NOTE: other than the initial playing of the main menu music, and some other changes back to the main menu music when internal code takes the UI back to the main menu).

It is also worth reminding of the existence of the SetMusicFile command 

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

New Script Commands: GetMapStyle & DeleteUserCampaign

Tile. 

//place the current map style string into the first work string.
GetMapStyle()

//delete a user campaign.  The filename is expected to include the CAMPAIGNS or MULTIPLAYER path element depending upon where the campaign is.  E.g. MULTIPLAYER/MYCAMPAIGN.  NOTE: it is good practice to prompt the user to confirm deletion.
DeleteUserCampaign(filename)

Including Templates in UI Files

You can now include other files in UI files. Note this should be used with care as objects with the same names are still prohibited. All includes must be the first thing in the UI file. Lines must be of the form 

#include "file.txt"

or 

include "file.txt"

The template files must be in DATA/UI/TEMPLATES

AreNewDownloads Script Command

//returns 1 if there are new user content downloads available, 0 otherwise
AreNewDownloads()

Button Text Colour Updates

You can now define different colours for buttons to use when they are being actioned. These colours can be set globally in the UIDEFAULTS.TXT file using 

BUTTONOVERCOLOUR <hex>
BUTTONDOWNCOLOUR <hex>
BUTTONDISABLEDCOLOUR <hex>

You can also over-ride these values on a per-button basis in the UI text file using 

OVERCOLOUR <hex>
DOWNCOLOUR <hex>
DISABLEDCOLOUR <hex>

PRESTARTEDITOR Callback

Tile. There is now a callback when the editor starts. This can be located in either or both the CORE.BSF and scenario scripts. The function is of the same form as PRESTARTBATTLE: 

FUNCTION PreStartEditor(mode)

Older Entries

Archive_1

Retrieved from "https://archonwiki.slitherine.com/index.php?title=Latest_Additions&oldid=571"