### Install Bullet libraries on Ubuntu

Source: https://github.com/pottus/colandreas/blob/master/readme.md

Install the required 32-bit Bullet physics libraries on an Ubuntu system to resolve shared object file errors.

```bash
sudo apt-get install libbulletcollision2.82:i386 libbulletdynamics2.82:i386 liblinearmath2.82:i386 libbulletsoftbody2.82:i386
```

--------------------------------

### Build ColAndreas from source on Debian

Source: https://github.com/pottus/colandreas/blob/master/readme.md

Commands to install dependencies and compile the ColAndreas plugin from source code on a Debian-based system.

```bash
sudo apt-get install libbullet-dev
sudo apt-get install cmake
cd ColAndreas-master
cmake -B build
cd build
make
```

--------------------------------

### Get Reflection Vector with CA_RayCastReflectionVector

Source: https://context7.com/pottus/colandreas/llms.txt

Calculates the reflection vector of a ray hitting a surface. Use this for simulating reflections or ricochets. Requires a raycast to determine the initial hit.

```pawn
CMD:laserreflect(playerid, params[])
{
    new Float:x, Float:y, Float:z, Float:fa;
    GetPlayerPos(playerid, x, y, z);
    GetPlayerFacingAngle(playerid, fa);

    new Float:dirX = floatsin(-fa, degrees);
    new Float:dirY = floatcos(-fa, degrees);
    new Float:endX = x + (100.0 * dirX);
    new Float:endY = y + (100.0 * dirY);

    new Float:hitX, Float:hitY, Float:hitZ;
    new Float:reflectX, Float:reflectY, Float:reflectZ;

    new modelid = CA_RayCastReflectionVector(x, y, z, endX, endY, z, hitX, hitY, hitZ, reflectX, reflectY, reflectZ);

    if(modelid > 0)
    {
        // Calculate where the reflected ray goes
        new Float:reflectEndX = hitX + (reflectX * 50.0);
        new Float:reflectEndY = hitY + (reflectY * 50.0);
        new Float:reflectEndZ = hitZ + (reflectZ * 50.0);

        // Cast the reflected ray
        new Float:hit2X, Float:hit2Y, Float:hit2Z;
        new modelid2 = CA_RayCastLine(hitX, hitY, hitZ, reflectEndX, reflectEndY, reflectEndZ, hit2X, hit2Y, hit2Z);

        new str[128];
        format(str, sizeof(str), "Laser hit model %d, reflected to model %d", modelid, modelid2);
        SendClientMessage(playerid, -1, str);
    }
    return 1;
}
```

--------------------------------

### Get Object Info with CA_RayCastLineEx

Source: https://context7.com/pottus/colandreas/llms.txt

Performs an extended raycast that returns the collided object's position and quaternion rotation. Use this to identify specific object instances and their transformations.

```pawn
CMD:objectinfo(playerid, params[])
{
    new Float:x, Float:y, Float:z, Float:fa;
    GetPlayerPos(playerid, x, y, z);
    GetPlayerFacingAngle(playerid, fa);

    new Float:endX = x + (100.0 * floatsin(-fa, degrees));
    new Float:endY = y + (100.0 * floatcos(-fa, degrees));

    new Float:hitX, Float:hitY, Float:hitZ;
    new Float:quatX, Float:quatY, Float:quatZ, Float:quatW;
    new Float:objX, Float:objY, Float:objZ;

    new modelid = CA_RayCastLineEx(x, y, z, endX, endY, z, hitX, hitY, hitZ,
        quatX, quatY, quatZ, quatW, objX, objY, objZ);

    if(modelid > 0)
    {
        new str[128];
        format(str, sizeof(str), "Hit model %d", modelid);
        SendClientMessage(playerid, -1, str);
        format(str, sizeof(str), "Object position: (%.2f, %.2f, %.2f)", objX, objY, objZ);
        SendClientMessage(playerid, -1, str);
        format(str, sizeof(str), "Object quaternion: (%.3f, %.3f, %.3f, %.3f)", quatX, quatY, quatZ, quatW);
        SendClientMessage(playerid, -1, str);
    }
    return 1;
}
```

--------------------------------

### Compile ColAndreas with Static Bullet on Linux

Source: https://github.com/pottus/colandreas/wiki/Instructions

Build ColAndreas while pointing CMake to a custom static Bullet installation.

```bash
git clone https://github.com/Pottus/ColAndreas.git
cd ColAndreas

mkdir build
cd build

cmake -DCMAKE_BUILD_TYPE=Release -DBULLET_ROOT=$(pwd)/../../bullet3-2.83.5/output ..
make -j4
```

--------------------------------

### Get All Collision Points with CA_RayCastMultiLine

Source: https://context7.com/pottus/colandreas/llms.txt

CA_RayCastMultiLine casts a ray and returns all collision points, not just the first. This is useful for determining wall thickness or detecting multiple objects in a line of sight. The function populates provided arrays with hit data and returns the number of hits.

