0ad/binaries/data/mods/public/simulation/components/Formation.js

function Formation() {}

Formation.prototype.Schema =
	"<element name='FormationName' a:help='Name of the formation'>" +
		"<text/>" +
	"</element>" +
	"<element name='SpeedMultiplier' a:help='The speed of the formation is determined by the minimum speed of all members, multiplied with this number.'>" +
		"<ref name='nonNegativeDecimal'/>" +
	"</element>" +
	"<element name='FormationShape' a:help='Formation shape, currently supported are square, triangle and special, where special will be defined in the source code.'>" +
		"<text/>" +
	"</element>" +
	"<element name='ShiftRows' a:help='Set the value to true to shift subsequent rows'>" +
		"<text/>" +
	"</element>" +
	"<element name='WidthDepthRatio' a:help='Average width/depth, counted in number of units.'>" +
		"<ref name='nonNegativeDecimal'/>" +
	"</element>" +
	"<optional>" +
		"<element name='MinColumns' a:help='When possible, this number of colums will be created. Overriding the wanted width depth ratio'>" +
			"<data type='nonNegativeInteger'/>" +
		"</element>" +
	"</optional>" +
	"<optional>" +
		"<element name='MaxColumns' a:help='When possible within the number of units, and the maximum number of rows, this will be the maximum number of columns.'>" +
			"<data type='nonNegativeInteger'/>" +
		"</element>" +
	"</optional>" +
	"<optional>" +
		"<element name='MaxRows' a:help='The maximum number of rows in the formation'>" +
			"<data type='nonNegativeInteger'/>" +
		"</element>" +
	"</optional>" +
	"<optional>" +
		"<element name='CenterGap' a:help='The size of the central gap, expressed in number of units wide'>" +
			"<ref name='nonNegativeDecimal'/>" +
		"</element>" +
	"</optional>" +
	"<element name='UnitSeparationWidthMultiplier' a:help='Place the units in the formation closer or further to each other. The standard separation is the footprint size.'>" +
		"<ref name='nonNegativeDecimal'/>" +
	"</element>" +
	"<element name='UnitSeparationDepthMultiplier' a:help='Place the units in the formation closer or further to each other. The standard separation is the footprint size.'>" +
		"<ref name='nonNegativeDecimal'/>" +
	"</element>";	

var g_ColumnDistanceThreshold = 128; // distance at which we'll switch between column/box formations

Formation.prototype.Init = function()
{
	this.formationShape = this.template.FormationShape;
	this.shiftRows = this.template.ShiftRows == "true";
	this.separationMultiplier = {
		"width": +this.template.UnitSeparationWidthMultiplier,
		"depth": +this.template.UnitSeparationDepthMultiplier
	};
	this.widthDepthRatio = +this.template.WidthDepthRatio;
	this.minColumns = +(this.template.MinColumns || 0);
	this.maxColumns = +(this.template.MaxColumns || 0);
	this.maxRows = +(this.template.MaxRows || 0);
	this.centerGap = +(this.template.CenterGap || 0);

	this.members = []; // entity IDs currently belonging to this formation
	this.inPosition = []; // entities that have reached their final position
	this.columnar = false; // whether we're travelling in column (vs box) formation
	this.formationName = this.template.FormationName;
	this.rearrange = true; // whether we should rearrange all formation members
	this.formationMembersWithAura = []; // Members with a formation aura
	this.width = 0;
	this.depth = 0;
	this.oldOrientation = {"sin": 0, "cos": 0};
	this.twinFormations = [];
	// distance from which two twin formations will merge into one.
	this.formationSeparation = 0;
	Engine.QueryInterface(SYSTEM_ENTITY, IID_Timer)
		.SetInterval(this.entity, IID_Formation, "ShapeUpdate", 1000, 1000, null);
};

/**
 * Set the value from which two twin formations will become one.
 */
Formation.prototype.SetFormationSeparation = function(value)
{
	this.formationSeparation = value;
};

