Latest Additions: Difference between revisions

From Archon Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(151 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= LoadVariableFromParserFile =
= Achievement Values =
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.
You can now get and set values for a campaign that are saved in the achievements file.  New script commands
<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.
SetAchievementValue, 2, 2, "(name, value) set the value of the named achievementvalue.  If doesn't exist will be created.")
LoadVariableFromParserFile(variableName, filename)</nowiki>
GetAchievementValue, 1, 1, "(name) get the value of the named achievementvalue. If doesn't exist, returns 0.")
An example input file might be of the form:
  <nowiki>[0]
side 10
data[0] 89
data[2] 5


[3]
= Region Map Highlights =
side 33</nowiki>
You can now enable dynamic highlights as the mouse moves over a region map. See [[UI#REGIONMAP]].
And would be used as such:
  <nowiki>struct TLoad
{
  int side ;
  int data[4] ;
}
TLoad gLoad[256] ;
...
  LoadVariableFromParserFile("gLoad", "MapData") ;</nowiki>


= SetCameraPositionPrecise & StopSFX =
= String File Naming =
Tile. New script commands.
You can now name string files with additional descriptive information. The filenames must be of the form:
  <nowiki>//set the camera to instantly point to the given point (defined in 100ths), centering it on the screen
Text<number><string>.TXT
SetCameraPositionPrecise(x, y)
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.


//stop a playing sample using a playback ID.  Has no effect if the sample is over, or has been stopped by the system.
= Stricter String File Checking =
StopSFX(playbackID)</nowiki>
There is now stricter string checking to determine that lines are either of the form
Note that the playbackID is newly returned from SFX playback functions.
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.


= Object Terrain Priority =
= ELO Reroll Allows =
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].
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.


= Unit Scaling =
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:
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.
GameAllowsRerolls
IsRanked


= Textbox Rescale and Scrolling =
= UI and Font Scaling =
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.
See: [[UI#UI_and_Font_Scaling]]


= Force Selection Script Additions =
= Copy + Paste in Edit Boxes =
Tile. Additional script commands to allow for custom force controls.
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 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)
You cannot copy from a password box.  You cannot paste over text (e.g. paste into a selection thus replacing it).
GetForceControlSelected(objectName, x, y)


//set the zoom level for the camera in battle
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.
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 =
= 4:3 Ratio UI overrides =
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.
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>FUNCTION UI_OBJ_RENDER(x,y,width,height,pass, name)
FUNCTION UI_OBJ_HANDLE(data, event, id, name)</nowiki>


= Water =
= Pick Callback =
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.
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.


= Flying Units =
= Custom Mouse Handling =
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.
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.


= GetPositionDistance Script Command =
= User Folder Redirection =
Takes two positions (in 100ths) and returns the distance between them.
If the user places a REDIRECT.TXT file in their local folder (e.g. Documents/My Games/<game>) which contains the line
  <nowiki>//return the distance in 100ths between two points that are also in 100ths
  FOLDER <fullpath>
GetPositionDistance(x1,y1,x2,y2)</nowiki>
Then the game will treat the provided folder as the user folder for this game.


= Terrain Following Objects =
= Hotkey Tooltips =
You can use the TERRAINFOLLOW tag to allow objects to align themselves to the terrain.
You can now enable automatic hotkey tooltips.  See the UI button documentation.


= New Script Functions =
= Hotkey Modifiers =
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.
Can now have UI control hotkeys with SHIFT and/or CTRL modifiers.  See the UI documentation.
<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
= New Tile Callbacks =
FindStringInArray(string, elementName, array)</nowiki>
Tile. New callbacks


An example would be
// Allows for additional text to be added to skirmish descriptions in the MP creation screen.
  <nowiki>struct TTest
  // Place any string to be added in the first UI string
{
FUNCTION SKIRMISH_COMMENT_CALLBACK()
  char name[32] ;
  int value ;
}
...
TTest array[2][32] ;


  Sort("value", array[1], 32) ;</nowiki>
// 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)


= AddVizUnitFormation Command =
= StartCampaign & ReplaceUnit Script Commands =
This command allows to you trigger and wait for a formation change.
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.


  <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.
= Screenshot/Movie Capture =
AddVizUnitFormation(id)</nowiki>
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.


=Formation Facing Control =
= Global saves =
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.
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.


<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
= Load Sequence Function =
SetFormationFacing(n, facing)</nowiki>
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.


= Scrollable Text Controls =
= Progress Bars Accept KEEPSQUARE =
Text controls can now be made scrollable. Add
You can now use a KEEPSQUARE tag for progress bars if desired.


  <nowiki>SCROLLING <control texture> </nowiki>
= 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_.


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.
= 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.
  <nowiki>//set the gamma value, if possible.  gamma is in 1000ths.
SetGamma(gamma)


= String Manipulation and Creation =
//returns 1 if the current setup allows for gamma adjustment (e.g. driver support, or because gamma requires fullscreen).
You can allow the user to create string entries (expected in the editor) via script. The new functions are:
AllowsGamma()</nowiki>


  <nowiki>//places the contents of the edit box into the first UI string.
= Get/SetUnitString Script Commands =
GetUIEditbox(objectName)
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)


//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
//place the contents of the unit custom string into the first UI string.  Returns 0 if there is no custom string, 1 otherwise
AddUserString(tagBody)
GetUnitString(me)


//remove the denoted user string from the temporary store.  Has no effect if the string has already been written out to the file.
= User Content Debugging =
RemoveUserString(tag)
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.


//flush out any user strings to the TEXT9.TXT file.  NOTE: this is done automatically at map save and editor exit.
= GetSkirmishPoints & GetCurrentMod =
FlushUserStrings()
Tile. New script commands to fetch the currently set skirmish points, and to query the current mod.
  <nowiki>//sets the first 4 values in the first work array with the current skirmish points values (fixed0, fixed1, select0, select1)
GetSkirmishPoints()


//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.
//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.
GetHighestStringIndex(tagBody)
GetCurrentMod()</nowiki>


//return 1 if the string exists, 0 otherwise
= Modding Updates =
DoesStringExist(tag)
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.


//get the denoted string into the first UI string if it exists.  Empty otherwise
= Lobby Colouring Tweak =
GetString(tag)</nowiki>
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.


So users can type in strings which are then added to the list of strings available to use ingame.
= 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
<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.


= Script Updates =
= UpdateUserStringFromUI and GetUIEditboxToInt Script Commands =
1 - the break directive to trigger the debugger has changed to DebugBreak ; to prevent confusion with the C break statement.
<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.
UpdateUserStringFromUI(objectName, tag)


2 - while loops are now supported.  Note that the test cannot be an operation, so
//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.
<code>while(i--)</code>
GetUIEditboxToInt(objectName, invalidValue)</nowiki>
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) =
= Review Battlefield After Battle =
Individual UI objects can now have their own scripts attached, including their own rendering callbacks.  As before the rendering callback is 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:
* 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.


  <code>FUNCTION UI_OBJ_RENDER(x,y,width,height,pass)</code>