```pawn
CMD:penetration(playerid, params[])
{
    new Float:x, Float:y, Float:z, Float:fa;
    GetPlayerPos(playerid, x, y, z);
    GetPlayerFacingAngle(playerid, fa);

    new Float:endX = x + (200.0 * floatsin(-fa, degrees));
    new Float:endY = y + (200.0 * floatcos(-fa, degrees));

    // Arrays to store multiple hit points
    new Float:hitX[10], Float:hitY[10], Float:hitZ[10];
    new Float:distances[10];
    new modelIds[10];

    new hits = CA_RayCastMultiLine(x, y, z, endX, endY, z, hitX, hitY, hitZ, distances, modelIds, 10);

    if(hits == -1)
    {
        SendClientMessage(playerid, -1, "Too many collision points!");
    }
    else if(hits == 0)
    {
        SendClientMessage(playerid, -1, "No collisions detected.");
    }
    else
    {
        new str[128];
        format(str, sizeof(str), "Found %d collision points:", hits);
        SendClientMessage(playerid, -1, str);

        for(new i = 0; i < hits; i++)
        {
            format(str, sizeof(str), "  Hit %d: Model %d at distance %.2f", i+1, modelIds[i], distances[i]);
            SendClientMessage(playerid, -1, str);
        }
    }
    return 1;
}
```

--------------------------------

### Get Surface and Object Rotation with CA_RayCastLineAngleEx

Source: https://context7.com/pottus/colandreas/llms.txt

An extended raycast that returns both the surface's rotation and the collided object's position and rotation in Euler angles. Useful for aligning objects to surfaces or understanding their orientation.

```pawn
CMD:aligntosurface(playerid, params[])
{
    new Float:x, Float:y, Float:z, Float:fa;
    GetPlayerPos(playerid, x, y, z);
    GetPlayerFacingAngle(playerid, fa);

    new Float:endX = x + (50.0 * floatsin(-fa, degrees));
    new Float:endY = y + (50.0 * floatcos(-fa, degrees));

    new Float:hitX, Float:hitY, Float:hitZ;
    new Float:surfRX, Float:surfRY, Float:surfRZ;
    new Float:objX, Float:objY, Float:objZ;
    new Float:objRX, Float:objRY, Float:objRZ;

    new modelid = CA_RayCastLineAngleEx(x, y, z, endX, endY, z, hitX, hitY, hitZ,
        surfRX, surfRY, surfRZ, objX, objY, objZ, objRX, objRY, objRZ);

    if(modelid > 0)
    {
        new str[128];
        format(str, sizeof(str), "Surface rotation: (%.2f, %.2f, %.2f)", surfRX, surfRY, surfRZ);
        SendClientMessage(playerid, -1, str);
        format(str, sizeof(str), "Object at (%.2f, %.2f, %.2f) rotated (%.2f, %.2f, %.2f)",
            objX, objY, objZ, objRX, objRY, objRZ);
        SendClientMessage(playerid, -1, str);
    }
    return 1;
}
```

--------------------------------

### Get Surface Normal with CA_RayCastLineNormal

Source: https://context7.com/pottus/colandreas/llms.txt

Retrieves the surface normal vector at the point of collision. Useful for determining surface orientation and for physics calculations. Casts a ray downwards by default in this example.

```pawn
CMD:surfaceinfo(playerid, params[])
{
    new Float:x, Float:y, Float:z;
    GetPlayerPos(playerid, x, y, z);

    // Cast ray straight down
    new Float:hitX, Float:hitY, Float:hitZ;
    new Float:normalX, Float:normalY, Float:normalZ;

    new modelid = CA_RayCastLineNormal(x, y, z, x, y, z - 100.0, hitX, hitY, hitZ, normalX, normalY, normalZ);

    if(modelid > 0)
    {
        new str[128];
        // A flat ground has normal (0, 0, 1) pointing straight up
        // A wall facing east has normal (1, 0, 0)
        format(str, sizeof(str), "Surface normal: (%.3f, %.3f, %.3f)", normalX, normalY, normalZ);
        SendClientMessage(playerid, -1, str);

        // Calculate slope angle
        new Float:slopeAngle = acos(normalZ); // Angle from vertical
        format(str, sizeof(str), "Surface slope: %.1f degrees", slopeAngle);
        SendClientMessage(playerid, -1, str);
    }
    return 1;
}
```

--------------------------------

### Build Bullet Physics on Windows

Source: https://github.com/pottus/colandreas/wiki/Instructions

Configure and build the Bullet library using NMake on Windows.

```bash
mkdir build
cd build

# Choose a folder for installing the Bullet libraries and headers
# Change it to your preferred path
set BULLET=C:\libs\bullet

cmake -DBUILD_EXTRAS=OFF -DBUILD_BULLET3=OFF -DBUILD_UNIT_TESTS=OFF -DBUILD_BULLET2_DEMOS=OFF -DBUILD_CPU_DEMOS=OFF -DINSTALL_LIBS=ON -DCMAKE_INSTALL_PREFIX=%BULLET% -DCMAKE_BUILD_TYPE=Release -G "NMake Makefiles" ..

nmake
nmake install
```

--------------------------------

### Initialize ColAndreas in Pawn

Source: https://github.com/pottus/colandreas/wiki/Instructions

Call CA_Init within OnGameModeInit to load the SA world. Ensure building removal and restoration are handled correctly around the initialization call.

```pawn
public OnGameModeInit()
{
	// Objects need to be removed BEFORE calling CA_Init
	CA_RemoveBuilding();

	// Load the SA map
	CA_Init();

	// Create objects and add them to the simulation
	CA_CreateDynamicObjectEx_SC();

	// Objects need to be restored AFTER calling CA_Init
	CA_RestoreBuilding();

	return 1;
}
```

