Scenario Creation Pt. 02
[CONTINUATION FROM PT. 01]
BASIC LEVEL SCAR CODING
— SCAR script and World Builder integration
In order for a scenario to be fully functional, there must be something that the code can use to execute its commands in the right place and the right time, somewhere in the map (i.e. the "playing field"). Something that links
SCAR scripts with parts of the map the scenario is using. The means for accomplishing this is referred to as "SCAR markers" (not to be confused with the "Action Markers" that are used for visual FX elements, e.g. a fire or smoke rising from debris - more details in the Level Design
section). They are WB objects/elements that can be placed anywhere on the map, and they are not
rendered in the scenario (i.e. they are invisible) when they are loaded into the game, and by themselves as map elements do not
affect gameplay at all. They only represent positions
on the map (i.e. they represent XYZ coordinates for a specific, unique location) which essentially tells the code where the actions it is programmed to execute should take place.
I would recommend creating your own set of generic SCAR marker names, preferrably short, and very descriptive. Examples would contain s_forestnorth1
, where "s" stands for "s
pawn", and the part on the right of the underscore would represent the map-specific location, along with additional information, which should be helpful for you in your scripting, without having to switch back and forth from the text editor to the WB. The number "1" is used just in case there are other markers with the same name. To place a SCAR marker in your map, simply use the
Render Marker Prox. tool, and select SCAR markers in the right pane. The ones we will be using for now will be the three Ally
and three Enemy
markers. For now, you may select the Ally Spawn
marker, and right click anywhere in your scenario to place one. Then double click its name to change it to s_pathfield1
. Explanation image:
— Function structure and basic functions
It is time to start with our very first SCAR function (advanced coders: notice the LUA-similar syntax):
player1 = World_GetPlayerAt(1)
player2 = World_GetPlayerAt(2)
This is what we call a "function". Functions in SCAR always start with function
, followed by a space, and the name of the function - in this case OnGameSetup()
(PLEASE NOTE the two parentheses "()" are essential
and must always be there) - and must end with end
. The function
part tells the game that we want to create a new function. The OnGameSetup()
is the name of the function, which is unique
for every function, and is associated with what each function does. The end
part tells the game that the function is complete, and that only the code between the beginning and the end of the function is to be executed.
Specifically for this example:
(case sensitive!) is a very basic and special function; it is ran automatically upon loading the map/scenario, and it must
be present in all
SCAR scripts for their proper functioning. This is where we place all the commands that configure basic settings for the players of the map/scenario, such as: 1. The name of each player (human or AI) 2. The choice of army (e.g. Soviet, German - or even custom armies for mods) It also provides the capability for coders to run desired commands at the start of the map (we will get to that later on).
Now then, the player1 = World_GetPlayerAt(1)
for player 1 (and player2 = World_GetPlayerAt(2)
for player 2, and so on for any other player) are essential
for EVERY map. Simply put, they tell the game that player 1 and 2, for example, exist
, and we wish to include them in the map.
They tell the game the location of those players in the map, as defined in the WB.
The actual function that's important is World_GetPlayerAt(
, where N is an integer, starting from 1. We place it in a variable
(player = ...
), i.e. a custom name for it, so we can refer
to it more easily, without having to type it all over again.
Now, the World_GetPlayerAt()
function does not
change any settings for the target player. If we wish to change any
settings for a player, we do the following:
player1 = World_GetPlayerAt(1)
player2 = World_GetPlayerAt(2)
player2name = Player_GetDisplayName(1)
Setup_Player(player2, player2name, "german", 2) --We can also use 2 instead of player2, to directly define the map location.
In this example we keep all the settings for player one, stating only his position in our scenario. Now for the second player, we use the Setup_Player()
function. The first argument we use defines which player
we want to change the settings for. The second defines the player name (in this case we use a function, stored in a variable, that retrieves the current name of the player, so that they have their in-game username). The third defines the player race, and is either "soviet"
for Soviets, or "german"
for Germans, including quotes(!)
. The last defines the player's team. (in this case player one is on team one by default
in W.B., and we set player two to team two). You will see more complex examples as we move on to create some basic missions, however, if you wish, you can view OnGameSetup() examples here
them, and open them with MS Notepad or Notepad++).
Do not worry, however; all this trouble just for the basic function that will always be pretty much be the same. It is only this function (as well as one more) that are all the trouble for SCAR scripting. The rest are much more enjoyable, and it is where you will truly experience the true capabilites of SCAR.
— Final explanations
We managed to create our very first function. Now, if we were to place it in a SCAR file for our maps to use, we would notice an error upon execution. That is because, our overall
SCAR script is not functional yet.
We are missing one very
important command. At the very start of EVERY
SCAR file, we have to place the import("ScarUtil.scar")
command. This command is extremely important, as it tells the game to import the complete code library from Relic, which contains all commands and game functions, and instructions on how they should run. Note that it is possible to set it up at the beginning of every SCAR file we make (or even import one of our own), but it is preferred to use the one provided by Relic, mainly because it is global
, meaning it will work for every unmodified
copy of the game.
If your SCAR file is missing this single command, it will simply not work.[CONTINUE TO PT. 03]