Formation.prototype.GetSize = function()
{
	return {"width": this.width, "depth": this.depth};
};

Formation.prototype.GetSpeedMultiplier = function()
{
	return +this.template.SpeedMultiplier;
};

Formation.prototype.GetMemberCount = function()
{
	return this.members.length;
};

/**
 * Returns the 'primary' member of this formation (typically the most
 * important unit type), for e.g. playing a representative sound.
 * Returns undefined if no members.
 * TODO: actually implement something like that; currently this just returns
 * the arbitrary first one.
 */
Formation.prototype.GetPrimaryMember = function()
{
	return this.members[0];
};

/**
 * Permits formation members to register that they've reached their
 * destination, and automatically disbands the formation if all members
 * are at their final positions and no controller orders remain.
 */
Formation.prototype.SetInPosition = function(ent)
{
	if (this.inPosition.indexOf(ent) != -1)
		return;

	// Only consider automatically disbanding if there are no orders left.
	var cmpUnitAI = Engine.QueryInterface(this.entity, IID_UnitAI);
	if (cmpUnitAI.GetOrders().length)
	{
		this.inPosition = [];
		return;
	}

	this.inPosition.push(ent);
	if (this.inPosition.length >= this.members.length)
		this.Disband();
};

/**
 * Called by formation members upon entering non-walking states.
 */
Formation.prototype.UnsetInPosition = function(ent)
{
	var ind = this.inPosition.indexOf(ent);
	if (ind != -1)
		this.inPosition.splice(ind, 1);
}

/**
 * Set whether we should rearrange formation members if
 * units are removed from the formation.
 */
Formation.prototype.SetRearrange = function(rearrange)
{
	this.rearrange = rearrange;
};

/**
 * Initialise the members of this formation.
 * Must only be called once.
 * All members must implement UnitAI.
 */
Formation.prototype.SetMembers = function(ents)
{
	this.members = ents;

	for each (var ent in this.members)
	{
		var cmpUnitAI = Engine.QueryInterface(ent, IID_UnitAI);
		cmpUnitAI.SetFormationController(this.entity);
		cmpUnitAI.SetLastFormationName(this.formationName);
		
		var cmpAuras = Engine.QueryInterface(ent, IID_Auras);
		if (cmpAuras && cmpAuras.HasFormationAura())
		{
			this.formationMembersWithAura.push(ent);
			cmpAuras.ApplyFormationBonus(ents);
		}
	}

	this.offsets = undefined;
	// Locate this formation controller in the middle of its members
	this.MoveToMembersCenter();

	this.ComputeMotionParameters();

};

/**
 * Remove the given list of entities.
 * The entities must already be members of this formation.
 */
Formation.prototype.RemoveMembers = function(ents)
{
	this.offsets = undefined;
	this.members = this.members.filter(function(e) { return ents.indexOf(e) == -1; });
	this.inPosition = this.inPosition.filter(function(e) { return ents.indexOf(e) == -1; });

	for each (var ent in ents)
	{
		var cmpUnitAI = Engine.QueryInterface(ent, IID_UnitAI);
		cmpUnitAI.UpdateWorkOrders();
		cmpUnitAI.SetFormationController(INVALID_ENTITY);
	}

	for each (var ent in this.formationMembersWithAura)
	{
		var cmpAuras = Engine.QueryInterface(ent, IID_Auras);
		cmpAuras.RemoveFormationBonus(ents);

		// the unit with the aura is also removed from the formation
		if (ents.indexOf(ent) !== -1)
			cmpAuras.RemoveFormationBonus(this.members);
	}

	this.formationMembersWithAura = this.formationMembersWithAura.filter(function(e) { return ents.indexOf(e) == -1; });

	// If there's nobody left, destroy the formation
	if (this.members.length == 0)
	{
		Engine.DestroyEntity(this.entity);
		return;
	}

	if (!this.rearrange)
		return;

	this.ComputeMotionParameters();

	// Rearrange the remaining members
	this.MoveMembersIntoFormation(true, true);
};

