Adding Locations

A location (a.k.a. booth) groups speakers (where audio plays) and controls (how players interact). You can define them in data/locations.lua or register them at runtime.

Runtime export: addBooth (available on client and server).

---

In-File (data/locations.lua)

['my_new_location'] = {
  label = 'My Place',
  icon = 'fa-solid fa-music',
  defaultVolume = 60,

  speakers = {
    ['main_room'] = {
      label = 'Main Room',
      coords = vec3(0, 0, 0),
      distance = 10.0
    },
  },

  controls = {
    -- Targeted interaction (ox_target/qb-target via sp_core bridge)
    {
      type = 'target',
      zone = 'sphere',          -- sphere | box | poly
      coords = vec3(0, 0, 0),
      radius = 2.0,
      drawSprite = true
    },
    -- Zone (ox_lib zones)
    -- { type = 'zone', zone='sphere', coords = vec3(0,0,0), radius = 2.0 },

    -- Points (ox_lib points)
    -- { type = 'points', coords = vec3(0,0,0), distance = 2.0 },

    -- Markers (ox_lib marker)
    -- { type = 'marker', coords = vec3(0,0,0), distance = 2.0, markerType = 1 },
  },
}

Fields

• label (string) — display name

• icon (string) — Font Awesome icon class

• defaultVolume (number 0–100) — initial volume

• speakers[key] — { label, coords:vec3, distance:number }

• controls[] — see types below

• groups?: string or string[] or table<string, number> ( Job/Gang Filter )

Control Types

• target: zone (sphere/box/poly), coords, radius, drawSprite?

• points: coords, distance?

• marker: coords, distance?, markerType?, width?, height?, color?

• zone : sphere | box | poly

---

Runtime (Export: addBooth)

You can register a location dynamically from client or server:

-- client.lua OR server.lua
exports['sp_music']:addBooth('my_runtime_booth', {
  label = 'Runtime Booth',
  icon = 'fa-solid fa-star',
  defaultVolume = 50,
  speakers = {
    ['lobby'] = { label = 'Lobby', coords = vec3(100, 100, 100), distance = 8.0 },
  },
  controls = {
    { type = 'target', zone = 'sphere', coords = vec3(100, 100, 100), radius = 2.0, drawSprite = true }
  }
})

The booth key must be unique. Re-adding with the same key updates the booth (implementation-dependent).

---

Tips

• Place speakers where you want audio to originate; use distance to shape how far it travels.

• Use multiple controls (e.g., front desk target + backroom marker) per location if needed.

• Default distances/volumes are configurable (see Config doc).