======================================================================
New in 1999
======================================================================

Keep all angles in terms of relative to my body.....so the turns 
are the same.  Visual info should just be converted based on my
neck_angle.



======================================================================
From 1988
======================================================================

------------------------
Overall flow of control:
------------------------
all in client.C

When the timer expires (every SP_simulator_step/CP_senses_per_cycle)
	-- block IO
	-- when time changes, update all object states to match 
		the current server time as well as possible, act
	-- if time is the same (or no action), communicate,
		change_view, or sense_body
	-- (don't communicate more than once every n cycles)
	-- unblock IO

When a sensation comes:
	-- block timer
	-- parse it
	-- store the information in temporary variables for later
		update (see above)
	-- unblock timer
	-- choose communcations in response and/or to coach


------------------------
Timing
------------------------
Time is represented as two integers:  
	t = server time 
	s = # cycles the clock's been stopped (incremented as the
					       action timer goes off)
addition and subtraction are defined to take into account the stopped
cycles.  But only the last time the clock restarted is stored.  So
you can't subtract arbitrarily far back or add beyond the current
time.

LastStartClockTime is set to be the time of the final action
opportunity before the mode changed away from PM_Before_Kick_Off.

One glitch is the transition from server time to stopped-clock time.
Some sights may have already occurred at the subsequent stopped-clock
time.  For this reason, sanitize_times must be called on all the time
variables that could have been updated since the last action
opportunity: 
	CurrentTime, 
	LastSightTime, 
	LastSoundTime, 
	sense_time,
	and all the times of temporary sight and sound info variables.
Sanitize_time just transfers the excess s to t.


------------------------
Sending actions: 
------------------------
One structure each for turn/dash/kick, communicate, change_view
	-- Running action loop (behave) possibly identifies a single
	   turn/dash/kick.  This command gets priority.
	-- If no action, check memory to see if there's something to say
	-- If no communication, execute a pending change_view
	-- Otherwise, just sense_body


-------------------------
At startup: 
-------------------------
MemOption has all the server, client, and initialize parameters.
They can be loaded from a file with the -file flag or from the 
command line with various flags as indicated in MemOption.C.
To add a new option, just need to add it in MemOption.h and in
2 places in MemOption.C (one to set the default, one to set the flag).
It should be possible to load from more than one file.

SP_ is a server parameter
CP_ is a client parameter
FP_ is a formation parameter


-------------------------
Object Knowledge representation 
-------------------------
              Object    	 
	    /   \
	----     ----
       /	     \
StationaryObject MobileObject
		   /   	  \
		  /   	   \
		 /  	    \
	     BallObject   PlayerObject
			     