Formation.prototype.AddMembers = function(ents)
{
	this.offsets = undefined;
	this.inPosition = []; 

	for each (var ent in this.formationMembersWithAura)
	{
		var cmpAuras = Engine.QueryInterface(ent, IID_Auras);
		cmpAuras.RemoveFormationBonus(ents);

		// the unit with the aura is also removed from the formation
		if (ents.indexOf(ent) !== -1)
			cmpAuras.RemoveFormationBonus(this.members);
	}

	this.members = this.members.concat(ents);

	for each (var ent in this.members)
	{
		var cmpUnitAI = Engine.QueryInterface(ent, IID_UnitAI);
		cmpUnitAI.SetFormationController(this.entity);
		
		var cmpAuras = Engine.QueryInterface(ent, IID_Auras);
		if (cmpAuras && cmpAuras.HasFormationAura())
		{
			this.formationMembersWithAura.push(ent);
			cmpAuras.ApplyFormationBonus(ents);
		}
	}

	this.MoveMembersIntoFormation(true, true);
};

/**
 * Called when the formation stops moving in order to detect
 * units that have already reached their final positions.
 */
Formation.prototype.FindInPosition = function()
{
	for (var i = 0; i < this.members.length; ++i)
	{
		var cmpUnitMotion = Engine.QueryInterface(this.members[i], IID_UnitMotion);
		if (!cmpUnitMotion.IsMoving())
		{
			// Verify that members are stopped in FORMATIONMEMBER.WALKING
			var cmpUnitAI = Engine.QueryInterface(this.members[i], IID_UnitAI);
			if (cmpUnitAI.IsWalking())
				this.SetInPosition(this.members[i]);
		}
	}
}

/**
 * Remove all members and destroy the formation.
 */
Formation.prototype.Disband = function()
{
	for each (var ent in this.members)
	{
		var cmpUnitAI = Engine.QueryInterface(ent, IID_UnitAI);
		cmpUnitAI.SetFormationController(INVALID_ENTITY);
	}

	for each (var ent in this.formationMembersWithAura)
	{
		var cmpAuras = Engine.QueryInterface(ent, IID_Auras);
		cmpAuras.RemoveFormationBonus(this.members);
	}


	this.members = [];
	this.inPosition = [];
	this.formationMembersWithAura = [];
	this.offsets = undefined;

	Engine.DestroyEntity(this.entity);
};

/**
 * Call obj.funcname(args) on UnitAI components of all members.
 */
Formation.prototype.CallMemberFunction = function(funcname, args)
{
	for each (var ent in this.members)
	{
		var cmpUnitAI = Engine.QueryInterface(ent, IID_UnitAI);
		cmpUnitAI[funcname].apply(cmpUnitAI, args);
	}
};

/**
 * Call obj.functname(args) on UnitAI components of all members,
 * and return true if all calls return true.
 */
Formation.prototype.TestAllMemberFunction = function(funcname, args)
{
	for each (var ent in this.members)
	{
		var cmpUnitAI = Engine.QueryInterface(ent, IID_UnitAI);
		if (!cmpUnitAI[funcname].apply(cmpUnitAI, args))
			return false;
	}
	return true;
};

Formation.prototype.GetMaxAttackRangeFunction = function(target)
{
	var result = 0;
	var range = 0;
	for each (var ent in this.members)
	{
		var cmpAttack = Engine.QueryInterface(ent, IID_Attack);
		if (!cmpAttack)
			continue;

		var type = cmpAttack.GetBestAttackAgainst(target);
		if (!type)
			continue;

		range = cmpAttack.GetRange(type);
		if (range.max > result)
			result = range.max;
	}
	return result;
};

