By: Krit
December 2008
Thanks to Fleetatks for discovering some of the information in this tutorial.
Contents
1. Tutorial Introduction
2. Identifying the Players
3. Scripting - Object Transfer upon Action
4. Scripting - Object Transfer upon Game Start
5. Scripting - Spawn Object for Player
1. Tutorial Introduction
While Fleetatks has already explained how to do this in his 'ZH: Map Scripting FAQ Table', I felt like the section needs expanding including giving it more descriptions, details and examples. Back in April, Fleetatks made a little discovery on how different players are defined in WorldBuilder, making unit and structure transfers for multiple players possible in both multiplayer and skirmish. Despite being much easier to script using Fleetatks' discovery, not many people noticed and are still using other, often flawed methods of transferring objects between players. This tutorial is aimed to further detail Fleetatks's discovery so people can put it to use on their own maps.
2. Identifying the Players
The basics are simple. All you need to know, if you already have scripting experiences, is that each player in the "Create Game Room" is given identification in WorldBuilder. For player one, the first player in the room - also the host -, the identification is "player0" This continues down the room with "player1" representing the second player in the room, "player2" representing the third player and so on. The general formula is "Player (X) in Create Game Room = player(X-1) in WorldBuilder" If you are unsure on the player numbers, it's the same numbers used to show the start locations on the map preview. The identifications are not available on the drop down menu in WorldBuilder and will have to be typed in manually by the user. Once typed in, WorldBuilder will show a question mark on the script icon and exclaim that the "player#" (Where # is the player number minus 1) does not exist. Ignore this exclamation and continue as the game will still register the script as valid. Scripting with these identifications is a long and tedious task as each script would need to be recreated as many as 7 times for each player. It is not advised to implement scripts only for the number of scripted players on the map because there can be cases where players in the Create Game Room are not in the order in which they joined; for example, player4 could be at spot number 2. Please note from this point onwards all the following scripts, unless specifically pointed out, are placed in the PlyrCivilian folder.
3. Scripting - Object Transfer upon Action
Objects placed in WorldBuilder on the map, such as units or structures, can be scripted to be transferred to certain players on completion of certain actions. For example, a set of tanks can be turned over to a player if the player has captured War Factory in the middle of the map. To do so, the objects that are going to be transferred (for example, the War Factory), along with the objects that are associated with the condition (for example, the tanks), must be each given a name. This is done by typing in the name in the Object Properties window.
Worked Example:
Script: AirfieldTransferPlyr0
*** IF ***
Unit 'Airfield01' is owned by Player 'player0'
*** THEN ***
Unit 'Comanche01' is transferred to the command of Player 'player0'
Unit 'Comanche02' is transferred to the command of Player 'player0'
Unit 'Comanche03' is transferred to the command of Player 'player0'
Unit 'Comanche04' is transferred to the command of Player 'player0'
Disable Script 'AirfieldTransferPlyr1'.
Disable Script 'AirfieldTransferPlyr2'.
Disable Script 'AirfieldTransferPlyr3'.
Disable Script 'AirfieldTransferPlyr4'.
Disable Script 'AirfieldTransferPlyr5'.
Disable Script 'AirfieldTransferPlyr6'.
Disable Script 'AirfieldTransferPlyr7'.
In words the above script tells WorldBuilder: if Player 1 captures the airfield on the map called "Airfield01", the Comanche helicopters "Comanche01", "Comanche02", "Comanche03" and "Comanche04" are immediately transferred to Player 1's ownership. At the same time, scripts "AirfieldTransferPlyr1-7", representing the same scripts for Player 2 to 7, is disabled so if any other player captures the airfield later, ownership of the Comanches will not be transferred with them.
Not all scripts which transfer units upon completion of an action have to follow this format. If the player wishes to transfer the ownership of the units upon the structure being captured by another player, the additional conditions for disabling the previously enabled scripts can be changed to enabling the new scripts (This allows for the same player to capture the structure twice and regain ownership of the units as scripts are disabled once used).
The condition can also be changed to the map maker's wishes (so the creator doesn’t need buildings to transfer units or other structures) Using the Airfield example above, if you want the Comanche to be transferred once the player enters a specific area called "AreaAirbase", simply change the Script Conditions to:
*** IF ***
Player 'player0' has units in area 'AreaAirbase'.
Areas on the map are defined using the Polygon Tool
Another example involves garrisoning a civilian building named "ControlTower":
*** IF ***
Player 'player0' has entered building named Unit 'ControlTower'
The condition script for object ownership is located at:
Player > Owns > Player owns a specific Unit.
Condition script for unit in area is at:
Player > Area > Player has units in an area.
And the condition script for entering buildings:
Player > Player has entered a specific building.
The action script for unit transfer is at:
Player > Transfer > Transfer a specific unit to the control of a player.
Script disabling is:
Scripting > Script > Disable script.
Enabling a script is:
Scripting > Script > Enable script.
4. Scripting - Object Transfer upon Game Start
While scripting for pre-placed objects to be transferred at game start is mainly the same as transferring objects upon action, there are a few important points which will be explained in this section.
Worked Example:
Script: ComancheTransPlyr0Start1
*** IF ***
Player 'player0' starting position is 1 .
*** THEN ***
Unit 'Start1Comanche01' is transferred to the command of Player 'player0'
Unit 'Start1Comanche02' is transferred to the command of Player 'player0'
With this script, when Player 1 starts at Starting Position 1, the Comanches “Start1Comanche01” and “Start1Comanche02” is transferred to the player.
As you may have noticed, this script would only work with Player 1 and only if Player 1 is on Starting Position 1. To making the map operational with all players, this script will have to be recreated another 7 times with different players in place of “player0” and more sets of such scripts created for each starting position placed on the map. In this case, the fewer starting positions on the map, the fewer scripts are required. As stated in section 2; Identifying the Players, a shortcut of only scripting players in accordance to how many players are actually on the map at once can be used, but this is not advised for a fully functioning map.
The script for allocating players with starting positions is:
Skirmish > Start Position.
5. Scripting - Spawn Object for Player
Spawning object requires two actions to be made in one script. This is because - currently - there are no known methods to directly spawn objects for a player that works for all players regardless player types (human and AI). Like the transfer scripts, different conditions can be set to trigger the spawn.
Worked Example:
Script: ChinaSpwnPlyr0Start1
*** IF ***
Player 'player0' starting position is 1 .
*AND* Player 'player0' is Faction Name: China
*** THEN ***
Spawn Unit 'Overlord01' of type 'ChinaTankOverlord' on Team 'teamPlyrCivilian' at waypoint Waypoint 'Spawn01'
Unit 'Overlord01' is transferred to the command of Player 'player0'
In this script, if the first player starts in Starting Position 1 and is using China, an Overlord tank will be transferred to the player at the waypoint "Spawn01". The Overlord tank is actually spawned as a civilian unit and then transferred to the command of Player 1. Some minor tests have already been made to spawn units directly to the control of players with limited success; while spawning for the first player succeeded, spawning for skirmish players in other slots failed with serious errors.
Waypoints are not always needed for spawning objects as another spawning script allows for the placement of objects on map coordinates and may sometimes be preferred over the script using the waypoint as it allows specifying the angle in which the unit is facing when spawned. This script is located at:
Unit > Spawn > Spawn -- named unit on a team at a position with an orientation.
The position is the coordinates on the map. Specific coordinates can be found on the map by placing the cursor over where you want the coordinates and looking at the lower left status bar. The coordinate of the current position of the cursor comes after the object and waypoint count. For orientation, just place a unit down, rotate it to where you need and copy down the angle from the Object Properties window. If you learn math, then everything is rather obvious.
The conditions to trigger the scripts can be changed at will. In this example, the script would only work if Player 1 starts at Starting Position 1 and is playing China. By also including faction conditions, players can spawn specific units if players are playing as specific factions. Units can also be scripted to spawn after a time delay later in game by using two scripts.
Worked Example:
Script: SpawnTimer
*** IF ***
True.
*** THEN ***
Set timer 'UnitSpawn' to expire in 60.00 seconds.
Script: OverlordSpawnPosition1
*** IF ***
Timer 'UnitSpawn' has expired.
*AND* Player 'player0' starting position is 1 .
*** THEN ***
Spawn Unit 'Overlord01' of type 'ChinaTankOverlord' on Team 'teamPlyrCivilian' at waypoint Waypoint 'Spawn01'
Unit 'Overlord01' is transferred to the command of Player 'player0'
In this example, the first script starts a 60 second timer. The second script is only enabled if the timer in the first script has expired. By doing so, the spawn script is given a delay and thus will not spawn the designated object until the timer in the timer script has expired. Multiple spawn scripts can use the same timer and thus only one timer is required if all the spawning times are the same.
Also note that like the Object Transfer upon Game Start scripts, all combinations between player slots and Starting Positions requires a copy of the script for the map to function correctly for all players.
The faction defining condition is located under:
Skirmish > Player > Player is faction.
The waypoint spawning script is at:
Unit > Spawn > Spawn -- named unit on a team at a waypoint
Timer start is located at:
Scripting > Timer > Seconds countdown timer -- set.
Timer expires is at:
Scripting > Timer expired.
It is also good to note that the timers can also be used with the transfer scripts so that objects can be transferred between players after a set amount of time.
Navigation
