Units - Revision history

Phil at 22:31, 4 January 2019

2019-01-04T22:31:32Z

← Older revision		Revision as of 22:31, 4 January 2019
Line 94:		Line 94:
	<nowiki>//set the banner index for a unit. A unit can have 2 banners (to allow for component-style banners). so index [0,1]. bannerIndex as defined in the BANNER.TXT file. zero for off.		<nowiki>//set the banner index for a unit. A unit can have 2 banners (to allow for component-style banners). so index [0,1]. bannerIndex as defined in the BANNER.TXT file. zero for off.
	SetUnitBanner(me, index, bannerIndex)</nowiki>		SetUnitBanner(me, index, bannerIndex)</nowiki>

			= Animation File Documentation =
			[Note this is incomplete]
			Unit animations are defined in a .txt file with the same name as the unit S4F file. The format of the chunks in the file is of the form:

			[<animName><index>]
			FRM <start> <end>

			e.g.

			[WAIT00]
			FRM 212 250

			Animation numbering needs to start at 00 and increment one by one. All index values must be double digits, 00, 01, 02, etc.

			Animations can also have various triggers attached. These are:

			SFX <frame> <sfxIndex> [<sfxIndex> <sfxIndex> <sfxIndex>] // play a random one of the provided sfxs.
			FX <frame> <particleEffectIndex> // play a particle effect on the unit
			FREQ <value> // alter the frequency of a specific index of an animation. Default 100, less means the animation is seen less.
			DELAY <value> // Set a random delay at the start of the animation of [0,N] frames where N is [0,10]. Note that this means any triggers on the first frame will be triggered multiple times.
			CALL <frame> <param0> [<param1> <param2>] // call the CUSTOM_TRIGGER function in the unit script with the provided params - params default to zero if not provided.
			AMBIENT <sfxIndex> [<sfxIndex> <sfxIndex> <sfxIndex>] // play randomised ambient sfx while playing this animation

Phil: /* Banners */

2017-02-06T22:59:40Z

Banners

← Older revision		Revision as of 22:59, 6 February 2017
Line 92:		Line 92:
	TEX <texture> // optional texture filename for a texture which will be applied to this mesh when rendered using this index</nowiki>		TEX <texture> // optional texture filename for a texture which will be applied to this mesh when rendered using this index</nowiki>
	To give a unit a banner use the new script command SetUnitBanner		To give a unit a banner use the new script command SetUnitBanner
	<nowiki> </nowiki>		<nowiki>//set the banner index for a unit. A unit can have 2 banners (to allow for component-style banners). so index [0,1]. bannerIndex as defined in the BANNER.TXT file. zero for off.
			SetUnitBanner(me, index, bannerIndex)</nowiki>

Phil at 22:54, 6 February 2017

2017-02-06T22:54:33Z

← Older revision		Revision as of 22:54, 6 February 2017
Line 84:		Line 84:
	<code>FUNCTION UIBUTTON_ALL_MOVE(me, x,y,width, height, tilex, tiley)</code>		<code>FUNCTION UIBUTTON_ALL_MOVE(me, x,y,width, height, tilex, tiley)</code>
	This function allows for custom rendering of the order button.		This function allows for custom rendering of the order button.

			= Banners =
			Banners are 3D meshes which can display over a squad. Any meshes and textures should live in the DATA/BATTLE/BANNERS folder in either the main or campaign folder. Campaign entries will generally over-ride main versions. You use a BANNER.TXT file to denote the banners which are used. This has the form:
			<nowiki>[chunk_name_can_be_anything]
			BANNER <mesh name> // the name of the mesh, with type omitted
			INDEX <index> // the index for this banner. Must be [1,255]
			TEX <texture> // optional texture filename for a texture which will be applied to this mesh when rendered using this index</nowiki>
			To give a unit a banner use the new script command SetUnitBanner
			<nowiki> </nowiki>

Richards: /* Custom Formations */

2016-04-26T18:12:39Z

Custom Formations

