Frictional Game Wiki

<h1>Entity Components</h1> <div class="level1"> </div> <h2>Overview</h2> <div class="level2"> <p> What follows here is an overview of all the different entity components that are present. Entity components are used to extend the functionality of any derived <code>iLuxEntity</code> class. </p> <p> To add a module simply call the creation function in the SetupAfterLoad() call in the entity script file. It is often required to save a handle to the returned class as well. </p> </div> <h2>CharMover</h2> <div class="level2"> <p> <b>Creation function:</b> <code>cLuxCharMover@ cLux_CreateEntityComponent_CharMover(iLuxEntity @apEntity, iCharacterBody @apCharBody)</code> </p> </div> <h3>General</h3> <div class="level3"> <p> This is used to more easily move around a character body. It controls movement forward, rotation and very simple avoidance behaviors. </p> </div> <h2>PathFinder</h2> <div class="level2"> <p> <b>Creation function:</b> <code>cLuxPathFinder@ cLux_CreateEntityComponent_PathFinder(iLuxEntity @apEntity)</code> </p> </div> <h3>General</h3> <div class="level3"> <p> This is used to add pathfinding capabilities. It relies on Path nodes being placed in the map and usually works together with CharMover (but this is not needed). </p> </div> <h2>StateMachine</h2> <div class="level2"> <p> <b>Creation function:</b> <code>cLuxPathFinder@ cLux_CreateEntityComponent_StateMachine(iLuxEntity @apEntity)</code> </p> </div> <h3>General</h3> <div class="level3"> <p> This adds a state machine to the entity. It can be used for pretty much every thing but is mainly used for AI purposes. </p> <p> It is important to note that there can only be ONE statemachine in a class! </p> <p> To use the statemachine, you need to create states right after having created the module. It is very important that all states are always created in the same order for all entities using the same script file (basically meaning you should not dynamically create states during the update loop or similar). For instance: </p> <pre class="code c++">@mpStateMachine <span class="sy0">=</span> cLux_CreateEntityComponent_StateMachine<span class="br0">(</span>mBaseObj<span class="br0">)</span><span class="sy0">;</span> mpStateMachine.<span class="me1">AddState</span><span class="br0">(</span>"Idle"<span class="sy0">,</span> eState_Idle<span class="br0">)</span><span class="sy0">;</span> mpStateMachine.<span class="me1">AddState</span><span class="br0">(</span>"Move"<span class="sy0">,</span> eState_Move<span class="br0">)</span><span class="sy0">;</span> mpStateMachine.<span class="me1">AddState</span><span class="br0">(</span>"Stop"<span class="sy0">,</span> eState_Stop<span class="br0">)</span><span class="sy0">;</span> </pre><p> </p> <p> Every state has a couple of actions (methods really) that called in response to different events. These are: </p> <p> <b>Enter()</b><br/> Called when the state is started.<br/> <b>Leave()</b><br/> Called when the state is over. This is called before Enter of the new state!<br/> <b>Update(float afTimeStep)</b><br/> Called every update.<br/> <b>SubStateOver(int alSubStateId)</b><br/> Called when a sub state is over. More on substates below.<br/> <b>Message(int alMessageId)</b><br/> This is any entity message that is intercepted. Can also be a custom message.<br/> <b>TimerUp(int alTimerId)</b><br/> When a timer is over.<br/> </p> <p> For each state, each of these functions get a name based on the syntax like this:<br/> <code>void State_[StateName]_[Action]</code><br/> For instance the <code>Enter()</code> action in the state "Idle" is:<br/> </p> <pre class="code c++"><span class="kw4">void</span> State_Idle_Enter<span class="br0">(</span><span class="br0">)</span> </pre><p> </p> <p> <span class='np_break'> </span> <br/> Note that you only have to define the actions that you want, so for instance a Stop state might only be something like:<br/> </p> <pre class="code c++"><span class="kw4">void</span> State_Stop_Enter<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span> <span class="co1">//Stop the character</span> <span class="br0">}</span> <span class="kw4">void</span> State_Stop_Leave<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span> <span class="co1">//Make the character move again</span> <span class="br0">}</span> </pre><p> </p> <p> <span class='np_break'> </span> And skip Update, etc. (This is actually the best practice too!) </p> </div> <h3>Sub State</h3> <div class="level3"> <p> A sub state is just like a state that runs along side the normal state. What makes it different is that they only last as long as the state that started it. Also sub states cannot change the normal state, only what the next substate will be. It can be sort of seen a smaller state machine inside a state. The sub states are created just like normal states but using the <code>AddSubState(tString, int)</code> method instead. Also note that substates can be shared between all of the states. They only belong to the a state in the sense that a sub state started in state X will only run while state X is active. </p> <p> The function syntax for sub states is:<br/> <code>void SubState_[StateName]_[Action]</code> For example: </p> <pre class="code c++"><span class="kw4">void</span> SubState_ThrowObject_Enter<span class="br0">(</span><span class="br0">)</span> </pre><p> </p> <p> When a sub state is over, the state that started it has the action <code>SubStateOver(int alSubStateId)</code> called, where <code>alSubStateId</code> contains the id of the sub state. </p> <p> Sub state as all the same actions as the normal state except for SubStateOver(int alSubStateId) </p> <p> Another important feature of sub states is that there not has to be one set. So it is okay to do: </p> <pre class="code c++"> mpStateMachine.<span class="me1">ChangeSubState</span><span class="br0">(</span><span class="sy0">-</span><span class="nu0">1</span><span class="br0">)</span> </pre><p> </p> <p> <span class='np_break'> </span> which set no state at all as sub state. This is actually the default setting when ever a new normal state is started. </p> </div> <h3>Default State</h3> <div class="level3"> <p> The default state is a state that can be used by both normal states and sub states. To add it just write a state function with the name "Default" instead of a state name. (This means a state cannot be named "Default".) Then this function will be called if the current state does not contain it. So for instance if you have something like: </p> <pre class="code c++"><span class="kw4">void</span> State_Default_Update<span class="br0">(</span><span class="kw4">float</span> afTimeStep<span class="br0">)</span><span class="br0">{</span> ... <span class="br0">}</span>   <span class="kw4">void</span> State_State1_Update<span class="br0">(</span><span class="kw4">float</span> afTimeStep<span class="br0">)</span><span class="br0">{</span> ... <span class="br0">}</span> </pre><p> </p> <p> <span class='np_break'> </span> If the state machine is currently in <code>State1</code> then the <code>Update</code> for <code>State1</code> will be called. However, if the current state is <code>State2</code> and it does not have an implemention of <code>Update</code>, the <code>Default</code> version of <code>Update</code> will be called. </p> <p> There is a special case for <code>State_Default_Message</code>. This is also called if the state specific function returns false. </p> </div> <h3>Timers</h3> <div class="level3"> <p> Timers are used to check if a certain amount of time has passed. They are only valid for the state that started it, so if a timer is active when state changes, then it becomes removed. Also, state and sub state do not share timers. So if sub state "ThrowObject" starts a timer, then <code>TimerUp</code> will only be called in the sub state, and not the normal state. Timers are started with <code>StartTimer(int alId, float afTime)</code> in the state machine and can be stopped with <code>StopTimer(int alId)</code>. </p> </div> <h2>SoundListener</h2> <div class="level2"> <p> <b>Creation function:</b> <code>cLuxSoundListener @ cLux_CreateEntityComponent_SoundListener (iLuxEntity @apEntity)</code> </p> </div> <h3>General</h3> <div class="level3"> <p> This simply makes the entity into a sound listener and it will now receive the event message eLuxEntityMessage_SoundHeard whenever a sound of a specific type (specfied in "sounds/ai_reaction_sounds.dat"). </p> </div> <h2>HeadTracker</h2> <div class="level2"> <p> <b>Creation function:</b> <code>cLuxHeadTracker @ cLux_CreateEntityComponent_HeadTracker(iLuxEntity @apEntity)</code> </p> </div> <h3>General</h3> <div class="level3"> <p> This will make the entitie's head follow a certain target. What is the head is set b setting up the bones that makes up the neck and how much influence each should have. This is done using Setup(…) or by using the variables in the .ent file (use LoadFromVariables from the script to load the variables). </p> </div> <h2>ForceEmitter</h2> <div class="level2"> <p> <b>Creation function:</b> <code>cLuxForceEmitter @ cLux_CreateEntityComponent_ForceEmitter(iLuxEntity @apEntity)</code> </p> </div> <h3>General</h3> <div class="level3"> <p> This will give the entity a force field (cForceField) which makes certain things in the game world (such as undergrowth) animate and react to its presence . If MaxForceSpeed is higher than 0 it will also vary in strength depending on the speed of the MainBody (or character if set). </p> </div> <h2>BarkMachine</h2> <div class="level2"> <p> <b>Creation function:</b> <code>cLuxBarkMachine @ cLux_CreateEntityComponent_BarkMachine (iLuxEntity @apEntity)</code> </p> </div> <h3>General</h3> <div class="level3"> <p> This creates a component that can have one or more states with random sounds or voice quips (barks). It is meant to be used with entities that require different sounds/voices to be randomly played depending on which state it is in. </p> </div> <h2>BackboneTail</h2> <div class="level2"> <p> <b>Creation function:</b> <code>cLuxBackboneTail @ cLux_CreateEntityComponent_BackboneTail (iLuxEntity @apEntity)</code> </p> </div> <h3>General</h3> <div class="level3"> <p> When this is added, the backbone of the entity (as defined in the ent file) will be bent as the entity moves along. It is meant to be used by things like fishes, etc to get more natural like movement, but can of course be used for whatever. Note that all setup should be done in the ent file, and have the component load the type variables. </p> </div>