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> <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> </div> <h2>Functions</h2> <div class="level2"> </div>