roseeast/OxTarget

OxTarget

OxTarget is a high-performance native C++17 targeting and interaction foundation for SA-MP 0.3.7 / 0.3.DL and open.mp. It resolves registered gameplay targets directly from the player's camera line-of-sight in 3D world space, maintains authoritative server-side interaction state, renders an optional built-in style interactive TextDraw UI with auto-touch support on Android, and exposes a platform-neutral Pawn API.

No client-side mods (ASI, CLEO, MoonLoader, DirectX hooks, memory hacks, or custom APKs) are required. It works out-of-the-box on standard PC and Android mobile clients.

---

Table of Contents

• Features
• Supported Platforms & Architectures
• Installation Guide
• Quick Start Example
• Built-in Interactive Style UI
  • Auto Cursor (PC) & Touch Mode (Android)
  • Keyboard Shortcuts
  • Customizing UI Coordinates
  • Disabling Built-in UI (Custom UI Mode)
• Universal Sub-Part Zones & Zone Filtering
  • Universal Zones Enum
  • Zone Filtering Toggle (OxTarget_SetZoneFiltering)
  • Registering Zone Options
• Target Types & Geometries
  • Streamer Integration
  • ColAndreas World Occlusion
• Pawn API Reference
  • Target Management Natives
  • Target Properties & Filtering
  • Option Management Natives
  • Player Targeting Controls
  • Selection API Natives
  • General Raycasting Natives
  • Built-in UI Helper Functions
  • Debug & Profiling Natives
• Callbacks Reference
• Enums & Constants
• Included Examples
• Building from Source
• License

---

Features

• Authoritative 3D Spatial Engine: Built in modern C++17 using a uniform spatial hash grid (16-metre cells); no costly full-entity per-tick loops.
• True 3rd-Person Camera Compensation: Target distance validation is measured from the player character's body (playerPos), while the camera line-of-sight ray is extended accordingly. No more needing to physically collide with an entity to interact.
• Camera Fallback Hierarchy: Smooth automatic fallback (Camera Front Vector → Aim Vector → Facing Angle) with finite/zero-vector sanitization.
• Universal Sub-Part Zones: Detects 3D directional hit sectors (Front, Rear, Left, Right, Top, Bottom) on any entity with oriented bounding boxes (Vehicles, Objects, Dynamic Objects, Player Objects).
• Configurable Zone Filtering: Choose per-target whether options appear all at once (zoneFiltering = false, default) or filtered dynamically per zone (zoneFiltering = true).
• Built-in Style Centered UI: Visually attached near the crosshair (330.0, 226.0) with a cyan reticle dot at (320, 240) on the targeted entity.
• Mobile / Android Touch Support: Automatically enables mouse cursor on PC and touch/tap mode on SA-MP Mobile (Android) clients.
• Fast Keyboard Selection: Press Y (KEY_YES) to instantly trigger option 1 without mouse clicking. Press H / Ctrl+Back to toggle cursor.
• Anti-Cheat & Validation: Revalidates distance, world, interior, target state, and user-defined permission callbacks before triggering selections.
• Standalone Raycasting Utility: Cast rays from camera, position, or direction and retrieve hit type, entity, coordinates, surface normal, distance, and zone.
• ColAndreas & Incognito Streamer Ready: Automatic compile-time integration without forced external dependencies.
• Cross-Platform: Binaries provided for Linux x86/x64 and Windows x86/x64.

---

Supported Platforms & Architectures

[!NOTE] Always match the architecture of your server executable: 32-bit server requires 32-bit plugin; 64-bit open.mp server requires 64-bit plugin.

---

Installation Guide

1. Download the archive matching your operating system and server architecture from Releases.
2. Copy the plugin binary to your server's plugins/ folder:
   • Linux: plugins/oxtarget.so
   • Windows: plugins/oxtarget.dll
3. Copy pawno/include/oxtarget.inc to your server's pawno/include/ (or qawno/include/).
4. Enable the plugin in your server configuration:

For SA-MP (server.cfg):

# Windows:
plugins oxtarget

# Linux:
plugins oxtarget.so

For open.mp (config.json):

{
  "pawn": {
    "legacy_plugins": [
      "oxtarget"
    ]
  }
}

---

Quick Start Example

Add OxTarget to your gamemode or filterscript:

#include <a_samp> // or <open.mp>
#include <oxtarget>

new OxTarget:gVehicleTarget;

public OnGameModeInit()
{
    // Create a vehicle (Infernus)
    new vehicleid = CreateVehicle(411, 1480.0, -1720.0, 13.5, 90.0, -1, -1, -1);
    
    // Register as an OxTarget with 4.0 meters interaction range
    gVehicleTarget = OxTarget_AddVehicle(vehicleid);
    OxTarget_SetDistance(gVehicleTarget, 4.0);

    // Add interactive options with icons and integer option IDs:
    OxTarget_AddOption(gVehicleTarget, "Lock / Unlock", "HUD:radar_impound", 1);
    OxTarget_AddOption(gVehicleTarget, "Inspect Vehicle", "HUD:radar_light", 2);
    return 1;
}

public OnPlayerOxTargetSelect(playerid, OxTarget:target, OxTargetOption:option, option_id)
{
    #pragma unused option
    new vehicleid = OxTarget_GetEntity(target);

    switch (option_id)
    {
        case 1:
        {
            // Lock / unlock logic
            SendClientMessage(playerid, 0x00FF00FF, "Vehicle door lock toggled!");
        }
        case 2:
        {
            new msg[64];
            format(msg, sizeof(msg), "Vehicle ID: %d | Model: %d", vehicleid, GetVehicleModel(vehicleid));
            SendClientMessage(playerid, 0x00FFFFFF, msg);
        }
    }
    return 1;
}

