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 * Sets focus of the bot when navigating (when using this object to run to some location target)!
101 * To reset focus call this method with null parameter.
102 * @param located
103 */
104 public void setFocus(ILocated located);
105
106 /**
107 * Stops navigation and resets the class.
108 *
109 * Does NOT reset focus!
110 */
111 public void stopNavigation();
112
113 /**
114 * This method can be called periodically or asynchronously. Will move bot to 'target'.
115 *
116 * The bot will stop on bad input (location == null).
117 *
118 * @param target target location
119 */
120 public void navigate(ILocated target);
121
122 /**
123 * This method can be called periodically or asynchronously. Will move bot to input location.
124 * Uses UT2004PathExecutor and FloydWarshallMap.
125 * The bot will stop on bad input (location null).
126 * @param location target location
127 */
128 public void navigate(Player player);
129
130 /**
131 * Let the bot to follow this path.
132 * @param pathHandle
133 */
134 public void navigate(IPathFuture<ILocated> pathHandle);
135
136 /**
137 * When the bot is about to reach its target, it will prolong his path to continue to 'target'.
138 *
139 * DOES NOT WORK WITH {@link IUT2004Navigation#navigate(Player)}.
140 *
141 * WARNING: continueTo is reset when bot stop navigating / stuck, etc.
142 *
143 * WARNING: continueTo is also "nullified" when the bot actually prolongs its path to reach the 'target'.
144 *
145 * @param target cannot be {@link Player}
146 */
147 public void setContinueTo(ILocated target);
148
149 /**
150 * Returns where the bot will continue to, for more info see {@link #setContinueTo(ILocated)}.
151 *
152 * WARNING: continueTo is reset when bot stop navigating / stuck, etc.
153 *
154 * WARNING: continueTo is also "nullified" when the bot actually prolongs its path to reach the 'target'.
155 *
156 * @return
157 */
158 public ILocated getContinueTo();
159
160 /**
161 * Returns nearest navigation point to input location. FloydWarshallMap works only on NavPoints.
162 * @param location
163 * @return
164 */
165 public NavPoint getNearestNavPoint(ILocated location);
166
167 /**
168 * Returns COPY of current path in list. May take some time to fill up. Returns
169 * empty list if path not computed.
170 * @return
171 */
172 public List<ILocated> getCurrentPathCopy();
173
174 /**
175 * Returns current path as in IPathFuture object that is used by ut2004pathExecutor
176 * to navigate. Can be altered. May return null if path not computed!
177 * Be carefull when altering this during UT2004PathExecutor run - it may cause
178 * undesirable behavior.
179 * @return
180 */
181 public List<ILocated> getCurrentPathDirect();
182
183 /**
184 * Current POINT where the navigation is trying to get to.
185 * @return
186 */
187 public ILocated getCurrentTarget();
188
189 /**
190 * If navigation is trying to get to some player, otherwise returns null.
191 * @return
192 */
193 public Player getCurrentTargetPlayer();
194
195 /**
196 * If navigation is trying to get to some item, otherwise returns null.
197 * @return
198 */
199 public Item getCurrentTargetItem();
200
201 /**
202 * If navigation is trying to get to some navpoint, otherwise returns null.
203 * @return
204 */
205 public NavPoint getCurrentTargetNavPoint();
206
207 /**
208 * Returns previous location we tried to get to (i.e., what was {@link UT2004Navigation#getCurrentTarget()} before
209 * another {@link UT2004Navigation#navigate(ILocated)} or {@link UT2004Navigation#navigate(Player)} was called.
210 * @return
211 */
212 public ILocated getLastTarget();
213
214 /**
215 * If previous target was a player, returns non-null player we previously tried to get to
216 * (i.e., what was {@link UT2004Navigation#getCurrentTargetPlayer()} before
217 * another {@link UT2004Navigation#navigate(ILocated)} or {@link UT2004Navigation#navigate(Player)} was called.
218 * @return
219 */
220 public Player getLastTargetPlayer();
221
222 /**
223 * If previous target was an item, returns non-null {@link Item} we previously tried to get to.
224 * (i.e., what was {@link UT2004Navigation#getCurrentTargetItem()} before
225 * another {@link UT2004Navigation#navigate(ILocated)} or {@link UT2004Navigation#navigate(Player)} was called.
226 * @return
227 */
228 public Item getLastTargetItem();
229
230 /**
231 * Returns an immutable flag with the current state of the navigation.
232 *
233 * @return an immutable flag with the current state of the navigation.
234 */
235 public Flag<NavigationState> getState();
236
237 /**
238 * Returns how far is our target (path-distance == real-distance).
239 *
240 * May return -1 if it cannot be computed.
241 *
242 * @return
243 */
244 public double getRemainingDistance();
245
246 /**
247 * Returns logger used by the object.
248 * @return
249 */
250 public Logger getLog();
251
252 }