# Gizmo

<figure><img src="/files/QrRi413o1S7EDir430YK" 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)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.menanak47.com/plugins/ak47_lib/interface/gizmo.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.