client

Options and examples

 ### Checking Player Distance from Specified Coordinates ###

  The `QT.InDistance` function checks whether the player is within a specified distance of a given set of coordinates. 
  This can be useful for determining if the player is close enough to interact with an object or location in the game world.

  ## Function Parameters: ##
  - coords: A table containing the coordinates (usually x, y, z) to check against.
  - distance: A number representing the maximum distance (in units) from the coordinates.

  ## Usage Example: ##
  local coords = { x = 100.0, y = 200.0, z = 30.0 } -- Example coordinates
  local isInDistance = QT.InDistance(coords, 5.0) -- Check if the player is within 5 units

  -- The function returns a boolean value:
  return isInDistance
  
  -- If the player is found within the specified distance of the given coordinates, 
  -- 'isInDistance' will be true; otherwise, it will be false.

 ### Checking Vehicle Location Near Specific Coordinates ###

  The `QT.VehicleNearPoint` function checks if there is a vehicle located near a specified set of coordinates within a given distance. 
  This is useful for determining whether a player or NPC is close to a vehicle in the game world.

  ## Function Parameters: ##
  - coords: A table containing the coordinates (usually x, y, z) to check against.
  - distance: A number representing the radius (in units) within which to check for vehicles.

  ## Usage Example: ##
  local coords = { x = 100.0, y = 200.0, z = 30.0 } -- Example coordinates
  local isVehicleNearby = QT.VehicleNearPoint(coords, 10.0) -- Check within a distance of 10 units

  -- The function returns a boolean value:
  return isVehicleNearby
  
  -- If a vehicle is found within the specified distance of the given coordinates, 
  -- 'isVehicleNearby' will be true; otherwise, it will be false.

 ### Getting Player Position Data ###

  The `QT.EntPos` function retrieves the position data of a specified entity, such as a player or NPC. 
  This function returns the coordinates of the entity in the game world.

  ## Function Parameters: ##
  - entity: The entity for which you want to get the position. This can be a player character or any NPC.

  ## Usage Example: ##
  local pos = QT.EntPos(entity)

  -- The variable 'pos' will hold a table containing the position data (x, y, z, and possibly w).
  
  -- To return the individual components of the position:
  return pos.x, pos.y, pos.z, pos.w

  -- Here, 'pos.x', 'pos.y', 'pos.z', and 'pos.w' represent the X, Y, Z coordinates and an optional W value of the entity's position.

### Animation & Dictionary Loader ###

The `QT.RequestAnim` function is used to load an animation dictionary before playing an animation. 
This ensures that the specified animation is available in memory, preventing errors when attempting to play it.

## Function Parameters: ##
- animation: A string representing the animation you want to load in the format "animation@example_animation".

## Usage Example: ##
QT.RequestAnim("animation@example_animation")

-- After requesting the animation, you can play it using the following function:

TaskPlayAnim(
  PlayerPedId(),               -- The player ped's ID (or the ped entity ID).
  "animation@example_animation", -- The animation name.
  "dict_example",              -- The name of the animation dictionary.
  8.0,                          -- Speed of the animation.
  -8.0,                         -- Speed of the playback.
  -1,                           -- Duration (-1 for infinite).
  2,                            -- Flags (2 for loop).
  0,                            -- Start time.
  false,                        -- Stop on last frame.
  false,                        -- Unkown parameter.
  false                         -- Unknown parameter.
)

## Note: ##
-- Ensure that the animation dictionary is loaded before calling `TaskPlayAnim`,
-- as attempting to play an unloaded animation may cause errors or result in no action being performed.

