Peak AI NPC

Peak AI NPC adds server-authoritative conversations to FiveM while keeping core decisions and economy transactions on the server. Configured NPCs are the privileged store, mission, and service roles; eligible networked ambient peds can also be spoken to with no pre-configuration and no gameplay tools. It supports contextual identity/location, scoped player-NPC memory, 3D subtitles, voice dictation, TTS, target integrations, vision, and local or cloud providers.

Per Peak Studios release rules, core runtime and network state machines are escrowed while customization files remain completely open for editing:

• shared/config.lua: Lore, interaction distance, framework selection, target system, voice limits, subtitle options, vision quality.
• npcs/examples.lua: NPC ped definitions, coordinates, behavioral prompts, identities, knowledge constraints, allowed tools.
• client/targets.lua: Custom interaction registration (ox_target, qb-target, native fallback).
• locales/*.lua: Subtitle and NUI notification text strings.
• shared/constants.lua: Event names and state keys.

For a managed-service installation, create a server slot in the customer portal and copy its reveal-once configuration. Provider keys remain on the Peak gateway:

cfg
set peak_ai_npc_gateway_url "https://<gateway-domain>"
set peak_ai_npc_server_id "srv_generated_by_portal"
set peak_ai_npc_install_token "peak_service_reveal_once_value"
ensure peak-ai-npc

Customize shared/config.lua to fit your server framework and limits:

lua
Config = {
    Debug = false,
    ServerLore = 'Los Santos is a bustling metropolis. Economy is realistic.',
    Framework = 'auto', -- auto, qbcore, esx, qbox, standalone
    Inventory = 'auto', -- auto, ox_inventory, qb-inventory, qs-inventory, esx_inventory
    Target = 'native',   -- native, ox_target, qb-target, auto

    Conversations = {
        interactionDistance = 3.0,
        maximumDistance = 8.0,
        maxTurns = 30,
        idleTimeoutSeconds = 60,
        exclusiveByDefault = true,
        maxRequestsPerMinute = 12
    },

    Ambient = {
        enabled = true,
        interactionDistance = 3.0,
        ignoredModels = {},
        memory = true
    },

    Security = {
        requireConfirmationForPurchases = true,
        maximumTransactionValue = 5000,
        auditWriteTools = true
    },

    Memory = {
        enabled = true,
        minimumImportance = 0.65,
        retentionDays = 7
    },

    Subtitles = {
        enabled = true,
        mode = 'always', -- always, never, player_preference, audio_failed, accessibility
        audience = 'nearby',
        maximumDistance = 22.0,
        accentColor = { 184, 255, 101 }
    }
}

Define custom AI peds in npcs/examples.lua or add new .lua files in npcs/:

lua
AINPCDefinitions = AINPCDefinitions or {}

AINPCDefinitions.shopkeeper = {
    id = 'shopkeeper',
    model = 'mp_m_shopkeep_01',
    coords = vec4(24.47, -1346.62, 29.5, 271.66),
    identity = {
        name = 'Martin Hale',
        occupation = 'Shopkeeper'
    },
    personality = 'Patient, observant, and concise. Never invents stock or prices.',
    knowledge = 'Only knows the shop catalog, public server lore, and facts returned by tools.',
    allowedTools = {
        'get_shop_catalog',
        'get_shop_stock',
        'create_purchase_quote',
        'confirm_purchase'
    },
    interactionDistance = 3.0
}

client/targets.lua registers configured roles by entity and adds a global Talk option for eligible ambient peds when ox_target or qb-target is installed. Ambient peds are resolved and validated server-side, receive no tools, and cannot perform purchases, missions, or other durable actions.

lua
function AINPCTargets.register(id, ped)
    local label = (AINPCDefinitions[id].identity and AINPCDefinitions[id].identity.name or id)
    if targetResource() == 'ox_target' then
        exports.ox_target:addLocalEntity(ped, {
            {
                name = 'peak_ai_npc_' .. id,
                icon = 'fa-solid fa-comments',
                label = 'Talk to ' .. label,
                distance = AINPCDefinitions[id].interactionDistance or 3.0,
                onSelect = function(data)
                    AINPCStartConversation(id, data and data.entity or ped)
                end
            }
        })
    end
end

The companion gateway is operated by Peak and keeps all model, voice, and transcription credentials off the customer server. Customers only configure the managed endpoint and the reveal-once server credential shown in the portal. Private deployments should use the operator intake and deployment runbook; do not add provider keys to server.cfg, Lua files, or the NUI bundle.

For same-computer testing, set both AI_NPC_PUBLIC_BASE_URL and peak_ai_npc_gateway_url to http://127.0.0.1:8787. Start the gateway with npm run build followed by node --env-file=../.env dist/server.js. Its /health response must report a speech provider other than none.

If the provider rejects synthesis, subtitles remain available. Some providers require accepting model-specific terms before TTS can work. Remote players need a public HTTPS gateway URL; loopback only works for the computer hosting both FiveM and the gateway.