-----------------------------------
    SSP - RELEASE VERSION 1.01 
  Segmented String Pathing System
-----------------------------------

Users Guide:

This guide assumes you have read Readme.txt and Install.txt, and that you have successfully created a virtual road using waypoints 1 to 5.  Make sure you can actually order your unit to go to the waypoints you have before you continue on.  

Important Information:  Before we delve into creating some complex roads, I should explain how the algorithm works so you understand how you should create the roads.  Dont worry about doing anything with the WE until part 2. 

Chapter 1) How roads are created and traveled.
----------------------------------------------

It begins by you defining an End Segment.  Any kind of segment, be it End or Mid, can be up to 25 waypoints in length.  You can have up to 100 waypoints total.  Since the algorithm can piece up to 3 segments together, a unit can therefore traverse up to a total of 75 Waypoints in a single order.

End Segments:  These are most likely going to be more numberous in your map.  End segments contain termination points where a particular part of a road ends.  The waypoint that the segment terminates, MUST be the first one you program into the STR_EndSEgments string.  The reason for this is that when a unit on an end segment tries to locate a route to other end segments or something on a mid segment, the algorithm ignores everything except the LAST value you enter.  In the follow example, the END of the road (when looking at the actual regions in the WE) would be Waypoint 1.  By END I mean the point where that part of a road actually comes to a stop, like at a guy's house or a church's door.

	Example 1:  STR_EndSegments[50] = 0102030405

This end segment tells the game there is a logical link going from waypoints 1 to 2 to 3 to 4 to 5.  It also implies to the game that waypoint 1 is where it terminates (think of a door or the edge of the map) and that waypoint 5 is where it CONNECTS to another segment.  I call the connection point of End SEgments, NODES.  EndSegments CAN connect directly to each other, but ONLY at the last waypoint, ie, the NODE.  

	Example 2:  STR_EndSegments[51] = 06070805

This example created another EndSegment #51.  Notice it tells the game that EndSegment 51 creates a logical link going from waypoint 6 to 7 to 8 to 5.  In this case, a unit that was sitting on any one of the waypoints in EndSegments 50 would be able to find any other waypoint in EndSegment[51] because they share a common NODE point, 5.

TO lead into Mid Segments, i'm first going to create another End Segment that doesn't share a common NODE with the first two.  This creates a problem that is solved by Mid Segments.

	Example 3: STR_EndSegments[52] = 091011121314

Example 3 creates a logical link called EndSegment #52 that connects 9 to 10 to 11 to 12 to 13 to 14.  The problem right now is that there is no way that a unit on Segment 52 to path to the first two example segments.  THis is where a MidSegment comes in.

Mid Segments:  These act as links between other end segments.  An SSA Pathing order can contain up to 3 strings consisting of 2 EndSEgments and one midsegment.  We'll create a MidSegment now.

	Example 4: STR_MidSegments[1] = 052014

This creates a middle segment that tells the game a logical link exists between waypoints 5 to 20 to 14.  The importance of a middle segment is that it acts as a link that connects the NODE points of end segments together.  Notice that the first 3 example segments share one of the Waypoints in the Mid Segment.  This middle segments tells the game that it can order a unit  starting on 52, to use MidSegment(1) to connect to either EndSegments(50) or (51).

Now using these 4 examples, we'll trace a unit going from Waypoint 1 to Waypoint 9.  Notice that Waypoint 1 rests on EndSegment 50 and Waypoint 9 rests on EndSegment 52.  The unit would start at Waypoint 1, and traverse to the NODE point of segment 50, which is Waypoint 5.  At this point, the algorithm would find a mid segment that is common to both Segments 50 and 52.  The MidSegment(1) we created contains both of the NODE points from Segments 50 and 52.  Thus, the unit would traverse MidSEgments(1) going from Waypoints 5 to 14.  Once at 14, the algorithm would tell it to traverse to waypoint 9 by using EndSegments(52) and the order would be considered fulfilled.

Q/A:  You are probably wondering why a system wasn't just devised to allow the creation of a single type of segment that the game can use to piece data together.  The short answer is that I put a lot of thought into this, and while it is far from a perfect routing system, it is very efficient in comparison to some more robust things that can be done.  I didn't need a full blown DNS server type system and this accomplishes the goal just fine.



-----------------------------------------------------
Chapter 2) Using this logic to create your own roads.  
-----------------------------------------------------

First off, i'm going to assume you have one EndSegment defined as "STR_EndSegments(50) = "0102030405"

A) To learn how to make your own roads, I would create another 5  Waypoints (6 to 10) and place them in sequence, somewhere far away from your first road you made.  Program this road in so that waypoint 6 is the NODE, so it would look something like this:  

	STR_EndSegments(51) = "1009080706".

B) Then, create another set of Waypoints, lets say 3 waypoints, 11 to 13 and put them inbetween waypoints 5 and waypoints 6.  These will connect the two end segments together and allow any unit on any waypoint to travel to any other waypoint.
C) To create the MidSegment, just piece them together in any order.  With midsegments the game doesn't care what order they're in, so it would look something like this:

	STR_MidSegments(1) = "111213"

D) Test the map, you're unit should be able to be ordered to any waypoint.



--------------------------------------------------------------
Chapter 3:  How can you actually impliment this into your map.
--------------------------------------------------------------

Well if you've gotten this far, you probably don't need me to explain much of the principles of variables to you.  The way you order a unit is to add them to the SSA_CreateSSAOrder unit group.  This unit group is handled by the queue controller and it will take the unit you added and then configure the assembly trigger with where you want the unit to go.

A) How to set the destination

For a unit to be capable of recieving an SSP order, it must have a custom value of between 5 and 400.  By default, SSP will take all unit's on the map that are level 1 or higher and give them a unique custom value.  You do not have to do anything, except make sure the unit's you want to order around are at least level 1.  Of course, you can add your own conditions to what unit's recieve the benefit.

Why do I mention custom values?  Because they are used as the index of the SSA_DestinationINT() variable.  

	EXAMPLE  :  If you wanted to order a unit whose custom value was 253 to Waypoint #10, you would set it's destination and then add him to the SSA_CreateSSAOrder unit group and the game will do the rest. It would look something like this:

	Set SSA_DestinationINT(253) = 10
	Add (unit) to SSA_CreateSSAOrder

To re-iterate: the trick is to set the Destination variable (using the unit's custom value as the index of the array) to the waypoint you want the unit to travel to.  Then you add the unit to the CreateSSAOrder unit group and the game does the rest.  Voila.

Chapter 4:  Limitations

With version 1.01, if you constantly spawn unit's that need to use this system, you will need to write your own trigger that re-allocates custom values to unit's entering the game or wait till 1.02 is ready.

NOTES:

Version 1.02 will have a trigger that controls the allocation of custom values.  Unit's leaving the game will automatically make their custom value available for use and unit's entering the game will get a custom value assigned.  IN the meantime, if you need to add unit's to your map, the INT_Custom variable starts at 5 and counts upward.   Never reset this, because you can use this to give units you add to the maps a unique custom value.