### Ped Scenario Function ###

  The `QT.Scenario` function is used to set a specific scenario for a pedestrian (ped) entity in the game. 
  This allows you to make the ped perform a predefined animation or behavior based on the specified scenario.

  ## Function Parameters: ##
  - entity: The ped entity that you want to apply the scenario to. This can be a player or NPC character.
  - scenario: A string representing the scenario name that defines the action the ped will perform.

  ## Usage Example: ##
  QT.Scenario(entity, "WORLD_HUMAN_SMOKING")
  
  -- In this example, the specified ped (entity) will start smoking as defined by the "WORLD_HUMAN_SMOKING" scenario.
  
  ## Note: ##
  -- Make sure the scenario you use is valid and supported in the game, 
  -- as trying to use an unsupported scenario may result in unexpected behavior or errors.

  ### Requesting an Object Model ###

  The `QT.RequestModel` function is used to request an object model in the game when the object is not currently loaded. 
  This function helps ensure that the desired model is loaded into memory before you attempt to use it in your script.

  ## Function Parameters: ##
  - prop_hash: A string or hash that represents the object model you want to load. 

  ## Usage Example: ##
  QT.RequestModel("prop_hash")
  
  -- This function sends a request to load the specified object model.
  -- Ensure to check if the model is loaded before using it in your script.
  
  ## Example of Checking Model Load Status: ##
  RequestModel("prop_hash")
  while not HasModelLoaded("prop_hash") do
      Wait(500) -- Waits for 500 milliseconds before checking again
  end
  
  -- Once the model is loaded, you can safely use it in your game environment.

  ### Triggering a Server Callback ###

  The `QT.TriggerServerCall` function is used to send a request to the server and handle the response on the client-side. 
  It triggers a specific server callback, waits for the server's data, and then executes the provided callback function with the returned data.

  ## Function Parameters: ##
  - callbackName: A string representing the name of the callback you want to call on the server.
  - callbackFunction: A function that handles the server response. The server's data is passed as a parameter to this function.

  ## Usage Example: ##
  QT.TriggerServerCall("calling_some_callback", function(data)
      if data ~= nil then 
          print("true")  -- If valid data is received from the server, print "true".
      else
          print("false") -- If no data (nil) is received, print "false".
      end
  end)
  
  In this example, the server callback `"calling_some_callback"` is triggered.
  The server's response is checked: 
  - If the response is not `nil`, it prints `"true"`.
  - If the response is `nil`, it prints `"false"`.
  
  This allows for handling server responses and performing specific actions based on the data received.

 ### Interval Function for Executing Actions at Specified Time Intervals ###

  The `QT.SetInterval` function allows you to execute an action at a set time interval (in seconds, which you configure).
  Each interval is assigned a unique ID for easy identification, allowing you to stop it later if needed.

  ## Function Parameters: ##
  - id: A unique identifier (string or number) used to index the interval. This is useful for tracking or stopping the interval later.
  - time: The time interval in milliseconds. You can convert this time based on your needs.

  ## Example Usage: ##
  QT.SetInterval("motel_days_remover", 60000, function()
      local hour, minute = TimeFunction()
  
      if hour == 23 and minute == 0 then
          for k, v in pairs(Motels) do 
              RemoveDay(v["doors"], k)
          end
      end
  end)
  
  -- To stop the interval:
  QT.ClearInterval("motel_days_remover") -- Stops the interval with the unique id

 ### Optimized Table Insert Function ###

  The `QT.Insert` function is used to insert elements into a table, similar to the standard `table.insert` function, 
  but with an optimized and faster response time, reducing execution time by several milliseconds.

  ## Function Parameters: ##
  - SomeTable: The table into which the new element will be inserted.
  - value: The value (or multiple values) that you want to insert into the table.

  ## Usage Example: ##
  QT.Insert(SomeTable, { value = 1, value2 = 2 } )
  
  -- This function works similarly to the standard `table.insert` but is more optimized.
  -- It inserts a table containing values into `SomeTable`.

 ### Checking and Setting Busy Status ###

  The `QT.IS_BUSY` and `QT.SetBusy` functions are used to manage the busy state of a player or entity in the game. 
  This is useful for preventing certain actions or interactions while a player is occupied with an ongoing task or animation.

  ## Checking Busy Status: ##
  - `QT.IS_BUSY`: This function checks whether the player is currently busy.

  ## Usage Example for Checking Busy Status: ##
  if QT.IS_BUSY() then
      print("The player is currently busy.")
  else
      print("The player is available for actions.")
  end

  ## Setting Busy Status: ##
  - `QT.SetBusy(busy)`: This function sets the busy status of the player. 
  - Parameters: 
    - busy: A boolean value (`true` or `false`). Pass `true` to mark the player as busy and `false` to mark them as available.

  ## Usage Example for Setting Busy Status: ##
  QT.SetBusy(true) -- Sets the player as busy
  -- Perform some tasks or animations here
  QT.SetBusy(false) -- Sets the player as available again

  ## Note: ##
  -- Make sure to manage the busy state appropriately to avoid blocking player actions unintentionally.

  ### Adding Commands with QT.AddCommand ###

  The `QT.AddCommand` function allows you to create custom commands that can be executed in the game, either on the server or client side. 
  This function simplifies the process of registering commands and associating them with specific handler functions.

  ## Function Parameters: ##
  - name: A string representing the name of the command you want to register (e.g., "myCommand").
  - handler: A function that will be called when the command is executed. 
    This function receives three parameters:
    - source: The ID of the player who executed the command (server-side only).
    - args: A table containing the arguments passed to the command.
    - rawCommand: The original command string as entered by the player.
  - restricted: A boolean value indicating whether the command should be restricted to specific user roles (e.g., admins). 
    Set to `true` to restrict, or `false` for public access.

  ## Usage Example (Server Side): ##
  -- This example shows how to register a command that can be used by players.
  QT.AddCommand("giveitem", function(source, args, rawCommand)
      -- Logic to give an item to the player
      local itemName = args[1] -- The item name from the command
      -- Code to give the item to the player using their source ID
  end, false) -- Allows all players to use this command

  ## Usage Example (Client Side): ##
  -- On the client side, you can also use the same command to trigger specific actions.
  QT.AddCommand("heal", function(args, rawCommand)
      local playerId = PlayerPedId() 
  end) 

  ## Note: ##
  -- Ensure that your handler functions contain appropriate logic to handle the command.
  -- Use restrictions wisely to control access to commands, especially for sensitive actions.