--------------------------------

### Get ColAndreas Object Index with CA_RayCastLineID

Source: https://context7.com/pottus/colandreas/llms.txt

Use CA_RayCastLineID to get the ColAndreas object index when a raycast hits an object created with the 'add' parameter set to true. Returns 0 for no collision and -1 for static objects or water.

```pawn
stock CheckObjectHit(playerid)
{
    new Float:x, Float:y, Float:z, Float:fa;
    GetPlayerPos(playerid, x, y, z);
    GetPlayerFacingAngle(playerid, fa);

    new Float:endX = x + (50.0 * floatsin(-fa, degrees));
    new Float:endY = y + (50.0 * floatcos(-fa, degrees));
    new Float:hitX, Float:hitY, Float:hitZ;

    new caIndex = CA_RayCastLineID(x, y, z, endX, endY, z, hitX, hitY, hitZ);

    if(caIndex == 0) return -1; // No collision
    if(caIndex == -1) return -2; // Hit static object or water

    // caIndex is the ColAndreas object index - can be used with CA_DestroyObject etc.
    return caIndex;
}
```

--------------------------------

### Create Static and Dynamic Objects with Collision

Source: https://context7.com/pottus/colandreas/llms.txt

Demonstrates creating objects that cannot be moved or destroyed using CA_CreateObject_SC and CA_CreateDynamicObject_SC.

```pawn
public OnGameModeInit()
{
    CA_Init();

    // Create static objects with permanent collision
    // These return the SA-MP object ID, collision cannot be managed
    CA_CreateObject_SC(1225, 100.0, 200.0, 10.0, 0.0, 0.0, 0.0);
    CA_CreateObject_SC(1226, 105.0, 200.0, 10.0, 0.0, 0.0, 0.0);

    // With Streamer plugin
    CA_CreateDynamicObject_SC(1227, 110.0, 200.0, 10.0, 0.0, 0.0, 0.0);

    return 1;
}
```

--------------------------------

### CA_Init

Source: https://github.com/pottus/colandreas/wiki/Functions

Initializes the map data. Returns 1 if data is already loaded, 0 otherwise.

```APIDOC
## CA_Init

### Description
Initializes the map data. Returns 1 if data is already loaded, 0 otherwise.

### Method
N/A (Function Call)

### Endpoint
N/A

### Returns
- 0: No data loaded (e.g., data file not found).
- 1: Map successfully loaded or was already loaded.
```

--------------------------------

### Compile Static Bullet Physics on Linux

Source: https://github.com/pottus/colandreas/wiki/Instructions

Compile a 32-bit static version of Bullet Physics for use with ColAndreas on Linux.

```bash
# Getting the source code
wget https://github.com/bulletphysics/bullet3/archive/2.83.5.tar.gz
tar -xzvf 2.83.5.tar.gz
rm 2.83.5.tar.gz
cd bullet3-2.83.5

# Creating a build directory
mkdir build
cd build

# Make sure we generate 32bit code
export CFLAGS="-m32"
export CXXFLAGS="-m32"

# Running CMake
cmake -DBUILD_EXTRAS=OFF -DBUILD_BULLET3=OFF -DBUILD_UNIT_TESTS=OFF -DBUILD_BULLET2_DEMOS=OFF -DBUILD_CPU_DEMOS=OFF -DCMAKE_INSTALL_PREFIX=../output  ..

# Building and installing the project
make -j4
make install

# Going back to where we came from
cd ../..
```

--------------------------------

### CMake configuration for Qt5 project

Source: https://github.com/pottus/colandreas/blob/master/WizardApp/CMakeLists.txt

Configures the build environment for a Qt5 application, including source file discovery, resource compilation, and platform-specific linking.

```cmake
cmake_minimum_required (VERSION 2.8.11)
cmake_policy(SET CMP0020 NEW)

find_package(Qt5 COMPONENTS Core Gui Widgets)

if(NOT WIN32)
	set(CMAKE_C_FLAGS "")
	set(CMAKE_CXX_FLAGS "-std=c++11 -Wno-write-strings")
endif(NOT WIN32)

include_directories("${CMAKE_CURRENT_SOURCE_DIR}/include" "${CMAKE_BINARY_DIR}/WizardApp" ${Qt5Core_INCLUDE_DIRS} ${Qt5Gui_INCLUDE_DIRS} ${Qt5Widgets_INCLUDE_DIRS})

file(GLOB Wizard_SRC
	"src/*.c"
	"src/*.cpp"
)

file(GLOB Wizard_MOC
	"src/Qt*.cpp"
)

file(GLOB Wizard_UI
	"ui/*.ui"
)

if(WIN32)
	list(APPEND Wizard_SRC "Windows.rc")
endif()

qt5_wrap_cpp(Qt_MOC ${Wizard_MOC})
qt5_wrap_ui(Qt_UI ${Wizard_UI})
qt5_add_resources(Qt_RES "Resources.qrc")
add_executable(WizardApp ${Wizard_SRC} ${Qt_MOC} ${Qt_UI} ${Qt_RES})

if(NOT WIN32)
	target_link_libraries(WizardApp -pthread Qt5::Core Qt5::Gui Qt5::Widgets)
else()
	target_link_libraries(WizardApp Qt5::Core Qt5::Gui Qt5::Widgets ${_qt5_install_prefix}\\..\\qtpcre.lib ${_qt5_install_prefix}\\..\\qtfreetype.lib ${_qt5_install_prefix}\\..\\Qt5PlatformSupport.lib ${_qt5_install_prefix}\\..\\..\\plugins\\platforms\\qwindows.lib Winmm.lib Imm32.lib ws2_32.lib)
	set_target_properties(WizardApp PROPERTIES LINK_FLAGS "/SUBSYSTEM:WINDOWS /ENTRY:mainCRTStartup")
endif()
```

