Introduce ActivateParatroopers Lua API.

SendParatroopers and SendParatroopersFrom are now deprecated.
The paratrooper actors themselves can be accessed using the
Trigger.OnPassengerExited trigger.

OpenRA.Mods.Common/Scripting/Properties/ParatroopersProperties.cs

@@ -27,19 +27,30 @@ namespace OpenRA.Mods.Common.Scripting
 			pp = self.TraitsImplementing<ParatroopersPower>().First();
 		}
 
-		[Desc("Activate the actor's Paratroopers Power. Returns the dropped units.")]
+		[Desc("Activate the actor's Paratroopers Power. Returns the aircraft that will drop the reinforcements.")]
-		public Actor[] SendParatroopers(WPos target, bool randomize = true, int facing = 0)
+		public Actor[] ActivateParatroopers(WPos target, int facing = -1)
 		{
-			return pp.SendParatroopers(Self, target, randomize, facing);
+			var actors = pp.SendParatroopers(Self, target, facing);
+			return actors.First;
 		}
 
-		[Desc("Activate the actor's Paratroopers Power. Returns the dropped units.")]
+		[Desc("Activate the actor's Paratroopers Power. Returns the dropped units. DEPRECATED! Will be removed.")]
+		public Actor[] SendParatroopers(WPos target, bool randomize = true, int facing = 0)
+		{
+			Game.Debug("SendParatroopers is deprecated. Use ActivateParatroopers instead.");
+			var actors = pp.SendParatroopers(Self, target, randomize ? -1 : facing);
+			return actors.Second;
+		}
+
+		[Desc("Activate the actor's Paratroopers Power. Returns the dropped units. DEPRECATED! Will be removed.")]
 		public Actor[] SendParatroopersFrom(CPos from, CPos to)
 		{
+			Game.Debug("SendParatroopersFrom is deprecated. Use ActivateParatroopers instead.");
 			var i = Self.World.Map.CenterOfCell(from);
 			var j = Self.World.Map.CenterOfCell(to);
 
-			return pp.SendParatroopers(Self, j, false, (i - j).Yaw.Facing);
+			var actors = pp.SendParatroopers(Self, j, (i - j).Yaw.Facing);
+			return actors.Second;
 		}
 	}
 }

OpenRA.Mods.Common/Traits/SupportPowers/ParatroopersPower.cs

@@ -93,17 +93,19 @@ namespace OpenRA.Mods.Common.Traits
 		{
 			base.Activate(self, order, manager);
 
-			SendParatroopers(self, order.Target.CenterPosition, !info.UseDirectionalTarget || order.ExtraData == uint.MaxValue, (int)order.ExtraData);
+			var facing = info.UseDirectionalTarget && order.ExtraData != uint.MaxValue ? (int)order.ExtraData : -1;
+			SendParatroopers(self, order.Target.CenterPosition, facing);
 		}
 
-		public Actor[] SendParatroopers(Actor self, WPos target, bool randomize = true, int dropFacing = 0)
+		public Pair<Actor[], Actor[]> SendParatroopers(Actor self, WPos target, int facing = -1)
 		{
+			var aircraft = new List<Actor>();
 			var units = new List<Actor>();
 
 			var info = Info as ParatroopersPowerInfo;
 
-			if (randomize)
+			if (facing < 0)
-				dropFacing = 256 * self.World.SharedRandom.Next(info.QuantizedFacings) / info.QuantizedFacings;
+				facing = 256 * self.World.SharedRandom.Next(info.QuantizedFacings) / info.QuantizedFacings;
 
 			var utLower = info.UnitType.ToLowerInvariant();
 			ActorInfo unitType;
@@ -111,7 +113,7 @@ namespace OpenRA.Mods.Common.Traits
 				throw new YamlException("Actors ruleset does not include the entry '{0}'".F(utLower));
 
 			var altitude = unitType.TraitInfo<AircraftInfo>().CruiseAltitude.Length;
-			var dropRotation = WRot.FromFacing(dropFacing);
+			var dropRotation = WRot.FromFacing(facing);
 			var delta = new WVec(0, -1024, 0).Rotate(dropRotation);
 			target = target + new WVec(0, 0, altitude);
 			var startEdge = target - (self.World.Map.DistanceToEdge(target, -delta) + info.Cordon).Length * delta / 1024;
@@ -168,15 +170,31 @@ namespace OpenRA.Mods.Common.Traits
 				}
 			};
 
-			// Create the units immediately so they can be returned
+			// Create the actors immediately so they can be returned
+			for (var i = -info.SquadSize / 2; i <= info.SquadSize / 2; i++)
+			{
+				// Even-sized squads skip the lead plane
+				if (i == 0 && (info.SquadSize & 1) == 0)
+					continue;
+
+				// Includes the 90 degree rotation between body and world coordinates
+				var so = info.SquadOffset;
+				var spawnOffset = new WVec(i * so.Y, -Math.Abs(i) * so.X, 0).Rotate(dropRotation);
+
+				aircraft.Add(self.World.CreateActor(false, info.UnitType, new TypeDictionary
+				{
+					new CenterPositionInit(startEdge + spawnOffset),
+					new OwnerInit(self.Owner),
+					new FacingInit(facing),
+				}));
+			}
+
 			foreach (var p in info.DropItems)
 			{
-				var unit = self.World.CreateActor(false, p.ToLowerInvariant(), new TypeDictionary
+				units.Add(self.World.CreateActor(false, p.ToLowerInvariant(), new TypeDictionary
 				{
 					new OwnerInit(self.Owner)
-				});
+				}));
-
-				units.Add(unit);
 			}
 
 			self.World.AddFrameEndTask(w =>
@@ -187,6 +205,7 @@ namespace OpenRA.Mods.Common.Traits
 
 				var passengersPerPlane = (info.DropItems.Length + info.SquadSize - 1) / info.SquadSize;
 				var added = 0;
+				var j = 0;
 				for (var i = -info.SquadSize / 2; i <= info.SquadSize / 2; i++)
 				{
 					// Even-sized squads skip the lead plane
@@ -197,13 +216,8 @@ namespace OpenRA.Mods.Common.Traits
 					var so = info.SquadOffset;
 					var spawnOffset = new WVec(i * so.Y, -Math.Abs(i) * so.X, 0).Rotate(dropRotation);
 					var targetOffset = new WVec(i * so.Y, 0, 0).Rotate(dropRotation);
-
+					var a = aircraft[j++];
-					var a = w.CreateActor(info.UnitType, new TypeDictionary
+					w.Add(a);
-					{
-						new CenterPositionInit(startEdge + spawnOffset),
-						new OwnerInit(self.Owner),
-						new FacingInit(dropFacing),
-					});
 
 					var drop = a.Trait<ParaDrop>();
 					drop.SetLZ(w.Map.CellContaining(target + targetOffset), !info.AllowImpassableCells);
@@ -252,7 +266,7 @@ namespace OpenRA.Mods.Common.Traits
 				}
 			});
 
-			return units.ToArray();
+			return Pair.New(aircraft.ToArray(), units.ToArray());
 		}
 
 		void RemoveCamera(Actor camera)