Table of Contents

Cursor library

The ACSUtils cursor library allows mods to easily add mouse cursor support.

It fully supports wide screens and takes into account all mouse settings of the user to provide consistent cursor support regardless of aiming settings.

Do not use the cursor library in serverside scripts. It isn't supported for a number of reasons:
  1. serverside cursors are very laggy.
  2. cursor library can't read user's mouse settings to adjust cursor speed and direction.
  3. cursor library can't read user's aspect ratio to find correct screen boundaries.

Basic usage

script "Menu" (void) CLIENTSIDE
{
    while (true)
    {
        UpdateCursor();
        
        SetHudSize(640, 480, false);
        // Draw cursor at CursorX(), CursorY()
        Delay(1);
    }
}

UpdateCursor reads player input and moves the cursor. CursorX and CursorY return the current position of the cursor on the screen in HUD coordinate system. The coordinate system is 640×480 by default.

The cursor library does not draw the cursor for you. You can draw it manually using HudMessage or HUD Library, or even keep it invisible.

Advanced features

Getting cursor motion

CursorDeltaX and CursorDeltaY return the difference between the current and the previous cursor positions.

CursorMotionX and CursorMotionY return the difference between the current and the previous cursor positions that would've been there if the cursor was not blocked by screen boundaries.

Setting coordinate system scale

SetCursorArea sets the scale of the coordinate system used by the cursor library. You can even set it to SetCursorArea(1.0, 1.0) and it will work, because the cursor library is fully fixed-point.

Calling SetCursorArea also transforms the cursor's coordinates that it stays in the same place on screen.

Moving the cursor

SetCursorPosition and CenterCursor can be used to move the cursor from ACS.

Changing cursor speed

SetCursorSpeed, SetCursorSpeedX, SetCursorSpeedY can change the cursor's speed (sensitivity).

Cursor wraparound

EnableCursorWrap, EnableCursorWrapX, EnableCursorWrapY can enable or disable cursor wrapping. If cursor wrapping is enabled, then reaching the edge of the screen will move the cursor to the opposite edge. This sudden teleportation will not affect CursorDeltaX and CursorDeltaY readings.