1 /* Copyright (C) 2018 Wildfire Games. 2 * This file is part of 0 A.D. 3 * 4 * 0 A.D. is free software: you can redistribute it and/or modify 5 * it under the terms of the GNU General Public License as published by 6 * the Free Software Foundation, either version 2 of the License, or 7 * (at your option) any later version. 8 * 9 * 0 A.D. is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 * GNU General Public License for more details. 13 * 14 * You should have received a copy of the GNU General Public License 15 * along with 0 A.D. If not, see <http://www.gnu.org/licenses/>. 16 */ 17 18 #ifndef INCLUDED_ICMPVISUAL 19 #define INCLUDED_ICMPVISUAL 20 21 #include "simulation2/system/Interface.h" 22 23 #include "ps/CStr.h" 24 #include "maths/BoundingBoxOriented.h" 25 #include "maths/BoundingBoxAligned.h" 26 #include "maths/Fixed.h" 27 #include "maths/FixedVector3D.h" 28 #include "lib/file/vfs/vfs_path.h" 29 30 class CUnit; 31 32 /** 33 * The visual representation of an entity (typically an actor). 34 */ 35 class ICmpVisual : public IComponent 36 { 37 public: 38 /** 39 * Get the world-space bounding box of the object's visual representation. 40 * (Not safe for use in simulation code.) 41 */ 42 virtual CBoundingBoxAligned GetBounds() const = 0; 43 44 /** 45 * Get the oriented world-space bounding box of the object's visual representation, clipped at the Y=0 plane in object space 46 * to prevent it from extending into the terrain. The primary difference with GetBounds is that this bounding box is not aligned 47 * to the world axes, but arbitrarily rotated according to the model transform. 48 */ 49 virtual CBoundingBoxOriented GetSelectionBox() const = 0; 50 51 /** 52 * Get the world-space position of the base point of the object's visual representation. 53 * (Not safe for use in simulation code.) 54 */ 55 virtual CVector3D GetPosition() const = 0; 56 57 /** 58 * Return the short name of the actor that's being displayed, or the empty string on error. 59 * (Not safe for use in simulation code.) 60 */ 61 virtual std::wstring GetActorShortName() const = 0; 62 63 /** 64 * Return the filename of the actor to be used for projectiles from this unit, or the empty string if none. 65 * (Not safe for use in simulation code.) 66 */ 67 virtual std::wstring GetProjectileActor() const = 0; 68 69 /** 70 * Return the exact position where a projectile should be launched from (based on the actor's 71 * ammo prop points). 72 * Return type is CFixedVector3D because it is exposed to the JS interface. 73 * Returns (0,0,0) if no point can be found. 74 */ 75 virtual CFixedVector3D GetProjectileLaunchPoint() const = 0; 76 77 /** 78 * Returns the underlying unit of this visual actor. May return NULL to indicate that no unit exists (e.g. may happen if the 79 * game is started without graphics rendering). 80 * Originally intended for introspection purposes in Atlas; for other purposes, consider using a specialized getter first. 81 */ 82 virtual CUnit* GetUnit() = 0; 83 84 /** 85 * Set the variant selection of the actor for a certain key. 86 * This overrides a previous selection on that key, so every component 87 * should use unique keys. 88 */ 89 virtual void SetVariant(const CStr& key, const CStr& selection) = 0; 90 91 /** 92 * Returns the name of the currently played animation. 93 */ 94 virtual std::string GetAnimationName() const = 0; 95 96 /** 97 * Start playing the given animation. If there are multiple possible animations then it will 98 * pick one at random (not network-synchronised). 99 * If @p soundgroup is specified, then the sound will be played at each 'event' point in the 100 * animation cycle. 101 * @param name animation name (e.g. "idle", "walk", "melee"; the names are determined by actor XML files) 102 * @param once if true then the animation will play once and freeze at the final frame, else it will loop 103 * @param speed animation speed multiplier (typically 1.0 for the default speed) 104 * @param soundgroup VFS path of sound group .xml, relative to audio/, or empty string for none 105 */ 106 virtual void SelectAnimation(const std::string& name, bool once, fixed speed) = 0; 107 108 /** 109 * Replaces a specified animation with another. Only affects the special speed-based 110 * animation determination behaviour. 111 * @param name Animation to match. 112 * @param replace Animation that should replace the matched animation. 113 */ 114 virtual void ReplaceMoveAnimation(const std::string& name, const std::string& replace) = 0; 115 116 /** 117 * Ensures that the given animation will be used when it normally would be, 118 * removing reference to any animation that might replace it. 119 * @param name Animation name to remove from the replacement map. 120 */ 121 virtual void ResetMoveAnimation(const std::string& name) = 0; 122 123 /** 124 * Start playing the walk/run animations, scaled to the unit's movement speed. 125 * @param runThreshold movement speed at which to switch to the run animation 126 */ 127 virtual void SelectMovementAnimation(fixed runThreshold) = 0; 128 129 /** 130 * Adjust the speed of the current animation, so it can match simulation events. 131 * @param repeattime time for complete loop of animation, in msec 132 */ 133 virtual void SetAnimationSyncRepeat(fixed repeattime) = 0; 134 135 /** 136 * Adjust the offset of the current animation, so it can match simulation events. 137 * @param actiontime time between now and when the 'action' event should occur, in msec 138 */ 139 virtual void SetAnimationSyncOffset(fixed actiontime) = 0; 140 141 /** 142 * Set the shading color that will be modulated with the model's textures. 143 * Default shading is (1, 1, 1, 1). 144 * Alpha should probably be 1 else it's unlikely to work properly. 145 * @param r red component, expected range [0, 1] 146 * @param g green component, expected range [0, 1] 147 * @param b blue component, expected range [0, 1] 148 * @param a alpha component, expected range [0, 1] 149 */ 150 virtual void SetShadingColor(fixed r, fixed g, fixed b, fixed a) = 0; 151 152 /** 153 * Set an arbitrarily-named variable that the model may use to alter its appearance 154 * (e.g. in particle emitter parameter computations). 155 */ 156 virtual void SetVariable(const std::string& name, float value) = 0; 157 158 /** 159 * Get actor seed used for random variations 160 */ 161 virtual u32 GetActorSeed() const = 0; 162 163 /** 164 * Set actor seed for random variations and reload model 165 */ 166 virtual void SetActorSeed(u32 seed) = 0; 167 168 /** 169 * Returns true if this entity should have a construction preview 170 */ 171 virtual bool HasConstructionPreview() const = 0; 172 173 /** 174 * Called when an actor file has been modified and reloaded dynamically. 175 * If this component uses the named actor file, it should regenerate its actor 176 * to pick up the new definitions. 177 */ 178 virtual void Hotload(const VfsPath& name) = 0; 179 180 DECLARE_INTERFACE_TYPE(Visual) 181 }; 182 183 // TODO: rename this to VisualActor, because the interface is actor-specific, maybe? 184 185 #endif // INCLUDED_ICMPVISUAL 186