Debian Codegraph @

engine/core/model/structures/instance.h

raw
1 /***************************************************************************
2 * Copyright (C) 2005-2019 by the FIFE team *
3 * http://www.fifengine.net *
4 * This file is part of FIFE. *
5 * *
6 * FIFE is free software; you can redistribute it and/or *
7 * modify it under the terms of the GNU Lesser General Public *
8 * License as published by the Free Software Foundation; either *
9 * version 2.1 of the License, or (at your option) any later version. *
10 * *
11 * This library is distributed in the hope that it will be useful, *
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
14 * Lesser General Public License for more details. *
15 * *
16 * You should have received a copy of the GNU Lesser General Public *
17 * License along with this library; if not, write to the *
18 * Free Software Foundation, Inc., *
19 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA *
20 ***************************************************************************/
21
22 #ifndef FIFE_INSTANCE_H
23 #define FIFE_INSTANCE_H
24
25 // Standard C++ library includes
26 #include <vector>
27
28 // 3rd party library includes
29
30 // FIFE includes
31 // These includes are split up in two parts, separated by one empty line
32 // First block: files included from the FIFE root src directory
33 // Second block: files included from the same folder
34 #include "util/base/fifeclass.h"
35
36 #include "model/metamodel/object.h"
37 #include "model/metamodel/ivisual.h"
38 #include "view/visual.h"
39
40 #include "location.h"
41
42
43 namespace FIFE {
44
45 class Layer;
46 class Action;
47 class Instance;
48 class ActionInfo;
49 class SayInfo;
50 class SoundSource;
51 class TimeProvider;
52 class Route;
53
54 class InstanceActionListener {
55 public:
56 virtual ~InstanceActionListener() {};
57 virtual void onInstanceActionFinished(Instance* instance, Action* action) = 0;
58 virtual void onInstanceActionCancelled(Instance* instance, Action* action) = 0;
59 virtual void onInstanceActionFrame(Instance* instance, Action* action, int32_t frame) = 0;
60 };
61
62 enum InstanceChangeType {
63 ICHANGE_NO_CHANGES = 0x0000,
64 ICHANGE_LOC = 0x0001,
65 ICHANGE_ROTATION = 0x0002,
66 ICHANGE_SPEED = 0x0004,
67 ICHANGE_ACTION = 0x0008,
68 ICHANGE_TIME_MULTIPLIER = 0x0010,
69 ICHANGE_SAYTEXT = 0x0020,
70 ICHANGE_BLOCK = 0x0040,
71 ICHANGE_CELL = 0x0080,
72 ICHANGE_TRANSPARENCY = 0x0100,
73 ICHANGE_VISIBLE = 0x0200,
74 ICHANGE_STACKPOS = 0x0400,
75 ICHANGE_VISUAL = 0x0800
76 };
77 typedef uint32_t InstanceChangeInfo;
78
79 class InstanceChangeListener {
80 public:
81 virtual ~InstanceChangeListener() {};
82 virtual void onInstanceChanged(Instance* instance, InstanceChangeInfo info) = 0;
83 };
84
85 class InstanceDeleteListener {
86 public:
87 virtual ~InstanceDeleteListener() {};
88 virtual void onInstanceDeleted(Instance* instance) =0;
89 };
90
91 /** An Instance is an "instantiation" of an Object at a Location.
92 *
93 */
94 class Instance : public FifeClass, public InstanceDeleteListener {
95 public:
96
97 /** Constructor
98 * Instances are created by calling addInstance from layer, thus
99 * this method should really be called only by layer or test code
100 */
101 Instance(Object* object, const Location& location, const std::string& identifier="");
102
103 /** Destructor
104 */
105 virtual ~Instance();
106
107 /** Get the identifier for this instance; possibly null.
108 */
109 const std::string& getId();
110
111 /** Set the identifier for this instance.
112 */
113 void setId(const std::string& identifier="");
114
115 /** Gets object where this instance is instantiated from
116 */
117 Object* getObject();
118
119 /** Sets location of the instance
120 * @param loc new location
121 */
122 void setLocation(const Location& loc);
123
124 /** Gets current location of instance
125 * @note does not return const Location&, since swig wont be const correct
126 * @return current location
127 */
128 Location getLocation() const;
129
130 /** Gets reference of current location of instance
131 * @return reference to current location
132 */
133 Location& getLocationRef();
134
135 /** Gets movement target in case instance is moving. In case not, returns current location
136 * To move target location, call move-method
137 * @see move
138 * @note does not return const Location&, since swig wont be const correct
139 * @return Movement target location
140 */
141 Location getTargetLocation() const;
142
143 /** Sets the direction where instance is heading. Useful e.g. with static
144 * instances which don't "move" or "act"
145 */
146 void setFacingLocation(const Location& loc);
147
148 /** Returns the direction where instance is heading
149 * @note does not return const Location&, since swig wont be const correct
150 * @return the direction of instance.
151 */
152 Location getFacingLocation();
153
154 /** Gets reference of old location of instance
155 * @return reference to old location
156 */
157 Location& getOldLocationRef();
158
159 /** Set the rotation offset of this instance
160 */
161 void setRotation(int32_t rotation);
162
163 /** Get the rotation offset of this instance
164 * Returns direction where instance is heading
165 */
166 int32_t getRotation() const;
167
168 /** Get the old rotation offset of this instance
169 * Returns direction where instance was heading
170 */
171 int32_t getOldRotation() const;
172
173 /** Sets if instance blocks movement
174 */
175 void setBlocking(bool blocking);
176
177 /** Gets if instance blocks movement
178 */
179 bool isBlocking() const;
180
181 /** Sets if instance blocking can overriden
182 */
183 void setOverrideBlocking(bool overblock);
184
185 /** Gets if instance blocking can overriden
186 */
187 bool isOverrideBlocking() const;
188
189 /** Auxiliary function to inform ActionListeners about the active ActionFrame.
190 * @param action pointer to the action
191 * @param frame frame index number of the animation
192 */
193 void callOnActionFrame(Action* action, int32_t frame);
194
195 /** Adds new instance action listener
196 * @param listener to add
197 */
198 void addActionListener(InstanceActionListener* listener);
199
200 /** Removes associated instance action listener
201 * @param listener to remove
202 */
203 void removeActionListener(InstanceActionListener* listener);
204
205 /** Adds new instance change listener
206 * @param listener to add
207 */
208 void addChangeListener(InstanceChangeListener* listener);
209
210 /** Removes associated instance change listener
211 * @param listener to remove
212 */
213 void removeChangeListener(InstanceChangeListener* listener);
214
215 /** Adds new instance delete listener
216 * @param listener to add
217 */
218 void addDeleteListener(InstanceDeleteListener* listener);
219
220 /** Removes associated instance delete listener
221 * @param listener to remove
222 */
223 void removeDeleteListener(InstanceDeleteListener* listener);
224
225 /** Gets the currently active action. This is owned by
226 * the instance's object, so don't delete it!
227 * @return current action, NULL in case there is none
228 */
229 Action* getCurrentAction() const;
230
231 /** Gets the speed in case instance is moving
232 * otherwise returns 0
233 * @return instance speed. Value 1 means distance 1 in layer coordinates / second
234 */
235 double getMovementSpeed() const;
236
237 /** Gets the time in milliseconds how long action has been active
238 * In case there is no current action, returns -1
239 * @return action runtime
240 */
241 uint32_t getActionRuntime();
242
243 /** Sets the time in milliseconds how long an action has been active
244 * This was requested in Ticket #373. This way the state
245 * of the action can be saved and restored at a later time
246 * @param time_offset The action time offset that should be applied
247 */
248 void setActionRuntime(uint32_t time_offset);
249
250 /** Performs given named action to the instance. While performing the action
251 * moves instance to given target with given speed
252 * @param actionName name of the action
253 * @param target place where to move this instance
254 * @param speed speed used for movement. Units = distance 1 in layer coordinates per second
255 * @param costId id for special costs which is be used as extra multiplier.
256 */
257 void move(const std::string& actionName, const Location& target, const double speed, const std::string& costId = "");
258
259 /** Performs given named action to the instance, once only. Performs no movement
260 * @param actionName name of the action
261 * @param direction coordinates for cell towards instance is heading to when performing the action
262 */
263 void actOnce(const std::string& actionName, const Location& direction);
264
265 /** Performs given named action to the instance, once only. Performs no movement
266 * @param actionName name of the action
267 * @param rotation rotation which the instance use when performing the action
268 */
269 void actOnce(const std::string& actionName, int32_t rotation);
270
271 /** Performs given named action to the instance, once only. Performs no movement and use current rotation
272 * @param actionName name of the action
273 */
274 void actOnce(const std::string& actionName);
275
276 /** Performs given named action to the instance, repeated. Performs no movement
277 * @param actionName name of the action
278 * @param direction coordinates for cell towards instance is heading to when performing the action
279 */
280 void actRepeat(const std::string& actionName, const Location& direction);
281
282 /** Performs given named action to the instance, repeated Performs no movement
283 * @param actionName name of the action
284 * @param rotation rotation which the instance use when performing the action
285 */
286 void actRepeat(const std::string& actionName, int32_t rotation);
287
288 /** Performs given named action to the instance, repeated. Performs no movement and use current rotation
289 * @param actionName name of the action
290 */
291 void actRepeat(const std::string& actionName);
292
293 /** Causes instance to "say" given text (shown on screen next to the instance)
294 * @param text text to say. If "" given, clear the text
295 * @param duration duration to show the text (in ms). If 0, shows forever
296 */
297 void say(const std::string& text, uint32_t duration=0);
298
299 /** Performs given named action to the instance. While performing the action
300 * follows given instance with given speed
301 * @param actionName name of the action
302 * @param leader followed instance
303 * @param speed speed used for movement. Units = distance 1 in layer coordinates per second
304 */
305 void follow(const std::string& actionName, Instance* leader, const double speed);
306
307 /** Performs given named action to the instance. While performing the action
308 * follows given route with given speed. Note: In this case route isn't deleted or resetted at the end.
309 * @param actionName name of the action
310 * @param route followed route
311 * @param speed speed used for movement. Units = distance 1 in layer coordinates per second
312 */
313 void follow(const std::string& actionName, Route* route, const double speed);
314
315 /** Cancel movement after a given length.
316 * If no length is set then 1 is used. This means that the instance
317 * stops at the center of the next cell (can be the same as the current).
318 */
319 void cancelMovement(uint32_t length = 1);
320
321 /** Returns pointer to currently set saytext. In case no text is set, returns NULL
322 */
323 const std::string* getSayText() const;
324
325 /** Updates the instance related to the current action
326 * @note call this only once in engine update cycle, so that tracking between
327 * current position and previous position keeps in sync.
328 * @returns marked changes
329 */
330 InstanceChangeInfo update();
331
332 /** If this returns true, the instance needs to be updated
333 */
334 bool isActive() const;
335
336 /** Sets visualization to be used. Transfers ownership.
337 */
338 void setVisual(IVisual* visual) { m_visual = visual; }
339
340 /** Gets used visualization
341 */
342 template<typename T> T* getVisual() const { return reinterpret_cast<T*>(m_visual); }
343
344 void callOnTransparencyChange();
345 void callOnVisibleChange();
346 void callOnStackPositionChange();
347
348 /** Sets speed for the map. See Model::setTimeMultiplier.
349 */
350 void setTimeMultiplier(float multip);
351
352 /** Gets instance speed. @see setTimeMultiplier.
353 */
354 float getTimeMultiplier();
355
356 /** Gets instance speed, considering also model and map speeds. @see setTimeMultiplier.
357 */
358 float getTotalTimeMultiplier();
359
360 /** Gets the scaled runtime in milliseconds
361 * @return runtime
362 */
363 uint32_t getRuntime();
364
365 /** Refreshes instance e.g. in case location is updated directly (not via setLocation)
366 * In this case e.g. instance's master time provider is changed, so it needs to be updated
367 */
368 void refresh();
369
370 /** Returns a bitmask of changes of the last update.
371 */
372 InstanceChangeInfo getChangeInfo();
373
374 /** callback so other instances we depend on can notify us if they go away
375 */
376 void onInstanceDeleted(Instance* instance);
377
378 /** Returns a pointer to the route, in case there is no, it returns NULL.
379 */
380 Route* getRoute();
381
382 /** Sets the cell stack position.
383 */
384 void setCellStackPosition(uint8_t stack);
385
386 /** Gets the cell stack position.
387 */
388 uint8_t getCellStackPosition();
389
390 /** Returns true if instance or object have special cost otherwise false.
391 */
392 bool isSpecialCost();
393
394 /** Sets for the given cost id a cost.
395 * @param id name of the cost id
396 * @param cost value for the cost
397 */
398 void setCost(const std::string& id, double cost);
399
400 /** Resets cost.
401 */
402 void resetCost();
403
404 /** Returns cost value. In case there is no it returns the object cost.
405 */
406 double getCost();
407
408 /** Returns cost id. In case there is no it returns the object cost id.
409 */
410 std::string getCostId();
411
412 /** Returns speed modifier.
413 */
414 double getSpeed();
415
416 /** Returns true if instance or object have special speed modifier otherwise false.
417 */
418 bool isSpecialSpeed();
419
420 /** Returns true if it is multi cell otherwise false
421 */
422 bool isMultiCell();
423
424 /** Returns true if it is multi object otherwise false
425 */
426 bool isMultiObject();
427
428 /** Updates the visual positions of all instances in case this is a multi object
429 */
430 void updateMultiInstances();
431
432 /** Returns a vector that contains all instances of a multi object
433 */
434 const std::vector<Instance*>& getMultiInstances();
435
436 /** Sets a instance to the main multi instance of this instance.
437 */
438 void setMainMultiInstance(Instance* main);
439
440 /** Returns a pointer to the main mulit instance or Null if the instance is not part of a multi instance object.
441 */
442 Instance* getMainMultiInstance();
443
444 /** Adds new static color overlay with given angle (degrees).
445 */
446 void addStaticColorOverlay(uint32_t angle, const OverlayColors& colors);
447
448 /** Returns closest matching static color overlay for given angle
449 * @return pointer to OverlayColor class
450 */
451 OverlayColors* getStaticColorOverlay(int32_t angle);
452
453 /** Removes a static color overlay with given angle (degrees).
454 */
455 void removeStaticColorOverlay(int32_t angle);
456
457 /** Indicates if there exists a static color overlay.
458 */
459 bool isStaticColorOverlay();
460
461 /** Adds new color overlay with given angle (degrees) to given action.
462 */
463 void addColorOverlay(const std::string& actionName, uint32_t angle, const OverlayColors& colors);
464
465 /** Returns closest matching color overlay for given angle and action.
466 * @return pointer to OverlayColor class
467 */
468 OverlayColors* getColorOverlay(const std::string& actionName, uint32_t angle);
469
470 /** Removes a color overlay with given angle (degrees) from given action.
471 */
472 void removeColorOverlay(const std::string& actionName, int32_t angle);
473
474 /** Adds new animation overlay with given angle (degrees) and order to given action.
475 */
476 void addAnimationOverlay(const std::string& actionName, uint32_t angle, int32_t order, const AnimationPtr& animationptr);
477
478 /** Gets map with animations closest to given angle.
479 * @return ordered animation map
480 */
481 std::map<int32_t, AnimationPtr> getAnimationOverlay(const std::string& actionName, int32_t angle);
482
483 /** Removes animation overlay with given angle (degrees) and order from action.
484 */
485 void removeAnimationOverlay(const std::string& actionName, uint32_t angle, int32_t order);
486
487 /** Adds new color overlay with given angle (degrees) and order to given action animation overlay.
488 */
489 void addColorOverlay(const std::string& actionName, uint32_t angle, int32_t order, const OverlayColors& colors);
490
491 /** Returns closest matching color overlay for given angle, order and action animation overlay.
492 * @return pointer to OverlayColor class
493 */
494 OverlayColors* getColorOverlay(const std::string& actionName, uint32_t angle, int32_t order);
495
496 /** Removes a color overlay with given angle (degrees), order from given action animation overlay.
497 */
498 void removeColorOverlay(const std::string& actionName, int32_t angle, int32_t order);
499
500 /** If the action have base animation and optional color overlay it gets converted to animation overlay.
501 */
502 void convertToOverlays(const std::string& actionName, bool color);
503
504 /** Indicates if there exists a animation overlay for given action.
505 */
506 bool isAnimationOverlay(const std::string& actionName);
507
508 /** Indicates if there exists a color overlay for given action or animation overlay.
509 */
510 bool isColorOverlay(const std::string& actionName);
511
512 private:
513 std::string m_id;
514
515 //! The rotation offset of this instance. This is in addition to possible camera rotation and
516 //! intended for setting, for example, a rotation of a tile.
517 int32_t m_rotation;
518
519 /** InstanceActivity gets allocated in case there is some runtime
520 * activity related to the instance. Keeping activity related variables
521 * in separate class keeps memory consumption lower e.g. for large tile
522 * areas.
523 * Class also keeps track of changes since the previous update call.
524 * With this bookkeeping, it is possible to optimize several spots in
525 * the engine, basically only reacting to changes instead of polling.
526 */
527 class InstanceActivity {
528 public:
529 InstanceActivity(Instance& source);
530 ~InstanceActivity();
531
532 // ----- Fields related to change tracking -----
533 //! updates cached variables, marks changes
534 void update(Instance& source);
535 //! location on previous round
536 Location m_location;
537 //! location on previous cell
538 Location m_oldLocation;
539 //! rotation on previous round
540 int32_t m_rotation;
541 //! rotation on previous round
542 int32_t m_oldRotation;
543 //! action on previous round. NOTE: might become invalid, only used for address comparison
544 Action* m_action;
545 //! sound source of action audio on previous round
546 SoundSource* m_soundSource;
547 //! speed on previous round
548 double m_speed;
549 //! time multiplier on previous round
550 float m_timeMultiplier;
551 //! say text on previous round
552 std::string m_sayText;
553 //! listeners for changes
554 std::vector<InstanceChangeListener*> m_changeListeners;
555
556 // ----- Fields related to generic activity -----
557 //! listeners for action related events
558 std::vector<InstanceActionListener*> m_actionListeners;
559 //! action information, allocated when actions are bind
560 ActionInfo* m_actionInfo;
561 //! text to say + duration, allocated when something is said
562 SayInfo* m_sayInfo;
563 //! time scaler for this instance
564 TimeProvider* m_timeProvider;
565 //! blocking status on previous round
566 bool m_blocking;
567 //! additional change info, used for visual class (transparency, visible, stackpos)
568 InstanceChangeInfo m_additional;
569 };
570 InstanceActivity* m_activity;
571 //! bitmask stating current changes
572 InstanceChangeInfo m_changeInfo;
573 //! listeners for deletion of the instance
574 std::vector<InstanceDeleteListener*> m_deleteListeners;
575
576 //! object where instantiated from
577 Object* m_object;
578 //! indicates if m_object is customized
579 bool m_ownObject;
580 //! current location
581 Location m_location;
582 //! instance visualization
583 IVisual* m_visual;
584 //! instance blocking info
585 bool m_blocking;
586 //! allow to override the blocking property
587 bool m_overrideBlocking;
588 //! position on cell stack
589 uint8_t m_cellStackPos;
590 //! indicates special cost
591 bool m_specialCost;
592 //! holds cost value
593 double m_cost;
594 //! holds cost id
595 std::string m_costId;
596 //! vector that holds all multi instances
597 std::vector<Instance*> m_multiInstances;
598 //! pointer to the main multi instance
599 Instance* m_mainMultiInstance;
600
601 Instance(const Instance&);
602 Instance& operator=(const Instance&);
603 //! Finalize current action
604 void finalizeAction();
605 //! Cancel current action
606 void cancelAction();
607 //! Initialize action for use
608 void initializeAction(const std::string& actionName);
609 //! Moves instance. Returns true if finished
610 bool processMovement();
611 //! Calculates movement based current location and speed
612 void calcMovement();
613 //! rebinds time provider based on new location
614 void bindTimeProvider();
615 //! called when instance has been changed. Causes instance to create InstanceActivity
616 void initializeChanges();
617 //! called to prepare the instance for an update
618 void prepareForUpdate();
619
620 //! Creates an own object for the instance to allow visual customization.
621 void createOwnObject();
622 //! Returns pointer to action visual, can also create it.
623 ActionVisual* getActionVisual(const std::string& actionName, bool create);
624 };
625 } // FIFE
626
627 #endif