Merge pull request #5789 from Mailaender/render-trait-documentation

Documented the various overlay and animation change traits

OpenRA.Mods.Cnc/RenderGunboat.cs

@@ -19,6 +19,11 @@ namespace OpenRA.Mods.RA.Render
 		[Desc("Turreted 'Turret' key to display")]
 		public readonly string Turret = "primary";
 
+		public readonly string LeftSequence = "left";
+		public readonly string RightSequence = "right";
+		public readonly string WakeLeftSequence = "wake-left";
+		public readonly string WakeRightSequence = "wake-right";
+
 		public override object Create(ActorInitializer init) { return new RenderGunboat(init.self, this); }
 	}
 
@@ -35,28 +40,28 @@ namespace OpenRA.Mods.RA.Render
 				.First(t => t.Name == info.Turret);
 
 			left = new Animation(self.World, name, () => turret.turretFacing);
-			left.Play("left");
+			left.Play(info.LeftSequence);
-			Add("left", new AnimationWithOffset(left, null, () => facing.Facing > 128, 0));
+			Add(info.LeftSequence, new AnimationWithOffset(left, null, () => facing.Facing > 128, 0));
 
 			right = new Animation(self.World, name, () => turret.turretFacing);
-			right.Play("right");
+			right.Play(info.RightSequence);
-			Add("right", new AnimationWithOffset(right, null, () => facing.Facing <= 128, 0));
+			Add(info.RightSequence, new AnimationWithOffset(right, null, () => facing.Facing <= 128, 0));
 
 			var leftWake = new Animation(self.World, name);
-			leftWake.Play("wake-left");
+			leftWake.Play(info.WakeLeftSequence);
-			Add("wake-left", new AnimationWithOffset(leftWake, null, () => facing.Facing > 128, -87));
+			Add(info.WakeLeftSequence, new AnimationWithOffset(leftWake, null, () => facing.Facing > 128, -87));
 
 			var rightWake = new Animation(self.World, name);
-			rightWake.Play("wake-right");
+			rightWake.Play(info.WakeRightSequence);
-			Add("wake-right", new AnimationWithOffset(rightWake, null, () => facing.Facing <= 128, -87));
+			Add(info.WakeRightSequence, new AnimationWithOffset(rightWake, null, () => facing.Facing <= 128, -87));
 
 			self.Trait<IBodyOrientation>().SetAutodetectedFacings(2);
 		}
 
 		public void DamageStateChanged(Actor self, AttackInfo e)
 		{
-			left.ReplaceAnim(NormalizeSequence(left, e.DamageState, "left"));
+			left.ReplaceAnim(NormalizeSequence(left, e.DamageState, left.CurrentSequence.Name));
-			right.ReplaceAnim(NormalizeSequence(right, e.DamageState, "right"));
+			right.ReplaceAnim(NormalizeSequence(right, e.DamageState, right.CurrentSequence.Name));
 		}
 	}
 }

OpenRA.Mods.Cnc/WithCargo.cs