/**
 * Set all members to form up into the formation shape.
 * If moveCenter is true, the formation center will be reinitialised
 * to the center of the units.
 * If force is true, all individual orders of the formation units are replaced,
 * otherwise the order to walk into formation is just pushed to the front.
 */
Formation.prototype.MoveMembersIntoFormation = function(moveCenter, force)
{
	var active = [];
	var positions = [];

	for each (var ent in this.members)
	{
		var cmpPosition = Engine.QueryInterface(ent, IID_Position);
		if (!cmpPosition || !cmpPosition.IsInWorld())
			continue;

		active.push(ent);
		// query the 2D position as exact hight calculation isn't needed
		// but bring the position to the right coordinates
		var pos = cmpPosition.GetPosition2D();
		pos.z = pos.y;
		pos.y = undefined;
		positions.push(pos);
	}

	var avgpos = this.ComputeAveragePosition(positions);

	// Reposition the formation if we're told to or if we don't already have a position
	var cmpPosition = Engine.QueryInterface(this.entity, IID_Position);
	var inWorld = cmpPosition.IsInWorld();
	if (moveCenter || !inWorld)
	{
		cmpPosition.JumpTo(avgpos.x, avgpos.z);
		// Don't make the formation controller entity show up in range queries
		if (!inWorld)
		{
			var cmpRangeManager = Engine.QueryInterface(SYSTEM_ENTITY, IID_RangeManager);
			cmpRangeManager.SetEntityFlag(this.entity, "normal", false);
		}
	}

	// Switch between column and box if necessary
	var cmpUnitAI = Engine.QueryInterface(this.entity, IID_UnitAI);
	var walkingDistance = cmpUnitAI.ComputeWalkingDistance();
	var columnar = walkingDistance > g_ColumnDistanceThreshold;
	if (columnar != this.columnar)
	{
		this.columnar = columnar;
		this.offsets = undefined;
	}

	var newOrientation = this.GetTargetOrientation(avgpos);
	var dSin = Math.abs(newOrientation.sin - this.oldOrientation.sin);
	var dCos = Math.abs(newOrientation.cos - this.oldOrientation.cos);
	// If the formation existed, only recalculate positions if the turning agle is somewhat biggish
	if (!this.offsets || dSin > 1 || dCos > 1)
		this.offsets = this.ComputeFormationOffsets(active, positions);

	this.oldOrientation = newOrientation;

	var xMax = 0;
	var zMax = 0;

	for (var i = 0; i < this.offsets.length; ++i)
	{
		var offset = this.offsets[i];

		var cmpUnitAI = Engine.QueryInterface(offset.ent, IID_UnitAI);
		if (!cmpUnitAI)
			continue;
		
		if (force)
		{
			cmpUnitAI.ReplaceOrder("FormationWalk", {
				"target": this.entity,
				"x": offset.x,
				"z": offset.z
			});
		}
		else
		{
			cmpUnitAI.PushOrderFront("FormationWalk", {
				"target": this.entity,
				"x": offset.x,
				"z": offset.z
			});
		}
		xMax = Math.max(xMax, offset.x);
		zMax = Math.max(zMax, offset.z);
	}
	this.width = xMax * 2;
	this.depth = zMax * 2;
};

Formation.prototype.MoveToMembersCenter = function()
{
	var positions = [];

	for each (var ent in this.members)
	{
		var cmpPosition = Engine.QueryInterface(ent, IID_Position);
		if (!cmpPosition || !cmpPosition.IsInWorld())
			continue;

		positions.push(cmpPosition.GetPosition());
	}

	var avgpos = this.ComputeAveragePosition(positions);

	var cmpPosition = Engine.QueryInterface(this.entity, IID_Position);
	var inWorld = cmpPosition.IsInWorld();
	cmpPosition.JumpTo(avgpos.x, avgpos.z);

	// Don't make the formation controller show up in range queries
	if (!inWorld)
	{
		var cmpRangeManager = Engine.QueryInterface(SYSTEM_ENTITY, IID_RangeManager);
		cmpRangeManager.SetEntityFlag(this.entity, "normal", false);
	}
};

