Skip to content

Latest commit

 

History

History
268 lines (261 loc) · 40.1 KB

kp.Actions.orig.md

File metadata and controls

268 lines (261 loc) · 40.1 KB

Actions

Actions are written in a form Actions.ACTION_NAME(ACTION_PARAMETERS); like so:

    if States.StatArmyCount(0) <= 3 then
      Actions.PlayerDefeat(0); // Defeat 1st player

Most of action parameters are numeric (except houses, units and some others when mentioned).

Version column description:
"-" Means this action was added from the start.
"5678" Means this action was introduced in revision 5678.
"-5678" Means this action was removed in revision 5678.


Ver
sion		 Action description Parameters
and types		 Returns
8250 CampaignChapterSetup
Sets up campaign chapter info in campaign menu. Campaign-only action!		 aChapter: Integer; //chapter index to set up
aTitle: String; //text to display for the chapter title
aShortTitle: String; //text to display for the chapter short title
aBackgroundImg: String; //sprite to be used for the chapter background map (*.png)
8794 CampaignMissionResult
Sets up mission result in campaign menu. Campaign-only action!		 aMission: Integer; //mission index to set up
aResult: String; //text to display for the mission result
8250 CampaignMissionSetup
Sets up all of the campaign mission info in campaign menu. Campaign-only action!		 aMission: Integer; //mission index to set up
aUnlocked: Boolean; //Should it be available for selection and play
aWon: Boolean; //should it be marked as won
aFlagImgLocked: String; //sprite to be used for the locked state flag (*.png)
aFlagImgNormal: String; //sprite to be used for the normal state flag (*.png)
aFlagImgWon: String; //sprite to be used for the won state flag (*.png)
aFlagPosX: Integer; //flag X position on the campaign map
aFlagPosY: Integer; //flag Y position on the campaign map
aTitle: String; //text to display for the mission title
aBriefing: String; //text to display for the mission briefing
8261 CampaignMissionUnlock
Sets up unlocked status of a campaign mission in a campaign menu. Campaign-only action!		 aMission: Integer; //mission index to unlock
aUnlocked: Boolean; //Should it be available for selection and play
8722 CampaignMissionWon
Sets up won status of a campaign mission in a campaign menu. Campaign-only action!		 aMission: Integer; //mission index to set up
aWon: Boolean; //Won status
8261 CampaignProgress
Sets up progress campaign info in campaign selection menu. Campaign-only action!		 aProgress: String; //campaign progress displayed in the campaign selection menu
8250 CampaignSetup
Sets up generic campaign info in campaign selection menu. Campaign-only action!		 aProgress: String; //campaign progress displayed in the campaign selection menu
aNodeImg: String; //sprite to be used for the nodes between mission flags (*.png)
aMissionNext: Integer; //which mission will be selected by default to be played next
8155 CinematicBarsHide
Hides cinematic black bars around the screen
8155 CinematicBarsShow
Shows cinematic black bars around the screen
8155 CinematicBegin
Starts cinematic mode. Blocks all viewport controls
8155 CinematicEnd
Ends cinematic mode. Unblocks viewport controls
8155 CinematicFadeIn
Gradually reveals the screen from full black		 aDurationSec: Single; //effect duration in seconds
8155 CinematicFadeOut
Gradually darkens the screen to full black		 aDurationSec: Single; //effect duration in seconds
8585 CinematicSpeechBubble
Shows speech bubble at specified location and height over terrain		 aX: Single;
aY: Single;
aHeight: Single;
aScale: Byte;
aText: String;
aDurationSec: Single;
8155 CinematicSubtitle
Shows the subtitles		 aText: String;
8155 CinematicText
Shows the text in the middle of the screen		 aText: String;
aScale: Byte; //Text scale 1..16
8155 CinematicViewMoveTo
Moves the camera		 aX: Single;
aY: Single;
aHeading: Single;
aZoom: Single;
aDurationSec: Single; //move duration in seconds
8155 CinematicViewMoveToEx
Moves the camera with more control over the setup		 aX: Single;
aY: Single;
aHeading: Single;
aPitch: Single;
aDist: Single;
aFOV: Single;
aDurationSec: Single; //move duration in seconds
8155 CinematicViewReset
Resets the camera to default orientation and zoom
8155 CinematicViewRevert
Restores player viewport setup (position, orientation, zoom)
8155 CinematicViewSetTo
Sets the camera		 aX: Single;
aY: Single;
aHeading: Single;
aZoom: Single;
8166 CinematicViewSetToDefault
Sets the camera X and Y. Heading and zoom are set to default		 aX: Single;
aY: Single;
8155 CinematicViewSetToEx
Sets the camera with more control over the setup		 aX: Single;
aY: Single;
aHeading: Single;
aPitch: Single;
aDist: Single;
aFOV: Single;
8155 CinematicViewStore
Saves player viewport setup (position, orientation, zoom)
8461 FenceAdd
Set a fence on terrain		 X,Y: Word;
aDir: Word;
aFenceType: Integer; //Type of the fence
TKMFenceType: Integer;
aPlayer: Integer; //Owner of the fence		 Boolean //Success or fail
8461 FenceRemove
Remove fence from terrain		 X,Y: Word;
aDir: Word;
- FogCoverAll
Cover whole map with fog of war for specified player		 aPlayer: Integer;
- FogCoverCircle
Cover circle with fog of war		 aPlayer: Integer;
X: Word;
Y: Word;
aRadius: Word;
- FogCoverRect
Cover rectangle with fog of war		 aPlayer: Integer;
X1: Word;
Y1: Word;
X2: Word;
Y2: Word;
- FogRevealAll
Reveal whole map		 aPlayer: Integer;
- FogRevealCircle
Reveal circle		 aPlayer: Integer;
X: Word;
Y: Word;
aRadius: Word;
- FogRevealRect
Reveal rectangle		 aPlayer: Integer;
X1: Word;
Y1: Word;
X2: Word;
Y2: Word;
- GiveGroup
Gives group to a player		 aPlayer: Integer;
aUnitType: TKMUnitType;
X,Y: Word;
aDir: Word;
aCount: Word;
aColumns: Word;		 Integer //UID of the group on success
4433 GiveHouse
Places house on terrain, removing removable objects below it (trees and such)
If there are units below - placement fails		 aPlayer: Integer;
aHouseType: TKMHouseType;
X,Y: Word;
aFace: TKMHouseFace;		 Integer //UID of the house on success
- GiveUnit
Gives unit to a player		 aPlayer: Integer;
aUnitType: TKMUnitType;
X,Y: Word;
aDir: Word;		 Integer //UID of the unit on success
- GiveWares
Wares are added to first Camp		 aPlayer: Integer;
aWareType: TKMWareType;
aCount: Word;
- GiveWeapons
Weapons are added to first Barracks		 aPlayer: Integer;
aWareType: TKMWareType;
aCount: Word;
- GroupOrderAttackHouse aGroupID: Integer;
aHouseID: Integer;
- GroupOrderAttackUnit aGroupID: Integer;
aUnitID: Integer;
- GroupOrderFood aGroupID: Integer;
- GroupOrderHalt aGroupID: Integer;
- GroupOrderLink
Order the group to link to another group (if possible)		 aGroupID: Integer;
aDestGroupID: Integer;
- GroupOrderSplit aGroupID: Integer; Integer //UID of the separated group
- GroupOrderStorm aGroupID: Integer;
- GroupOrderWalk aGroupID: Integer;
aX: Word;
aY: Word;
aDirection: Word;
6982 GroupOwnerChange
Change owner of the group. Technically it kills old units and creates new ones with the same basic props
(type, position, direction, hp, condition). All the advanced props and states do not get copied over.
If old group was moving/fighting, it is not guaranteed that new group units will be placed on the same positions		 aGroupID: Integer;
aPlayer: Integer;		 Integer //UID of new group
- GroupSetFormation aGroupID: Integer;
aNumColumns: Byte;
- HouseAddDamage aHouseID: Integer;
aDamage: Word; //number of hitpoints to take from the house
- HouseAddRepair aHouseID: Integer;
aRepair: Word; //number of hitpoints to give to the house
-7981 HouseAddWaresTo
❌Removed
Method was removed, use HouseWareAdd instead		 aHouseID: Integer;
aWareType: TKMWareType;
aCount: Word;
-10696 HouseAllow
❌Removed
Method was removed, use PlayerHouseBlock instead
Allow or block the house from being built		 aPlayer: Integer;
aHouseType: TKMHouseType;
aAllowed: Boolean;
- HouseDestroy aHouseID: Integer;
aSilent: Boolean; //Wherever to play the sound and leave rubble on terrain or not
5194 HouseOwnerChange
Change owner of the House. Technically it kills old House and creates a new one with the same basic props
(type, position, direction, hp, ..). All the advanced props and states do not get copied over.
Wares do not get copied over yet.		 aHouseID: Integer;
aPlayer: Integer;		 Integer //UID of new House
- HouseRepairEnable aHouseID: Integer;
aRepairEnabled: Boolean;
4820 HouseTrainQueueAdd
Train units in the house (School/Fort/Barracks)		 aHouseID: Integer;
aUnitType: TKMUnitType;
aCount: Integer;		 Integer //number of units added to the queue
4820 HouseTrainQueueRemove
Try to remove units from training queue in the house (School/Fort/Barracks)		 aHouseID: Integer;
aQueueIndex: Integer; //Should be in 0..5 range
-10696 HouseUnlock
❌Removed
Method was removed, use PlayerHouseGrant instead
Allow the house to be built irregardless of preceeding houses availability		 aPlayer: Integer;
aHouseType: TKMHouseType;
7981 HouseWareAdd
Adds wares to specified house		 aHouseID: Integer;
aWareType: TKMWareType;
aCount: Word; //number of wares to add. Gets trimmed to not exceed house max storage
7021 HouseWareInBlock
Set spacious house ware delivery policy. Works only for spacious houses (Camp, Fort, Store, Barracks)		 aHouseID: Integer;
aWareType: TKMWareType;
aBlock: Integer; //0 - allow, 1 - block, 2 - evacuate
7985 HouseWareRemove
Removes wares from specified house. Works only on complete houses		 aHouseID: Integer;
aWareType: TKMWareType;
aCount: Word; //number of wares to take		 Word //number of wares that were actually taken
10399 HouseWaresInBlock
Set common house ware delivery policy. Works only for spacious houses (Camp, Fort, Store, Barracks)		 aHouseID: Integer;
aBlock: Integer; //0 - allow, 1 - block
- HouseWeaponsOrderSet aHouseID: Integer;
aWareType: TKMWareType;
aAmount: Integer;
8900 HouseWoodcutterMode
Modes are: 1 - cut and plant, 2 - chop only, 3 - plant only		 aHouseID: Integer;
aChopMode: Byte;
8775 MissionHighscore
Sets the mission score
Score can be set only for single-player Campaign and Story missions that have Highscores enabled in MapEd.
Timed missions can have highscores too, but the score there is supplementary.
Good highscore mission are:
- Single-Player, so other players can not affect the outcome
- Story, so player can not choose weaker or stronger AI opponents
- If it is in a campaign - not affected by previous campaign missions
- Have no random or dynamic difficulty or difficulty/bonuses choice via script
Thus, only mapmaker can tell if mission should be scored or not, and it can be done by calling this action		 aScore: Integer; //number between -1 and 99999. -1 will keep highscore calculation to the default game formula
- PlanAddField aPlayer: Integer;
X: Word;
Y: Word;		 Boolean //success or fail
4433 PlanAddHouse
Places house plan on terrain, removing removable objects below it (trees and such)		 aPlayer: Integer;
aHouseType: TKMHouseType;
X,Y: Word;
aFace: TKMHouseFace;		 Boolean //success or fail
- PlanAddOrchard aPlayer: Integer;
X: Word;
Y: Word;		 Boolean //success or fail
- PlanAddRoad aPlayer: Integer;
X: Word;
Y: Word;		 Boolean //success or fail
- PlanRemove
Removes any house or fieldwork plan		 aPlayer: Integer;
X: Word;
Y: Word;		 Boolean //success or fail
5374 PlayerAIArmyCompositionReset
Reset the rate at which AI should equip new warriors to 0		 aPlayer: Integer;
5374 PlayerAIArmyCompositionSet
Change the rate at which AI should equip new warriors (units per hour)		 aPlayer: Integer;
aUnitType: TKMUnitType;
aWarriorsPerHour: Word;
5735 PlayerAIDispositionAdd
Add disposition for players AI		 aPlayer: Integer;
X: Word;
Y: Word;
aDir: Word;
aGroupType: Word;
TKMGroupType: Word;
aGuardRadius: Word;
aNumUnits: Word;
aUnitsPerRow: Word;		 Boolean //Success or fail (due to bad parameters or already existing position)
5735 PlayerAIDispositionRemove
Remove disposition		 aPlayer: Integer;
X: Word;
Y: Word;		 //Success or fail
4053 PlayerAllianceChange
Change alliance between players. Always symmetrical		 aPlayer1: Integer;
aPlayer2: Integer;
aAllied: Boolean; //Ally or enemy
aShareFOW: Boolean; //Start sharing FOW between players
5422 PlayerColorChange
Change players color. Note that animals have their own colors on the minimap		 aPlayer: Integer; //Player index (0..N-1)
aColor: Integer; //New color
- PlayerDefeat
Set player defeated		 aPlayer: Integer;
- PlayerGoalsSetDefault
Add default multiplayer goals for a player - to kill all enemies.		 aPlayer: Integer; //Player index (0..N-1)
aBuildings: Boolean; //destroy core houses too
10696 PlayerHouseBlock
Block the house from being built irregardless of preceeding houses availability
If house is both granted and blocked - it will be blocked		 aPlayer: Integer;
aHouseType: TKMHouseType;
aBlock: Boolean;
10696 PlayerHouseGrant
Allow the house to be built irregardless of preceeding houses availability
If house is both granted and blocked - it will be blocked		 aPlayer: Integer;
aHouseType: TKMHouseType;
aGrant: Boolean;
8180 PlayerMessage
Send a message to the player. Message gets stored in message log		 aPlayer: Integer; //can be -1 to send the message to all the players
aText: String; //text with libx codes to substitute
aOpen: Boolean; //should the message be opened to the player at once
-8131 PlayerMessageFormatted
❌Removed
Method was removed, Formatted messages can be made with Utils.Format()		 aPlayer: Integer;
aText: String;
Params: array of const;
-8180 PlayerMessageGoto
❌Removed
Method was removed, Goto messages should be done with Actions.PlayerMessageWithButtons		 aPlayer: Integer;
aX: Word;
aY: Word;
aText: String;
-8131 PlayerMessageGotoFormatted
❌Removed
Method was removed, Formatted messages can be made with Utils.Format()		 aPlayer: Integer;
aX: Word;
aY: Word;
aText: String;
Params: array of const;
-8180 PlayerMessageOpen
❌Removed
Method was removed, Adjoined with PlayerMessage with a boolean key		 aPlayer: Integer;
aText: String;
9746 PlayerMessageWithButtons
Send a message to the player with options (buttons) player can choose from
Message result will return asynchronously in the OnScriptButton event from each player (possibly even in different ticks).
In multiplayer games, event might be several ticks later due to lag.
When you need to show several modal messages - spread them over different ticks, to avoid piling up.
In rare cases, when player cheats, he can miss the message altogether (e.g. by viewing different Hand during message invocation).		 aPlayer: Integer;
aText: String; //Message text
aButtons: array of String; //Array of button captions. Can be up to 8
aImages: array of String; //Array of button image names (need to be .png)
aTags: array of Integer; //Array of button tags (need to be > 0. Will be passed back in click event)
aOpen: Boolean; //Opens the message and sets the game on pause after current tick is done
aBlockAfterClick: Boolean; //Block buttons after click
aModal: Boolean; //Block "close" and "prev/next" buttons, forcing player to choose one of the message options
8742 PlayerMissionResultString
Sets a message shown to the player on mission result.
Typically used in campaign and story missions.
Can be set at any moment and is shown for any mission outcome.
Available size is around 18 by 8 characters.		 aPlayer: Integer;
aText: String;
5027 PlayerNameSet
Rename a player (works only in Singleplayer and for AIs in Multiplayer)
Note: renaming a player updates texts for all affected objectives created from goals		 aPlayer: Integer;
aName: String;
3026 PlayerObjectiveAdd
Add objective for the player		 aPlayer: Integer;
aObjectiveType: TKMObjectiveType; //type of the objective (see TKMObjectiveType for details)
aPriority: Integer; //Affects objective position in the list. Smaller numbers come first. Otherwise objectives keep order in which they were added
aStatus: TKMObjectiveStatus; //status of the objective (see TKMObjectiveStatus for details)
aCaption: String; //text displayed		 Integer //UID of the objective
3026 PlayerObjectiveUpdateStatus
Update objective status		 aPlayer: Integer;
aObjectiveId: Integer;
aStatus: TKMObjectiveStatus;
- PlayerObjectiveUpdateText
Update objective text displayed in GUI. Color-coding is supported		 aPlayer: Integer;
aObjectiveId: Integer;
aText: String;
4947 PlayerOverlayAppend aPlayer: Integer;
aText: String;
-8131 PlayerOverlayAppendFormatted
❌Removed
Method was removed, Formatted messages can be made with Utils.Format()		 aPlayer: Integer;
aText: String;
Params: array of const;
4947 PlayerOverlaySet aPlayer: Integer;
aText: String;
-8131 PlayerOverlaySetFormatted
❌Removed
Method was removed, Formatted messages can be made with Utils.Format()		 aPlayer: Integer;
aText: String;
Params: array of const;
- PlayerShareFog
Start or stop sharing FOW between players. This can be done assymetrically
True means that aPlayer1 shares his FOW with aPlayer2 (in other words, P1 allows P2 to see his FOW		 aPlayer1: Integer;
aPlayer2: Integer;
aShare: Boolean;
8460 PlayerTradeAllow
Allows or forbids trading of certain ware in Marketplace		 aPlayer: Integer;
aWareType: TKMWareType;
aAllowed: Boolean;
- PlayerWareDistribution
Change ware distribution between players houses		 aPlayer: Integer;
aWareType: TKMWareType;
aHouseType: TKMHouseType;
aAmount: Byte; //Sets how many wares of the type can be a maximum in the house type. Allowed values (0..5)
- PlayerWin
Sets all player IDs in aVictors to victorious. All other players are set to defeated.		 aVictors: array of Integer;
aTeamVictory: Boolean; //If all teammates win too
- PlayWAV
Play WAV file		 aPlayer: Integer;
aFilename: String; //Name of the file from the map folder, without a path. Must have ".wav" extension.
aVolume: Single; //Playback volume. From 0.0 to 1.0
- PlayWAVAtLocation
Play WAV file at specified location on map		 aPlayer: Integer;
aFilename: String; //Name of the file from the map folder, without a path. Must have ".wav" extension.
aVolume: Single; //Playback volume. From 0.0 to 1.0
X: Word; //X tile coordinate
Y: Word; //Y tile coordinate
10523 RoadAdd
Set a road on terrain		 X,Y: Word;
aPlayer: Integer; //Owner of the road		 Boolean //Success or fail
10523 RoadRemove
Remove road from terrain		 X,Y: Word;
4586 StockpileAdd
Add stockpile on the map		 aWareType: TKMWareType; //Ware type
aX: Word;
aY: Word;
aCount: Word; //Ware count. Must be in range 1 .. 10		 Integer //UID of the stockpile in case of success
4586 StockpileSetCount
Change number of wares in a stockpile. Stockpile must be not empty		 aStockpileID: Integer; //UID of the stockpile
aCount: Word; //New ware count. If zero, stockpile will be removed
8166 TerrainHighlightDelete
Delete highlight previously placed on terrain		 aUID: Integer;
8166 TerrainHighlightFill
Add highlighted area to terrain		 aX: Single;
aY: Single;
aWidth: Single;
aHeight: Single;
aColor: Cardinal;		 Integer
8166 TerrainHighlightLine
Add outline highlight to terrain		 aX: Single;
aY: Single;
aWidth: Single;
aHeight: Single;
aThickness: Single;
aColor: Cardinal;		 Integer //Id of the highlight (to be used in delete). -1 in case of fail
6620 TerrainParticleEmitterAdd
Adds particle emitter on to terrain. Replaces any existing emitter on the spot		 aX: Word;
aY: Word;
aType: Integer;
6620 TerrainParticleEmitterDelete
Remove particle emitter from terrain		 aX: Word;
aY: Word;
5094 TerrainTriggerAdd
Adds rectangle trigger area on to terrain		 aLeft: Word;
aTop: Word;
aRight: Word;
aBottom: Word;		 Integer //Id of trigger in case of success. Otherwise -1.
5094 TerrainTriggerDelete
Remove trigger area from terrain		 aId: Integer;
9785 UnitAnimalSteer
Tells animals to walk around new anchor		 aUnitID: Integer; //ID of the unit (needs to be an animal)
aAnchorX: Word; //New anchor around which the animal will try to walk
aAnchorY: Word; //New anchor around which the animal will try to walk
aGuardRadius: Word; //New guard radius (for agressive animals). How far from the anchor animal can actively attack foes. 0..255
aWanderRadius: Word; //New wandering radius. How far from the anchor animal can wander. 0..255
7968 UnitCarryGive
Give wares to the unit (only Wagons supported yet)		 aUnitID: Integer;
aCarry: TKMWareType;
aCount: Integer;		 Integer //number of wares Given (could be 0 or smaller than requested due to max Wagon capacity and ware type mismatch)
2732 UnitCarryTake
Take wares from the unit (only Wagons supported yet)		 aUnitID: Integer;
aCarry: TKMWareType;
aCount: Integer;		 Integer //number of wares taken (0 if unsuccessfull)
- UnitDirectionSet
Make idle unit face specified direction		 aUnitID: Integer;
aDir: Integer;		 Boolean //success or fail
6692 UnitHungerSet
Set unit hunger level.		 aUnitID: Integer; //ID of the unit
aHungerSec: Integer; //Hunger level in seconds of unit life. Should be within 0 and 2700 (45min)
- UnitKill
Kills a unit
Actual death could still take up to a couple of ticks, until all internal interactions are resolved
Units in training can not die until they are trained.		 aUnitID: Integer;
aSilent: Boolean; //Makes unit die without exiting house, death animation and sound
- UnitOrderWalk
Order a unit to walk to location. Can not order to animals. Only idle units can be ordered to walk.		 aUnitID: Integer;
X: Word;
Y: Word;		 Boolean //success or fail
5128 UnitOwnerChange
Change owner of the unit. Technically it kills old unit and creates a new one with the same basic props
(type, position, direction, hp, condition, wares). All the advanced props and states do not get copied over.
Warriors need to change owner via GroupOwnerChange (even single ones)		 aUnitID: Integer;
aPlayer: Integer;		 Integer //UID of new unit
Alpha 11.2 UnitUnlock
Allow the unit to be trained (if was blocked in a static script)		 aPlayer: Integer;
aUnitType: TKMUnitType;
r10636 UnitWagonOrderEnterHouse aWagonID: Integer;
aHouseID: Integer;
r10636 UnitWagonOrderHalt aWagonID: Integer;
r10636 UnitWagonOrderWalk aWagonID: Integer;
aX: Word;
aY: Word;
aDirection: Word;