feat(speech): support isNetworked param

Author: ThatMadCap

client/cl_main.lua

@@ -28,12 +28,13 @@ local resourceName = GetCurrentResourceName()
 
 -- Event Registration ------------------------------------------------
 -- Handles playing voice response
-RegisterNetEvent(resourceName .. ':client:playVoice', function(data)
+---@param data SpeechData
+RegisterNetEvent(resourceName .. ':client:playVoice', function(data, message)
     if not data then
         return
     end
 
-    speech.playResponse(data)
+    speech.playResponse(data, message)
 end)
 
 -- Handles setting character
@@ -42,7 +43,11 @@ RegisterNetEvent(resourceName .. ':client:setAI', function(character, location)
         return
     end
 
-    state.setCharacter(character)
+    local success = state.setCharacter(character)
+    if not success then
+        return
+    end
+
     speech.playSpeech('XM25_GENERIC_HI', character, state.getAddressal(), location)
     target.updateTargets()
     object.updateObjectForCharacter(character)
@@ -54,7 +59,11 @@ RegisterNetEvent(resourceName .. ':client:setAddressal', function(addressal, loc
         return
     end
 
-    state.setAddressal(addressal)
+    local success = state.setAddressal(addressal)
+    if not success then
+        return
+    end
+
     speech.playSpeech('XM25_GENERIC_POSITIVE', state.getCharacter(), addressal, location)
 end)
 
@@ -173,15 +182,15 @@ end
 
 -- Event Handlers --------------------------------------------------
 AddEventHandler('onClientResourceStart', function(resName)
-    if GetCurrentResourceName() ~= resName then
+    if resourceName ~= resName then
         return
     end
 
     init()
 end)
 
 AddEventHandler('onResourceStop', function(resName)
-    if GetCurrentResourceName() ~= resName then
+    if resourceName ~= resName then
         return
     end
 

locales/en.json

@@ -27,7 +27,7 @@
   "ai_selection": "${ai} ${selection}",
   "ai_updated": "${ai} ${updated}",
   "invalid_ai_character": "Invalid ${ai}: '%s'. Choose '${angel}', '${haviland}', or '${og}'.",
-  "invalid_addressal_choice": "Invalid choice. Use ${male} or ${female}.",
+  "invalid_addressal_choice": "Invalid choice '%s'. Use ${male} or ${female}.",
   "change_ai_character": "${change} ${ai} ${character}",
   "change_addressal": "${change} ${addressal}",
   "addressal_selection": "${addressal} ${selection}",

modules/client/menu.lua

@@ -5,6 +5,9 @@ local state = lib.require('modules.client.state')
 local utils = lib.require('modules.shared.utils')
 local speech = lib.require('modules.client.speech')
 
+-- Localised Functions ----------------------------------------------
+local exports = exports
+
 -- Local Variables ----------------------------------------------
 local resourceName = GetCurrentResourceName()
 local submenusRegistered = false

modules/client/speech.lua

@@ -12,13 +12,13 @@ local type = type
 local GetEntityCoords = GetEntityCoords
 local vector3 = vector3
 local PlayAmbientSpeechFromPositionNative = PlayAmbientSpeechFromPositionNative
+local exports = exports
 
 -- Local Variables ----------------------------------------------
 local resourceName = GetCurrentResourceName()
 
 -- Functions --------------------------------------------------------
 ---Resolve location for speech playback
----@alias LocationInput nil|vector3|number|string|{x:number,y:number,z:number}|number[]
 ---@param location? LocationInput Location to resolve
 ---@return vector3 coords Resolved world coordinates
 local function resolveLocation(location)
@@ -137,36 +137,36 @@ end
 ---@param speechName string Base speech name
 ---@param character CharacterName Character voice to use
 ---@param addressal Addressal Player's addressal preference
----@param location? vector3|string|table Optional location for speech
-local function playSpeech(speechName, character, addressal, location)
-    assert(type(speechName) == 'string', 'speechName must be a string')
-    assert(type(character) == 'string', 'character must be a string')
-    assert(constants.isValidCharacter(character), 'invalid character name: ' .. tostring(character))
-    assert(type(addressal) == 'string', 'addressal must be a string')
-    assert(constants.isValidAddressal(addressal), 'invalid addressal: ' .. tostring(addressal))
-
+---@param isNetworked boolean Whether to play for nearby players
+---@param location? LocationInput Optional location for speech playback
+local function playSpeech(speechName, character, addressal, isNetworked, location)
     local baseName = getBaseSpeechName(speechName)
     local finalName = resolveSpeechName(baseName, addressal)
     local voiceName = constants.getVoiceName(character)
     local finalLocation = resolveLocation(location)
 
-    -- this client
     PlayAmbientSpeechFromPositionNative(finalName, voiceName, finalLocation.x, finalLocation.y, finalLocation.z, constants.speechParams.default)
+    lib.print.debug(format('Playing Speech: "%s" | Location: %s | Voice: "%s"', finalName, tostring(finalLocation), voiceName))
+
+    if isNetworked == nil then
+        isNetworked = true
+    end
+
+    if not isNetworked then
+        return
+    end
 
-    -- nearby clients
     TriggerServerEvent(resourceName .. ':server:playSpeech', {
         speechName = finalName,
         voiceName = voiceName,
         location = finalLocation,
         speechParams = constants.speechParams.default,
     })
-
-    lib.print.debug(format('Playing Speech: "%s" | Location: %s | Voice: "%s"', finalName, tostring(finalLocation), voiceName))
 end
 
 ---Play voice response for an intent/topic
----@param data table Data containing speechName, topic, location
-local function playResponse(data)
+---@param data SpeechData
+local function playResponse(data, message)
     if not data.speechName then
         return
     end
@@ -183,7 +183,7 @@ local function playResponse(data)
             'AI: "%s" | Responding to: "%s" | Message: "%s" | Topic: "%s"',
             utils.capital(currentCharacter),
             utils.capital(currentAddressal),
-            data.message,
+            message or 'no message',
             utils.capital(data.topic)
         )
     )
@@ -198,26 +198,27 @@ local function playResponse(data)
         duration = sharedConfig.notify.duration,
     })
 