--------------------------------

### CA_Init

Source: https://context7.com/pottus/colandreas/llms.txt

Initializes and loads the San Andreas map collision data into ColAndreas. Must be called before using any raycast functions.

```APIDOC
## CA_Init

### Description
Initializes and loads the San Andreas map collision data into ColAndreas. Must be called before using any raycast functions. Buildings should be removed before this call and restored after.

### Response
- **result** (int) - Returns 1 on success, 0 if the data file is not found.
```

--------------------------------

### Generate ColAndreas Solution on Windows

Source: https://github.com/pottus/colandreas/wiki/Instructions

Generate the Visual Studio solution file for ColAndreas using CMake.

```bash
mkdir vs
cd vs

cmake -DBULLET_ROOT=%BULLET% ..
```

--------------------------------

### Get Surface Rotation with CA_RayCastLineAngle

Source: https://context7.com/pottus/colandreas/llms.txt

CA_RayCastLineAngle returns the rotation angles required to orient an object perpendicular to the surface hit by a raycast. This is ideal for placing decals, bullet holes, or any object that needs to align with a surface. The function returns the model ID of the hit object if successful.

```pawn
CMD:bullethole(playerid, params[])
{
    new Float:x, Float:y, Float:z, Float:fa;
    GetPlayerPos(playerid, x, y, z);
    GetPlayerFacingAngle(playerid, fa);

    new Float:endX = x + (50.0 * floatsin(-fa, degrees));
    new Float:endY = y + (50.0 * floatcos(-fa, degrees));

    new Float:hitX, Float:hitY, Float:hitZ;
    new Float:hitRX, Float:hitRY, Float:hitRZ;

    new modelid = CA_RayCastLineAngle(x, y, z, endX, endY, z, hitX, hitY, hitZ, hitRX, hitRY, hitRZ);

    if(modelid > 0)
    {
        // Create a bullet hole decal aligned to the surface
        CreateObject(19306, hitX, hitY, hitZ, hitRX, hitRY, hitRZ);

        new str[128];
        format(str, sizeof(str), "Created bullet hole at (%.2f, %.2f, %.2f) with rotation (%.2f, %.2f, %.2f)",
            hitX, hitY, hitZ, hitRX, hitRY, hitRZ);
        SendClientMessage(playerid, -1, str);
    }
    return 1;
}
```

--------------------------------

### Create Streamer Dynamic Collision Objects

Source: https://context7.com/pottus/colandreas/llms.txt

Creates Streamer plugin objects with ColAndreas collision. Requires the streamer include.

```pawn
#include <streamer>

CMD:dynamicobject(playerid, params[])
{
    new Float:x, Float:y, Float:z, Float:fa;
    GetPlayerPos(playerid, x, y, z);
    GetPlayerFacingAngle(playerid, fa);

    new Float:objX = x + (5.0 * floatsin(-fa, degrees));
    new Float:objY = y + (5.0 * floatcos(-fa, degrees));

    // Create dynamic object with collision
    new dcIndex = CA_CreateDynamicObject_DC(1225, objX, objY, z, 0.0, 0.0, 0.0);

    // Or with extended parameters
    new worlds[] = {0, 1}; // Visible in world 0 and 1
    new interiors[] = {0};
    new players[] = {-1}; // All players
    new STREAMER_TAG_AREA:areas[] = {STREAMER_TAG_AREA:-1};

    new dcIndex2 = CA_CreateDynamicObjectEx_DC(1225, objX, objY + 5.0, z, 0.0, 0.0, 0.0,
        STREAMER_OBJECT_SD, STREAMER_OBJECT_DD, worlds, interiors, players, areas);

    return 1;
}
```

--------------------------------

### Create Dynamic Collision Object

Source: https://context7.com/pottus/colandreas/llms.txt

Creates a visible SA-MP object and its ColAndreas collision, returning an internal index for management.

```pawn
new g_DCObjects[MAX_PLAYERS][10];

CMD:createbarrel(playerid, params[])
{
    new Float:x, Float:y, Float:z, Float:fa;
    GetPlayerPos(playerid, x, y, z);
    GetPlayerFacingAngle(playerid, fa);

    new Float:objX = x + (3.0 * floatsin(-fa, degrees));
    new Float:objY = y + (3.0 * floatcos(-fa, degrees));

    // Creates both the visible object AND collision
    new dcIndex = CA_CreateObject_DC(1218, objX, objY, z, 0.0, 0.0, 0.0, 300.0);

    if(dcIndex == -1)
    {
        SendClientMessage(playerid, -1, "Failed to create object!");
        return 1;
    }

    // Store for later management
    g_DCObjects[playerid][0] = dcIndex;

    new str[64];
    format(str, sizeof(str), "Created barrel with DC index: %d", dcIndex);
    SendClientMessage(playerid, -1, str);
    return 1;
}
```

--------------------------------

