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