Difference between revisions of "Script Modding Guide"

From Holdfast: Nations At War
Jump to navigation Jump to search
Line 62: Line 62:
 
The game will call this on round start with details regarding the current round.
 
The game will call this on round start with details regarding the current round.
  
  void OnRoundDetails(int roundId, string serverName, string mapName, FactionCountry attackingFaction, FactionCountry defendingFaction, GameplayMode gameplayMode,
+
  void OnRoundDetails(int roundId, string serverName, string mapName, [[Server_Configuration_Enums#Faction|FactionCountry]] attackingFaction, [[Server_Configuration_Enums#Faction|FactionCountry]] defendingFaction, GameplayMode gameplayMode,
 
         GameType gameType);
 
         GameType gameType);
  
Line 85: Line 85:
 
The game will call this when a player spawns in game.
 
The game will call this when a player spawns in game.
  
  void OnPlayerSpawned(int playerId, int spawnSectionId, FactionCountry playerFaction, PlayerClass playerClass, int uniformId, GameObject playerObject);
+
  void OnPlayerSpawned(int playerId, int spawnSectionId, [[Server_Configuration_Enums#Faction|FactionCountry]] playerFaction, [[Server_Configuration_Enums#PlayerClass|PlayerClass]] playerClass, int uniformId, GameObject playerObject);
  
 
==== OnPlayerHurt ====
 
==== OnPlayerHurt ====
 
The game will call this when a player is hurt in game.
 
The game will call this when a player is hurt in game.
  
  void OnPlayerHurt(int playerId, byte oldHp, byte newHp, EntityHealthChangedReason reason);
+
  void OnPlayerHurt(int playerId, byte oldHp, byte newHp, [[Server_Configuration_Enums#EntityHealthChangedReason|EntityHealthChangedReason]] reason);
  
 
==== OnPlayerKilledPlayer ====
 
==== OnPlayerKilledPlayer ====
 
The game will call this when a player is killed by another player.
 
The game will call this when a player is killed by another player.
  
  void OnPlayerKilledPlayer(int killerPlayerId, int victimPlayerId, EntityHealthChangedReason reason, string details);
+
  void OnPlayerKilledPlayer(int killerPlayerId, int victimPlayerId, [[Server_Configuration_Enums#EntityHealthChangedReason|EntityHealthChangedReason]] reason, string details);
  
 
==== OnScorableAction ====
 
==== OnScorableAction ====
 
The game will call this when a player receives any score.
 
The game will call this when a player receives any score.
  
  void OnScorableAction(int playerId, int score, ScorableActionType reason);
+
  void OnScorableAction(int playerId, int score, [[Server_Configuration_Enums#ScorableActionType|ScorableActionType]] reason);
  
 
==== OnPlayerShoot ====
 
==== OnPlayerShoot ====
Line 111: Line 111:
 
Note: This requires `rc set drawFirearmTajectories true` or `rc set drawFirearmTajectoriesInfo true`.
 
Note: This requires `rc set drawFirearmTajectories true` or `rc set drawFirearmTajectoriesInfo true`.
  
  void OnShotInfo(int playerId, int shotCount, Vector3[][] shotsPointsPositions, float[] trajectileDistances, float[] distanceFromFiringPositions,
+
  void OnShotInfo(int playerId, int shotCount, Vector3[][] shotsPointsPositions, float[] trajectileDistances, float[] distanceFromFiringPositions, float[] horizontalDeviationAngles, float[] maxHorizontalDeviationAngles, float[] muzzleVelocities, float[] gravities, float[] damageHitBaseDamages, float[] damageRangeUnitValues, float[] damagePostTraitAndBuffValues, float[] totalDamages, Vector3[] hitPositions, Vector3[] hitDirections, int[] hitPlayerIds, int[] hitDamageableObjectIds, int[] hitShipIds, int[] hitVehicleIds);
        float[] horizontalDeviationAngles, float[] maxHorizontalDeviationAngles, float[] muzzleVelocities, float[] gravities,
 
        float[] damageHitBaseDamages, float[] damageRangeUnitValues, float[] damagePostTraitAndBuffValues, float[] totalDamages,
 
        Vector3[] hitPositions, Vector3[] hitDirections, int[] hitPlayerIds, int[] hitDamageableObjectIds, int[] hitShipIds, int[] hitVehicleIds);
 
  
 
==== OnPlayerBlock ====
 
==== OnPlayerBlock ====
Line 134: Line 131:
 
The game will call this when a player starts carrying an object.
 
The game will call this when a player starts carrying an object.
  
  void OnPlayerStartCarry(int playerId, CarryableObjectType carryableObject);
+
  void OnPlayerStartCarry(int playerId, [[Server_Configuration_Enums#CarryableObjectType|CarryableObjectType]] carryableObject);
  
 
==== OnPlayerEndCarry ====
 
==== OnPlayerEndCarry ====
Line 144: Line 141:
 
The game will call this when a player shouts using the ingame voice commands(not voip).
 
The game will call this when a player shouts using the ingame voice commands(not voip).
  
  void OnPlayerShout(int playerId, CharacterVoicePhrase voicePhrase);
+
  void OnPlayerShout(int playerId, [[Server_Configuration_Enums#CharacterVoicePhrase|CharacterVoicePhrase]] voicePhrase);
  
 
==== OnConsoleCommand ====
 
==== OnConsoleCommand ====
Line 167: Line 164:
 
The game will call this when a message is received in the chat system.
 
The game will call this when a message is received in the chat system.
  
  void OnTextMessage(int playerId, TextChatChannel channel, string text);
+
  void OnTextMessage(int playerId, [[Server_Configuration_Enums#TextChatChannel|TextChatChannel]] channel, string text);
  
 
==== OnAdminPlayerAction ====
 
==== OnAdminPlayerAction ====
 
The game will call this when an administrator does an admin action using the rc commands or the P menu.
 
The game will call this when an administrator does an admin action using the rc commands or the P menu.
  
  void OnAdminPlayerAction(int playerId, int adminId, ServerAdminAction action, string reason);
+
  void OnAdminPlayerAction(int playerId, int adminId, [[Server_Configuration_Enums#ServerAdminAction|ServerAdminAction]] action, string reason);
  
 
==== OnDamageableObjectDamaged ====
 
==== OnDamageableObjectDamaged ====
Line 182: Line 179:
 
The game will call this when an object is interacted with.
 
The game will call this when an object is interacted with.
  
  void OnInteractableObjectInteraction(int playerId, int interactableObjectId, GameObject interactableObject, InteractionActivationType interactionActivationType,
+
  void OnInteractableObjectInteraction(int playerId, int interactableObjectId, GameObject interactableObject, [[Server_Configuration_Enums#InteractionActivationType|InteractionActivationType]] interactionActivationType, int nextActivationStateTransitionIndex);
        int nextActivationStateTransitionIndex);
 
  
 
==== OnEmplacementPlaced ====
 
==== OnEmplacementPlaced ====
 
The game will call this when an emplacement (sapper object) is initially placed.
 
The game will call this when an emplacement (sapper object) is initially placed.
  
  void OnEmplacementPlaced(int itemId, GameObject objectBuilt, EmplacementType emplacementType);
+
  void OnEmplacementPlaced(int itemId, GameObject objectBuilt, [[Server_Configuration_Enums#EmplacementType|EmplacementType]] emplacementType);
  
 
==== OnEmplacementConstructed ====
 
==== OnEmplacementConstructed ====
Line 203: Line 199:
 
The game will call this when a capture point changes owner.
 
The game will call this when a capture point changes owner.
  
  void OnCapturePointOwnerChanged(int capturePoint, FactionCountry factionCountry);
+
  void OnCapturePointOwnerChanged(int capturePoint, [[Server_Configuration_Enums#Faction|FactionCountry]] factionCountry);
  
 
==== OnCapturePointDataUpdated ====
 
==== OnCapturePointDataUpdated ====
Line 214: Line 210:
 
Note: Buffs that already exist on a player may stack, so this call will be called multiple times even if a player already has the buff.
 
Note: Buffs that already exist on a player may stack, so this call will be called multiple times even if a player already has the buff.
  
  void OnBuffStart(int playerId, BuffType buff);
+
  void OnBuffStart(int playerId, [[Server_Configuration_Enums#BuffType|BuffType]] buff);
  
 
==== OnBuffStop ====
 
==== OnBuffStop ====
 
The game will call this when a buff is removed from a player.
 
The game will call this when a buff is removed from a player.
  
  void OnBuffStop(int playerId, BuffType buff);
+
  void OnBuffStop(int playerId, [[Server_Configuration_Enums#BuffType|BuffType]] buff);
  
 
==== OnRoundEndFactionWinner ====
 
==== OnRoundEndFactionWinner ====
Line 225: Line 221:
 
Note: Most of them except for Army Deathmatch.
 
Note: Most of them except for Army Deathmatch.
  
  void OnRoundEndFactionWinner(FactionCountry factionCountry, FactionRoundWinnerReason reason);
+
  void OnRoundEndFactionWinner([[Server_Configuration_Enums#Faction|FactionCountry]] factionCountry, [[Server_Configuration_Enums#FactionRoundWinnerReason|FactionRoundWinnerReason]] reason);
  
 
==== OnRoundEndPlayerWinner ====
 
==== OnRoundEndPlayerWinner ====
Line 236: Line 232:
 
The game will call this when a vehicle(horse) is spawned.
 
The game will call this when a vehicle(horse) is spawned.
  
  void OnVehicleSpawned(int vehicleId, FactionCountry vehicleFaction, PlayerClass vehicleClass, GameObject vehicleObject, int ownerPlayerId);
+
  void OnVehicleSpawned(int vehicleId, [[Server_Configuration_Enums#Faction|FactionCountry]] vehicleFaction, [[Server_Configuration_Enums#PlayerClass|PlayerClass]] vehicleClass, GameObject vehicleObject, int ownerPlayerId);
  
 
==== OnVehicleHurt ====
 
==== OnVehicleHurt ====
 
The game will call this when a vehicle(horse) is hurt.
 
The game will call this when a vehicle(horse) is hurt.
  
  void OnVehicleHurt(int vehicleId, byte oldHp, byte newHp, EntityHealthChangedReason reason);
+
  void OnVehicleHurt(int vehicleId, byte oldHp, byte newHp, [[Server_Configuration_Enums#EntityHealthChangedReason|EntityHealthChangedReason]] reason);
  
 
==== OnPlayerKilledVehicle ====
 
==== OnPlayerKilledVehicle ====
 
The game will call this when a vehicle(horse) is killed by a player.
 
The game will call this when a vehicle(horse) is killed by a player.
  
  void OnPlayerKilledVehicle(int killerPlayerId, int victimVehicleId, EntityHealthChangedReason reason, string details);
+
  void OnPlayerKilledVehicle(int killerPlayerId, int victimVehicleId, [[Server_Configuration_Enums#EntityHealthChangedReason|EntityHealthChangedReason]] reason, string details);
  
 
==== OnShipSpawned ====
 
==== OnShipSpawned ====
 
The game will call this when a ship is spawned.
 
The game will call this when a ship is spawned.
  
  void OnShipSpawned(int shipId, GameObject shipObject, FactionCountry shipfaction, ShipType shipType, int shipName);
+
  void OnShipSpawned(int shipId, GameObject shipObject, [[Server_Configuration_Enums#Faction|FactionCountry]] shipfaction, [[Server_Configuration_Enums#ShipType|ShipType]] shipType, int shipName);
  
 
==== OnShipDamaged ====
 
==== OnShipDamaged ====

Revision as of 16:12, 16 July 2021

SDK Modding Script Documentation

Basic knowledge of C# and Unity is required.

To start with script modding in holdfast, create a new mod and in this mod’s folder create a new script. This script should implement the shared interface IHoldfastSharedMethods.

For example, here’s a mod that’s called “LineFormer” that has the script called “LineFormer.cs” which implements the IHoldfastSharedMethods interface.

Script Modding Create Project.png

New RC commands specific for modding use

Make carbon player bots not do any auto input

If you plan on modifying bots position or rotation, call the following script to force bots to not auto move or rotate. Note: this is different than setting the carbonplayer forceInputAxis/forceInputRotation, since thoses ones will lock ALL the bots in the action, whereas this will allow you to individually control bots's facing rotation and movement system.

rc carbonPlayers ignoreAutoControls <true/false>

Send network trajectory info to client without showing it to players

Similar to drawFirearmTrajectories, this will send the trajectory data from server to client. Unlike the aforementioned command, this will NOT display it to the player, but the mod will still be recieving the data. Enable this only if you're planning on using the "OnShotInfo" on a client side, for server side mods, this isn't required.

rc set drawFirearmTajectoriesInfo <true/false>

Quiet Messages

These messages will not shown to the player anywhere. The intended use for them is for a server-side mod to be able to communicate to a client side mod.

For example;

You have a mod that every time a player presses a button on your mod custom ui, you want to slap a player for 5 damage and they will be shown the message `haha you got slapped by <playername>` on their end of the mod. You are be able to do this by creating a mod that on the player's client side [ie player 3], you have a custom ui panel with a button, which when the button is pressed will send a message to the server (multiple ways of doing this, for example using rc system). This message is than read by the server side mod (could be the same mod, just need conditional logic using the "OnIsServer" and "OnIsClient" to split the mod up) and slaps the targetted player [ie player 5]. Than the server would send a quietPrivateMessage to the slapped target [player 5] informing him that he just got slapped by player 3. The client side of player 5 will than read the quiet private message (using OnTextMessage) and handle it appriopiately.

rc serverAdmin quietPrivateMessage <player_id> <message>
rc serverAdmin quietBroadcastMessage <message>

IHoldfastSharedMethods

All this can be viewed in script by checking the summery. In visual studio you can do this by pressing F12 or hovering on the method.

OnSyncValueState

The game will share an int when the mod loads. A random synchronized value (same on client and server), for example useful if you need a seed for a map generator.

void OnSyncValueState(int value);

OnUpdateSyncedTime

The game will share the current synchronized time (same on client and server) on every frame of the game.

void OnUpdateSyncedTime(double time);

OnUpdateElapsedTime

The game will return the seconds since the round started on every frame of the game.

void OnUpdateElapsedTime(float time);

OnUpdateTimeRemaining

The game will share the current remaining time on every frame of the game.

void OnUpdateTimeRemaining(float time);

OnIsServer

The game will return if the mod is loaded on a server.

void OnIsServer(bool server);

OnIsClient

The game will return if the mod is loaded on a client, if it is, you'll retrieve the current player's steam id.

void OnIsClient(bool client, ulong steamId);

OnRoundDetails

The game will call this on round start with details regarding the current round.

void OnRoundDetails(int roundId, string serverName, string mapName, FactionCountry attackingFaction, FactionCountry defendingFaction, GameplayMode gameplayMode,
        GameType gameType);

PassConfigVariables

The game will call this once with all the config variables set on the config file of the server. Note: you will receive all variables, so make sure to filter only the ones you care about.

void PassConfigVariables(string[] value);

OnPlayerJoined

The game will call this when a player or a bot joins the round.

void OnPlayerJoined(int playerId, ulong steamId, string name, string regimentTag, bool isBot);

OnPlayerLeft

The game will call this when a player leaves the round. Note: Bots cannot leave, they'll keep respawning once dead.

void OnPlayerLeft(int playerId);

OnPlayerSpawned

The game will call this when a player spawns in game.

void OnPlayerSpawned(int playerId, int spawnSectionId, FactionCountry playerFaction, PlayerClass playerClass, int uniformId, GameObject playerObject);

OnPlayerHurt

The game will call this when a player is hurt in game.

void OnPlayerHurt(int playerId, byte oldHp, byte newHp, EntityHealthChangedReason reason);

OnPlayerKilledPlayer

The game will call this when a player is killed by another player.

void OnPlayerKilledPlayer(int killerPlayerId, int victimPlayerId, EntityHealthChangedReason reason, string details);

OnScorableAction

The game will call this when a player receives any score.

void OnScorableAction(int playerId, int score, ScorableActionType reason);

OnPlayerShoot

The game will call this when a player shoots his gun.

void OnPlayerShoot(int playerId, bool dryShot);

OnShotInfo

The game will call this when a bullet. Note: This requires `rc set drawFirearmTajectories true` or `rc set drawFirearmTajectoriesInfo true`.

void OnShotInfo(int playerId, int shotCount, Vector3[][] shotsPointsPositions, float[] trajectileDistances, float[] distanceFromFiringPositions, float[] horizontalDeviationAngles, float[] maxHorizontalDeviationAngles, float[] muzzleVelocities, float[] gravities, float[] damageHitBaseDamages, float[] damageRangeUnitValues, float[] damagePostTraitAndBuffValues, float[] totalDamages, Vector3[] hitPositions, Vector3[] hitDirections, int[] hitPlayerIds, int[] hitDamageableObjectIds, int[] hitShipIds, int[] hitVehicleIds);

OnPlayerBlock

The game will call this when a player successfully blocks another player.

void OnPlayerBlock(int attackingPlayerId, int defendingPlayerId);

OnPlayerMeleeStartSecondaryAttack

The game will call this when a player starts a secondary attack (shove).

void OnPlayerMeleeStartSecondaryAttack(int playerId);

OnPlayerWeaponSwitch

The game will call this when a player swaps their weapon.

void OnPlayerWeaponSwitch(int playerId, string weapon);

OnPlayerStartCarry

The game will call this when a player starts carrying an object.

void OnPlayerStartCarry(int playerId, CarryableObjectType carryableObject);

OnPlayerEndCarry

The game will call this when a player stops carrying an object.

void OnPlayerEndCarry(int playerId);

OnPlayerShout

The game will call this when a player shouts using the ingame voice commands(not voip).

void OnPlayerShout(int playerId, CharacterVoicePhrase voicePhrase);

OnConsoleCommand

The game will call this when the console command is used. Note: This will be only called on the client, or on the server that is executing the console command.

void OnConsoleCommand(string input, string output, bool success);

OnRCLogin

The game will call this when a player requests a remote console login. Note: This will be called on the client that is executing the request, and the server. Not other people.

void OnRCLogin(int playerId, string inputPassword, bool isLoggedIn);

OnRCCommand

The game will call this when a player requests a remote console command. Note: This will be called on the client that is doing the request, and the server. Not other people.

void OnRCCommand(int playerId, string input, string output, bool success);

OnTextMessage

The game will call this when a message is received in the chat system.

void OnTextMessage(int playerId, TextChatChannel channel, string text);

OnAdminPlayerAction

The game will call this when an administrator does an admin action using the rc commands or the P menu.

void OnAdminPlayerAction(int playerId, int adminId, ServerAdminAction action, string reason);

OnDamageableObjectDamaged

The game will call this when an object is damaged.

void OnDamageableObjectDamaged(GameObject damageableObject, int damageableObjectId, int shipId, int oldHp, int newHp);

OnInteractableObjectInteraction

The game will call this when an object is interacted with.

void OnInteractableObjectInteraction(int playerId, int interactableObjectId, GameObject interactableObject, InteractionActivationType interactionActivationType, int nextActivationStateTransitionIndex);

OnEmplacementPlaced

The game will call this when an emplacement (sapper object) is initially placed.

void OnEmplacementPlaced(int itemId, GameObject objectBuilt, EmplacementType emplacementType);

OnEmplacementConstructed

The game will call this when an emplacement (sapper object) is fully constructed.

void OnEmplacementConstructed(int itemId);

OnCapturePointCaptured

The game will call this when a capture point is fully captured.

void OnCapturePointCaptured(int capturePoint);

OnCapturePointOwnerChanged

The game will call this when a capture point changes owner.

void OnCapturePointOwnerChanged(int capturePoint, FactionCountry factionCountry);

OnCapturePointDataUpdated

The game will call this when a capture data changes.

void OnCapturePointDataUpdated(int capturePoint, int defendingPlayerCount, int attackingPlayerCount);

OnBuffStart

The game will call this when a buff is applied to a player. Note: Buffs that already exist on a player may stack, so this call will be called multiple times even if a player already has the buff.

void OnBuffStart(int playerId, BuffType buff);

OnBuffStop

The game will call this when a buff is removed from a player.

void OnBuffStop(int playerId, BuffType buff);

OnRoundEndFactionWinner

The game will call this when a faction vs faction round is over. Note: Most of them except for Army Deathmatch.

void OnRoundEndFactionWinner(FactionCountry factionCountry, FactionRoundWinnerReason reason);

OnRoundEndPlayerWinner

The game will call this when a free for all round is over. Note: Only Army Deathmatch.

void OnRoundEndPlayerWinner(int playerId);

OnVehicleSpawned

The game will call this when a vehicle(horse) is spawned.

void OnVehicleSpawned(int vehicleId, FactionCountry vehicleFaction, PlayerClass vehicleClass, GameObject vehicleObject, int ownerPlayerId);

OnVehicleHurt

The game will call this when a vehicle(horse) is hurt.

void OnVehicleHurt(int vehicleId, byte oldHp, byte newHp, EntityHealthChangedReason reason);

OnPlayerKilledVehicle

The game will call this when a vehicle(horse) is killed by a player.

void OnPlayerKilledVehicle(int killerPlayerId, int victimVehicleId, EntityHealthChangedReason reason, string details);

OnShipSpawned

The game will call this when a ship is spawned.

void OnShipSpawned(int shipId, GameObject shipObject, FactionCountry shipfaction, ShipType shipType, int shipName);

OnShipDamaged

The game will call this when a ship takes damage.

void OnShipDamaged(int shipId, int oldHp, int newHp);

Examples

AGS's Misc Examples

https://github.com/CM2Walki/HoldfastMods

Elf's AutoAdmin

https://github.com/LoganBlinco/HF_AutoAdmin

Feel free to post in the Official Holdfast Discord #Mod-Support for any help