← Older revision		Revision as of 18:12, 26 April 2016
Line 15:		Line 15:
	SetFormationRowXY(n, x, y)</code>		SetFormationRowXY(n, x, y)</code>

			NOTE: What both these functions set is the points making up the formation. They do not assign a particular man to a particular formation point. A scoring algorithm determines which man moves to which formation point when the formation changes.

	= Unit Order Scripting =		= Unit Order Scripting =

Richards at 18:01, 15 March 2016

2016-03-15T18:01:42Z

← Older revision		Revision as of 18:01, 15 March 2016
Line 11:		Line 11:
	or, alternatively, the SetFormationRowXY function:		or, alternatively, the SetFormationRowXY function:

	<code>//Set the location of the nth man in the unit relative to the center of the tile, using offsets when facing 0. Only relevant in FORMATION_CALLBACK		<code>//Set the location of the nth man in the unit relative to the center of the tile, using offsets when facing 0. offset is [0, 32]. Only relevant in FORMATION_CALLBACK

	SetFormationRowXY(n, x, y)</code>		SetFormationRowXY(n, x, y)</code>

Richards at 17:59, 15 March 2016

2016-03-15T17:59:47Z

← Older revision		Revision as of 17:59, 15 March 2016
Line 12:		Line 12:

	<code>//Set the location of the nth man in the unit relative to the center of the tile, using offsets when facing 0. Only relevant in FORMATION_CALLBACK		<code>//Set the location of the nth man in the unit relative to the center of the tile, using offsets when facing 0. Only relevant in FORMATION_CALLBACK

	SetFormationRowXY(n, x, y)</code>		SetFormationRowXY(n, x, y)</code>

Richards at 17:59, 15 March 2016

2016-03-15T17:59:25Z

← Older revision		Revision as of 17:59, 15 March 2016
Line 8:		Line 8:
	<code>//Set the location of the nth man in the unit relative to the center of the tile. offset is [0, 32], angle is [0, 359]. Only relevant in FORMATION_CALLBACK		<code>//Set the location of the nth man in the unit relative to the center of the tile. offset is [0, 32], angle is [0, 359]. Only relevant in FORMATION_CALLBACK
	SetFormationRow(n, offset, angle)</code>		SetFormationRow(n, offset, angle)</code>

			or, alternatively, the SetFormationRowXY function:

			<code>//Set the location of the nth man in the unit relative to the center of the tile, using offsets when facing 0. Only relevant in FORMATION_CALLBACK
			SetFormationRowXY(n, x, y)</code>

Phil: /* Unit Order Scripting */

2016-01-25T17:19:08Z

Unit Order Scripting

← Older revision		Revision as of 17:19, 25 January 2016
Line 60:		Line 60:

	If the check function returns >=0 then this is taken as the AP cost of the action, and the system then calls the REACT_ function. The react function should return a 'score' for this unit using this action to react to the threat. Examples of how to calculate this score we be based on things like chance of success, range to target, etc - as dependent upon the game model. The system will go through all units on the reacting side and then sort the reactions by their scores, and execute them in the 'best' order. Note that returning -1 from a REACT_ function means that you do not want the unit to attempt to react with this action.		If the check function returns >=0 then this is taken as the AP cost of the action, and the system then calls the REACT_ function. The react function should return a 'score' for this unit using this action to react to the threat. Examples of how to calculate this score we be based on things like chance of success, range to target, etc - as dependent upon the game model. The system will go through all units on the reacting side and then sort the reactions by their scores, and execute them in the 'best' order. Note that returning -1 from a REACT_ function means that you do not want the unit to attempt to react with this action.

			== Other Unit Callbacks ==
			=== Moving from Tile ===
			<code>FUNCTION MOVE_FROM_TILE_CALLBACK(me)</code>
			This callback is called whenever a unit is about to move off from a tile during a movement (e.g. it is called once for each tile on the route). Returning -1 or -2 will cancel the movement (e.g. the whole route), the difference being that -1 does not refund any APs used for movement, while -2 does. Return zero for normal movement.

			=== Deployment ===
			<code>FUNCTION DEPLOYCHECK_ALL_MOVE(me, unit, tilex, tiley)</code>
			This works in the same way as the normal CHECK_ function, but is only called during a deployment phase - if it exists then it is called rather than the normal CHECK_ function during deployment.

	=== Icon Setup ===		=== Icon Setup ===
	<code>FUNCTION UISETUP_ALL_<name>( x, y, width, height, me, tilex, tiley )</code>		<code>FUNCTION UISETUP_ALL_<name>( x, y, width, height, me, tilex, tiley )</code>
	This optional function can be used to setup and draw the order icon. The x,y,width,height parameters are the onscreen positions of the button.		This optional function can be used to setup and draw the order icon. The x,y,width,height parameters are the onscreen positions of the button. Functions such as SetUITexture are used within this function, and any button tooltip is also set up here.

			=== Custom Button Rendering ===
			<code>FUNCTION UIBUTTON_ALL_MOVE(me, x,y,width, height, tilex, tiley)</code>
			This function allows for custom rendering of the order button.

