1 // Copyright 2001-2018 Crytek GmbH / Crytek Group. All rights reserved.
5 #include <CryMath/Cry_Math.h>
6 #include <CryExtension/ICryUnknown.h>
7 #include <CryExtension/ClassWeaver.h>
8 #include <CryNetwork/SerializeFwd.h>
9 #include <CryAudio/IAudioSystem.h>
10 #include <CrySerialization/IArchiveHost.h>
11 #include <CrySerialization/Serializer.h>
12 #include <CryCore/Containers/CryArray.h>
13 #include <CryCore/BitMask.h>
14 #include <CryNetwork/ISerialize.h>
15 #include <CryNetwork/INetEntity.h>
17 #include <CrySchematyc/Reflection/TypeDesc.h>
18 #include <CrySchematyc/Utils/EnumFlags.h>
20 #include <CryMath/Rotation.h>
21 #include <CryMath/Transform.h>
23 #include <CryEntitySystem/IEntityBasicTypes.h>
25 // Forward declarations
26 struct SEntitySpawnParams
;
28 struct SEntityUpdateContext
;
29 struct IShaderPublicParams
;
31 struct IEntityEventListener
;
32 struct IPhysicalEntity
;
43 struct INetworkSpawnParams
;
45 struct SEntityPreviewContext
;
52 // Forward declaration of Sandbox's entity object, should be removed when IEntityComponent::Run is gone
55 //! Derive from this interface to expose custom entity properties in the editor using the serialization framework.
56 //! Each entity component can contain one property group, each component will be separated by label in the entity property view
57 struct IEntityPropertyGroup
59 virtual ~IEntityPropertyGroup() {}
61 virtual const char* GetLabel() const = 0;
62 virtual void SerializeProperties(Serialization::IArchive
& archive
) = 0;
65 //////////////////////////////////////////////////////////////////////////
66 //! Compatible to the CRYINTERFACE_DECLARE
67 #define CRY_ENTITY_COMPONENT_INTERFACE(iname, iidHigh, iidLow) CRY_PP_ERROR("Deprecated macro: Use CRY_ENTITY_COMPONENT_INTERFACE_GUID instead. Please refer to the Migrating Guide from CRYENGINE 5.3 to CRYENGINE 5.4 for more details.")
68 #define CRY_ENTITY_COMPONENT_INTERFACE_GUID(iname, iguid) CRYINTERFACE_DECLARE_GUID(iname, iguid)
70 #define CRY_ENTITY_COMPONENT_CLASS(implclassname, interfaceName, cname, iidHigh, iidLow) CRY_PP_ERROR("Deprecated macro: Use CRY_ENTITY_COMPONENT_CLASS_GUID instead. Please refer to the Migrating Guide from CRYENGINE 5.3 to CRYENGINE 5.4 for more details.")
72 #define CRY_ENTITY_COMPONENT_CLASS_GUID(implclassname, interfaceName, cname, cguid) \
73 CRYINTERFACE_BEGIN() \
74 CRYINTERFACE_ADD(IEntityComponent) \
75 CRYINTERFACE_ADD(interfaceName) \
77 CRYGENERATE_CLASS_GUID(implclassname, cname, cguid)
79 #define CRY_ENTITY_COMPONENT_INTERFACE_AND_CLASS(implclassname, cname, cguid) CRY_PP_ERROR("Deprecated macro: Use CRY_ENTITY_COMPONENT_INTERFACE_AND_CLASS_GUID instead. Please refer to the Migrating Guide from CRYENGINE 5.3 to CRYENGINE 5.4 for more details.")
81 #define CRY_ENTITY_COMPONENT_INTERFACE_AND_CLASS_GUID(implclassname, cname, cguid) \
82 CRY_ENTITY_COMPONENT_INTERFACE_GUID(implclassname, cguid) \
83 CRY_ENTITY_COMPONENT_CLASS_GUID(implclassname, implclassname, cname, cguid)
85 #include <CrySchematyc/Component.h>
87 enum class EEntityComponentFlags
: uint32
90 Singleton
= BIT(0), //!< Allow only of one instance of this component per class/object.
91 Legacy
= BIT(1), //!< Legacy component, only for backward computability should not be accessible for creation in the UI. (Will also enable saving with LegacySerializeXML)
92 Transform
= BIT(2), //!< Component has transform.
93 Socket
= BIT(3), //!< Other components can be attached to socket of this component.
94 Attach
= BIT(4), //!< This component can be attached to socket of other components.
95 Schematyc
= BIT(5), //!< Component was created and owned by the Schematyc.
96 SchematycEditable
= BIT(6), //!< Schematyc components where properties of it can be edited per each Entity instance.
97 SchematycModified
= BIT(7), //!< Only in combination with the SchematycEditable component to indicate that some parameters where modified from Schematyc defaults by the user.
98 UserAdded
= BIT(8), //!< This component was added in the Editor by the user
99 NoSave
= BIT(9), //!< Not save this component under entity components list when saving/loading
100 NetNotReplicate
= BIT(10), //!< This component should be not be network replicated.
101 HideFromInspector
= BIT(11), //!< This component can not be added from the Inspector, instead requiring use in Schematyc or C++.
102 ServerOnly
= BIT(12), //!< This component can only be loaded when we are running as local or dedicated server
103 ClientOnly
= BIT(13), //!< This component can only be loaded when we are running as a client, never on a dedicated server
104 HiddenFromUser
= BIT(14), //!< This component will not be shown to the user
105 NoCreationOffset
= BIT(15), //!< Disables the creation offset in sandbox. The sandbox uses the bounding box radius as an offset to place new entities so they don't clip into the terrain.
107 typedef CEnumFlags
<EEntityComponentFlags
> EntityComponentFlags
;
109 //! Structure that describes how one entity component
110 //! interacts with another entity component.
111 struct SEntityComponentRequirements
113 enum class EType
: uint32
115 Incompatibility
, //!< These components are incompatible and cannot be used together
116 SoftDependency
, //!< Dependency must be initialized before component.
117 HardDependency
//!< Dependency must exist and be initialized before component.
120 inline SEntityComponentRequirements(EType _type
, const CryGUID
& _guid
)
129 //! Interface used by the editor to Preview Render of the entity component
130 //! This can be used to draw helpers or preview elements in the sandbox
132 //! \include CryEntitySystem/Examples/PreviewComponent.cpp
133 struct IEntityComponentPreviewer
135 virtual ~IEntityComponentPreviewer() {}
137 //! Override this method to Edit UI properties for previewer of the component
138 virtual void SerializeProperties(Serialization::IArchive
& archive
) = 0;
140 //! Override this method to Render a preview of the Entity Component
141 //! This method is not used when entity is normally rendered
142 //! But only used for previewing the entity in the Sandbox Editor
143 //! \param entity Entity which gets drawn
144 //! \param component Component which is gets drawn
145 //! \param context PreviewContext contains information and settings for the rendering
146 //! \see IEntity::SEntityPreviewContext
147 virtual void Render(const IEntity
& entity
, const IEntityComponent
& component
, SEntityPreviewContext
& context
) const = 0;
151 //! A class that describe and reflect members of the entity component
152 //! Properties of the component are reflected using run-time class
153 //! reflection system, and stored in here.
154 class CEntityComponentClassDesc
: public Schematyc::CClassDesc
157 inline void SetComponentFlags(const EntityComponentFlags
& flags
)
162 EntityComponentFlags
GetComponentFlags() const
167 inline void AddComponentInteraction(SEntityComponentRequirements::EType type
, const CryGUID
& guid
)
169 m_interactions
.emplace_back(type
, guid
);
173 inline void AddComponentInteraction(SEntityComponentRequirements::EType type
)
175 m_interactions
.emplace_back(type
, Schematyc::GetTypeGUID
<T
>());
178 inline bool IsCompatibleWith(const CryGUID
& guid
) const
180 for (const SEntityComponentRequirements
& dependency
: m_interactions
)
182 if (dependency
.type
== SEntityComponentRequirements::EType::Incompatibility
&& dependency
.guid
== guid
)
191 inline bool DependsOn(const CryGUID
& guid
) const
193 for (const SEntityComponentRequirements
& dependency
: m_interactions
)
195 if ((dependency
.type
== SEntityComponentRequirements::EType::SoftDependency
|| dependency
.type
== SEntityComponentRequirements::EType::HardDependency
)
196 && dependency
.guid
== guid
)
205 const DynArray
<SEntityComponentRequirements
>& GetComponentInteractions() const { return m_interactions
; }
208 EntityComponentFlags m_flags
;
209 DynArray
<SEntityComponentRequirements
> m_interactions
;
215 struct SObjectSignal
;
216 //////////////////////////////////////////////////////////////////////////
217 // All classes derived from IEntityComponent will be using
218 // CEntityComponentClassDesc
219 //////////////////////////////////////////////////////////////////////////
222 template<typename TYPE
> struct SIsCustomClass
<TYPE
, typename
std::enable_if
<std::is_convertible
<TYPE
, IEntityComponent
>::value
>::type
>
224 static const bool value
= true;
227 template<typename TYPE
>
228 class CTypeDesc
<TYPE
, typename
std::enable_if
<std::is_convertible
<TYPE
, IEntityComponent
>::value
>::type
>
229 : public CClassDescInterface
<TYPE
, CEntityComponentClassDesc
>
235 //! \brief Represents a component that can be attached to an individual entity instance
236 //! Allows for populating entities with custom game logic
237 //! \anchor MinimalEntityComponent
239 //! \include CryEntitySystem/Examples/MinimalEntityComponent.cpp
240 struct IEntityComponent
: public ICryUnknown
, ISimpleEntityEventListener
242 // Helper to serialize both legacy and Schematyc properties of an entity
243 struct SPropertySerializer
245 void Serialize(Serialization::IArchive
& archive
)
247 // Start with the legacy properties
248 if (IEntityPropertyGroup
* pPropertyGroup
= pComponent
->GetPropertyGroup())
250 struct SSerializeWrapper
252 void Serialize(Serialization::IArchive
& archive
)
254 pGroup
->SerializeProperties(archive
);
257 IEntityPropertyGroup
* pGroup
;
260 archive(SSerializeWrapper
{ pPropertyGroup
}, "legacy", "legacy");
263 // Serialize Schematyc properties
264 Schematyc::Utils::SerializeClass(archive
, pComponent
->GetClassDesc(), pComponent
, "schematyc", "schematyc");
267 IEntityComponent
* pComponent
;
270 CRY_ENTITY_COMPONENT_INTERFACE_GUID(IEntityComponent
, "6a6ffe9a-a3d4-4cd6-9ef1-fc42ee649776"_cry_guid
)
272 typedef int ComponentEventPriority
;
274 typedef EEntityComponentFlags EFlags
;
275 typedef EntityComponentFlags ComponentFlags
;
277 static constexpr int EmptySlotId
= -1;
279 //! SInitParams is only used from Schematyc to call PreInit to initialize Schematyc Entity Component
284 const CryGUID
& guid_
,
286 const CEntityComponentClassDesc
* classDesc_
,
287 EntityComponentFlags flags_
,
288 IEntityComponent
* pParent_
,
289 const CryTransform::CTransformPtr
& transform_
294 , classDesc(classDesc_
)
295 , transform(transform_
)
303 const CEntityComponentClassDesc
* classDesc
;
304 const CryTransform::CTransformPtr transform
;
305 IEntityComponent
* pParent
= nullptr;
306 INetworkSpawnParams
* pNetworkSpawnParams
= nullptr;
307 EntityComponentFlags flags
;
312 virtual ICryFactory
* GetFactory() const { return nullptr; }
315 virtual void* QueryInterface(const CryInterfaceID
& iid
) const { return nullptr; }
316 virtual void* QueryComposite(const char* name
) const { return nullptr; }
320 // Return Host entity pointer
321 ILINE IEntity
* GetEntity() const { return m_pEntity
; }
322 ILINE EntityId
GetEntityId() const;
325 IEntityComponent() {}
326 IEntityComponent(IEntityComponent
&& other
)
327 : m_pEntity(other
.m_pEntity
)
328 , m_componentFlags(other
.m_componentFlags
)
329 , m_guid(other
.m_guid
)
330 , m_name(other
.m_name
.c_str())
331 , m_pTransform(std::move(other
.m_pTransform
))
332 , m_pParent(other
.m_pParent
)
333 , m_pClassDesc(other
.m_pClassDesc
)
334 , m_entitySlotId(other
.m_entitySlotId
)
336 other
.m_pTransform
.reset();
337 other
.m_entitySlotId
= EmptySlotId
;
339 IEntityComponent(const IEntityComponent
&) = default;
340 IEntityComponent
& operator=(const IEntityComponent
&) = default;
341 IEntityComponent
& operator=(IEntityComponent
&&) = default;
342 virtual ~IEntityComponent() {}
344 //! Return ClassDesc for this component
345 //! Class description is storing runtime C++ class reflection information
346 //! It contain information about member variables of the component and how to serialize them,
347 //! information how to create an instance of class and all relevant additional information to handle this class.
348 const CEntityComponentClassDesc
& GetClassDesc() const
350 if (m_pClassDesc
== nullptr)
352 static CEntityComponentClassDesc nullClassDesc
;
353 return nullClassDesc
;
355 return *m_pClassDesc
;
358 //////////////////////////////////////////////////////////////////////////
359 // BEGIN IEntityComponent virtual interface
360 // Derived classes mostly interested in overriding these virtual methods
361 //////////////////////////////////////////////////////////////////////////
364 //! Only called by system classes to initalize component.
365 //! Users must not call this method directly
366 virtual void PreInit(const SInitParams
& params
)
368 m_guid
= params
.guid
;
369 m_name
= params
.name
;
370 m_pClassDesc
= params
.classDesc
;
373 m_componentFlags
.Add(m_pClassDesc
->GetComponentFlags());
375 m_componentFlags
.Add(params
.flags
);
376 m_pTransform
= params
.transform
;
377 //m_pPreviewer = params.pPreviewer;
378 m_pParent
= params
.pParent
;
381 //! Called at the very first initialization of the component, at component creation time.
382 virtual void Initialize() {}
384 //! Called on all Entity components right before all of the Entity Components are destructed.
385 virtual void OnShutDown() {};
387 //! Called when the transformation of the component is changed
388 virtual void OnTransformChanged() {}
390 //! By overriding this function component will be able to handle events sent from the host Entity.
391 //! Requires returning the desired event flag in GetEventMask.
392 //! \param event Event structure, contains event id and parameters.
394 //! \include CryEntitySystem/Examples/ComponentEvents.cpp
395 virtual void ProcessEvent(const SEntityEvent
& event
) {}
398 //! Return bit mask of the EEntityEvent flags that we want to receive in ProcessEvent
399 //! (ex: BIT64(ENTITY_EVENT_HIDE) | BIT64(ENTITY_EVENT_UNHIDE))
400 //! Only events matching the returned bit mask will be sent to the ProcessEvent method
402 //! \include CryEntitySystem/Examples/ComponentEvents.cpp
403 virtual uint64
GetEventMask() const { return 0; }
405 //! Determines the order in which this component will receive entity events (including update). Lower number indicates a higher priority.
406 virtual ComponentEventPriority
GetEventPriority() const { return (ComponentEventPriority
)GetProxyType(); }
408 //! \brief Network serialization. Override to provide a mask of active network aspects
409 //! used by this component. Called once during binding to network.
411 //! \include CryEntitySystem/Examples/ComponentNetSerialize.cpp
412 virtual NetworkAspectType
GetNetSerializeAspectMask() const { return 0; }
414 //! \brief Network serialization. Will be called for each active aspect for both reading and writing.
415 //! @param[in,out] ser Serializer for reading/writing values.
416 //! @param[in] aspect The number of the aspect being serialized.
417 //! @param[in] profile Can be ignored, used by CryPhysics only.
418 //! @param[in] flags Can be ignored, used by CryPhysics only.
419 //! \see ISerialize::Value()
421 //! \include CryEntitySystem/Examples/ComponentNetSerialize.cpp
422 virtual bool NetSerialize(TSerialize ser
, EEntityAspects aspect
, uint8 profile
, int flags
) { return true; };
424 //! Used to match an entity's state when it is replicated onto a remote machine.
425 //! This is called once when spawning an entity, in order to serialize its data - and once again on the remote client to deserialize the state.
426 //! Deserialization will always occur *before* IEntityComponent::Initialize is called.
427 //! @param[in,out] ser Serializer for reading / writing values.
428 //! \see ISerialize::Value()
430 //! \include CryEntitySystem/Examples/ComponentNetReplicate.cpp
431 virtual void NetReplicateSerialize(TSerialize ser
) {}
433 //! \brief Call this to trigger aspect synchronization over the network. A shortcut.
434 //! \see INetEntity::MarkAspectsDirty()
436 //! \include CryEntitySystem/Examples/ComponentNetSerialize.cpp
437 virtual void NetMarkAspectsDirty(const NetworkAspectType aspects
); // The definition is in IEntity.h
439 //! \brief Override this to return preview render interface for the component.
440 //! Multiple component instances can usually share the same previewer class instance.
441 //! \see IEntityComponentPreviewer
442 virtual IEntityComponentPreviewer
* GetPreviewer() { return nullptr; }
444 //////////////////////////////////////////////////////////////////////////
445 //! END IEntityComponent virtual interface
446 //////////////////////////////////////////////////////////////////////////
449 //! Set flags for this component
450 void SetComponentFlags(ComponentFlags flags
) { m_componentFlags
= flags
; };
452 //! Return flags for this component
453 const ComponentFlags
& GetComponentFlags() const { return m_componentFlags
; };
454 ComponentFlags
& GetComponentFlags() { return m_componentFlags
; };
456 //! Return GUID of this component.
457 //! This GUID is only guaranteed to be unique within the host entity, different entities can have components with equal GUIDs.
458 //! Each component in the entity have type guid (GetClassDesc().GetGUID()) (ex: identify EntityLightComponent class)
459 //! and a unique instance guid IEntityComponent::GetGUID() (ex: identify Light01,Light02,etc.. component)
460 const CryGUID
& GetGUID() const { return m_guid
; }
462 //! Return Parent component, only used by Schematyc components
463 //! Initialized by the PreInit call
464 IEntityComponent
* GetParent() const { return m_pParent
; };
466 //! Return Transformation of the entity component relative to the owning entity or parent component
467 const CryTransform::CTransformPtr
& GetTransform() const { return m_pTransform
; }
469 //! Sets the transformation form a matrix. If the component doesn't have a transformation yet the function will add one.
470 void SetTransformMatrix(const Matrix34
& transform
);
472 //! Sets the transformation from another transformation. If the component doesn't have a transformation yet the function will add one.
473 void SetTransformMatrix(const CryTransform::CTransformPtr
& transform
);
475 //! Return Transformation of the entity component relative to the world
476 Matrix34
GetWorldTransformMatrix() const;
478 //! Return Calculated Transformation Matrix for current component transform
479 Matrix34
GetTransformMatrix() const { return (m_componentFlags
.Check(EEntityComponentFlags::Transform
) && m_pTransform
) ? m_pTransform
->ToMatrix34() : IDENTITY
; }
481 //! Get name of this individual component, usually only Schematyc components will have names
482 const char* GetName() const { return m_name
.c_str(); };
484 //! Set a new name for this component
485 //! Names of the components must not be unique
486 void SetName(const char* szName
) { m_name
= szName
; };
488 //////////////////////////////////////////////////////////////////////////
489 // HELPER METHODS FOR WORKING WITH ENTITY SLOTS
490 //////////////////////////////////////////////////////////////////////////
492 //! Return optional EntitySlot id used by this Component
493 int GetEntitySlotId() const { return m_entitySlotId
; }
495 //! Return optional EntitySlot id used by this Component
496 //! If slot id is not allocated, new slotid will be allocated and returned
497 int GetOrMakeEntitySlotId();
499 //! Stores Entity slot id used by this component.
500 void SetEntitySlotId(int slotId
) { m_entitySlotId
= slotId
; }
502 //! Frees entity slot used by this component
503 void FreeEntitySlot();
504 //////////////////////////////////////////////////////////////////////////
506 //! Return Current simulation mode of the host Entity
507 EEntitySimulationMode
GetEntitySimulationMode() const;
509 //! Send event to this specific component, first checking if the component is interested in the event
510 //! \param event description
511 //! \param receiving component
512 inline void SendEvent(const SEntityEvent
& event
)
514 if ((GetEventMask() & BIT64(event
.event
)) != 0)
520 //////////////////////////////////////////////////////////////////////////
521 // SCHEMATYC SIGNALS HELPERS
522 //////////////////////////////////////////////////////////////////////////
523 //void ProcessSignal( const Schematyc::SObjectSignal &signal );
526 //////////////////////////////////////////////////////////////////////////
527 // BEGIN Deprecated Methods
528 //////////////////////////////////////////////////////////////////////////
529 virtual void GetMemoryUsage(ICrySizer
* pSizer
) const {};
531 //! SaveGame serialization. Override to specify what to serialize in a saved game.
532 //! \param ser Serializing stream. Use IsReading() to decide read/write phase. Use Value() to read/write a property.
533 virtual void GameSerialize(TSerialize ser
) {}
534 //! SaveGame serialization. Override to enable serialization for the component.
535 //! \return true If component needs to be serialized to/from a saved game.
536 virtual bool NeedGameSerialize() { return false; };
538 //! Optionally serialize component to/from XML.
539 //! For user-facing properties, see GetProperties.
540 virtual void LegacySerializeXML(XmlNodeRef
& entityNode
, XmlNodeRef
& componentNode
, bool bLoading
) {}
542 //! Only for backward compatibility to Release 5.3.0 for loading
543 virtual struct IEntityPropertyGroup
* GetPropertyGroup() { return nullptr; }
545 //! Legacy, used for old entity proxies
546 virtual EEntityProxy
GetProxyType() const { return ENTITY_PROXY_LAST
; };
547 //////////////////////////////////////////////////////////////////////////
548 // ~END Deprecated Methods
549 //////////////////////////////////////////////////////////////////////////
553 friend class CEntity
;
554 friend class CEntitySystem
;
555 // Needs access to OnShutDown to maintain legacy game object extension shutdown behavior
556 friend class CGameObject
;
557 // Needs access to Initialize
558 friend Schematyc::CObject
;
560 // Host Entity pointer
561 IEntity
* m_pEntity
= nullptr;
563 ComponentFlags m_componentFlags
;
565 //! Unique GUID of the instance of this component
568 //! name of this component
571 //! Optional transformation setting for the component within the Entity object
572 CryTransform::CTransformPtr m_pTransform
;
574 //! Optional pointer to our parent component
575 IEntityComponent
* m_pParent
= nullptr;
577 //! Reflected type description for this component
578 //! Contain description of the reflected member variables
579 const CEntityComponentClassDesc
* m_pClassDesc
= nullptr;
581 //! Optional Entity SlotId for storing component data like geometry of character
582 int m_entitySlotId
= EmptySlotId
;
585 //! Lua Script component interface.
586 struct IEntityScriptComponent
: public IEntityComponent
588 CRY_ENTITY_COMPONENT_INTERFACE_GUID(IEntityScriptComponent
, "bd6403cf-3b49-f39e-9540-3fd1c6d4f755"_cry_guid
)
590 virtual void SetScriptUpdateRate(float fUpdateEveryNSeconds
) = 0;
591 virtual IScriptTable
* GetScriptTable() = 0;
592 virtual void CallEvent(const char* sEvent
) = 0;
593 virtual void CallEvent(const char* sEvent
, float fValue
) = 0;
594 virtual void CallEvent(const char* sEvent
, bool bValue
) = 0;
595 virtual void CallEvent(const char* sEvent
, const char* sValue
) = 0;
596 virtual void CallEvent(const char* sEvent
, const Vec3
& vValue
) = 0;
597 virtual void CallEvent(const char* sEvent
, EntityId nEntityId
) = 0;
599 //! Change current state of the entity script.
600 //! \return If state was successfully set.
601 virtual bool GotoState(const char* sStateName
) = 0;
603 //! Change current state of the entity script.
604 //! \return If state was successfully set.
605 virtual bool GotoStateId(int nStateId
) = 0;
607 //! Check if entity is in specified state.
608 //! \param sStateName Name of state table within entity script (case sensitive).
609 //! \return If entity script is in specified state.
610 virtual bool IsInState(const char* sStateName
) = 0;
612 //! Retrieves name of the currently active entity script state.
613 //! \return Name of current state.
614 virtual const char* GetState() = 0;
616 //! Retrieves the id of the currently active entity script state.
617 //! \return Index of current state.
618 virtual int GetStateId() = 0;
620 //! Fires an event in the entity script.
621 //! This will call OnEvent(id,param) Lua function in entity script, so that script can handle this event.
622 virtual void SendScriptEvent(int Event
, IScriptTable
* pParamters
, bool* pRet
= NULL
) = 0;
623 virtual void SendScriptEvent(int Event
, const char* str
, bool* pRet
= NULL
) = 0;
624 virtual void SendScriptEvent(int Event
, int nParam
, bool* pRet
= NULL
) = 0;
626 //! Change the Entity Script used by the Script Component.
627 //! Caller is responsible for making sure new script is initialised and script bound as required
628 //! \param pScript an entity script object that has already been loaded with the new script.
629 //! \param params parameters used to set the properties table if required.
630 virtual void ChangeScript(IEntityScript
* pScript
, SEntitySpawnParams
* params
) = 0;
632 //! Sets physics parameters from an existing script table
633 //! \param type - one of PHYSICPARAM_... values
634 //! \param params script table containing the values to set
635 virtual void SetPhysParams(int type
, IScriptTable
* params
) = 0;
637 //! Determines whether or not the script should receive update callbacks
638 //! Replaces IEntity::Activate for legacy projects
639 virtual void EnableScriptUpdate(bool bEnable
) = 0;
642 //! Interface to the trigger component, exposing support for tracking enter / leave events for other entities entering a predefined trigger box
643 //! An in-game example that uses this functionality is the ProximityTrigger entity
645 //! \include CryEntitySystem/Examples/TriggerComponent.cpp
646 struct IEntityTriggerComponent
: public IEntityComponent
648 CRY_ENTITY_COMPONENT_INTERFACE_GUID(IEntityTriggerComponent
, "de73851b-7e35-419f-a509-51d204f555de"_cry_guid
)
650 //! Creates a trigger bounding box.
651 //! When physics will detect collision with this bounding box it will send an events to the entity.
652 //! If entity have script OnEnterArea and OnLeaveArea events will be called.
653 //! \param bbox Axis aligned bounding box of the trigger in entity local space (Rotation and scale of the entity is ignored). Set empty bounding box to disable trigger.
654 virtual void SetTriggerBounds(const AABB
& bbox
) = 0;
656 //! Retrieve trigger bounding box in local space.
657 //! \return Axis aligned bounding box of the trigger in the local space.
658 virtual void GetTriggerBounds(AABB
& bbox
) = 0;
660 //! Forward enter/leave events to this entity
661 virtual void ForwardEventsTo(EntityId id
) = 0;
663 //! Invalidate the trigger, so it gets recalculated and catches things which are already inside when it gets enabled.
664 virtual void InvalidateTrigger() = 0;
667 //! Helper component for playing back audio on the current world-space position of an entity.
668 //! Wraps low-level CryAudio logic.
669 struct IEntityAudioComponent
: public IEntityComponent
671 CRY_ENTITY_COMPONENT_INTERFACE_GUID(IEntityAudioComponent
, "9824845c-fe37-7889-b172-4a63f331d8a2"_cry_guid
)
673 virtual void SetFadeDistance(float const fadeDistance
) = 0;
674 virtual float GetFadeDistance() const = 0;
675 virtual void SetEnvironmentFadeDistance(float const environmentFadeDistance
) = 0;
676 virtual float GetEnvironmentFadeDistance() const = 0;
677 virtual float GetGreatestFadeDistance() const = 0;
678 virtual void SetEnvironmentId(CryAudio::EnvironmentId
const environmentId
) = 0;
679 virtual CryAudio::EnvironmentId
GetEnvironmentId() const = 0;
680 //! Creates an additional audio object managed by this component, allowing individual handling of effects
681 //! IEntityAudioComponent will always create an audio object by default where audio will be played unless otherwise specified.
682 virtual CryAudio::AuxObjectId
CreateAudioAuxObject() = 0;
683 virtual bool RemoveAudioAuxObject(CryAudio::AuxObjectId
const audioAuxObjectId
) = 0;
684 virtual void SetAudioAuxObjectOffset(Matrix34
const& offset
, CryAudio::AuxObjectId
const audioAuxObjectId
= CryAudio::DefaultAuxObjectId
) = 0;
685 virtual Matrix34
const& GetAudioAuxObjectOffset(CryAudio::AuxObjectId
const audioAuxObjectId
= CryAudio::DefaultAuxObjectId
) = 0;
686 virtual bool PlayFile(CryAudio::SPlayFileInfo
const& playbackInfo
, CryAudio::AuxObjectId
const audioAuxObjectId
= CryAudio::DefaultAuxObjectId
, CryAudio::SRequestUserData
const& userData
= CryAudio::SRequestUserData::GetEmptyObject()) = 0;
687 virtual void StopFile(char const* const szFile
, CryAudio::AuxObjectId
const audioAuxObjectId
= CryAudio::DefaultAuxObjectId
) = 0;
688 //! Executes the specified trigger on the entity
689 //! \param audioTriggerId The trigger we want to execute
690 //! \param audioAuxObjectId Audio object within the component that we want to set, see IEntityAudioComponent::CreateAudioAuxObject. If not provided it is played on the default object.
692 //! \include CryEntitySystem/Examples/Audio/ExecuteTrigger.cpp
693 virtual bool ExecuteTrigger(CryAudio::ControlId
const audioTriggerId
, CryAudio::AuxObjectId
const audioAuxObjectId
= CryAudio::DefaultAuxObjectId
, CryAudio::SRequestUserData
const& userData
= CryAudio::SRequestUserData::GetEmptyObject()) = 0;
694 virtual void StopTrigger(CryAudio::ControlId
const audioTriggerId
, CryAudio::AuxObjectId
const audioAuxObjectId
= CryAudio::DefaultAuxObjectId
, CryAudio::SRequestUserData
const& userData
= CryAudio::SRequestUserData::GetEmptyObject()) = 0;
695 //! Sets the current state of a switch in the entity
696 //! \param audioSwitchId Identifier of the switch whose state we want to change
697 //! \param audioStateId Identifier of the switch state we want to set to
698 //! \param audioAuxObjectId Audio object within the component that we want to set, see IEntityAudioComponent::CreateAudioAuxObject. If not provided it is played on the default object.
700 //! \include CryEntitySystem/Examples/Audio/SetSwitchState.cpp
701 virtual void SetSwitchState(CryAudio::ControlId
const audioSwitchId
, CryAudio::SwitchStateId
const audioStateId
, CryAudio::AuxObjectId
const audioAuxObjectId
= CryAudio::DefaultAuxObjectId
) = 0;
702 //! Sets the value of the specified parameter on the entity
703 //! \param parameterId Identifier of the parameter we want to modify the value of
704 //! \param audioAuxObjectId Audio object within the component that we want to set, see IEntityAudioComponent::CreateAudioAuxObject. If not provided it is played on the default object.
706 //! \include CryEntitySystem/Examples/Audio/SetParameterValue.cpp
707 virtual void SetParameter(CryAudio::ControlId
const parameterId
, float const value
, CryAudio::AuxObjectId
const audioAuxObjectId
= CryAudio::DefaultAuxObjectId
) = 0;
708 virtual void SetObstructionCalcType(CryAudio::EOcclusionType
const occlusionType
, CryAudio::AuxObjectId
const audioAuxObjectId
= CryAudio::DefaultAuxObjectId
) = 0;
709 virtual void SetEnvironmentAmount(CryAudio::EnvironmentId
const audioEnvironmentId
, float const amount
, CryAudio::AuxObjectId
const audioAuxObjectId
= CryAudio::DefaultAuxObjectId
) = 0;
710 virtual void SetCurrentEnvironments(CryAudio::AuxObjectId
const audioAuxObjectId
= CryAudio::DefaultAuxObjectId
) = 0;
711 virtual void AudioAuxObjectsMoveWithEntity(bool const bCanMoveWithEntity
) = 0;
712 virtual void AddAsListenerToAudioAuxObject(CryAudio::AuxObjectId
const audioAuxObjectId
, void (* func
)(CryAudio::SRequestInfo
const* const), CryAudio::ESystemEvents
const eventMask
) = 0;
713 virtual void RemoveAsListenerFromAudioAuxObject(CryAudio::AuxObjectId
const audioAuxObjectId
, void (* func
)(CryAudio::SRequestInfo
const* const)) = 0;
714 virtual CryAudio::AuxObjectId
GetAuxObjectIdFromAudioObject(CryAudio::IObject
* pObject
) = 0;
717 //! Type of an area managed by IEntityAreaComponent.
720 ENTITY_AREA_TYPE_SHAPE
, //!< Area type is a closed set of points forming shape.
721 ENTITY_AREA_TYPE_BOX
, //!< Area type is a oriented bounding box.
722 ENTITY_AREA_TYPE_SPHERE
, //!< Area type is a sphere.
723 ENTITY_AREA_TYPE_GRAVITYVOLUME
, //!< Area type is a volume around a bezier curve.
724 ENTITY_AREA_TYPE_SOLID
//!< Area type is a solid which can have any geometry figure.
727 //! Area component allow for entity to host an area trigger.
728 //! Area can be shape, box or sphere, when marked entities cross this area border,
729 //! it will send ENTITY_EVENT_ENTERAREA, ENTITY_EVENT_LEAVEAREA, and ENTITY_EVENT_AREAFADE
730 //! events to the target entities.
731 struct IEntityAreaComponent
: public IEntityComponent
733 CRY_ENTITY_COMPONENT_INTERFACE_GUID(IEntityAreaComponent
, "98eda61f-de8b-e2b1-a1ca-2a88e4eede66"_cry_guid
)
735 enum EAreaComponentFlags
737 FLAG_NOT_UPDATE_AREA
= BIT(1), //!< When set points in the area will not be updated.
738 FLAG_NOT_SERIALIZE
= BIT(2) //!< Areas with this flag will not be serialized.
742 virtual void SetFlags(int nAreaComponentFlags
) = 0;
745 virtual int GetFlags() = 0;
747 //! Retrieve area type.
748 //! \return One of EEntityAreaType enumerated types.
749 virtual EEntityAreaType
GetAreaType() const = 0;
751 //! Get the actual area referenced by this component.
752 virtual struct IArea
* GetArea() const = 0;
754 //! Sets area to be a shape, and assign points to this shape.
755 //! Points are specified in local entity space, shape will always be constructed in XY plane,
756 //! lowest Z of specified points will be used as a base Z plane.
757 //! If fHeight parameter is 0, shape will be considered 2D shape, and during intersection Z will be ignored
758 //! If fHeight is not zero shape will be considered 3D and will accept intersection within vertical range from baseZ to baseZ+fHeight.
759 //! \param pPoints Array of 3D vectors defining shape vertices.
760 //! \param pSoundObstructionSegments Array of corresponding booleans that indicate sound obstruction.
761 //! \param numLocalPoints Number of vertices in vPoints array.
762 //! \param height Height of the shape.
763 virtual void SetPoints(Vec3
const* const pPoints
, bool const* const pSoundObstructionSegments
, size_t const numLocalPoints
, bool const bClosed
, float const height
) = 0;
765 //! Sets area to be a Box, min and max must be in local entity space.
766 //! Host entity orientation will define the actual world position and orientation of area box.
767 virtual void SetBox(const Vec3
& min
, const Vec3
& max
, const bool* const pabSoundObstructionSides
, size_t const nSideCount
) = 0;
769 //! Sets area to be a Sphere, center and radius must be specified in local entity space.
770 //! Host entity world position will define the actual world position of the area sphere.
771 virtual void SetSphere(const Vec3
& vCenter
, float fRadius
) = 0;
773 //! This function need to be called before setting convex hulls for a AreaSolid.
774 //! Then AddConvexHullSolid() function is called as the number of convexhulls consisting of a geometry.
775 //! \see AddConvexHullToSolid, EndSettingSolid
776 virtual void BeginSettingSolid(const Matrix34
& worldTM
) = 0;
778 //! Add a convex hull to a solid. This function have to be called after calling BeginSettingSolid()
779 //! \see BeginSettingSolid, EndSettingSolid
780 virtual void AddConvexHullToSolid(const Vec3
* verticesOfConvexHull
, bool bObstruction
, int numberOfVertices
) = 0;
782 //! Finish setting a solid geometry. Generally the BSPTree based on convex hulls which is set before is created in this function.
783 //!\see BeginSettingSolid, AddConvexHullToSolid
784 virtual void EndSettingSolid() = 0;
786 //! Retrieve number of points for shape area, return 0 if not area type is not shape.
787 virtual int GetPointsCount() = 0;
789 //! Retrieve array of points for shape area, will return NULL for all other area types.
790 virtual const Vec3
* GetPoints() = 0;
792 //! Set shape area height, if height is 0 area is 2D.
793 virtual void SetHeight(float const value
) = 0;
795 //! Retrieve shape area height, if height is 0 area is 2D.
796 virtual float GetHeight() const = 0;
798 //! Retrieve min and max in local space of area box.
799 virtual void GetBox(Vec3
& min
, Vec3
& max
) = 0;
801 //! Retrieve center and radius of the sphere area in local space.
802 virtual void GetSphere(Vec3
& vCenter
, float& fRadius
) = 0;
804 virtual void SetGravityVolume(const Vec3
* pPoints
, int nNumPoints
, float fRadius
, float fGravity
, bool bDontDisableInvisible
, float fFalloff
, float fDamping
) = 0;
806 //! Set area ID, this id will be provided to the script callback OnEnterArea, OnLeaveArea.
807 virtual void SetID(const int id
) = 0;
809 //! Retrieve area ID.
810 virtual int GetID() const = 0;
812 //! Set area group id, areas with same group id act as an exclusive areas.
813 //! If 2 areas with same group id overlap, entity will be considered in the most internal area (closest to entity).
814 virtual void SetGroup(const int id
) = 0;
816 //! Retrieve area group id.
817 virtual int GetGroup() const = 0;
819 //! Set priority defines the individual priority of an area,
820 //! Area with same group id will depend on which has the higher priority
821 virtual void SetPriority(const int nPriority
) = 0;
823 //! Retrieve area priority.
824 virtual int GetPriority() const = 0;
826 //! Sets sound obstruction depending on area type
827 virtual void SetSoundObstructionOnAreaFace(size_t const index
, bool const bObstructs
) = 0;
829 //! Add target entity to the area.
830 //! When someone enters/leaves an area, it will send ENTERAREA, LEAVEAREA, AREAFADE, events to these target entities.
831 virtual void AddEntity(EntityId id
) = 0;
833 //! Add target entity to the area.
834 //! When someone enters/leaves an area, it will send ENTERAREA, LEAVEAREA, AREAFADE, events to these target entities.
835 virtual void AddEntity(EntityGUID guid
) = 0;
837 //! Remove target entity from the area.
838 //! When someone enters/leaves an area, it will send ENTERAREA, LEAVEAREA, AREAFADE, events to these target entities.
839 virtual void RemoveEntity(EntityId
const id
) = 0;
841 //! Remove target entity from the area.
842 //! When someone enters/leaves an area, it will send ENTERAREA ,LEAVEAREA, AREAFADE, events to these target entities.
843 virtual void RemoveEntity(EntityGUID
const guid
) = 0;
845 //! Removes all added target entities.
846 virtual void RemoveEntities() = 0;
848 //! Set area proximity region near the border.
849 //! When someone is moving within this proximity region from the area outside border
850 //! Area will generate ENTITY_EVENT_AREAFADE event to the target entity, with a fade ratio from 0, to 1.
851 //! Where 0 will be at the area outside border, and 1 inside the area in distance fProximity from the outside area border.
852 virtual void SetProximity(float fProximity
) = 0;
854 //! Retrieves area proximity.
855 virtual float GetProximity() = 0;
857 //! Compute and return squared distance to a point which is outside
858 //! OnHull3d is the closest point on the hull of the area
859 virtual float CalcPointNearDistSq(EntityId
const nEntityID
, Vec3
const& Point3d
, Vec3
& OnHull3d
) = 0;
861 //! Computes and returns squared distance from a point to the hull of the area
862 //! OnHull3d is the closest point on the hull of the area
863 //! This function is not sensitive of if the point is inside or outside the area
864 virtual float ClosestPointOnHullDistSq(EntityId
const nEntityID
, Vec3
const& Point3d
, Vec3
& OnHull3d
) = 0;
866 //! Checks if a given point is inside the area.
867 //! \note Ignoring the height speeds up the check.
868 virtual bool CalcPointWithin(EntityId
const nEntityID
, Vec3
const& Point3d
, bool const bIgnoreHeight
= false) const = 0;
870 //! get number of entities in area
871 virtual size_t GetNumberOfEntitiesInArea() const = 0;
873 //! get entity in area by index
874 virtual EntityId
GetEntityInAreaByIdx(size_t const index
) const = 0;
876 //! Retrieve inner fade distance of this area.
877 virtual float GetInnerFadeDistance() const = 0;
879 //! Set this area's inner fade distance.
880 virtual void SetInnerFadeDistance(float const distance
) = 0;
883 struct IClipVolumeComponent
: public IEntityComponent
885 CRY_ENTITY_COMPONENT_INTERFACE_GUID(IClipVolumeComponent
, "92bc520e-aaa2-b3f0-9095-087aee67d9ff"_cry_guid
)
887 virtual void SetGeometryFilename(const char* sFilename
) = 0;
888 virtual void UpdateRenderMesh(IRenderMesh
* pRenderMesh
, const DynArray
<Vec3
>& meshFaces
) = 0;
889 virtual IClipVolume
* GetClipVolume() const = 0;
890 virtual IBSPTree3D
* GetBspTree() const = 0;
891 virtual void SetProperties(bool bIgnoresOutdoorAO
) = 0;
894 //! Flow Graph component allows entity to host reference to the flow graph.
895 struct IEntityFlowGraphComponent
: public IEntityComponent
897 CRY_ENTITY_COMPONENT_INTERFACE_GUID(IEntityFlowGraphComponent
, "17e5eba7-57e4-4662-a1c2-1f41de946cda"_cry_guid
)
899 virtual void SetFlowGraph(IFlowGraph
* pFlowGraph
) = 0;
900 virtual IFlowGraph
* GetFlowGraph() = 0;
903 //! Substitution component remembers IRenderNode this entity substitutes and unhides it upon deletion
904 struct IEntitySubstitutionComponent
: public IEntityComponent
906 CRY_ENTITY_COMPONENT_INTERFACE_GUID(IEntitySubstitutionComponent
, "429b0bce-2947-49d9-a458-df6faee6830c"_cry_guid
)
908 virtual void SetSubstitute(IRenderNode
* pSubstitute
) = 0;
909 virtual IRenderNode
* GetSubstitute() = 0;
912 //! Represents entity camera.
913 struct IEntityCameraComponent
: public IEntityComponent
915 CRY_ENTITY_COMPONENT_INTERFACE_GUID(IEntityCameraComponent
, "9da92df2-37d7-4d2f-b64f-b827fcecfdd3"_cry_guid
)
917 virtual void SetCamera(CCamera
& cam
) = 0;
918 virtual CCamera
& GetCamera() = 0;
921 //! Interface to the rope component, providing support for creating a rendered and physical rope on the entity position
923 //! \include CryEntitySystem/Examples/RopeComponent.cpp
924 struct IEntityRopeComponent
: public IEntityComponent
926 CRY_ENTITY_COMPONENT_INTERFACE_GUID(IEntityRopeComponent
, "368e5dcd-0d95-4101-b1f9-da514945f40c"_cry_guid
)
928 virtual struct IRopeRenderNode
* GetRopeRenderNode() = 0;
933 struct IResponseActor
;
934 struct IVariableCollection
;
935 typedef std::shared_ptr
<IVariableCollection
> IVariableCollectionSharedPtr
;
938 //! Component for dynamic response system actors.
939 struct IEntityDynamicResponseComponent
: public IEntityComponent
941 CRY_ENTITY_COMPONENT_INTERFACE_GUID(IEntityDynamicResponseComponent
, "67994647-83dd-41b8-a098-e26b4b2c95fd"_cry_guid
)
943 virtual void ReInit(const char* szName
, const char* szGlobalVariableCollectionToUse
) = 0;
944 virtual DRS::IResponseActor
* GetResponseActor() const = 0;
945 virtual DRS::IVariableCollection
* GetLocalVariableCollection() const = 0;
948 //! Component interface for GeomEntity to work in the CreateObject panel
949 struct IGeometryEntityComponent
: public IEntityComponent
951 CRY_ENTITY_COMPONENT_INTERFACE_GUID(IGeometryEntityComponent
, "54b2c130-8e27-4e07-8bf0-f1fe89228d14"_cry_guid
)
953 virtual void SetGeometry(const char* szFilePath
) = 0;
956 //! Component interface for ParticleEntity to work in the CreateObject panel
957 struct IParticleEntityComponent
: public IEntityComponent
959 CRY_ENTITY_COMPONENT_INTERFACE_GUID(IParticleEntityComponent
, "68e3655d-ddd3-4390-aad5-448264e74461"_cry_guid
)
961 virtual void SetParticleEffectName(const char* szEffectName
) = 0;