documentation.txt

RoboCup 2D 仿真组老牌强队Mersad 2005的完整源代码

                In the name of GOD

Authored by:    Darioush Jalali <[e-mail]>

Hello.


Introduction
------------

The HPS is a hierarchical planning system which allows a programmer to imply
many different techniques of AI progrmming together in separate layers.
It is useful for both dynamic and scenario based codes. The HPS is a
very high level decision code; it is one level higher than advanced actions.


Library
-------

The class Library is useful for
items that only have to be calculated ONCE per cycle (????). The
entire HPS should finish quickly. The entire HPS system may be even
recalled in 1 cycle, although the library is only updated once. All
lengthy and static processing should be moved to this section.


Form
----

The agent has default behaviors for some fundamental issues,
especially neck decision and say desision. Such a plan will require to
change one of these behaviors, it should `fill out' the form sent to
it. The form's contents will be applied at `throw' level. Any plans
created after a form change have access to change and view the form.


WorldModel
----------

Each plan will have a const WorldModel * to base its deciding on.


SuccessRate
-----------

Each plan can have an idea about how successfully it can run. It
should return this value between 0 and 1. One of the major factors on
HPS deciding is this factor.


isFinished
----------

This function is required for each plan, and should return true in two
conditions; either the plan wants to finish, or it cannot start.


writing a new Plan class
------------------------

Each plan should somehow inherit public from Plan. The constructor
should take a const WorldModel *, a Form & and a const Library &.
It is required to override the ::decide, ::isFinished and
::successRate functions.


basicPlans
----------

These plans are like `plan' wrappers for the advanced actions which
help them obey the HPS structure such as isFinished and successRate,
and also comply to the form/library structure explained above. these
plans will normally throw a command.


Infrastructure
--------------

There are two operative modes for the agent. Either the agent enters
the RootPlan HPS, or it falls back to StatelessPlan. StatelessPlan is
ONLY runned in two conditions; either RootPlan should give an
isFinished(), or its successRate() should fall below a certain
rate. (the latter method is not applied in the current
implementation). In the current implementation, (for simplicity),
stateless plan is used durring defending.

The AdvancedAgent will catch any Commands thrown by either RootPlan or
StatelessPlan, or their sub-plans. This command is sent to
communication sections of the agent for more handling.


Plan
----

Each plan has three descision levels.
1. Urgent: this level is executed every time the plan runs,
	regardless to the existance of previous decisions in the stack.
2. Remembering stack: If a plan has already queued plans for execution
	in its stack, after checking for minimal success rate, and
	!isFinished(), it runs the top plan on the stack. otherwise, it pops
	the plan and continues until its stack is empty. in case of such an
	event, the deciding will move on to the third level.
3. Normal descision: The plan will provide a new descision this
	level. It will normally ::/.decide() another plan or throw a command
	directly. It may then also choose to add some plans to its stack.
	Normally a Plan's ::decide() function it looks something like this:

void
MyPlan::decide()
{
       // urgent code
       Plan::decide() // this line runs the default code for
                      // remembering the stack. the code is
                      // actually in Plan.cpp
       // normal code
}


Good Practices
--------------

There are some functions & structures available for dealing with
common situations.
1. tryPlan( Plan * plan, float minSR )
	This function will ->decide plan if plan->successRate() > minSR.
2. startPlan ( Plan * plan, float minSR )
	This function will .push (plan) to the plan's stack if
	plan->successRate() > minSR and then tryPlan( plan , minSR ).
3. bestPlan ( vector <Plan *> plans, bool deltePlans )
	This function will return the plan in plans with the highest SR and if
	(deletePlans), it will delete the others.
4. bestPlan ( vector <Plan *> plans, vector <float> addedSR, bool
	deletePlans)
	Like 3, except it adds the corresponding member in addedSR to each
	plans successRate() before performing comparison.
5. bestPlan(int count, bool delete, ... (place for Plan*s))
	Like 3, except it is made for programmer convenience, i.e, laziness in
	creating a vector. see example.

A simple and tidy `normal desicion code' will look like:
startPlan( bestPlan(3, true, new Plan1 (wm, form, library),
                            new Plan2 (wm, form, library),
                            new Plan3 (wm, form, library)), 0.2);


StatlessPlan
------------

This is a very basic plan that runs the best advanced action (based on the
getValues) of the valid actions available to it in each cycle.


Be careful
----------

Try to make sure that no matter which Plan path occurs in your HPS,
somewhere, a command gets throwed. Even this being said, such you
don't throw a command the default behaviour (which happens to be
nothing) runs, which is normally not what you want.


Special Thanks
--------------

Special thanks goto

- Arash Rahimi <[e-mail]> for ideas and
	leadership on the HPS creation,

- Sassan Haradji <[e-mail]> for implementation and ideas and
	some of those great utilities.

- Ahmad Boorghany <[e-mail]> for ideas and help for
	sycnhronizing and integration of HPS with other systems in the team.