Scripting Introduction: Difference between revisions

From Soldat2 Wiki
Jump to navigation Jump to search
mNo edit summary
m (move to Category:Modding)
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Scripting in Soldat 2 is done in a Unity/C# environment. For a script to be usable in-game, the script file must be placed under <code>Soldat2/Scripts/</code> and there needs to be a ruleset that specifies that script in the <i>GameScript</i> object in its json - for example, see <code>Soldat2/Rules/Standard/Climb.json</code>. The script can be tested by starting a game that uses that ruleset.
Scripting in Soldat 2 is done in a Unity/C# environment. For a script to be usable in-game, the script file must be placed under <code>Soldat2/Scripts/</code> and there needs to be a ruleset that specifies that script in the <i>GameScript</i> object in its json - for example, see <code>Soldat2/Rules/Standard/Climb.json</code>. The script can be tested by starting a game that uses that ruleset.


[[Category:Scripting]]
[[Category:Modding]]




Line 9: Line 9:
There is some [https://soldat2.com/docs/ preliminary documentation] for the Soldat 2 engine, however it is currently rather limited.
There is some [https://soldat2.com/docs/ preliminary documentation] for the Soldat 2 engine, however it is currently rather limited.


Some examples of scripts can be found in your Soldat 2 game directory under the path <code>Soldat2/Scripts/Standard/</code>.
Some examples of scripts can be found in your Soldat 2 game directory under the path <code>Soldat2/Scripts/Standard/</code>. Some unofficial examples are available at [[Scripting Examples]].


More documentation is added to this wiki under [[:Category:Scripting]].
See [[:Category:Scripting]] for a list of all pages on this wiki related to scripting.


== Using Scripts ==
== Using Scripts ==
Line 20: Line 20:
Example of a modifier <code>Modifiers/Custom/FlagIsPoison.json</code> applying the <code>Scripts/Custom/FlagIsPoison.cs</code> script:
Example of a modifier <code>Modifiers/Custom/FlagIsPoison.json</code> applying the <code>Scripts/Custom/FlagIsPoison.cs</code> script:


<pre>
<syntaxhighlight lang="JSON">
{
{
   "Objects": {
   "Objects": {
Line 35: Line 35:
   }
   }
}
}
</pre>
</syntaxhighlight>


A script can be parametrized, where the parameters are defined in the modifier or rule definition. In the above example the <code>FlagDamagePerSecond</code> parameter is applied when the script class contains a <code>JsonProperty</code> with a default value:
A script can be parametrized, where the parameters are defined in the modifier or rule definition. In the above example the <code>FlagDamagePerSecond</code> parameter is applied when the script class contains a <code>JsonProperty</code> with a default value:


<pre>
<syntaxhighlight lang="C#">
[JsonProperty("FlagDamagePerSecond")] public float flagDPS = 5.0;
[JsonProperty("FlagDamagePerSecond")] public float flagDPS = 5.0;
</pre>
</syntaxhighlight>




=== In a rule / game mode ===
=== In a rule / game mode ===


Add the script name to the <code>GameRules</code> section of the rule definition in <code>Rules/Custom/YourGameMode.json</code>:
To add a script to all matches of a gamemode, edit <code>Rules/Custom/YourGameMode.json</code>.


<pre>
Add a script by adding its class name as a key to the game mode definition (on the same level as <code>GameScript</code>). Inside that object, you can define parameters the script potentially exposes via <code>JSONProperty</code> tags:
 
<syntaxhighlight lang="JSON">
{
{
   "Objects": {
   ...
    "YourGameMode": {
      "GameScript": { ... },
      "YourScriptName": {
        "ExampleParameter": true,
      }
  ...
}
</syntaxhighlight>
 
 


An alternative way, is to add the class name of your script to the <code>GameScript.Scripts</code> array:
<syntaxhighlight lang="JSON">
{
  ...
       "GameScript": {
       "GameScript": {
         "Scripts": [
         "Scripts": [
Line 59: Line 73:
         ]
         ]
       }
       }
 
   ...
    }
   }
}
}
</pre>
</syntaxhighlight>
 
* TODO: check if parameters can be passed in this syntax too (eg <code>"Scripts": [{ "YourScriptName": { MyParam: false } }]</code>

Latest revision as of 11:47, 10 June 2023

Scripting in Soldat 2 is done in a Unity/C# environment. For a script to be usable in-game, the script file must be placed under Soldat2/Scripts/ and there needs to be a ruleset that specifies that script in the GameScript object in its json - for example, see Soldat2/Rules/Standard/Climb.json. The script can be tested by starting a game that uses that ruleset.


Scripting Resources

The Soldat 2 engine uses Unity, so it may be useful to familiarise yourself with the Unity Manual.

There is some preliminary documentation for the Soldat 2 engine, however it is currently rather limited.

Some examples of scripts can be found in your Soldat 2 game directory under the path Soldat2/Scripts/Standard/. Some unofficial examples are available at Scripting Examples.

See Category:Scripting for a list of all pages on this wiki related to scripting.

Using Scripts

A script can be applied to a match via Modifiers or via a Game Mode ("Rules").

In a modifier

Example of a modifier Modifiers/Custom/FlagIsPoison.json applying the Scripts/Custom/FlagIsPoison.cs script:

{
  "Objects": {
    "Rules": {
      "FlagIsPoison": {
        "FlagDamagePerSecond": 3.0
      }
    }   
  },
  "Meta": {
    "Description": "(applies the FlagIsPoison script)",
    "Author": "noerw",
    "Version": 1.0
  }
}

A script can be parametrized, where the parameters are defined in the modifier or rule definition. In the above example the FlagDamagePerSecond parameter is applied when the script class contains a JsonProperty with a default value:

[JsonProperty("FlagDamagePerSecond")] public float flagDPS = 5.0;


In a rule / game mode

To add a script to all matches of a gamemode, edit Rules/Custom/YourGameMode.json.

Add a script by adding its class name as a key to the game mode definition (on the same level as GameScript). Inside that object, you can define parameters the script potentially exposes via JSONProperty tags:

{
  ...
      "GameScript": { ... },
      "YourScriptName": {
        "ExampleParameter": true,
      }
  ...
}


An alternative way, is to add the class name of your script to the GameScript.Scripts array:

{
  ...
      "GameScript": {
        "Scripts": [
          ... potentially other scripts ...,
          "YourScriptName"
        ]
      }
  ...
}