When a player approaches the vehicle and looks at it:

1. The cyan reticle dot targets the vehicle.
2. The style option cards pop up right in their crosshair.
3. The mouse cursor appears on PC; touch/tap mode activates on Android.
4. Clicking card 1 or pressing Y triggers OnPlayerOxTargetSelect.

---

Built-in Interactive Style UI

By default, oxtarget.inc comes with a built-in player TextDraw menu modeled after interaction widget.

• Centered On-Target Placement: Option cards are located at screen center (X = 330.0, Y = 226.0) right next to the cyan crosshair dot at (320, 240).
• Dynamic Card Mapping: When an option is clicked or hotkey Y is pressed, OxTarget deterministically selects the displayed option.
• Contextual Zone Refresh: Shifting camera aim dynamically refreshes visible option cards if zone filtering is enabled.

Auto Cursor (PC) & Touch Mode (Android)

• PC: The mouse cursor appears automatically when locking onto a target (SelectTextDraw), and automatically disappears when looking away (CancelSelectTextDraw).
• Android Mobile: Players on SA-MP Mobile can directly tap on option cards on the touchscreen.

Keyboard Shortcuts

• Y Key (KEY_YES): Instantly executes option card 1 without requiring mouse clicks.
• H / Ctrl+Back (KEY_CTRL_BACK): Toggles the mouse cursor on/off while a target is active.

Customizing UI Coordinates

You can override the widget position before including oxtarget:

#define OXTARGET_UI_X (330.0)
#define OXTARGET_UI_Y (226.0)
#include <oxtarget>

Disabling Built-in UI (Custom UI Mode)

If your gamemode provides its own custom UI (e.g. SA-MP Dialog list, custom TextDraws, Radial Menus, or CEF browser widgets):

#define OXTARGET_CUSTOM_UI
#include <a_samp>
#include <oxtarget>

When OXTARGET_CUSTOM_UI is defined, the built-in TextDraws and default ALS input hooks are completely omitted, leaving full UI control to your script callbacks.

---

Universal Sub-Part Zones & Zone Filtering

OxTarget calculates the exact local 3D intersection coordinates on an entity's Oriented Bounding Box (OBB) to detect which side is being targeted.

Universal Zones Enum

enum OxZone {
    OX_ZONE_ALL = 0,            // Available on all parts of the entity
    OX_ZONE_FRONT = 1,          // Front face (+Y)
    OX_ZONE_REAR = 2,           // Rear face (-Y)
    OX_ZONE_SIDES = 3,          // Any side (Left or Right)
    OX_ZONE_LEFT = 4,           // Left face (-X)
    OX_ZONE_RIGHT = 5,          // Right face (+X)
    OX_ZONE_TOP = 6,            // Top face (+Z)
    OX_ZONE_BOTTOM = 7,         // Bottom face (-Z)

    // Vehicle semantic aliases:
    OX_ZONE_HOOD = 1,           // Front / engine hood
    OX_ZONE_TRUNK = 2,          // Rear / trunk
    OX_ZONE_DOORS = 3,          // Any door (left or right)
    OX_ZONE_DOOR_DRIVER = 4,    // Driver door (left side)
    OX_ZONE_DOOR_PASSENGER = 5  // Passenger door (right side)
};

Zone Filtering Toggle (OxTarget_SetZoneFiltering)

By default, zone filtering is disabled (false), meaning all options registered on a target appear at once in the target menu.

Developers can enable per-target zone filtering whenever desired:

// Enable zone filtering so options only appear when aiming at their respective zone:
OxTarget_SetZoneFiltering(target, true);

// Check if zone filtering is active:
new bool:isFiltering = OxTarget_IsZoneFiltering(target);

Registering Zone Options

Use OxTarget_AddZoneOption (or OxTarget_AddVehicleOption):

new OxTarget:veh = OxTarget_AddVehicle(vehicleid);
OxTarget_SetDistance(veh, 4.5);
OxTarget_SetZoneFiltering(veh, true);

// Only appears when aiming at the vehicle hood:
OxTarget_AddZoneOption(veh, OX_ZONE_HOOD, "Open Hood", "HUD:radar_impound", 1);

// Only appears when aiming at the trunk:
OxTarget_AddZoneOption(veh, OX_ZONE_TRUNK, "Open Trunk", "HUD:radar_impound", 2);

// Appears on both driver and passenger doors:
OxTarget_AddZoneOption(veh, OX_ZONE_DOORS, "Enter Vehicle", "HUD:radar_impound", 3);

// Appears on all parts of the entity regardless of zone:
OxTarget_AddZoneOption(veh, OX_ZONE_ALL, "Inspect Vehicle", "HUD:radar_light", 4);

Universal zones work seamlessly across Vehicles, Static Objects, Streamer Dynamic Objects, and Player Objects!

---

Target Types & Geometries

OxTarget supports multiple distinct 3D collision bounding geometries:

Streamer Integration

Include <streamer> before <oxtarget>:

#include <streamer>
#include <oxtarget>

ColAndreas World Occlusion

If ColAndreas is installed on your server, include <colandreas> before <oxtarget>:

#include <colandreas>
#include <oxtarget>

OxTarget automatically tests world occlusion against static buildings and terrain. If ColAndreas is not present, OxTarget functions normally without errors.

---

Pawn API Reference

Target Management Natives

Target Properties & Filtering

Option Management Natives

Player Targeting Controls

Selection API Natives

General Raycasting Natives