# Gizmo

<figure><img src="https://2088945756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkHcyR2RbVMcj5NHJ2HEa%2Fuploads%2Ft7rvMFS9Yfl1sUotUd0q%2Fimage.png?alt=media&#x26;token=68d770e6-f838-48b5-bf8f-ba0e39e7ced2" alt=""><figcaption></figcaption></figure>

***

### 📦 Exports

#### `StartGizmo`

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

Syntax:

```lua
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:

```lua
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.

```lua
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)
```