Phil: /* Unit Order Scripting */

2016-01-25T17:11:56Z

Unit Order Scripting

← Older revision		Revision as of 17:11, 25 January 2016
Line 35:		Line 35:
	=== Init Functions ===		=== Init Functions ===

	<code>FUNCTION INIT_*( me )<code>		<code>FUNCTION INIT_*( me )</code>
	Any function which is named with INIT_ as the first 5 characters will be called on unit creation. You can use this to set up attributes, initialised starting values, etc. Note that if there is more than one INIT_ function then the order they will be called in cannot be guaranteed.		Any function which is named with INIT_ as the first 5 characters will be called on unit creation. You can use this to set up attributes, initialised starting values, etc. Note that if there is more than one INIT_ function then the order they will be called in cannot be guaranteed.

Phil: /* Unit Order Scripting */

2016-01-25T17:11:25Z

Unit Order Scripting

← Older revision		Revision as of 17:11, 25 January 2016
Line 28:		Line 28:
	This function is called at the start of a unit's side's turn. This would be used to reset any per-turn counters or limits. Examples would be a unit's shots, or tick up its morale. STARTTURN is a required function for every unit.		This function is called at the start of a unit's side's turn. This would be used to reset any per-turn counters or limits. Examples would be a unit's shots, or tick up its morale. STARTTURN is a required function for every unit.

	CustomTrigger		=== CustomTrigger ===

	FUNCTION CUSTOM_TRIGGER( me, a, b, c, d )		<code>FUNCTION CUSTOM_TRIGGER( me, a, b, c, d )</code>
	The custom trigger is a low level function used to trigger scripting from the unit animation files. It passes through any of the 4 parameters allowed in the animation file for a unit.		The custom trigger is a low level function used to trigger scripting from the unit animation files. It passes through any of the 4 parameters allowed in the animation file for a unit.

	Init Functions		=== Init Functions ===

	FUNCTION INIT_*( me )		<code>FUNCTION INIT_*( me )<code>
	Any function which is named with INIT_ as the first 5 characters will be called on unit creation. You can use this to set up attributes, initialised starting values, etc. Note that if there is more than one INIT_ function then the order they will be called in cannot be guaranteed.		Any function which is named with INIT_ as the first 5 characters will be called on unit creation. You can use this to set up attributes, initialised starting values, etc. Note that if there is more than one INIT_ function then the order they will be called in cannot be guaranteed.

	Unit Ability Functions		=== Unit Ability Functions ===
			To actually allow a unit to do anything, it needs to have scripted behaviours.
	To actually allow a unit to do anything, it needs to have scripted behaviours. An example can be seen in the Case Study at the end of this document, but the key functionality is described below. Once again we also recommend reading through and editing (in your own custom campaign, never in the main game data!) the existing unit scripts to see how it all hangs together.

	There are 3 types of ability, depending upon the contents of the tile you are attempting to action. These are TILE_, ALL_, and UNIT_. TILE_ can operate only on empty tiles, ALL_ will attempt to work on all tiles, and UNIT_ will only operate on a tile with a unit present on it.		There are 3 types of ability, depending upon the contents of the tile you are attempting to action. These are TILE_, ALL_, and UNIT_. TILE_ can operate only on empty tiles, ALL_ will attempt to work on all tiles, and UNIT_ will only operate on a tile with a unit present on it.
