1 package cz.cuni.amis.pogamut.ut2004.agent.navigation;
2
3 import java.util.List;
4 import java.util.logging.Logger;
5
6 import cz.cuni.amis.pogamut.base.agent.navigation.IPathFuture;
7 import cz.cuni.amis.pogamut.base3d.worldview.object.ILocated;
8 import cz.cuni.amis.pogamut.ut2004.agent.navigation.floydwarshall.FloydWarshallMap;
9 import cz.cuni.amis.pogamut.ut2004.communication.messages.gbinfomessages.Item;
10 import cz.cuni.amis.pogamut.ut2004.communication.messages.gbinfomessages.NavPoint;
11 import cz.cuni.amis.pogamut.ut2004.communication.messages.gbinfomessages.Player;
12 import cz.cuni.amis.utils.flag.Flag;
13 import cz.cuni.amis.utils.flag.FlagListener;
14
15 /**
16 * Facade for navigation in UT2004. Method navigate() can be called both synchronously and asynchronously.
17 *
18 * Uses {@link IUT2004PathExecutor}, {@link FloydWarshallMap}, {@link IUT2004RunStraight} and {@link IUT2004GetBackToNavGraph}
19 * to handle all possible navigation cases.
20 *
21 * @author Jimmy
22 */
23 public interface IUT2004Navigation {
24
25 /**
26 * Use this to register listeners to various states the navigation - stuck, target reached, etc.
27 * See {@link NavigationState}.
28 *
29 * @param listener
30 */
31 public void addStrongNavigationListener(FlagListener<NavigationState> listener);
32
33 /**
34 * Removes path state listener.
35 * @param listener
36 */
37 public void removeStrongNavigationListener(FlagListener<NavigationState> listener);
38
39 /**
40 * Returns underlying {@link IUT2004PathExecutor} object that is being used by this {@link IUT2004Navigation}.
41 * @return
42 */
43 public IUT2004PathExecutor<ILocated> getPathExecutor();
44
45 /**
46 * Returns underlying {@link IUT2004GetBackToNavGraph} object that is being used by this {@link IUT2004Navigation}.
47 * @return
48 */
49 public IUT2004GetBackToNavGraph getBackToNavGraph();
50
51 /**
52 * Returns underlying {@link IUT2004RunStraight} object that is being used by this {@link IUT2004Navigation}.
53 * @return
54 */
55 public IUT2004RunStraight getRunStraight();
56
57 /**
58 * True if navigating, e.g., trying to get somewhere using either {@link IUT2004PathExecutor}, {@link IUT2004GetBackToNavGraph} or {@link IUT2004RunStraight}.
59 * @return
60 */
61 public boolean isNavigating();
62
63 /**
64 * Whether we're currently navigating to navpoint (final target).
65 * @return
66 */
67 public boolean isNavigatingToNavPoint();
68
69 /**
70 * Whether we're currently navigating to item (final target).
71 * @return
72 */
73 public boolean isNavigatingToItem();
74
75 /**
76 * Whether we're currently navigating to player (final target).
77 * @return
78 */
79 public boolean isNavigatingToPlayer();
80
81 /**
82 * Whether {@link UT2004Navigation} is currently trying to get back to nav using {@link IUT2004GetBackToNavGraph}.
83 * @return
84 */
85 public boolean isTryingToGetBackToNav();
86
87 /**
88 * Whether {@link UT2004Navigation} is currently using {@link IUT2004PathExecutor} to follow the path.
89 * @return
90 */
91 public boolean isPathExecuting();
92
93 /**
94 * Whether {@link UT2004Navigation} is currently using {@link UT2004Navigation#runStraight} to get to player by running straight to it/him/her.
95 * @return
96 */
97 public boolean isRunningStraight();
98
99 /**
100 * Returns current focus of the bots, may be null (== no focus).
101 * @param located
102 */
103 public ILocated getFocus();
104
105 /**
106 * Sets focus of the bot when navigating (when using this object to run to some location target)!
107 * To reset focus call this method with null parameter.
108 * @param located
109 */
110 public void setFocus(ILocated located);
111
112 /**
113 * Stops navigation and resets the class.
114 *
115 * Does NOT reset focus!
116 */
117 public void stopNavigation();
118
119 /**
120 * This method can be called periodically or asynchronously. Will move bot to 'target'.
121 *
122 * The bot will stop on bad input (location == null).
123 *
124 * @param target target location
125 */
126 public void navigate(ILocated target);
127
128 /**
129 * This method can be called periodically or asynchronously. Will move bot to input location.
130 * Uses UT2004PathExecutor and FloydWarshallMap.
131 * The bot will stop on bad input (location null).
132 * @param location target location
133 */
134 public void navigate(Player player);
135
136 /**
137 * Let the bot to follow this path.
138 * @param pathHandle
139 */
140 public void navigate(IPathFuture<ILocated> pathHandle);
141
142 /**
143 * When the bot is about to reach its target, it will prolong his path to continue to 'target'.
144 *
145 * DOES NOT WORK WITH {@link IUT2004Navigation#navigate(Player)}.
146 *
147 * WARNING: continueTo is reset when bot stop navigating / stuck, etc.
148 *
149 * WARNING: continueTo is also "nullified" when the bot actually prolongs its path to reach the 'target'.
150 *
151 * @param target cannot be {@link Player}
152 */
153 public void setContinueTo(ILocated target);
154
155 /**
156 * Returns where the bot will continue to, for more info see {@link #setContinueTo(ILocated)}.
157 *
158 * WARNING: continueTo is reset when bot stop navigating / stuck, etc.
159 *
160 * WARNING: continueTo is also "nullified" when the bot actually prolongs its path to reach the 'target'.
161 *
162 * @return
163 */
164 public ILocated getContinueTo();
165
166 /**
167 * Returns nearest navigation point to input location. FloydWarshallMap works only on NavPoints.
168 * @param location
169 * @return
170 */
171 public NavPoint getNearestNavPoint(ILocated location);
172
173 /**
174 * Returns COPY of current path in list. May take some time to fill up. Returns
175 * empty list if path not computed.
176 * @return
177 */
178 public List<ILocated> getCurrentPathCopy();
179
180 /**
181 * Returns current path as in IPathFuture object that is used by ut2004pathExecutor
182 * to navigate. Can be altered. May return null if path not computed!
183 * Be carefull when altering this during UT2004PathExecutor run - it may cause
184 * undesirable behavior.
185 * @return
186 */
187 public List<ILocated> getCurrentPathDirect();
188
189 /**
190 * Current POINT where the navigation is trying to get to.
191 * @return
192 */
193 public ILocated getCurrentTarget();
194
195 /**
196 * If navigation is trying to get to some player, otherwise returns null.
197 * @return
198 */
199 public Player getCurrentTargetPlayer();
200
201 /**
202 * If navigation is trying to get to some item, otherwise returns null.
203 * @return
204 */
205 public Item getCurrentTargetItem();
206
207 /**
208 * If navigation is trying to get to some navpoint, otherwise returns null.
209 * @return
210 */
211 public NavPoint getCurrentTargetNavPoint();
212
213 /**
214 * Returns previous location we tried to get to (i.e., what was {@link UT2004Navigation#getCurrentTarget()} before
215 * another {@link UT2004Navigation#navigate(ILocated)} or {@link UT2004Navigation#navigate(Player)} was called.
216 * @return
217 */
218 public ILocated getLastTarget();
219
220 /**
221 * If previous target was a player, returns non-null player we previously tried to get to
222 * (i.e., what was {@link UT2004Navigation#getCurrentTargetPlayer()} before
223 * another {@link UT2004Navigation#navigate(ILocated)} or {@link UT2004Navigation#navigate(Player)} was called.
224 * @return
225 */
226 public Player getLastTargetPlayer();
227
228 /**
229 * If previous target was an item, returns non-null {@link Item} we previously tried to get to.
230 * (i.e., what was {@link UT2004Navigation#getCurrentTargetItem()} before
231 * another {@link UT2004Navigation#navigate(ILocated)} or {@link UT2004Navigation#navigate(Player)} was called.
232 * @return
233 */
234 public Item getLastTargetItem();
235
236 /**
237 * Returns an immutable flag with the current state of the navigation.
238 *
239 * @return an immutable flag with the current state of the navigation.
240 */
241 public Flag<NavigationState> getState();
242
243 /**
244 * Returns how far is our target (path-distance == real-distance).
245 *
246 * May return -1 if it cannot be computed.
247 *
248 * @return
249 */
250 public double getRemainingDistance();
251
252 /**
253 * Returns logger used by the object.
254 * @return
255 */
256 public Logger getLog();
257
258 }