### Measure room height with CA_GetRoomHeight

Source: https://context7.com/pottus/colandreas/llms.txt

Calculates the vertical distance between the floor and ceiling at the player's current position.

```pawn
CMD:roomheight(playerid, params[])
{
    new Float:x, Float:y, Float:z;
    GetPlayerPos(playerid, x, y, z);

    new Float:height = CA_GetRoomHeight(x, y, z);

    if(height == 0.0)
    {
        SendClientMessage(playerid, -1, "No enclosed room detected (no floor or ceiling)");
    }
    else
    {
        new str[64];
        format(str, sizeof(str), "Room height: %.2f meters", height);
        SendClientMessage(playerid, -1, str);
    }
    return 1;
}
```

--------------------------------

### Clone and Build ColAndreas on Linux

Source: https://github.com/pottus/colandreas/wiki/Instructions

Standard procedure for cloning and building the dynamic version of ColAndreas on Linux.

```bash
git clone https://github.com/Pottus/ColAndreas.git
cd ColAndreas
```

```bash
mkdir build
cd build

# Replace "Release" with "Debug" if you want debug symbols
cmake -DCMAKE_BUILD_TYPE=Release ..
```

```bash
make -j4
```

--------------------------------

### Create Collision Objects with CA_CreateObject

Source: https://context7.com/pottus/colandreas/llms.txt

Creates collision data for objects in ColAndreas. Use `add=true` to create a managed object with an index for later manipulation, or `add=false` for static, unremovable collision.

```pawn
// Create static collision (cannot be removed)
stock CreateStaticCollision(modelid, Float:x, Float:y, Float:z, Float:rx, Float:ry, Float:rz)
{
    // add = false: collision is permanent, returns -1
    CA_CreateObject(modelid, x, y, z, rx, ry, rz, false);
}
```

```pawn
// Create managed collision (can be moved/destroyed)
new g_CollisionObjects[100];
new g_CollisionCount = 0;

stock CreateManagedCollision(modelid, Float:x, Float:y, Float:z, Float:rx, Float:ry, Float:rz)
{
    // add = true: collision can be managed, returns index
    new index = CA_CreateObject(modelid, x, y, z, rx, ry, rz, true);

    if(index >= 0)
    {
        g_CollisionObjects[g_CollisionCount] = index;
        g_CollisionCount++;
    }
    return index;
}
```

--------------------------------

### Initialize ColAndreas Map Data

Source: https://context7.com/pottus/colandreas/llms.txt

Initializes the map collision data. Must be called after removing buildings and before any raycast operations.

```pawn
public OnGameModeInit()
{
    // Remove buildings BEFORE CA_Init
    CA_RemoveBuilding(1220, 0.0, 0.0, 0.0, 4242.6407); // Remove specific model worldwide
    CA_RemoveBarriers(); // Remove all native SA barriers
    CA_RemoveBreakableBuildings(); // Remove breakable objects like fences

    // Initialize ColAndreas with the SA map
    new result = CA_Init();
    if(result == 0)
    {
        print("ERROR: ColAndreas data file not found!");
        return 0;
    }
    print("ColAndreas map loaded successfully!");

    // Restore buildings AFTER CA_Init if needed
    CA_RestoreBuilding(1220, 100.0, 200.0, 10.0, 50.0);

    return 1;
}
```

--------------------------------

### Calculate room center with CA_GetRoomCenter

Source: https://context7.com/pottus/colandreas/llms.txt

Determines the approximate center coordinates and radius of an enclosed room based on player position.

```pawn
CMD:roomcenter(playerid, params[])
{
    new Float:x, Float:y, Float:z;
    GetPlayerPos(playerid, x, y, z);

    new Float:centerX, Float:centerY;
    new Float:radius = CA_GetRoomCenter(x, y, z, centerX, centerY);

    if(radius == -1.0)
    {
        SendClientMessage(playerid, -1, "Cannot determine room center");
        return 1;
    }

    new str[64];
    format(str, sizeof(str), "Room center: (%.2f, %.2f), radius: %.2f", centerX, centerY, radius);
    SendClientMessage(playerid, -1, str);

    // Create marker at center
    CreateObject(19130, centerX, centerY, z, 0.0, 0.0, 0.0);
    return 1;
}
```

--------------------------------

### Load custom model collision with CA_LoadFromDff

Source: https://context7.com/pottus/colandreas/llms.txt

Loads collision data from a DFF file before initializing the plugin, enabling custom model support.

```pawn
public OnGameModeInit()
{
    // Load custom model collision before CA_Init
    new result = CA_LoadFromDff(50000, "models/custom_building.dff");

    if(result == -1)
    {
        print("ERROR: Could not open DFF file");
    }
    else if(result == 0)
    {
        print("WARNING: DFF has no collision data");
    }
    else
    {
        print("Custom model collision loaded successfully");
    }

    CA_Init();

    // Now create objects using the custom model
    CA_CreateObject(50000, 100.0, 200.0, 10.0, 0.0, 0.0, 0.0, false);
    return 1;
}
```

--------------------------------

### Manage Custom Object Extra IDs

Source: https://context7.com/pottus/colandreas/llms.txt

Shows how to store and retrieve custom integer data on ColAndreas objects using CA_SetObjectExtraID and CA_GetObjectExtraID.

