Frictional Game Wiki

<h1>ID Handles</h1> <div class="level1"> </div> <h2>General</h2> <div class="level2"> <p> <b>Storing</b> </p> <p> A ID handle is used to store and retrieve a object. Instead of storing the object handle directly the ID of the object should be stored. </p> <pre class="code">class cMyClass { iPhysicsBody@ mpBody; // unsafe tID mBodyID; // safe } </pre><p> </p> <p> Storing a ID instead of class handle is safer and allows for saving of the handle. </p> <pre class="code">void OnStart() { // Retrive the object from name and setup the id iPhysicsBody@ pBody = Map_GetEntityFromName("..."); mBodyID = pBody.GetID(); } </pre><p> </p> <p> The ID of a object is returned from the GetID() function or by calling one of the functions that return the ID of a object directly. </p> <p> <b>Accessing</b> </p> <p> After storing the ID it can be used to retrieve the object. Retrieving the object is safe and will return a null pointer if it has been deleted. </p> <pre class="code">void OnUpdate() { cLux_ID_Body(mBodyID).SetMass(2.0); // Retrieve object and set mass to 2.0 } </pre><p> </p> <p> Even if the body has been deleted elsewhere the code will not crash, since accessing a null pointer only generates a warning. </p> <p> Retrieving the object using the ID handle is very fast and can be used directly. When changing multiple properties of a object it is adviced to retrieve it once and then call all the function from the object itself. </p> <pre class="code">void OnUpdate() { // Retrieve the object iPhysicsBody@ pBody = cLux_ID_Body(mBodyID); if(pBody !is null) { // Check if it is valid pBody.SetMass(2.0); pBody.ApplyForce(cVector3f(1.0, 0.0 ,0.0); } } </pre><p> </p> <p> The retrieval functions perform safe cast. The ID for a Prop can be used to retrieve a Entity, but if you use it to try to retrieve a Area then it will return null. </p> <p> <b>Default Value</b> </p> <p> The default value of the tID class is tID_Invalid. Calling any retrieval function with that value will cause the function to return null. When a handle is no longer in use it should have its value set to tID_Invalid. </p> <p> <b>Saving and loading</b> </p> <p> A ID handle can be saved to the save file and it will retrieve the same object after load. The ID will also stay the same when working on the map which means that the save file will stay valid even after a patch on a map. This will also work with the realtime reload of the entity maptrack. </p> </div> <h2>Functions</h2> <div class="level2"> <pre class="file">iEntity3D@ cLux_IDEntity3D(tID aID); cMeshEntity@ cLux_IDMeshEntity(tID aID); cSubMeshEntity@ cLux_IDSubMeshEntity(tID aID); iLight@ cLux_IDLight(tID aID); cLightMaskBox@ cLux_IDLightMaskBox(tID aID); cBillboard@ cLux_IDBillboard(tID aID); cBillboardGroup@ cLux_IDBillboardGroup(tID aID); cLensFlare@ cLux_IDLensFlare(tID aID); cBeam@ cLux_IDBeam(tID aID); cParticleSystem@ cLux_IDParticleSystem(tID aID); cGuiSetEntity@ cLux_IDGuiSetEntity(tID aID); iRopeEntity@ cLux_IDRopeEntity(tID aID); cClothEntity@ cLux_IDClothEntity(tID aID); cFogArea@ cLux_IDFogArea(tID aID); cExposureArea@ cLux_IDExposureArea(tID aID); cForceField@ cLux_IDForceField(tID aID); cSoundEntity@ cLux_IDSoundEntity(tID aID); iPhysicsBody@ cLux_IDPhysicsBody(tID aID); iPhysicsJoint@ cLux_IDPhysicsJoint(tID aID); iCharacterBody@ cLux_IDCharacterBody(tID aID); iLuxEntity@ cLux_IDEntity(tID aID); cLuxProp@ cLux_IDProp(tID aID); cLuxArea@ cLux_IDArea(tID aID); cLuxLiquidArea@ cLux_IDLiquidArea(tID aID); cLuxReverbArea@ cLux_IDReverbArea(tID aID); cLuxCritter@ cLux_IDCritter(tID aID); cLuxAgent@ cLux_IDAgent(tID aID); </pre><p> </p> </div>