Formation.prototype.GetAvgFootprint = function(active)
{
	var footprints = [];
	for each (var ent in active)
	{
		var cmpFootprint = Engine.QueryInterface(ent, IID_Footprint);
		if (cmpFootprint)
			footprints.push(cmpFootprint.GetShape());
	}
	if (!footprints.length)
		return {"width":1, "depth": 1};

	var r = {"width": 0, "depth": 0};
	for each (var shape in footprints)
	{
		if (shape.type == "circle")
		{
			r.width += shape.radius * 2;
			r.depth += shape.radius * 2;
		}
		else if (shape.type == "square")
		{
			r.width += shape.width;
			r.depth += shape.depth;
		}
	}
	r.width /= footprints.length;
	r.depth /= footprints.length;
	return r;
};

Formation.prototype.ComputeFormationOffsets = function(active, positions)
{
	var separation = this.GetAvgFootprint(active);
	separation.width *= this.separationMultiplier.width;
	separation.depth *= this.separationMultiplier.depth;

	// the entities will be assigned to positions in the formation in 
	// the same order as the types list is ordered
	var types = {
		"Cavalry" : [],
		"Hero" : [],
		"Melee" : [],
		"Ranged" : [],
		"Support" : [],
		"Unknown": []
	}; 

	for (var i in active)
	{
		var cmpIdentity = Engine.QueryInterface(active[i], IID_Identity);
		var classes = cmpIdentity.GetClassesList();
		var done = false;
		for each (var cla in classes)
		{
			if (cla in types)
			{
				types[cla].push({"ent": active[i], "pos": positions[i]});
				done = true;
				break;
			}
		}
		if (!done)
			types["Unknown"].push({"ent": active[i], "pos": positions[i]});
	}

	var count = active.length;

	var shape = this.formationShape;
	var shiftRows = this.shiftRows;
	var centerGap = this.centerGap;
	var ordering = [];

	var offsets = [];

	// Choose a sensible size/shape for the various formations, depending on number of units
	var cols;

	if (this.columnar)
	{
		shape = "square";
		cols = Math.min(count,3);
		shiftRows = false;
		centerGap = 0;
	}
	else
	{
		var depth = Math.sqrt(count / this.widthDepthRatio);
		if (this.maxRows && depth > this.maxRows)
			depth = this.maxRows;
		cols = Math.ceil(count / Math.ceil(depth) + (this.shiftRows ? 0.5 : 0));
		if (cols < this.minColumns)
			cols = Math.min(count, this.minColumns);
		if (this.maxColumns && cols > this.maxColumns && this.maxRows != depth)
			cols = this.maxColumns;
	}

	// define special formations here
	switch(this.formationName)
	{
	case "Scatter":
		var width = Math.sqrt(count) * (separation.width + separation.depth) * 2.5;

		for (var i = 0; i < count; ++i)
			offsets.push({"x": Math.random()*width, "z": Math.random()*width});
		break;
	case "Box":
		var root = Math.ceil(Math.sqrt(count));

		var left = count;
		var meleeleft = types["Melee"].length;
		for (var sq = Math.floor(root/2); sq >= 0; --sq)
		{
			var width = sq * 2 + 1;
			var stodo;
			if (sq == 0)
			{
				stodo = left;
			}
			else
			{
				if (meleeleft >= width*width - (width-2)*(width-2)) // form a complete box
				{
					stodo = width*width - (width-2)*(width-2);
					meleeleft -= stodo;
				}
				else	// compact
				{
					stodo = Math.max(0, left - (width-2)*(width-2));
				}
			}

			for (var r = -sq; r <= sq && stodo; ++r)
			{
				for (var c = -sq; c <= sq && stodo; ++c)
				{
					if (Math.abs(r) == sq || Math.abs(c) == sq)
					{
						var x = c * separation.width;
						var z = -r * separation.depth;
						offsets.push({"x": x, "z": z});
						stodo--;
						left--;
					}
				}
			}
		}
		break;
	case "Battle Line":
		ordering.push("FillFromTheSides");
		break;
	default:
		break;
	}

	// For non-special formations, calculate the positions based on the number of entities
	if (shape != "special")
	{
		var r = 0;
		var left = count;
		// while there are units left, start a new row in the formation
		while (left > 0)
		{
			// save the position of the row
			var z = -r * separation.depth;
			// switch between the left and right side of the center to have a symmetrical distribution
			var side = 1;
			// determine the number of entities in this row of the formation
			if (shape == "square")
			{
				var n = cols;
				if (shiftRows)
					n -= r%2;
			}
			else if (shape == "triangle")
			{
				if (shiftRows)
					var n = r + 1;
				else
					var n = r * 2 + 1;
			}
			if (!shiftRows && n > left)
				n = left;
			for (var c = 0; c < n && left > 0; ++c)
			{
				// switch sides for the next entity
				side *= -1;
				if (n%2 == 0)
					var x = side * (Math.floor(c/2) + 0.5) * separation.width;
				else
					var x = side * Math.ceil(c/2) * separation.width;
				if (centerGap)
				{
					if (x == 0) // don't use the center position with a center gap
						continue;
					x += side * centerGap / 2;
				}
				offsets.push({"x": x, "z": z});
				left--
			}
			++r;
		}
	}

	// make sure the average offset is zero, as the formation is centered around that
	// calculating offset distances without a zero average makes no sense, as the formation
	// will jump to a different position any time
	var avgoffset = this.ComputeAveragePosition(offsets);
	for each (var offset in offsets)
	{
		offset.x -= avgoffset.x;
		offset.z -= avgoffset.z;
	}

	// sort the available places in certain ways
	// the places first in the list will contain the heaviest units as defined by the order
	// of the types list
	for each (var order in ordering)
	{
		if (order == "FillFromTheSides")
			offsets.sort(function(o1, o2) { return Math.abs(o1.x) < Math.abs(o2.x);});
		else if (order == "FillFromTheCenter")
			offsets.sort(function(o1, o2) { return Math.abs(o1.x) > Math.abs(o2.x);});
		else if (order == "FillFromTheFront")
			offsets.sort(function(o1, o2) { return o1.z < o2.z;});
	}

	// query the 2D position of the formation, and bring to the right coordinate system
	var cmpPosition = Engine.QueryInterface(this.entity, IID_Position);
	var formationPos = cmpPosition.GetPosition2D();
	formationPos.z = formationPos.y;
	formationPos.y = undefined;

	// use realistic place assignment,
	// every soldier searches the closest available place in the formation
	var newOffsets = [];
	var realPositions = this.GetRealOffsetPositions(offsets, formationPos);
	for each (var t in types)
	{
		var usedOffsets = offsets.splice(0,t.length);
		var usedRealPositions = realPositions.splice(0, t.length);
		for each (var entPos in t)
		{
			var closestOffsetId = this.TakeClosestOffset(entPos, usedRealPositions);
			usedRealPositions.splice(closestOffsetId, 1);
			newOffsets.push(usedOffsets.splice(closestOffsetId, 1)[0]);
			newOffsets[newOffsets.length - 1].ent = entPos.ent;
		}
	}

	return newOffsets;
};

