Using the Plugin - Pottus/ColAndreas GitHub Wiki

San Andreas Map

There are three main functions in this entire library that handle the San Andreas native map, CA_Init, CA_RemoveBuilding and CA_RestoreBuilding. They are all really easy to use as long as you are using them in the right order.

The SA map is not loaded by default, you must use CA_Init to do that. That is all the function does.

If you remove buildings from the SA map and there collision should not be loaded, you must use CA_RemoveBuilding before loading the map with CA_Init.

If you restore removed buildings from the SA map and there collision should still be loaded, you must use CA_RestoreBuilding after loading the map with CA_Init.

There's also CA_RemoveBarriers to remove all of the native SA barriers (that block the bridges and other areas) and CA_RemoveBreakableBuildings to remove fences, haystacks, and other breakable objects. ColAndreas can't detect when these objects are broken, so you must use this function if you don't want floating collisions when they break.

Object Manager

Notice, in the include there wrapper functions for creating _SC and _DC objects. These functions represent the object manager provided by the include. These are NOT REQUIRED for creating the collisions! These are simply wrapper functions for CA_CreateObject, SA-MP's CreateObject, and Streamer's CreateDynamicObject.

I will explain the difference between CA_CreateObject, CA_CreateObject_DC, CA_CreateObject_SC, CA_CreateDynamicObject_DC, and CA_CreateDynamicObject_SC.

  • ColAndreas Collision Manager

    • These are the internal plugin functions that handle the collision mesh used by ColAndreas. These do NOT handle the server map, they only handle the map in the ColAndreas plugin.

    • CA_CreateObject

      • This function creates ONLY the ColAndreas collision. When using this function, ColAndreas will add the specified model's mesh to it's map.
      • Important note, this functions add parameter controls whether the ColAndreas collision will be stored with an accessible ID or not.
        • When set to true, you can store the collision's index and use that to delete, move, or access information from the collision.
        • When false, the collision is added to the ColAndreas and cannot be removed. This would be used for example when the object is not going to be moved or deleted like the SA map when loaded by CA_Init.

    • CA_DestroyObject

      • Use this to destroy the collision created by CA_CreateObject.
      • This will only destroy the collision, not an object.
      • Only works if the add parameter was enabled.

    • CA_SetObjectPos and CA_SetObjectRot

      • These are the only functions that are able to edit the collision data without removing or deleting a collision. They work just like the SA-MP SetObjectPos or Rot, except they only work for the collision and not an object.

  • ColAndreas Object Wrappers

    • These all use the object manager provided in the include. They eliminate the need to use the CA_Create/DestroyObject functions. Use these to create either a regular SA-MP object or Streamer object, as well as the ColAndreas collision.

    • CA_CreateObject_DC and CA_CreateDynamicObject_DC

      • Since these functions are appended by _DC, the collisions are created with the add parameter being true.
      • These collisions and objects can be destroyed and accessed like regular objects.

    • CA_DestroyObject_DC and CA_DestroyDynamicObject_DC

      • TODO

    • CA_DestroyAllObjects_DC and CA_DestroyDynamicObject_DC

      • TODO

    • CA_CreateObject_SC and CA_CreateDynamicObject_SC

      • These functions work just like the _DC functions, however...
      • Since these are appended by _SC, the collisions are created with the add parameter being false.
      • These return the objects ID, but the collision is not managed with the object. If you destroy these objects, the collision will remain in the ColAndreas map.
      • As mentioned before, this would be for objects that you do not plan on moving or destroying. Like CA_Init.

    • CA_SetObjectPos_DC and CA_SetObjectRot_DC

      • Use these to move or rotate objects handled by the _DC functions. They will not work for static _SC functions.
      • These functions will rotate both, the server object and the ColAndreas collision.

Collision Functions

Raycasting

Raycasting is most basically the process of detecting a face between two points. ColAndreas provides mutliple functions to do so, each of which will tell you the exact point that was collided.

  • CA_RayCastLine
    • The main function. This is basically the point of the entire plugin, in one function. If you don't know which of these to use, this is probably the one you're looking for. Each of the following work like this one, but with added functionalities.
  • CA_RayCastLineID
    • Use this if you would like to detect the ID of the collided collision object. Only works for add collisions.
  • CA_RayCastLineExtraID
  • CA_RayCastMultiLine
    • This is basically a series of CA_RayCastLine calls. This would be used if you wanted to for example, detect the width of a wall or detect collisions beyond said wall.
  • CA_RayCastLineAngle
    • This works exactly like the main function, but also has parameters that store the X and Y angles needed to rotate an object to be perpendicular with the collided surface.
  • CA_RayCastReflectionVector
    • This works exactly like the main function, but also has parameters that store the normalized reflecting vector of the ray against the collided surface.
    • For example, if you were to shine a laser on a mirror, this function can be used to determine where the laser will land.
  • CA_RayCastLineNormal
    • This works exactly like the main function, but also has parameters that store the normalized normal vector of the collided surface.
    • For example, a flat ground would be [0, 0, 1], because that would be facing upwards.
  • CA_RayCastLineEx and CA_RayCastLineAngleEx
    • These both work like there normal counterparts, but also include parameters holding the collided objects position and rotation.
  • CA_RayCastExplode
    • It casts rays in ALL directions. It's basically CA_GetRoomCenter but instead of returning the center of 3 points it returns every collided point as an array.
    • This could be used for example, calculating the size of a room instead of just the center as CA_GetRoomCenter does.

Contact Test

  • CA_ContactTest
    • The contact testing function deserves it's own section, it's a bit different from the rest. CA_ContactTest is another way of testing collisions, without the line-of-sight limitation. Instead of using a ray, this function uses an object model.
    • For example, if you had an in-game house furniture editor. Say you wanted to be able to place a couch, but it must be within the walls of the house. You can run a CA_ContactTest using that couch model, current position, and current rotation and it will tell you whether this object collides with the ColAndreas world or not.

Extra ID's

We wanted to give the server just a bit more insight on collided-object information, so extra ID's were born. You can use Extra ID's to store information such as bit-flags or anything. For example, you could store the object's streamer ID in Extra ID 0 and be able to obtain that information during a raycast. The functions to set and alternatively retrieve this information are described below. These only work for add objects (or _DC objects if you use the wrappers).

  • CA_SetObjectExtraID
    • Use this to set a ColAndreas collision's extra ID's.
    • Extra ID's only range from 0 to 9, so you get a total of 10 data variables.
    • The data in these variables is a regular 32bit integer.
  • CA_GetObjectExtraID
    • Use this to retrieve the extra data using the collision's stored index instead of CA_RayCastLineExtraID.

Model Sizes

This plugin also includes it's very own functions to retrieve the size of object models. These are just like the old modelsizes.inc, but MUCH more precise and MUCH faster. In fact, I've release a new version of that model sizes library using these values. In that release I presented just (how far off)[https://github.com/Crayder/Model-Sizes-Plus/blob/master/README.md#extra] the old values were.

  • CA_GetModelBoundingSphere
    • This will return the exact radius and offset of the model's collision.
  • CA_GetModelBoundingBox
    • This returns coordinates to put a box perfectly around the given model. Google "bounding box" or "AABB" for more information if needed.