-    playSpeech(data.speechName, currentCharacter, currentAddressal, data.location)
+    playSpeech(data.speechName, currentCharacter, currentAddressal, data.isNetworked, data.location)
 end
 
 ---Send a message to the AI and get a voice response (routes to server NLP processing)
 ---@param message string The message to send to the AI
+---@param isNetworked boolean Whether to play for nearby players
 ---@param location? LocationInput Optional location for speech playback (defaults to player ped)
 ---@return boolean success Whether the request was successful
-local function talk(message, location)
+local function talk(message, isNetworked, location)
     if not message or type(message) ~= 'string' or #message == 0 then
         lib.print.warn('talk: Invalid message')
         return false
     end
 
-    local success = lib.callback.await(resourceName .. ':server:talk', false, message, location)
+    local success = lib.callback.await(resourceName .. ':server:talk', false, message, isNetworked, location)
 
     return success or false
 end
 
 ---Plays a random voice line
-local function playRandomLine(location)
+local function playRandomLine(isNetworked, location)
     local speechName = lib.callback.await(resourceName .. ':server:getRandomLine', false)
     if not speechName then
         lib.print.warn('Failed to get random line')
@@ -227,7 +228,7 @@ local function playRandomLine(location)
     local currentCharacter = state.getCharacter()
     local currentAddressal = state.getAddressal()
 
-    playSpeech(speechName, currentCharacter, currentAddressal, location)
+    playSpeech(speechName, currentCharacter, currentAddressal, isNetworked, location)
 end
 
 -- Exports -----------------------------------------------------------

modules/client/state.lua

@@ -10,6 +10,7 @@ local lower = string.lower
 local SetResourceKvp = SetResourceKvp
 local GetResourceKvpString = GetResourceKvpString
 local IsPedMale = IsPedMale
+local exports = exports
 
 -- Local Variables ----------------------------------------------
 local resourceName = GetCurrentResourceName()
@@ -70,14 +71,11 @@ local function setCharacter(character)
         return false
     end
 
-    if not constants.isValidCharacter(character) then
-        return false
-    end
-
     local normalised = normaliseCharacterName(character)
     local theme = utils.getTheme('characters', normalised)
 