```pawn
#define EXTRA_OWNER     CA_EXTRA_1  // Slot 0
#define EXTRA_TYPE      CA_EXTRA_2  // Slot 1
#define EXTRA_HEALTH    CA_EXTRA_3  // Slot 2
#define EXTRA_STREAMER  CA_EXTRA_4  // Slot 3

stock CreateTrackedBarricade(playerid, Float:x, Float:y, Float:z)
{
    new caIndex = CA_CreateObject(1228, x, y, z, 0.0, 0.0, 0.0, true);
    new objectId = CreateObject(1228, x, y, z, 0.0, 0.0, 0.0);

    // Store custom data
    CA_SetObjectExtraID(caIndex, EXTRA_OWNER, playerid);
    CA_SetObjectExtraID(caIndex, EXTRA_TYPE, 1); // 1 = barricade
    CA_SetObjectExtraID(caIndex, EXTRA_HEALTH, 100);
    CA_SetObjectExtraID(caIndex, EXTRA_STREAMER, objectId);

    return caIndex;
}

CMD:shootbarricade(playerid, params[])
{
    new Float:x, Float:y, Float:z, Float:fa;
    GetPlayerPos(playerid, x, y, z);
    GetPlayerFacingAngle(playerid, fa);

    new Float:endX = x + (50.0 * floatsin(-fa, degrees));
    new Float:endY = y + (50.0 * floatcos(-fa, degrees));
    new Float:hitX, Float:hitY, Float:hitZ;

    new caIndex = CA_RayCastLineID(x, y, z, endX, endY, z, hitX, hitY, hitZ);

    if(caIndex > 0)
    {
        // Retrieve stored data
        new owner = CA_GetObjectExtraID(caIndex, EXTRA_OWNER);
        new type = CA_GetObjectExtraID(caIndex, EXTRA_TYPE);
        new health = CA_GetObjectExtraID(caIndex, EXTRA_HEALTH);
        new objectId = CA_GetObjectExtraID(caIndex, EXTRA_STREAMER);

        if(type == 1) // Is barricade
        {
            health -= 25; // Deal damage

            if(health <= 0)
            {
                // Destroy barricade
                CA_DestroyObject(caIndex);
                DestroyObject(objectId);

                new str[64];
                format(str, sizeof(str), "You destroyed %s's barricade!", GetPlayerNameEx(owner));
                SendClientMessage(playerid, -1, str);
            }
            else
            {
                // Update health
                CA_SetObjectExtraID(caIndex, EXTRA_HEALTH, health);

                new str[64];
                format(str, sizeof(str), "Barricade hit! Health: %d", health);
                SendClientMessage(playerid, -1, str);
            }
        }
    }
    return 1;
}
```

--------------------------------

### CA_CreateObject

Source: https://github.com/pottus/colandreas/wiki/Functions

Creates a collision model.

```APIDOC
## CA_CreateObject

### Description
Creates a collision model (does not create the in-game object).

### Parameters
- **modelid** (int) - Required - Collision model ID
- **x, y, z** (Float) - Required - Position
- **rx, ry, rz** (Float) - Required - Rotation
- **add** (bool) - Optional - Whether to store index for management

### Response
- **Returns** (int) - Index of the created object or -1 on failure
```

--------------------------------

### Restore Building Collision

Source: https://context7.com/pottus/colandreas/llms.txt

Restores collision for previously removed models within a specified radius. Requires the map to be initialized.

```pawn
CMD:restorebuilding(playerid, params[])
{
    new Float:x, Float:y, Float:z;
    GetPlayerPos(playerid, x, y, z);

    // Restore model 1220 (fence) within 50 units of the player
    new result = CA_RestoreBuilding(1220, x, y, z, 50.0);
    if(result == 1)
    {
        SendClientMessage(playerid, -1, "Building collision restored!");
    }
    else
    {
        SendClientMessage(playerid, -1, "Map not initialized yet!");
    }
    return 1;
}
```

--------------------------------

### Detect Obstacles in Front of Player with CA_IsPlayerBlocked

Source: https://context7.com/pottus/colandreas/llms.txt

Detects if there is a wall or obstacle directly in front of the player. Useful for preventing players from moving through solid objects or walls.

```pawn
public OnPlayerKeyStateChange(playerid, newkeys, oldkeys)
{
    if(newkeys & KEY_SPRINT)
    {
        if(CA_IsPlayerBlocked(playerid, 1.0, 0.5))
        {
            // Player trying to run into wall - don't allow
            SendClientMessage(playerid, -1, "You can't go that way!");

            new Float:x, Float:y, Float:z;
            GetPlayerPos(playerid, x, y, z);
            SetPlayerPos(playerid, x, y, z); // Stop movement
        }
    }
    return 1;
}
```

--------------------------------

### Convert Euler Angles to Quaternions with CA_EulerToQuat

Source: https://context7.com/pottus/colandreas/llms.txt

Converts Euler angles (used by SA-MP) to Quaternions (used by Bullet Physics). Also demonstrates converting back from Quaternions to Euler angles using CA_QuatToEuler.

```pawn
stock ConvertRotation(Float:rx, Float:ry, Float:rz)
{
    new Float:qx, Float:qy, Float:qz, Float:qw;

    // Convert Euler to Quaternion
    CA_EulerToQuat(rx, ry, rz, qx, qy, qz, qw);

    printf("Euler (%.2f, %.2f, %.2f) = Quat (%.4f, %.4f, %.4f, %.4f)",
        rx, ry, rz, qx, qy, qz, qw);

    // Convert back to Euler
    new Float:ex, Float:ey, Float:ez;
    CA_QuatToEuler(qx, qy, qz, qw, ex, ey, ez);

    printf("Converted back: (%.2f, %.2f, %.2f)", ex, ey, ez);
}
```