/**
 * Search the closest position in the realPositions list to the given entity
 * @param ent, the queried entity
 * @param realPositions, the world coordinates of the available offsets
 * @return the index of the closest offset position
 */
Formation.prototype.TakeClosestOffset = function(entPos, realPositions)
{
	var pos = entPos.pos;
	var closestOffsetId = -1;
	var offsetDistanceSq = Infinity;
	for (var i = 0; i < realPositions.length; i++)
	{
		var dx = realPositions[i].x - pos.x;
		var dz = realPositions[i].z - pos.z;
		var distSq = dx * dx + dz * dz;
		if (distSq < offsetDistanceSq)
		{
			offsetDistanceSq = distSq;
			closestOffsetId = i;
		}
	}
	return closestOffsetId;
};

/**
 * Get the world positions for a list of offsets in this formation
 */
Formation.prototype.GetRealOffsetPositions = function(offsets, pos)
{
	var offsetPositions = [];
	var {sin, cos} = this.GetTargetOrientation(pos);
	// calculate the world positions
	for each (var o in offsets)
		offsetPositions.push({
			"x" : pos.x + o.z * sin + o.x * cos, 
			"z" : pos.z + o.z * cos - o.x * sin
		});

	return offsetPositions;
};

/**
 * calculate the estimated rotation of the formation 
 * based on the first unitAI target position
 * Return the sine and cosine of the angle
 */