-    if not normalised then
+    if type(character) ~= 'string' or not constants.isValidCharacter(character) or not normalised then
+        lib.print.warn('verifySpeechInput: invalid character name: ' .. tostring(character))
         ClientNotify.Notify({
             title = locale('ai_selection'),
             description = locale('invalid_ai_character', character),
@@ -111,17 +109,14 @@ local function setAddressal(addressal)
         return false
     end
 
-    if not constants.isValidAddressal(addressal) then
-        return false
-    end
-
     local normalised = normaliseAddressal(addressal)
     local addrTheme = utils.getTheme('addressals', normalised)
 
-    if not normalised then
+    if type(addressal) ~= 'string' or not constants.isValidAddressal(addressal) or not normalised then
+        lib.print.warn('verifySpeechInput: invalid addressal: ' .. tostring(addressal))
         ClientNotify.Notify({
             title = locale('addressal_selection'),
-            description = locale('invalid_addressal_choice'),
+            description = locale('invalid_addressal_choice', addressal),
             icon = addrTheme.icon,
             iconColor = addrTheme.colour,
             type = 'error',

modules/server/speech.lua

@@ -18,6 +18,7 @@ local math = math
 local random = math.random
 local TriggerClientEvent = TriggerClientEvent
 local GetCurrentResourceName = GetCurrentResourceName
+local exports = exports
 
 -- Local Variables ----------------------------------------------
 local resourceName = GetCurrentResourceName()
@@ -111,9 +112,10 @@ end
 ---Processes player input through NLP and triggers voice response (central talking point)
 ---@param source number Client source
 ---@param message string Message to process
----@param location? any Optional location data to pass to client
+---@param isNetworked boolean Whether to play for nearby players
+---@param location? LocationInput Optional location data to pass to client
 ---@return boolean success
-local function talk(source, message, location)
+local function talk(source, message, isNetworked, location)
     if not nlp.isModelReady() then
         lib.print.warn('NLP model not ready')
         return false
@@ -126,26 +128,28 @@ local function talk(source, message, location)
     end
 
     local clientState = lib.callback.await(resourceName .. ':client:getState', source)
-    local genderTarget = clientState?.isMale and 'male' or 'female'
     local clientHour = clientState?.hour
 
     local res = nlp.classifyToTopic(input)
+    local genderTarget = clientState?.isMale and 'male' or 'female'
     local timeContext = getTimeContext(clientHour)
-
     local bestBucket, highestFinalScore = pickBestBucket(res.scores, voiceLines.speech_buckets, genderTarget, timeContext)
 
     local minScoreThreshold = sharedConfig.nlp.thresholds.score.minimum
-    if not bestBucket or highestFinalScore < minScoreThreshold then
+    local isFallback = (highestFinalScore < minScoreThreshold)
+
+    if not bestBucket or isFallback then
         bestBucket = (genderTarget == 'male') and 'XM25_GENERIC_NEGATIVE_MALE' or 'XM25_GENERIC_NEGATIVE_FEMALE'
         lib.print.debug(format('Fallback triggered for: "%s" (Score: %.2f)', input, highestFinalScore))
     end
 
+    local topic = res.topic
     TriggerClientEvent(resourceName .. ':client:playVoice', source, {
-        topic = (highestFinalScore < minScoreThreshold) and 'fallback' or res.topic,
+        topic = topic,
         speechName = bestBucket,
-        message = message,
+        isNetworked = isNetworked,
         location = location,
-    })
+    }, message)
 
     if serverConfig.logs.talk.enabled then
         logs.talk(source, message)

modules/shared/constants.lua

@@ -2,53 +2,73 @@
 local string = string
 local lower = string.lower
 local pairs = pairs
+local exports = exports
 
 -- Types --------------------------------------------------------
----@alias CharacterName 'angel'|'haviland'|'og'
----@alias Addressal 'male'|'female'
----@alias ModelName string
+
+---Available AI character names
+---@alias CharacterName
+---| 'angel' # Female secretary AI
+---| 'haviland' # Male butler AI
+---| 'og' # Male gang AI
+
+---Player addressal preference for gendered speech lines
+---@alias Addressal
+---| 'male' # Use male speech variants
+---| 'female' # Use female speech variants
+
+---@alias LocationInput nil|vector3|number|string|{x:number,y:number,z:number}|number[]
+
+---Data structure for speech playback
+---@class SpeechData
+---@field speechName string Base speech name (gender suffix auto-resolved)
+---@field character CharacterName AI character voice to use
+---@field addressal Addressal Player's gender preference for speech
+---@field isNetworked? boolean Whether to play for nearby players
+---@field location? LocationInput Optional location for speech playback
 
 -- Constants ----------------------------------------------------
----Valid AI character names
----@type table<CharacterName, boolean>
+
+---Valid AI character names for validation
+---@enum ValidCharacters
 local validCharacters = {
-    ['angel'] = true,
-    ['haviland'] = true,
-    ['og'] = true,
+    angel = true,
+    haviland = true,
+    og = true,
 }
 
----Valid addressal options
----@type table<Addressal, boolean>
+---Valid addressal options for validation
+---@enum ValidAddressals
 local validAddressals = {
-    ['male'] = true,
-    ['female'] = true,
+    male = true,
+    female = true,
 }
 
----Character to voice name mapping
----@type table<CharacterName, string>
+---Character to GTA voice name mapping
+---@enum CharacterVoices
 local characterVoices = {
-    ['angel'] = 'XM25_AISECRETARY',
-    ['haviland'] = 'XM25_AIBUTLER',
-    ['og'] = 'XM25_AIGANG',
+    angel = 'XM25_AISECRETARY',
+    haviland = 'XM25_AIBUTLER',
+    og = 'XM25_AIGANG',
 }
 
----Speech parameters
----@type table<string, string>
+---Speech parameters for native calls
+---@enum SpeechParams
 local speechParams = {
     default = 'SPEECH_PARAMS_FORCE',
 }
 
----Character tablet model mappings
----@type table<CharacterName|'blank', string>
+---Character tablet prop model mappings
+---@enum CharacterTabletModels
 local characterTabletModels = {
     blank = 'm25_2_prop_m52_aitablet',
     og = 'm25_2_prop_m52_aitablet_01a',
     haviland = 'm25_2_prop_m52_aitablet_02a',
     angel = 'm25_2_prop_m52_aitablet_03a',
 }
 
----Character TV model mappings
----@type table<CharacterName, string>
+---Character TV prop model mappings
+---@enum CharacterTVModels
 local characterTVModels = {
     og = 'm25_2_prop_m52_mansiontv_ogai',
     haviland = 'm25_2_prop_m52_mansiontv_havilandai',