--------------------------------

### Find Ground Z Coordinate with CA_FindZ_For2DCoord

Source: https://context7.com/pottus/colandreas/llms.txt

Maps any X,Y position to its ground Z coordinate. Useful for spawning vehicles or teleporting players to the ground. Works in all environments, including interiors.

```pawn
CMD:groundz(playerid, params[])
{
    new Float:x, Float:y, Float:z;
    GetPlayerPos(playerid, x, y, z);

    new Float:groundZ;
    if(CA_FindZ_For2DCoord(x, y, groundZ))
    {
        new str[64];
        format(str, sizeof(str), "Ground Z at your position: %.4f", groundZ);
        SendClientMessage(playerid, -1, str);

        // Teleport to ground level
        SetPlayerPos(playerid, x, y, groundZ + 1.0);
    }
    else
    {
        SendClientMessage(playerid, -1, "No ground found!");
    }
    return 1;
}

stock SpawnVehicleOnGround(modelid, Float:x, Float:y, Float:angle)
{
    new Float:z;
    CA_FindZ_For2DCoord(x, y, z);
    return CreateVehicle(modelid, x, y, z + 1.0, angle, -1, -1, -1);
}
```

--------------------------------

### Perform Line-of-Sight Raycast

Source: https://context7.com/pottus/colandreas/llms.txt

Casts a ray between two points to detect collisions. Returns the model ID or a constant for water.

```pawn
CMD:raycast(playerid, params[])
{
    new Float:x, Float:y, Float:z, Float:fx, Float:fy, Float:fz, Float:fa;
    GetPlayerPos(playerid, x, y, z);
    GetPlayerFacingAngle(playerid, fa);

    // Cast ray 100 units in front of player
    new Float:endX = x + (100.0 * floatsin(-fa, degrees));
    new Float:endY = y + (100.0 * floatcos(-fa, degrees));

    new Float:hitX, Float:hitY, Float:hitZ;
    new modelid = CA_RayCastLine(x, y, z, endX, endY, z, hitX, hitY, hitZ);

    if(modelid == 0)
    {
        SendClientMessage(playerid, -1, "No collision detected!");
    }
    else if(modelid == WATER_OBJECT)
    {
        SendClientMessage(playerid, -1, "Water detected at that point!");
    }
    else
    {
        new str[128];
        format(str, sizeof(str), "Hit model %d at position: %.2f, %.2f, %.2f", modelid, hitX, hitY, hitZ);
        SendClientMessage(playerid, -1, str);

        // Create a visual marker at the hit point
        CreateObject(19130, hitX, hitY, hitZ, 0.0, 0.0, 0.0);
    }
    return 1;
}
```

--------------------------------

### CA_RestoreBuilding

Source: https://github.com/pottus/colandreas/wiki/Functions

Restores buildings within a specified radius around a given coordinate. Requires the map to be initialized.

```APIDOC
## CA_RestoreBuilding

### Description
Restores buildings within a specified radius around a given coordinate. Requires the map to be initialized.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
- **modelid** (integer) - The model ID of the building to be restored.
- **Float:x, Float:y, Float:z** (float) - The coordinates of the center point for restoration.
- **Float:radius** (float) - The radius around the specified point within which buildings will be restored.

### Request Example
N/A

### Response
#### Success Response (200)
- **Return Value** (integer) - Description:
  - 0: The map is not initialized.
  - 1: Successfully restored.

#### Response Example
N/A

### Remarks
- You must use this function after using `CA_Init`.
```

--------------------------------

### CA_CreateObject_DC

Source: https://context7.com/pottus/colandreas/llms.txt

Creates both a visible SA-MP object and its ColAndreas collision.

```APIDOC
## CA_CreateObject_DC

### Description
Creates both a visible SA-MP object and its ColAndreas collision. Returns an internal DC index for management.

### Parameters
- **modelid** (int) - Required - The model ID of the object.
- **x, y, z** (float) - Required - Coordinates.
- **rx, ry, rz** (float) - Required - Rotation angles.
- **drawDistance** (float) - Required - The draw distance of the object.

### Response
- **dcIndex** (int) - Returns the internal DC index or -1 on failure.
```

--------------------------------

### CA_GetRoomHeight

Source: https://github.com/pottus/colandreas/wiki/Functions

Calculates the height of a room at a given 3D point.

```APIDOC
## CA_GetRoomHeight

### Description
Calculates the distance between the floor and ceiling at a specified 3D coordinate.

### Method
N/A (This appears to be a function call, not a REST endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (Return Value)
- **0.0** (float) - If there is no floor or no ceiling detected.
- **distance** (float) - The distance from the ceiling to the floor.

#### Response Example
```
5.2
```
```

--------------------------------

### Obstacle Detection

Source: https://context7.com/pottus/colandreas/llms.txt

Functions to detect if a wall or obstacle is in front of an entity.

```APIDOC
## CA_IsPlayerBlocked / CA_IsVehicleBlocked

### Description
Detects if a wall or obstacle is directly in front of the player or vehicle.
```