Object -- global position stored with confidence
StationaryObject -- nothing added
MobileObject -- add global velocity info
BallObject -- nothing added (except if the ball's kickable)
PlayerObject -- add global facing info

When seen or heard (from teammate), relative or global info about the
object status is stored with confidences and time stamps in temporary
variables.

When updated, precedence is given to seen information (sets
confidence to 1) unless a teammate saw the object from closer.

If no new information arrived, the velocity and actions taken (kick)
are used to update the position of the objcet.  Then confidence is
decayed.

In PositionInfo, all lines and markers are stored as
StationaryObjects.  There is one ball, and several players allocated
as well.  Pointers to seen markers, and players on each team are
maintained.

Players are stored in a big array of size 21 (11*2-1).
Arrays of pointers into this array representing my players, their
players, and teamless players are stored.  Free players are players
in the top array that aren't in any of the others.  
Players that are seen without numbers and/or side are stored as
unknown players until their positions can be determined based on my
position when they were seen.  Then they are reconciled with closest
appropriate players.
	
Determine the x,y positions, headings, speeds of all players, ball.
When relative info needed, convert 



-------------------------
Updating Memory
-------------------------
PositionInfo updates the global info once a cycle (right before
action).  The goal is to match the server's state at the current time
as closely as possible.  If there's a sight, it came from the server
either at the current time or one cycle ago.

1. Update my position 
	-- if there's a new sight, bring my position up to date for
		that time (either now or one cycle ago).
	-- from the sight, use the line and closest object to localize
	-- use the sensed speed from that time to determine velocity.
		Assume velocity is in the direction I'm facing
	-- if there's no sight, bring velocity up to date, possibly
		using known dashes, then update position, decay
		velocity
2. Update the ball 
	-- if there's a new sight, use my position and the ball's
		relative position info to set its position.  Also
		update its velocity if moving.  Otherwise check if 
		the new position is where it would have been estimated
		to see if velocity is correct.	
	-- if it should be in sight, but isn't, set confidence to 0
	-- update its position by estimating, including possible kick
		information.  Perhaps only the velocity needs to be 
		estimated.
	-- if it should be in sight, but isn't, set confidence to 0
	-- see if any heard information would increase the confidence
		in the ball's position or velocity at this time.  If
		so, go for it, estimating the position up to the
		current time.	
3. Update the players
	-- First see if any of the teamless players seen match up with
		previously known players
	-- do the same update as for the ball, except adding in
		information about which way each player is facing
	-- If any players are no longer valid, free up the pointers
		appropriately
4. Update my position to the current time
	-- at this point it might only be known to the previous time
		step so that the relative ball and player positions
		would be correct.  If so, estimate the final step.
5. Update my stamina based on dashes taken, effort decays, and sensed
		info

-------------------------
Parsing 
-------------------------
Find the closest flag and visible line for angle knowledge.
No longer worrying about motion from markers -- using sense_body.
Store relative positions of objects, sense_body info, or heard info
with time stamps to be used later when positions are updated.


-------------------------
Memory structure 
-------------------------
		OptionInfo

		PlayerInfo

		PositionInfo

		FormationInfo (formations)
	  ______/   | 	\____________     
	 /          |         \      \
       /            |	        \     \
     /              |	          \    \
AdversarialInfo   RLInfo        DTInfo
     \              |             /    /
       \            |           /     /
         \________  |  _______/______/
                  \ | /	      
                    | 
		SetplayInfo
		
                ActionInfo

                 PatInfo

             CommunicateInfo

                 Memory	      
			      
OptionInfo to get options     
PlayerInfo action queues, time, stamina, game status (score, mode), etc.
PositionInfo with all other object positions
TeamPositionInfo  with formations (need position info, or just player info???)
RewardInfo RL stuff
AdversarialInfo keep track of opponents, stats, etc.
ActionInfo keep track of action variables
PatInfo for temporary stuff
Memory  with all else


-------------------------
Communication
-------------------------

Messages include the following fields in order:

HEAD:
-- team side (l/r)
-- player number

STATE:
-- key encoding the time the message was sent (.t)
-- formation number
-- time formation was set (.t)
-- x,y position
-- ball confidence 
	(if > 0 ballx,bally)
-- ball velocity confidence
	(if > 0 ball dx,ball dy)
-- for each teammate in order:
	how long ago position was set (-1 means never changed)
	teammate position
	Teammate Position Confidence
		(if > 0 teammate x,y)
-- for each opponent in order:
	Opponent Position Confidence
		(if > 0 opponet x,y)

BODY:
-- target type
-- target
-- message type
-- data 1
-- data 2

Target types are 
	TT_Player (only target player listens to body)
	TT_Position (only player in target position listens to body)
	TT_Unit (only target unit members listen to body)
	TT_All
Everyone parses the state and updates the values

Messages (says and responses) are stored in a MessageList of
MessageStructs.
	MessageStruct keeps track of the target, message, data

Communicate when there's a message in the list and the time and delay
	indicate that it's time to send it.  
If it's a response, need to fill in the message type and data.

To add a new message:   add the type in types.h
			say how to react to it in ParseMessageBody
				(reason about delaying and staggering responses)
			say how to respond to it (if necessary) in FillMessageBody

Players say SOMETHING periodically to keep each other up to date
	

-------------------------
Action modes 
-------------------------
  AM_Unknown,
  AM_Localize,
  AM_Face_Ball,
  AM_Before_Kick_Off,
  AM_Setplay,

  AM_With_Ball,                dribble/pass/shoot
  AM_Offense_Active,           go to the ball
  AM_Offense_Auxiliary,        get open for a pass
  AM_Offense_Passive,          move to a strategic offensive position (ball behind)
                               choose form, pos., go to position

  AM_Defense_Active,           try to steal the ball
  AM_Defense_Auxiliary,        mark a player
  AM_Defense_Passive,          track a player

Within each mode, different behaviors per position types


-------------------------
Utils
-------------------------
Use vectors from server, all the old stuff
time, debugging
need some geometry:  line between 2 points, distance to that
				line (is there someone between the
				ball and my target location?) Vectors


-------------------------
Set Plays
-------------------------
Initialize on the fly or when needed?
Need communication, action to make it work








[ /OLD ]

------------------- 
Levels of Behavior 
------------------- 
There is a notion of levels of behavior, where each level is built upon the 
actions of the level below it. There are currently three levels of behavior 
in our client.  
Level 0 corresponds to the actual commands. It is only a subset of 
the actual possible commands and is there mostly for resons 
of consistency. 
Level 1 contains such behaviors as go_to_point, turnball, and hardkick. 
Level 2 contains such behaviors as intercept ball, pass, and go to position. 
 
The enumerated types and structures are defined in Memaction.h. 
Each level has an an enumerated type with an entry for each behavior at that 
level. The naming is BL?_<behavior> where ? is the level. 
Each level also has an assocaited structure which contains an entry for the  
type and all possible parameters that each behavior type may need 
(for example, BL1_GoToPoint takes a Vector to the position to go to) 
 
All functions described are part of ActionInfo. 
The functions BehaveLevel2To1 and BehaveLevel1To0 translate the higher level 
action into a lower level one and return that. By storing the returned command 
structure, you can avoid having to repeat any computation. 
 
The function GenerateAction takes a command structure of any level and uses 
the above functions to actually put an action into the Memory structure. 
If there is a failure of some sort, it returns 0. 
 
If you want to get a certain behavior, all you have to do is take a command 
structure of the appropriate type, fill it out, and call GenerateAction. 
