Scripting Modding

From Bohemia Interactive Community
Revision as of 17:34, 9 May 2022 by biki>Lou Montana (Some wiki formatting)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Before starting working on modified scripts, we need to prepare the basic structure for our new version of the scoring system. Therefore we will create:

In this tutorial, the scoring system will be used as an example of script modding and following things will be changed:

Permanently changing scoring coefficients for death & suicide

  • Playing a sound upon character suicide
  • Those changes are fairly simple and should be a good showcase about how to proceed when modding files.


File structure

Before writing any code, let's start with investigating which files we need to modify and then, prepare structure for our modded files.

Since we want to modify the scoring system, we can begin by searching for terms related to it. By typing scoring into the Find Symbol search field, we should see SCR_ScoringSystemComponent.c on the first place. Double clicking Double Left Mouse Button opens the file containing that class and reveals its location in the file structure. Next to it is SCR_BaseScoringSystemComponent.c and those two files should be enough to achieve the goals stated above.

Note that these two files are located in the Scripts/Game/GameMode/Scoring directory and contain most of the scoreboard-related functionality.


We will be interested in changing the behaviour of:

// SCR_BaseScoringSystemComponent.c
void AddSuicide(int playerID) // method which increases suicides & deaths count in score system
// SCR_ScoringSystemComponent.c
int CalculateScore(SCR_ScoreInfo info) // method used to calculate total score

It is usually a good habit to keep the original script and file structures; for the purpose of this tutorial, the following addon structure will be used:

SampleMod_ModdedScript/Scripts/Game/GameMode/Scoring/Modded

Once the directory is prepared, create two new script files inside the Modded folder. To do so, right-click on the Resource Browser field to open the context menu. From there, select "Script" to create a new script file. From here, it is time to create actual code!

  1. Create a new Script File: In Resources Manager, click the Create button then "Script" to create a script file
  2. Name the new Script File: the files should have the same name as the modded ones; namely SCR_BaseScoringSystemComponent.c and SCR_ScoringSystemComponent.c


Create a Modified Script

Syntax

It is possible to modify already existing scripts by using some of special keyword:

  • modded - keyword used to modify existing scripting class
  • override - keyword to override methods in modded classes
  • super - allows to invoke content of overridden method

We will use all these three words to create modded variants of SCR_ScoringSystemComponent.


Writing

Please note that:
  • this is a proof of concept used for this tutorial and there are other ways to achieve the same effect
  • this particularly method is only going to work when the scoring system is present in the mission.

First, we will begin with the modded keyword:

modded class SCR_ScoringSystemComponent // declares which class is being modded
{
}

Next, we can proceed with replacing the CalculateScore method by using the override keyword:

modded class SCR_ScoringSystemComponent : SCR_BaseScoringSystemComponent
{
	override int CalculateScore(SCR_ScoreInfo info) // declares a method replacing an existing one
	{
	}
}

As there is no intention to modify regular kill, team kills or objective score, lines containing:

  • info.m_iKills * m_iKillScoreMultiplier
    
  • info.m_iTeamKills * m_iTeamKillScoreMultiplier
    
  • info.m_iObjectives * m_iObjectiveScoreMultiplier
    

are left untouched.

int score =	info.m_iKills		* m_iKillScoreMultiplier +
			info.m_iTeamKills	* m_iTeamKillScoreMultiplier +
			info.m_iDeaths		* m_iDeathScoreMultiplier +
			info.m_iSuicides	* m_iSuicideScoreMultiplier +
			info.m_iObjectives	* m_iObjectiveScoreMultiplier;

We are replacing there modifiers which would normally provided via parameters

  • m_iDeathScoreMultiplier is replaced by 10
  • m_iSuicideScoreMultiplier is also replaced by 10
int score =	info.m_iKills		* m_iKillScoreMultiplier +
			info.m_iTeamKills	* m_iTeamKillScoreMultiplier +
			info.m_iDeaths		* 10 +
			info.m_iSuicides	* 10 +
			info.m_iObjectives	* m_iObjectiveScoreMultiplier;

This translates into what we want: for every death or suicide, ten points are obtained.

Original code - calculated score is only returned if its above 0, otherwise method returns 0.

if (score < 0)
	return 0;
return score;

Super

Same as with SCR_ScoringSystemComponent, we will use the modded keyword on SCR_BaseScoringSystemComponent to modify the content of that class. The AddSuicide method is called every time the player commits suicide and adds score according to previously defined modifiers. Since we don't want to change that part and instead want to add a new behaviour to it, we will use the super keyword to call the overridden method's code.

Once this is done, we can use the PlaySound method from the AudioSystem class - this takes one argument, ResourceName of a sound file - and plays a 2D, non spatial, sound.

modded class SCR_BaseScoringSystemComponent: SCR_BaseGameModeComponent
{
	override void AddSuicide(int playerId, int count = 1)
	{
		super.AddSuicide(playerId, count); // calls the original method
		AudioSystem.PlaySound("{E89D9A1F4BA63CDC}Sounds/Props/Furniture/Piano/Samples/Props_Piano_Jingle_1.wav"); // plays a sound
	}
}

The code is now ready to compile (⇧ Shift + F7) and the result can be tested in-game.


Mod Test

Terrain Preparation

At minimum, a new test scenario built in World Editor requires the following prefabs:

All those prefabs can be placed in World Editor's viewport by drag and dropping them from the Resource Browser.

Debug Process

While testing scripts, built-in debugging options such as Breakpoints, Console and Watch features - see Script Editor - Debugging for more information.