Formation.prototype.GetTargetOrientation = function(pos)
{
	var cmpUnitAI = Engine.QueryInterface(this.entity, IID_UnitAI);
	var targetPos = cmpUnitAI.GetTargetPositions();
	var sin = 0;
	var cos = 1;
	if (targetPos.length)
	{
		var dx = targetPos[0].x - pos.x;
		var dz = targetPos[0].z - pos.z;
		if (dx || dz)
		{
			var dist = Math.sqrt(dx * dx + dz * dz);
			cos = dz / dist;
			sin = dx / dist;
		}
	}
	return {"sin": sin, "cos": cos};
};

Formation.prototype.ComputeAveragePosition = function(positions)
{
	var sx = 0;
	var sz = 0;
	for each (var pos in positions)
	{
		sx += pos.x;
		sz += pos.z;
	}
	return { "x": sx / positions.length, "z": sz / positions.length };
};

/**
 * Set formation controller's radius and speed based on its current members.
 */
Formation.prototype.ComputeMotionParameters = function()
{
	var maxRadius = 0;
	var minSpeed = Infinity;

	for each (var ent in this.members)
	{
		var cmpObstruction = Engine.QueryInterface(ent, IID_Obstruction);
		if (cmpObstruction)
			maxRadius = Math.max(maxRadius, cmpObstruction.GetUnitRadius());

		var cmpUnitMotion = Engine.QueryInterface(ent, IID_UnitMotion);
		if (cmpUnitMotion)
			minSpeed = Math.min(minSpeed, cmpUnitMotion.GetWalkSpeed());
	}
	minSpeed *= this.GetSpeedMultiplier();

	var cmpUnitMotion = Engine.QueryInterface(this.entity, IID_UnitMotion);
	cmpUnitMotion.SetUnitRadius(maxRadius);
	cmpUnitMotion.SetSpeed(minSpeed);

	// TODO: we also need to do something about PassabilityClass, CostClass
};