--------------------------------

### Surface Detection Functions

Source: https://context7.com/pottus/colandreas/llms.txt

Functions to check if a player or vehicle is standing on a solid surface.

```APIDOC
## CA_IsPlayerOnSurface

### Description
Checks if a player is standing on any solid surface.

## CA_IsVehicleOnSurface

### Description
Checks if a vehicle is on the ground.
```

--------------------------------

### Cast Rays in All Directions with CA_RayCastExplode

Source: https://context7.com/pottus/colandreas/llms.txt

Casts rays in all directions from a point to find collision points. Useful for determining room boundaries or simulating explosion effects. Requires an array to store collision data.

```pawn
CMD:roomscan(playerid, params[])
{
    new Float:x, Float:y, Float:z;
    GetPlayerPos(playerid, x, y, z);

    // Array to store collision points [point][x/y/z]
    new Float:collisions[100][3];

    // Cast rays in all directions with 20 degree intervals, 50 unit radius
    new hits = CA_RayCastExplode(x, y, z, 50.0, 20.0, collisions);

    if(hits > 0)
    {
        new str[128];
        format(str, sizeof(str), "Room scan found %d walls/surfaces", hits);
        SendClientMessage(playerid, -1, str);

        // Calculate approximate room size
        new Float:minX = collisions[0][0], Float:maxX = collisions[0][0];
        new Float:minY = collisions[0][1], Float:maxY = collisions[0][1];

        for(new i = 1; i < hits; i++)
        {
            if(collisions[i][0] < minX) minX = collisions[i][0];
            if(collisions[i][0] > maxX) maxX = collisions[i][0];
            if(collisions[i][1] < minY) minY = collisions[i][1];
            if(collisions[i][1] > maxY) maxY = collisions[i][1];
        }

        format(str, sizeof(str), "Room approximate size: %.1f x %.1f", maxX - minX, maxY - minY);
        SendClientMessage(playerid, -1, str);
    }
    return 1;
}
```

--------------------------------

### Check if Player is on Surface with CA_IsPlayerOnSurface

Source: https://context7.com/pottus/colandreas/llms.txt

Checks if a player is standing on any solid surface. Useful for anti-cheat systems to detect airwalking. The second parameter specifies the tolerance for the check.

```pawn
public OnPlayerUpdate(playerid)
{
    static lastCheck[MAX_PLAYERS];

    if(GetTickCount() - lastCheck[playerid] < 1000) return 1;
    lastCheck[playerid] = GetTickCount();

    new keys, ud, lr;
    GetPlayerKeys(playerid, keys, ud, lr);

    // Player not in vehicle, not parachuting, and pressing movement keys
    if(!IsPlayerInAnyVehicle(playerid) && GetPlayerSpecialAction(playerid) != SPECIAL_ACTION_USEJETPACK)
    {
        if(!CA_IsPlayerOnSurface(playerid, 2.0))
        {
            new Float:x, Float:y, Float:z;
            GetPlayerPos(playerid, x, y, z);
            GetPlayerVelocity(playerid, x, y, z);

            // Player is in air but not falling (potential airwalk)
            if(z > -0.05 && z < 0.05)
            {
                printf("Warning: Player %d may be airwalking", playerid);
            }
        }
    }
    return 1;
}
```

--------------------------------

### CA_RayCastLineEx

Source: https://context7.com/pottus/colandreas/llms.txt

Extended raycast that returns collision point, object position, and quaternion rotation.

```APIDOC
## CA_RayCastLineEx

### Description
Extended raycast that also returns the collided object's position and quaternion rotation. Useful for identifying exactly which object instance was hit.

### Parameters
- **x, y, z** (Float) - Start coordinates.
- **endX, endY, endZ** (Float) - End coordinates.
- **hitX, hitY, hitZ** (Float) - Output collision point.
- **quatX, quatY, quatZ, quatW** (Float) - Output object quaternion rotation.
- **objX, objY, objZ** (Float) - Output object position.

### Response
- **modelid** (int) - The ID of the model hit, or 0 if no collision occurred.
```

--------------------------------

### Move and Rotate Dynamic Collision Objects

Source: https://context7.com/pottus/colandreas/llms.txt

Updates the position or rotation of both the visible object and its collision simultaneously.

```pawn
CMD:moveobject(playerid, params[])
{
    new Float:x, Float:y, Float:z;
    if(sscanf(params, "fff", x, y, z))
        return SendClientMessage(playerid, -1, "Usage: /moveobject [x] [y] [z]");

    new dcIndex = g_DCObjects[playerid][0];

    // Moves both the visible object AND collision
    new result = CA_SetObjectPos_DC(dcIndex, x, y, z);

    if(result == 1)
    {
        SendClientMessage(playerid, -1, "Object moved!");
    }
    else
    {
        SendClientMessage(playerid, -1, "Failed to move object!");
    }
    return 1;
}

CMD:rotateobject(playerid, params[])
{
    new Float:rx, Float:ry, Float:rz;
    if(sscanf(params, "fff", rx, ry, rz))
        return SendClientMessage(playerid, -1, "Usage: /rotateobject [rx] [ry] [rz]");

    new dcIndex = g_DCObjects[playerid][0];

    // Rotates both the visible object AND collision
    CA_SetObjectRot_DC(dcIndex, rx, ry, rz);
    return 1;
}
```