SetPlayerClass: Difference between revisions

Latest revision as of 16:51, 12 March 2023

This article documents a Zandronum-specific ACS feature which may not be supported by ZDoom and its other child ports.

bool SetPlayerClass (int player, str class, bool respawn)

Usage

Changes the class a player is currently using. Note that in order for this to work, the player must exist and not a true spectator, and the class must be a valid player class that isn't forbidden to the player (eg. the class is restricted to a team the player isn't on).

Parameters

player: The number of the player whose class with be changed.
class: The name of the actor to change the player to. This must be a valid actor that inherits from PlayerPawn, or the string "random" to assign a random class.
respawn: If true, the player will immediately respawn with the new class, otherwise their class won't change until they respawn normally.

Return value

Returns true if the player's class was successfully changed, false on failure (eg. the player or class don't exist, or if choosing random classes is forbidden).

Examples

This script is used in the context of a custom menu and respawns the player as the custom player class "Scout" when the option is selected. Integer 'pNum' is used to track the activator's player number before executing.

Script 1 (void) NET
{
    int pNum = PlayerNumber();
    SetPlayerClass(pNum, "Scout", true);
}

@@ Line 1: / Line 1: @@
 {{Template:ACSWarning}}
-int '''SetPlayerClass'''(int player, str class, bool respawn) '''(<font color="darkblue">3.1-alpha</font> <font color="red">only</font>)'''
+bool '''SetPlayerClass''' (int ''player'', str ''class'', bool ''respawn'')
-==Usage==
+== Usage ==
 Changes the class a player is currently using. Note that in order for this to work, the player must exist and not a true spectator, and the class must be a valid player class that isn't forbidden to the player (eg. the class is restricted to a team the player isn't on).
-==Parameters==
+=== Parameters ===
-*player: The number of the player to change their class.
+* ''player'': The number of the player whose class with be changed.
-*class: The name of the actor to change the player to. This must be a valid actor that inherits from APlayerPawn.
+* ''class'': The name of the actor to change the player to. This must be a valid actor that inherits from {{Zdoomwiki|Classes:PlayerPawn|PlayerPawn}}, or the string "random" to assign a random class.
-*respawn: If true, the player will immediately respawn with the new class, otherwise their class won't change until they respawn normally.
+* ''respawn'': If true, the player will immediately respawn with the new class, otherwise their class won't change until they respawn normally.
-==Return Value==
+=== Return value ===
-Returns 1 if the player's class was successfully changed, 0 on failure (eg. the player or class don't exist).
+Returns true if the player's class was successfully changed, false on failure (eg. the player or class don't exist, or if choosing random classes is forbidden).
-[[category:ACS Functions]]
+== Examples ==
+This script is used in the context of a custom menu and respawns the player as the custom player class "Scout" when the option is selected. Integer 'pNum' is used to track the activator's player number before executing.<syntaxhighlight lang="c" line="1">
+Script 1 (void) NET
+{
+    int pNum = PlayerNumber();
+    SetPlayerClass(pNum, "Scout", true);
+}
+</syntaxhighlight>
+[[Category:ACS functions]]