Gizmo

---

📦 Exports

StartGizmo

Initializes the 3D Gizmo interface, spawning a dummy entity (if provided) and locking focus to the NUI for precise manipulation.

Syntax:

exports['ak47_lib']:StartGizmo(options, callback)

Parameters:

Parameter	Type	Required	Description
options	table	Yes	Configuration table for the Gizmo deployment.
callback	function	Yes	Triggers continuously on positional updates, and once upon closing or cancelling.

options Table Breakdown:

Key	Type	Default	Description
model	string / hash	nil	The model name or hash to spawn as the visual dummy prop.
coords	vector3	N/A	The starting coordinates for the Gizmo.
rot	vector3	vector3(0,0,0)	The starting rotation for the Gizmo.

Callback Event Types (result.event):

• update: Fires constantly as the player moves the object via the NUI. Returns raw axis data (x, y, z, rotX, rotY, rotZ).
• closed: Fires when the player confirms the placement. Returns coords and rot as vector3.
• cancelled: Fires when the player cancels the placement. Returns the initial starting coords and rot as vector3.

---

StopGizmo

Programmatically stops the active Gizmo session. This is typically handled internally by the NUI, but can be forced via code if required (e.g., if a player is killed or restrained while placing an item).

Syntax:

exports['ak47_lib']:StopGizmo(isCancel)

Parameters:

Parameter	Type	Required	Description
isCancel	boolean	Yes	true aborts placement and returns the object to its starting position. false confirms the current placement.

---

🎮 Player Controls

When the Gizmo is active, the library handles the following native inputs automatically to ensure a smooth user experience:

• Right Mouse Button (Hold): Temporarily hides the cursor and disables player firing/aiming, allowing the user to free-look with the camera while keeping the Gizmo open.
• Bounding Box: A visual 3D bounding box automatically renders around the active dummy prop to help users visualize the physical footprint.

---

💻 Complete Example Implementation

Below is a fully functional client-side script utilizing the Gizmo export to spawn, move, and finalize a networked prop.

local isPlacingObject = false
local finalCoords = nil
local finalRotation = nil

-- Function to handle the spawning of the actual server-sided object
local function SpawnFinalNetworkedObject(model, coords, rot)
    local hash = type(model) == 'string' and joaat(model) or model
    RequestModel(hash)
    
    while not HasModelLoaded(hash) do 
        Wait(0) 
    end
    
    local obj = CreateObject(hash, coords.x, coords.y, coords.z, true, true, false)
    SetEntityRotation(obj, rot.x, rot.y, rot.z, 2, true)
    FreezeEntityPosition(obj, true)
end

-- Main function to trigger the Gizmo
function StartPlacingProp(modelName)
    if isPlacingObject then return end
    isPlacingObject = true
    
    local playerPed = PlayerPedId()
    local startCoords = GetEntityCoords(playerPed) + GetEntityForwardVector(playerPed) * 2.0
    local startHeading = GetEntityHeading(playerPed)
    
    -- Initialize the Gizmo via ak47_lib
    exports['ak47_lib']:StartGizmo({
        model = modelName,
        coords = startCoords,
        rot = vector3(0.0, 0.0, startHeading)
    }, function(result)
        
        -- Handle real-time movement updates (Useful for zone/distance checks)
        if result.event == 'update' then
            -- Example: print("Moving to:", result.x, result.y, result.z)
            return
        end
        
        -- Handle cancellation
        if result.event == 'cancelled' then
            isPlacingObject = false
            print("Placement cancelled by user.")
            return
        end
        
        -- Handle the final confirmed placement
        if result.event == 'closed' then
            isPlacingObject = false
            finalCoords = result.coords
            finalRotation = result.rot
            
            print("Finished placing prop!")
            print("Final Coords:", finalCoords)
            print("Final Rotation:", finalRotation)
            
            -- Spawn the persistent object
            SpawnFinalNetworkedObject(modelName, finalCoords, finalRotation)
        end
    end)
end

-- Test Command
RegisterCommand('testgizmo', function()
    StartPlacingProp('prop_bench_01a')
end, false)