@@ -1,6 +1,6 @@
 #region Copyright & License Information
 /*
- * Copyright 2007-2011 The OpenRA Developers (see AUTHORS)
+ * Copyright 2007-2014 The OpenRA Developers (see AUTHORS)
  * This file is part of OpenRA, which is free software. It is made
  * available to you under the terms of the GNU General Public License
  * as published by the Free Software Foundation. For more information,
@@ -17,10 +17,12 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.Cnc
 {
+	[Desc("Renders the cargo loaded into the unit.")]
 	public class WithCargoInfo : ITraitInfo, Requires<CargoInfo>, Requires<IBodyOrientationInfo>
 	{
 		[Desc("Cargo position relative to turret or body. (forward, right, up) triples")]
 		public readonly WRange[] LocalOffset = { };
+		[Desc("Passenger CargoType to display.")]
 		public readonly string[] DisplayTypes = { };
 
 		public object Create(ActorInitializer init) { return new WithCargo(init.self, this); }

OpenRA.Mods.Cnc/WithDeliveryAnimation.cs

@@ -12,6 +12,7 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Building animation to play when ProductionAirdrop is used to deliver units.")]
 	public class WithDeliveryAnimationInfo : ITraitInfo, Requires<RenderBuildingInfo>
 	{
 		public readonly string ActiveSequence = "active";

OpenRA.Mods.Cnc/WithFire.cs

@@ -13,8 +13,12 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.Cnc
 {
+	[Desc("Renders a flame sprite on top of the actor.")]
 	class WithFireInfo : ITraitInfo, Requires<RenderSpritesInfo>
 	{
+		public readonly string StartSequence = "fire-start";
+		public readonly string LoopSequence = "fire-loop";
+
 		public object Create(ActorInitializer init) { return new WithFire(init.self, this); }
 	}
 
@@ -23,9 +27,9 @@ namespace OpenRA.Mods.Cnc
 		public WithFire(Actor self, WithFireInfo info)
 		{
 			var rs = self.Trait<RenderSprites>();
-			var roof = new Animation(self.World, rs.GetImage(self));
+			var fire = new Animation(self.World, rs.GetImage(self));
-			roof.PlayThen("fire-start", () => roof.PlayRepeating("fire-loop"));
+			fire.PlayThen(info.StartSequence, () => fire.PlayRepeating(info.LoopSequence));
-			rs.Add("fire", new AnimationWithOffset(roof, null, null, 1024));
+			rs.Add("fire", new AnimationWithOffset(fire, null, null, 1024));
 		}
 	}
 }

OpenRA.Mods.Cnc/WithRoof.cs

@@ -13,18 +13,21 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.Cnc
 {
+	[Desc("Provides an overlay for the Tiberian Dawn hover craft.")]
 	public class WithRoofInfo : ITraitInfo, Requires<RenderSpritesInfo>
 	{
-		public object Create(ActorInitializer init) { return new WithRoof(init.self); }
+		public readonly string Sequence = "roof";
+
+		public object Create(ActorInitializer init) { return new WithRoof(init.self, this); }
 	}
 
 	public class WithRoof
 	{
-		public WithRoof(Actor self)
+		public WithRoof(Actor self, WithRoofInfo info)
 		{
 			var rs = self.Trait<RenderSprites>();
 			var roof = new Animation(self.World, rs.GetImage(self), () => self.Trait<IFacing>().Facing);
-			roof.Play("roof");
+			roof.Play(info.Sequence);
 			rs.Add("roof", new AnimationWithOffset(roof, null, null, 1024));
 		}
 	}

OpenRA.Mods.D2k/DamagedWithoutFoundation.cs

@@ -12,8 +12,9 @@ using System.Linq;
 using OpenRA.GameRules;
 using OpenRA.Traits;
 
-namespace OpenRA.Mods.Cnc
+namespace OpenRA.Mods.D2k
 {
+	[Desc("Reduces health points over time when the actor is placed on unsafe terrain.")]
 	class DamagedWithoutFoundationInfo : ITraitInfo, Requires<HealthInfo>
 	{
 		[WeaponReference]

OpenRA.Mods.D2k/Render/WithBuildingPlacedOverlayInfo.cs

@@ -14,6 +14,7 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Rendered when the actor constructed a building.")]
 	public class WithBuildingPlacedOverlayInfo : ITraitInfo, Requires<RenderSpritesInfo>, Requires<IBodyOrientationInfo>
 	{
 		[Desc("Sequence name to use")]

OpenRA.Mods.D2k/Render/WithCrumbleOverlay.cs

@@ -13,6 +13,7 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Rendered together with the \"make\" animation.")]
 	public class WithCrumbleOverlayInfo : ITraitInfo, Requires<RenderSpritesInfo>
 	{
 		[Desc("Sequence name to use")]

OpenRA.Mods.D2k/Render/WithDeliveryOverlay.cs

@@ -15,6 +15,7 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Rendered when ProductionAirdrop is in progress.")]
 	public class WithDeliveryOverlayInfo : ITraitInfo, Requires<RenderSpritesInfo>, Requires<IBodyOrientationInfo>
 	{
 		[Desc("Sequence name to use")]

OpenRA.Mods.D2k/Render/WithDockingOverlay.cs

@@ -15,6 +15,7 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Rendered when a harvester is docked.")]
 	public class WithDockingOverlayInfo : ITraitInfo, Requires<RenderSpritesInfo>, Requires<IBodyOrientationInfo>
 	{
 		[Desc("Sequence name to use")]

OpenRA.Mods.D2k/Render/WithProductionOverlay.cs

@@ -16,6 +16,8 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Renders an animation when the Production trait of the actor is activated.",
+		"Works both with per player ClassicProductionQueue and per building ProductionQueue, but needs any of these.")]
 	public class WithProductionOverlayInfo : ITraitInfo, Requires<RenderSpritesInfo>, Requires<IBodyOrientationInfo>
 	{
 		[Desc("Sequence name to use")]

OpenRA.Mods.D2k/ThrowsShrapnel.cs

@@ -14,6 +14,7 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.D2k
 {
+	[Desc("Throws particles when the actor is destroyed that do damage on impact.")]
 	public class ThrowsShrapnelInfo : ITraitInfo
 	{
 		[WeaponReference]

OpenRA.Mods.RA/Render/WithBuildingExplosion.cs

@@ -14,15 +14,32 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
-	class WithBuildingExplosionInfo : TraitInfo<WithBuildingExplosion> { }
+	[Desc("Display explosions over the building footprint when it is destroyed.")]
+	class WithBuildingExplosionInfo : ITraitInfo, Requires<BuildingInfo>
+	{
+		[Desc("Explosion sequence name to use")]
+		public readonly string Sequence = "building";
+
+		[Desc("Custom palette name")]
+		public readonly string Palette = "effect";
+		
+		public object Create(ActorInitializer init) { return new WithBuildingExplosion(this); }
+	}
+
 	class WithBuildingExplosion : INotifyKilled
 	{
+		WithBuildingExplosionInfo info;
+
+		public WithBuildingExplosion(WithBuildingExplosionInfo info)
+		{
+			this.info = info;
+		}
+
 		public void Killed(Actor self, AttackInfo e)
 		{
-			//TODO: Make palette for this customizable as well
+			var buildingInfo = self.Info.Traits.Get<BuildingInfo>();
-			var bi = self.Info.Traits.Get<BuildingInfo>();
+			FootprintUtils.UnpathableTiles(self.Info.Name, buildingInfo, self.Location).Do(
-			FootprintUtils.UnpathableTiles(self.Info.Name, bi, self.Location).Do(
+				t => self.World.AddFrameEndTask(w => w.Add(new Explosion(w, w.Map.CenterOfCell(t), info.Sequence, info.Palette))));
-				t => self.World.AddFrameEndTask(w => w.Add(new Explosion(w, w.Map.CenterOfCell(t), "building", "effect"))));
 		}
 	}
 }

OpenRA.Mods.RA/Render/WithBuildingPlacedAnimation.cs

@@ -12,6 +12,7 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Changes the animation when the actor constructed a building.")]
 	public class WithBuildingPlacedAnimationInfo : ITraitInfo, Requires<RenderSimpleInfo>
 	{
 		[Desc("Sequence name to use")]

OpenRA.Mods.RA/Render/WithCrateBody.cs

@@ -15,9 +15,12 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Renders crates with both water and land variants.")]
 	class WithCrateBodyInfo : ITraitInfo, Requires<RenderSpritesInfo>
 	{
 		public readonly string[] Images = { "crate" };
+
+		[Desc("Easteregg sequences to use in december.")]
 		public readonly string[] XmasImages = { };
 
 		public object Create(ActorInitializer init) { return new WithCrateBody(init.self, this); }
@@ -35,7 +38,7 @@ namespace OpenRA.Mods.RA.Render
 			var images = info.XmasImages.Any() && DateTime.Today.Month == 12 ? info.XmasImages : info.Images;
 			anim = new Animation(self.World, images.Random(Game.CosmeticRandom));
 			anim.Play("idle");
-			rs.Add("", anim);
+			rs.Add("crate", anim);
 		}
 
 		public void OnLanded()

OpenRA.Mods.RA/Render/WithHarvestAnimation.cs

@@ -13,6 +13,7 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Displays an overlay whenever resources are harvested by the actor.")]
 	class WithHarvestAnimationInfo : ITraitInfo, Requires<RenderSpritesInfo>, Requires<IBodyOrientationInfo>
 	{
 		[Desc("Sequence name to use")]

OpenRA.Mods.RA/Render/WithIdleOverlay.cs

@@ -15,6 +15,7 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Renders a decorative animation on units and buildings.")]
 	public class WithIdleOverlayInfo : ITraitInfo, Requires<RenderSpritesInfo>, Requires<IBodyOrientationInfo>
 	{
 		[Desc("Sequence name to use")]

OpenRA.Mods.RA/Render/WithMuzzleFlash.cs

@@ -16,6 +16,7 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Renders the MuzzleSequence from the Armament trait.")]
 	class WithMuzzleFlashInfo : ITraitInfo, Requires<RenderSpritesInfo>, Requires<AttackBaseInfo>, Requires<ArmamentInfo>
 	{
 		[Desc("Ignore the weapon position, and always draw relative to the center of the actor")]

OpenRA.Mods.RA/Render/WithRepairAnimation.cs

@@ -14,6 +14,7 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Replaces the building animation when it repairs a unit.")]
 	public class WithRepairAnimationInfo : ITraitInfo, Requires<RenderBuildingInfo>
 	{
 		[Desc("Sequence name to use")]

OpenRA.Mods.RA/Render/WithRepairOverlay.cs

@@ -16,6 +16,7 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Displays an overlay when the building is being repaired by the player.")]
 	public class WithRepairOverlayInfo : ITraitInfo, Requires<RenderSpritesInfo>, Requires<IBodyOrientationInfo>
 	{
 		[Desc("Sequence name to use")]

OpenRA.Mods.RA/Render/WithResources.cs

@@ -1,6 +1,6 @@
 #region Copyright & License Information
 /*
- * Copyright 2007-2013 The OpenRA Developers (see AUTHORS)
+ * Copyright 2007-2014 The OpenRA Developers (see AUTHORS)
  * This file is part of OpenRA, which is free software. It is made
  * available to you under the terms of the GNU General Public License
  * as published by the Free Software Foundation. For more information,
@@ -13,6 +13,7 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Displays the fill status of PlayerResources with an extra sprite overlay on the actor.")]
 	class WithResourcesInfo : ITraitInfo, Requires<RenderSimpleInfo>
 	{
 		[Desc("Sequence name to use")]

OpenRA.Mods.RA/Render/WithRotor.cs

@@ -13,6 +13,7 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Displays a helicopter rotor overlay.")]
 	public class WithRotorInfo : ITraitInfo, Requires<RenderSpritesInfo>, Requires<IBodyOrientationInfo>
 	{
 		[Desc("Sequence name to use when flying")]
@@ -24,6 +25,7 @@ namespace OpenRA.Mods.RA.Render
 		[Desc("Position relative to body")]
 		public readonly WVec Offset = WVec.Zero;
 
+		[Desc("Change this when using this trait multiple times on the same actor.")]
 		public readonly string Id = "rotor";
 
 		public object Create(ActorInitializer init) { return new WithRotor(init.self, this); }

OpenRA.Mods.RA/Render/WithShadow.cs

@@ -17,10 +17,23 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
-	class WithShadowInfo : TraitInfo<WithShadow> {}
+	[Desc("Clones the aircraft sprite with another palette below it.")]
+	class WithShadowInfo : ITraitInfo
+	{
+		public readonly string Palette = "shadow";
+
+		public object Create(ActorInitializer init) { return new WithShadow(this); }
+	}
 
 	class WithShadow : IRenderModifier
 	{
+		WithShadowInfo info;
+
+		public WithShadow(WithShadowInfo info)
+		{
+			this.info = info;
+		}
+
 		public IEnumerable<IRenderable> ModifyRender(Actor self, WorldRenderer wr, IEnumerable<IRenderable> r)
 		{
 			var ios = self.Trait<IOccupySpace>();
@@ -32,7 +45,7 @@ namespace OpenRA.Mods.RA.Render
 
 			// Contrails shouldn't cast shadows
 			var shadowSprites = r.Where(s => !s.IsDecoration)
-				.Select(a => a.WithPalette(wr.Palette("shadow"))
+				.Select(a => a.WithPalette(wr.Palette(info.Palette))
 				.OffsetBy(new WVec(0, 0, -a.Pos.Z))
 				.WithZOffset(a.ZOffset + a.Pos.Z)
 				.AsDecoration());

OpenRA.Mods.RA/Render/WithSmoke.cs

@@ -13,9 +13,13 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Renders an overlay when the actor is taking heavy damage.")]
 	public class WithSmokeInfo : ITraitInfo, Requires<RenderSpritesInfo>
 	{
-		public object Create(ActorInitializer init) { return new WithSmoke(init.self); }
+		[Desc("Needs to define \"idle\", \"loop\" and \"end\" sub-sequences.")]
+		public readonly string Sequence = "smoke_m";
+
+		public object Create(ActorInitializer init) { return new WithSmoke(init.self, this); }
 	}
 
 	public class WithSmoke : INotifyDamage
@@ -23,11 +27,11 @@ namespace OpenRA.Mods.RA.Render
 		bool isSmoking;
 		Animation anim;
 
-		public WithSmoke(Actor self)
+		public WithSmoke(Actor self, WithSmokeInfo info)
 		{
 			var rs = self.Trait<RenderSprites>();
 
-			anim = new Animation(self.World, "smoke_m");
+			anim = new Animation(self.World, info.Sequence);
 			rs.Add("smoke", new AnimationWithOffset(anim, null, () => !isSmoking));
 		}
 

OpenRA.Mods.RA/Render/WithTurret.cs

@@ -15,6 +15,7 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA.Render
 {
+	[Desc("Renders barrels for units with the Turreted trait.")]
 	class WithTurretInfo : ITraitInfo, Requires<RenderSpritesInfo>, Requires<TurretedInfo>, Requires<IBodyOrientationInfo>
 	{
 		[Desc("Sequence name to use")]