= 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])


Where pass is 0/1 for pre/post normal control rendering.
= 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.


Listboxes can also include
= 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)


<code>FUNCTION UI_OBJ_RENDER_ITEM(x,y,width,height,pass,flags, item, name)</code>
= Multiline for UI Edit Controls =
Adding a CHATMODE tag to edit controls will now allow them to contain more than one line.


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.
= 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]]


= Listboxes: Multiple Selection =
= User Music Control =
You can enable multiple selection for listboxes with the MULTISELECT tag in their UI definition. Then use
Tile.  You can alter the music that is playing using the new script command
<nowiki>//switch to the denoted music track.  Must be [0,5] currently as per the MUSIC.TXT file order.
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).


  <nowiki>//return 1 if the specified item is selected, zero otherwise
It is also worth reminding of the existence of the SetMusicFile command
IsUIListboxItemSelected(object, index)
  <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>


//returns the number of items in a listbox
= New Script Commands: GetMapStyle & DeleteUserCampaign =
GetUIListboxCount(object)</nowiki>
Tile.
<nowiki>//place the current map style string into the first work string.
GetMapStyle()


to interrogate the listbox.   
//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>


<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>
= 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


= Scripting: GetWorkString =
= AreNewDownloads Script Command =
You can now use GetWorkString on the RHS of an assignment expression, e.g.
//returns 1 if there are new user content downloads available, 0 otherwise
<code>char myString[32] ;
  AreNewDownloads()
  myString = GetWorkString() ;</code>
The contents will be safely truncated to the source string's size.


= 3DVIEW UI Control =
= 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>


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).
= 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:
<nowiki>FUNCTION PreStartEditor(mode)</nowiki>


Script commands to control this are:
= Older Entries =
 
[[Archive_1]]
<nowiki>
//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)
</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"