Formation.prototype.ShapeUpdate = function()
{
	// Check the distance to twin formations, and merge if when 
	// the formations could collide
	for (var i = this.twinFormations.length - 1; i >= 0; --i)
	{
		// only do the check on one side
		if (this.twinFormations[i] <= this.entity)
			continue;

		var cmpPosition = Engine.QueryInterface(this.entity, IID_Position);
		var cmpOtherPosition = Engine.QueryInterface(this.twinFormations[i], IID_Position);
		var cmpOtherFormation = Engine.QueryInterface(this.twinFormations[i], IID_Formation);
		if (!cmpPosition || !cmpOtherPosition || !cmpOtherFormation)
			continue;

		var thisPosition = cmpPosition.GetPosition2D();
		var otherPosition = cmpOtherPosition.GetPosition2D();
		var dx = thisPosition.x - otherPosition.x;
		var dy = thisPosition.y - otherPosition.y;
		var dist = Math.sqrt(dx * dx + dy * dy);

		var thisSize = this.GetSize();
		var otherSize = cmpOtherFormation.GetSize();
		var minDist = Math.max(thisSize.width / 2, thisSize.depth / 2) +
			Math.max(otherSize.width / 2, otherSize.depth / 2) +
			this.formationSeparation;

		if (minDist < dist)
			continue;

		// merge the members from the twin formation into this one
		// twin formations should always have exactly the same orders
		this.AddMembers(cmpOtherFormation.members);
		Engine.DestroyEntity(this.twinFormations[i]);
		this.twinFormations.splice(i,1);
	}
	// Switch between column and box if necessary
	var cmpUnitAI = Engine.QueryInterface(this.entity, IID_UnitAI);
	var walkingDistance = cmpUnitAI.ComputeWalkingDistance();
	var columnar = walkingDistance > g_ColumnDistanceThreshold;
	if (columnar != this.columnar)
	{
		this.offsets = undefined;
		this.columnar = columnar;
		this.MoveMembersIntoFormation(false, true);
		// (disable moveCenter so we can't get stuck in a loop of switching
		// shape causing center to change causing shape to switch back)
	}
};

Formation.prototype.OnGlobalOwnershipChanged = function(msg)
{
	// When an entity is captured or destroyed, it should no longer be
	// controlled by this formation

	if (this.members.indexOf(msg.entity) != -1)
		this.RemoveMembers([msg.entity]);
};

Formation.prototype.OnGlobalEntityRenamed = function(msg)
{
	if (this.members.indexOf(msg.entity) != -1)
	{
		this.offsets = undefined;
		var cmpNewUnitAI = Engine.QueryInterface(msg.newentity, IID_UnitAI);
		if (cmpNewUnitAI)
			this.members[this.members.indexOf(msg.entity)] = msg.newentity;

		var cmpOldUnitAI = Engine.QueryInterface(msg.entity, IID_UnitAI);
		cmpOldUnitAI.SetFormationController(INVALID_ENTITY);

		if (cmpNewUnitAI)
			cmpNewUnitAI.SetFormationController(this.entity);

		// Because the renamed entity might have different characteristics,
		// (e.g. packed vs. unpacked siege), we need to recompute motion parameters
		this.ComputeMotionParameters();
	}
}

Formation.prototype.RegisterTwinFormation = function(entity)
{
	var cmpFormation = Engine.QueryInterface(entity, IID_Formation);
	if (!cmpFormation)
		return;
	this.twinFormations.push(entity);
	cmpFormation.twinFormations.push(this.entity);
};

Formation.prototype.DeleteTwinFormations = function()
{
	for each (var ent in this.twinFormations)
	{
		var cmpFormation = Engine.QueryInterface(ent, IID_Formation);
		if (cmpFormation)
			cmpFormation.twinFormations.splice(cmpFormation.twinFormations.indexOf(this.entity), 1);
	}
	this.twinFormations = [];
};

Formation.prototype.LoadFormation = function(formationName)
{
	if (formationName == this.formationName)
	{
		var cmpUnitAI = Engine.QueryInterface(this.entity, IID_UnitAI);
		cmpUnitAI.MoveIntoFormation();
		return;
	}
	var members = this.members;
	this.Disband();
	var newFormation = Engine.AddEntity("formations/"+formationName.replace(/\s+/g, "_").toLowerCase());

	var cmpFormation = Engine.QueryInterface(newFormation, IID_Formation);
	cmpFormation.SetMembers(members);

	var cmpThisUnitAI = Engine.QueryInterface(this.entity, IID_UnitAI);
	var cmpNewUnitAI = Engine.QueryInterface(newFormation, IID_UnitAI);
	var orders = cmpThisUnitAI.GetOrders();
	if (orders.length)
		cmpNewUnitAI.AddOrders(orders);
	else
		cmpNewUnitAI.MoveIntoFormation();

};

Engine.RegisterComponentType(IID_Formation, "Formation", Formation);