Gizmo

The Gizmo is an interactive 3D manipulator that is drawn on top of the game and can be dragged with the mouse to translate or rotate a target in world space.

info

The Gizmo never modifies the game entity itself. Dragging it only changes an internal transform, which you read with GetTransform and apply yourself using the regular game natives. This keeps you in control of how the change is applied (physics, freezing, network sync) and avoids breaking engine state.

Quick Reference

Name	Type	Description
SetEnabled	Client	Shows or hides the Gizmo.
IsEnabled	Client	Returns whether the Gizmo is currently shown.
AttachToVehicle	Client	Attaches the Gizmo to a vehicle.
AttachToPed	Client	Attaches the Gizmo to a ped.
AttachToObject	Client	Attaches the Gizmo to an object.
AttachToTransform	Client	Attaches the Gizmo to a free transform that is not bound to an entity.
Detach	Client	Detaches the Gizmo from its current target.
IsAttached	Client	Returns whether the Gizmo is attached to a target.
GetTarget	Client	Returns the current target type and id.
GetTransform	Client	Returns the current position and rotation of the Gizmo.
SetTransform	Client	Sets the position and rotation of the Gizmo.
SetOperation	Client	Changes the manipulation mode (translate, rotate, scale).
GetOperation	Client	Returns the current manipulation mode.
SetSpace	Client	Changes the reference space (world or local).
GetSpace	Client	Returns the current reference space.
IsUsing	Client	Returns whether the Gizmo is currently being dragged.
IsOver	Client	Returns whether the mouse hovers over the Gizmo.
PollDragEnd	Client	Returns true once after a drag has finished.
SetFov	Client	Sets the field of view used to project the Gizmo.
GetFov	Client	Returns the field of view used to project the Gizmo.

---

Client Functions

SetEnabled

Shows or hides the Gizmo.

Gizmo.SetEnabled(bool enable, [optional] bool blockGameInput)

While the Gizmo is enabled the mouse cursor is released so the axes can be grabbed. By default the game no longer receives input. Pass false as blockGameInput to keep the player controllable while the Gizmo is visible.

---

IsEnabled

Returns whether the Gizmo is currently shown.

bool enabled = Gizmo.IsEnabled()

---

AttachToVehicle

Attaches the Gizmo to a vehicle.

Gizmo.AttachToVehicle(int vehicleId)

warning

Throws a script error if no vehicle with the given id exists.

---

AttachToPed

Attaches the Gizmo to a ped.

Gizmo.AttachToPed(int pedId)

warning

Throws a script error if no ped with the given id exists.

---

AttachToObject

Attaches the Gizmo to an object.

Gizmo.AttachToObject(int objectId)

warning

Throws a script error if no object with the given id exists.

---

AttachToTransform

Attaches the Gizmo to a free transform that is not bound to an entity.

Gizmo.AttachToTransform(float x, float y, float z, float rx, float ry, float rz)

Use this to place things the game does not know about yet, such as spawn points, checkpoints or pickups.

---

Detach

Detaches the Gizmo from its current target.

Gizmo.Detach()

info

The Gizmo detaches itself automatically when the attached entity no longer exists, for example after it has been deleted or streamed out.

---

IsAttached

Returns whether the Gizmo is attached to a target.

bool attached = Gizmo.IsAttached()

---

GetTarget

Returns the current target type and id.

string type, int id = Gizmo.GetTarget()

The type is one of "vehicle", "ped", "object", "free" or "none". The id is -1 for "free" and "none".

Example:

Lua

local targetType, targetID = Gizmo.GetTarget()

if targetType == "none" then
    Chat.AddMessage("The gizmo target no longer exists.")
end

Squirrel

local targetType, targetID = Gizmo.GetTarget();

if (targetType == "none") {
    Chat.AddMessage("The gizmo target no longer exists.");
}

---

GetTransform

Returns the current position and rotation of the Gizmo.

float x, float y, float z, float rx, float ry, float rz = Gizmo.GetTransform()

Rotation is returned in degrees, where rx is pitch, ry is roll and rz is heading.

Example:

