1 package cz.cuni.amis.pogamut.ut2004.agent.navigation;
2
3 import java.util.List;
4
5 import cz.cuni.amis.pogamut.base.agent.navigation.IPathExecutor;
6 import cz.cuni.amis.pogamut.base.agent.navigation.IPathExecutorHelper;
7 import cz.cuni.amis.pogamut.base3d.worldview.object.ILocated;
8 import cz.cuni.amis.pogamut.ut2004.bot.impl.UT2004Bot;
9 import cz.cuni.amis.pogamut.ut2004.communication.messages.gbinfomessages.NavPointNeighbourLink;
10 import cz.cuni.amis.pogamut.ut2004.communication.messages.gbinfomessages.Self;
11
12 /**
13 * Navigator purpose is to actually move the bot through the UT2004 environment - if you did not read {@link IPathExecutor}
14 * and {@link UT2004PathExecutor} documentation, do it now. If you did, read on.
15 * <p><p>
16 * The {@link IUT2004PathNavigator} navigator is the easiest-to-implement piece of {@link UT2004PathExecutor} in
17 * terms that it has only two methods to implement. On the other hand - it is acrually very hard to navigate the bot
18 * through UT2004 environment. But! If you need to actually change the way how bot is running inside the UT2004,
19 * implementing own {@link IUT2004PathNavigator} is the best thing to do (you should probably start
20 * by copy-pasting the code from {@link UT2004PathExecutorNavigator} into your new class and experiment with it a bit).
21 * <p><p>
22 * This navigator interface is actually used by {@link UT2004PathExecutor} that covers the tricky part when and how
23 * to call its methods {@link IUT2004PathNavigator#navigate()} and {@link IUT2004PathNavigator#reset()}.
24 *
25 * @author Jimmy
26 *
27 * @param <PATH_ELEMENT>
28 */
29 public interface IUT2004PathNavigator<PATH_ELEMENT extends ILocated> {
30
31 /**
32 * Sets the {@link UT2004Bot} instance that the navigator should navigate. Use its {@link UT2004Bot#getAct()}
33 * to pass commands to the bot.
34 *
35 * @param bot
36 */
37 public void setBot(UT2004Bot bot);
38
39 /**
40 * Sets the {@link IPathExecutorHelper} who is using the navigator, i.e., are calling its
41 * {@link IUT2004PathNavigator#navigate(Self)} and {@link IUT2004PathNavigator#reset()}
42 * methods.
43 * <p><p>
44 * Used by {@link IPathExecutorHelper} implementation to inject its instance into the navigator,
45 * so the navigator may call methods such as {@link IPathExecutorHelper#checkStuckDetectors()},
46 * {@link IPathExecutorHelper#switchToAnotherPathElement(int)}, {@link IPathExecutorHelper#stuck()}
47 * and {@link IPathExecutorHelper#targetReached()}.
48 *
49 * @param owner
50 */
51 public void setExecutor(IUT2004PathExecutorHelper<PATH_ELEMENT> owner);
52
53 /**
54 * This method is regularly called by {@link UT2004PathExecutor} to continue the navigation of the bot
55 * inside the UT2004.
56 *
57 * @param focus where the bot should have its focus
58 */
59 public void navigate(ILocated focus);
60
61 /**
62 * Returns current link the bot is following (if such link exist... may return null).
63 * @return
64 */
65 public NavPointNeighbourLink getCurrentLink();
66
67 /**
68 * {@link UT2004PathExecutor} reports that execution of current path has been terminated - clean up your internal data
69 * structure and prepare to navigate the bot along the new path in the future.
70 */
71 public void reset();
72
73 /**
74 * {@link UT2004PathExecutor} reports that new path has been received and the {@link IUT2004PathNavigator#navigate()}
75 * is about to be called in near future. The new path is passed as a parameter.
76 *
77 * @param path
78 */
79 public void newPath(List<PATH_ELEMENT> path);
80
81
82 }