Handleables

[This is preliminary documentation and is subject to change.]

A handleable may become invalid, so before using it, it's important to ensure it's still valid.
For example, if a plugin spawns a Vehicle, then yields,
another plugin, or the game may remove it in the mean time, and thus, any further access by the plugin will fail.

If the handleable you're working with may have been deleted since the last time you accessed it, you should validate it.
For example, if you yield your plugin, other fibers in your plugin, another plugin, or the game may delete it; so you should always validate a handleable after yielding. Also be sure to validate or not access a handleable if you have code that may delete it, even without yielding; for example:

vehicle.Explode();
DeleteVehicleIfExploded(vehicle);

// This will fail (granted the custom method above does what it says).
vehicle.IsEngineOn = true;

When yielding, other fibers (including the game) may delete the handleable; so you should always validate handleables after yielding.

vehicle.Explode();

GameFiber.Sleep(3000);

// This may fail, as other fibers (including the game) has had time to delete the vehicle.
vehicle.IsEngineOn = true;

To verify that a handleable like Vehicle still represents a valid vehicle, IHandleable defines the method IsValid. Calling this method will return whether the handle is still valid.

This however, only verifies that the handle is valid, but not that the object reference is valid.
Therefore, you must also verify that the instance is not null in addition to the IsValid call.

if (vehicle != null && vehicle.IsValid())
{
}

As a convenience, the API defines the extension method Exists that can be used to avoid having to do a null and an IsValid call.
Since it's an extension method, passing null to it is fine. The extension method will verify both that the instance is not null, and that the handle is valid.

if (vehicle.Exists())
{
}

Furthermore, most (if not all) of the handleable types implement an implicit operator to a boolean. This means that casting a handleable to a boolean will result in a boolean that's true if the handleable is not null and has a valid handle.
This allows simply using the instance itself to check whether it's valid.

if (vehicle) // vehicle is implicitly converted to bool
{
}