Lua

-- Apply the gizmo transform to the vehicle every frame while dragging.
if Gizmo.IsUsing() then
    local x, y, z, rx, ry, rz = Gizmo.GetTransform()

    Game.SetCarCoordinates(g_vehicle, x, y, z)
    Game.SetCarHeading(g_vehicle, rz)
end

Squirrel

// Apply the gizmo transform to the vehicle every frame while dragging.
if (Gizmo.IsUsing()) {
    local x, y, z, rx, ry, rz = Gizmo.GetTransform();

    Game.SetCarCoordinates(g_vehicle, x, y, z);
    Game.SetCarHeading(g_vehicle, rz);
}

---

SetTransform

Sets the position and rotation of the Gizmo.

Gizmo.SetTransform(float x, float y, float z, float rx, float ry, float rz)

---

SetOperation

Changes the manipulation mode.

Gizmo.SetOperation(string operation)

Valid values are "translate", "rotate" and "scale".

warning

"scale" is only supported while the Gizmo is attached to a free transform. Attaching to an entity resets the operation to "translate".

Example:

Lua

Events.Subscribe("chatCommand", function(command)
    if command == "/rotate" then
        Gizmo.SetOperation("rotate")
        Gizmo.SetSpace("local")
    end
end)

Squirrel

Events.Subscribe("chatCommand", function(command) {
    if (command == "/rotate") {
        Gizmo.SetOperation("rotate");
        Gizmo.SetSpace("local");
    }
});

---

GetOperation

Returns the current manipulation mode.

string operation = Gizmo.GetOperation()

---

SetSpace

Changes the reference space the Gizmo axes are aligned to.

Gizmo.SetSpace(string space)

Valid values are "world" and "local". Local space aligns the axes with the target, which is usually the more intuitive choice when rotating.

---

GetSpace

Returns the current reference space.

string space = Gizmo.GetSpace()

---

IsUsing

Returns whether the Gizmo is currently being dragged.

bool using = Gizmo.IsUsing()

---

IsOver

Returns whether the mouse hovers over the Gizmo.

bool over = Gizmo.IsOver()

Useful to suppress your own mouse handling while the Gizmo would consume the click.

---

PollDragEnd

Returns true once after a drag has finished.

bool ended = Gizmo.PollDragEnd()

The result is consumed, so it is true exactly once per drag no matter how often you call it. Use this to run expensive work only after the user releases the mouse instead of every frame.

Example:

Lua

Events.Subscribe("chatCommand", function(command)
    if command == "/editvehicle" then
        Gizmo.AttachToVehicle(g_vehicle)
        Gizmo.SetEnabled(true)

        Thread.Create(function()
            while Gizmo.IsEnabled() do
                if Gizmo.PollDragEnd() then
                    local x, y, z, rx, ry, rz = Gizmo.GetTransform()

                    Game.SetCarCoordinates(g_vehicle, x, y, z)
                    Game.SetCarHeading(g_vehicle, rz)

                    Chat.AddMessage("Vehicle moved.")
                end

                Thread.Pause(0)
            end
        end)
    end
end)

Squirrel

Events.Subscribe("chatCommand", function(command) {
    if (command == "/editvehicle") {
        Gizmo.AttachToVehicle(g_vehicle);
        Gizmo.SetEnabled(true);

        Thread.Create(function() {
            while (Gizmo.IsEnabled()) {
                if (Gizmo.PollDragEnd()) {
                    local x, y, z, rx, ry, rz = Gizmo.GetTransform();

                    Game.SetCarCoordinates(g_vehicle, x, y, z);
                    Game.SetCarHeading(g_vehicle, rz);

                    Chat.AddMessage("Vehicle moved.");
                }

                Thread.Pause(0);
            }
        });
    }
});

---

SetFov

Sets the field of view in degrees used to project the Gizmo.

Gizmo.SetFov(float degrees)

info

Only change this if the Gizmo does not line up with its target. The default value is calibrated for the standard camera.

---

GetFov

Returns the field of view in degrees used to project the Gizmo.

float degrees = Gizmo.GetFov()