Line 48:		Line 47:
	Note that for all the functions described here, you can omit any of the parameters you don't use, and that the code will correctly assign them no matter where in the param list they are. Indeed, you can have extra parameters in a function header and they will be set to zero if they are called by the code rather than by you.		Note that for all the functions described here, you can omit any of the parameters you don't use, and that the code will correctly assign them no matter where in the param list they are. Indeed, you can have extra parameters in a function header and they will be set to zero if they are called by the code rather than by you.

	Checking		=== Checking ===
			<code>FUNCTION CHECK_ALL_<name>( me, unit, tilex, tiley [, reaction] )</code>
	FUNCTION CHECK_ALL_<name>( me, unit, tilex, tiley [, reaction] )
	This function is used to determine whether a unit can perform a task. The return value can be either the cost of the action in AP, or -2 if you with the task icon not to be shown, or -1 if you wish to show the icon in a disabled state. See below for details on the optional reaction parameter.		This function is used to determine whether a unit can perform a task. The return value can be either the cost of the action in AP, or -2 if you with the task icon not to be shown, or -1 if you wish to show the icon in a disabled state. See below for details on the optional reaction parameter.

	~~Icon Setup~~		=== Executing ===
			<code>FUNCTION ALL_<name>(me, unit, tilex, tiley)</code>
	~~FUNCTION UISETUP_ALL_~~<~~name~~>~~( x, y, width, height, me, tilex, tiley )~~
	~~This function can be used to setup and draw the order icon. The x,y,width,height parameters are the onscreen positions of the button.~~

	~~Executing~~

	FUNCTION ALL_<name>(me, unit, tilex, tiley)
	This is the function which is called when the user selects the action for the unit. Note this cannot happen if the check function returns -1 or -2 as the icon will not be selectable.		This is the function which is called when the user selects the action for the unit. Note this cannot happen if the check function returns -1 or -2 as the icon will not be selectable.

	Reacting		=== Reacting ===
			<code>FUNCTION REACT_ALL_<name>(me, unit, tilex, tiley)</code>
	FUNCTION REACT_ALL_<name>(me, unit, tilex, tiley)
	If you want a unit to be able to react to other units, then you make use of the reaction function. This works in concert with the CHECK_ function for a given command. The system first calls the CHECK_ function to determine whether an action is possible against the reacted-against unit. Note that when CHECK_ is called in this case, the optional reaction parameter is set to 1, rather than 0 as it normally is.		If you want a unit to be able to react to other units, then you make use of the reaction function. This works in concert with the CHECK_ function for a given command. The system first calls the CHECK_ function to determine whether an action is possible against the reacted-against unit. Note that when CHECK_ is called in this case, the optional reaction parameter is set to 1, rather than 0 as it normally is.

	If the check function returns >=0 then this is taken as the AP cost of the action, and the system then calls the REACT_ function. The react function should return a 'score' for this unit using this action to react to the threat. Examples of how to calculate this score we be based on things like chance of success, range to target, etc - as dependent upon the game model. The system will go through all units on the reacting side and then sort the reactions by their scores, and execute them in the 'best' order. Note that returning -1 from a REACT_ function means that you do not want the unit to attempt to react with this action.		If the check function returns >=0 then this is taken as the AP cost of the action, and the system then calls the REACT_ function. The react function should return a 'score' for this unit using this action to react to the threat. Examples of how to calculate this score we be based on things like chance of success, range to target, etc - as dependent upon the game model. The system will go through all units on the reacting side and then sort the reactions by their scores, and execute them in the 'best' order. Note that returning -1 from a REACT_ function means that you do not want the unit to attempt to react with this action.

			=== Icon Setup ===
			<code>FUNCTION UISETUP_ALL_<name>( x, y, width, height, me, tilex, tiley )</code>
			This optional function can be used to setup and draw the order icon. The x,y,width,height parameters are the onscreen positions of the button.