Neocortex Logo

Garry's Mod AI NPC 애드온: 똑똑한 NPC와 퀴즈 쇼 진행자

Lua로 Garry's Mod AI NPC 애드온을 만드는 방법입니다. 샌드박스와 롤플레이 서버용 똑똑한 NPC, 서버 전체가 즐기는 퀴즈 쇼 진행자와 리더보드, 음성 명령을 다룹니다.

Neocortex TeamThe team behind Neocortex

· 6분 분량

Lua로 Garry's Mod AI NPC 애드온을 만드는 방법입니다. 샌드박스와 롤플레이 서버용 똑똑한 NPC, 서버 전체가 즐기는 퀴즈 쇼 진행자와 리더보드, 음성 명령을 다룹니다.

Garry's Mod AI NPC 애드온은 플레이어가 한 말을 게임의 내장 HTTP() 함수로 AI 캐릭터에게 보내고, 돌아온 답에 따라 행동하는 Lua 애드온입니다. Garry's Mod 서버는 플레이어가 직접 만들어 내는 것들로 굴러갑니다. 그저 서 있기만 하는 NPC는 기회를 낭비하는 셈입니다. Neocortex를 쓰면 샌드박스와 롤플레이 서버의 캐릭터가 실제로 말합니다. 값을 흥정하는 상점 주인, 서버 전체가 함께하는 게임을 진행하는 퀴즈 쇼 진행자, 음성 명령을 따르는 도우미가 그렇습니다. Neocortex는 AI 캐릭터, Conversation Flows, 퀴즈 엔진, 기기 내 음성 명령을 제공하고, Lua가 이것들을 여러분의 서버와 연결합니다.

Garry's Mod 게임 내 스크린샷 스크린샷: Garry's Mod © Valve

서버에서 실행되는 것과 클라이언트에서 실행되는 것

Garry's Mod 애드온은 Lua 스크립트와 콘텐츠를 담은 폴더로, garrysmod/addons에 설치하거나 Steam 워크숍에서 구독해 씁니다. Lua는 두 개의 영역(realm)에서 실행되며, AI NPC 애드온은 이 둘로 깔끔하게 나뉩니다. Garry's Mod 위키가 모든 함수를 문서화하고 있습니다.

작업영역(realm)도구
NPC, 엔티티, 게임 로직서버Lua 엔티티
Neocortex 호출과 API 키 보관서버HTTP(), http.Fetch, http.Post
플레이어에게 응답 보내기서버에서 클라이언트로net 라이브러리
자막과 HUD클라이언트chat.AddText 또는 직접 만든 HUD 패널
음성 재생클라이언트sound.PlayURL
음성 명령클라이언트플레이어 PC의 Neocortex Voice Commands

몇 가지 세부 사항이 중요합니다. HTTP()는 URL, 메서드, 헤더, 본문, 콜백과 함께 비동기 요청을 시작합니다. http.Fetch와 http.Post는 간단한 경우를 위한 래퍼입니다. 성공 콜백은 오류 상태 코드에도 호출되므로 반드시 코드를 확인하세요. sound.PlayURL은 외부 사운드 파일을 재생하므로, 생성된 음성은 여러분이 관리하는 작은 엔드포인트에서 제공하세요. 그러면 클라이언트는 API 키를 보지 않고 음성을 스트리밍할 수 있습니다. 네이티브 모듈(서버용 gmsv_, 클라이언트용 gmcl_)은 garrysmod/lua/bin에 넣고 require로 불러옵니다. 다만 워크숍 애드온으로는 설치할 수 없으므로, 네이티브 모듈은 플레이어나 서버 운영자가 따로 설치해야 합니다.

플레이어가 대화할 수 있는 롤플레이 NPC

롤플레이 서버라면 도시에 등장인물을 배치하세요. 값을 흥정하고 누가 자기에게 빚을 떼먹었는지 기억하는 상점 주인, 서버의 설정을 아는 바텐더, 플레이어의 신고에 반응하는 경찰 교환원 같은 인물입니다. 각 캐릭터에는 Neocortex 에디터에서 Personality, Emotion 설정, Knowledge 베이스를 줍니다. 서버 규칙, 맵의 장소, 경제 정보가 들어갈 수 있습니다.

플레이어는 NPC에게 사용 키를 누르고 채팅으로 말합니다. 애드온은 그 메시지를 근처 오브젝트(상점 카운터, 자판기, 감옥 문)와 최근 사건("플레이어가 체포됨", "은행 경보가 울리는 중")과 함께 보냅니다. 캐릭터는 매 대사마다 감정 태그를 붙여 답하고, { "name": "OPEN_DOOR", "targetId": "jail_door" } 같은 행동을 돌려주며, 애드온은 그 행동을 서버에서 실행합니다.

그룹 채팅(Pro 및 Team 요금제)은 최대 6명의 캐릭터를 하나의 대화에 넣으므로, NPC 무리가 플레이어와 한꺼번에 논쟁할 수 있습니다. Conversation Flow는 롤플레이 강도 브리핑 같은 긴 장면을 이끌고, 애드온이 반응하는 체크포인트 키워드(flowState)를 돌려줄 수 있습니다.

퀴즈 나이트 열기

퀴즈 엔진(Team 요금제)은 무대, 버저, 점수판을 서버 이벤트로 바꿔 줍니다.

  1. Neocortex 대시보드에서 질문 세트를 만듭니다. 서버의 상식 퀴즈 나이트, 새 롤플레이어를 위한 설정 퀴즈, 또는 새 플레이어가 직업을 받기 전에 통과해야 하는 규칙 확인 같은 것이 됩니다.
  2. 무대 위의 진행자 NPC가 라운드를 엽니다.
  3. 플레이어는 채팅으로 답하고, 애드온은 /v3/quiz를 통해 각 답을 퀴즈 엔진으로 보냅니다.
  4. 진행자가 누가 맞았는지 발표하고, 퀴즈 엔진이 점수와 리더보드를 처리합니다.
  5. 라운드 사이에 애드온이 HUD 패널에 순위를 그립니다.

Garry's Mod 게임 내 스크린샷 스크린샷: Garry's Mod © Valve

음성 명령을 따르는 도우미

플레이어마다 말을 듣는 도우미 NPC를 주세요. "나를 따라와", "여기서 기다려", "문을 지켜", "상자 두 개 가져와" 같은 명령을 따릅니다. Neocortex 대시보드에서는 명령 세트를 액터, 행동, 대상으로 설계합니다. 예를 들어 액터는 "helper", 행동은 "follow", "wait", "guard", "bring", 대상은 "me", "door", "crate"입니다.

플레이어는 자연스럽게 말하고, 애드온은 일치한 명령을 즉시 받습니다. 한 문장에 여러 행동과 수량이 들어 있어도 됩니다. 푸시투토크와 항상 듣기 모두 지원하고, 여러 언어에서 동작하며, 클라우드 왕복이 없습니다. 플레이어의 기기에서 실행되므로 클라이언트는 일치한 명령을 서버로 보냅니다.

Voice Commands는 라이선스가 필요한 SDK입니다. Voice Commands 라이선스 문의하기.

Garry's Mod AI NPC 애드온 코드

API와 관련된 모든 것은 서버에서 실행됩니다. 서버는 게임 상태를 읽어 플레이어의 메시지와 함께 /v3/chat을 통해 Neocortex 캐릭터에게 보내고, 답을 자막으로 보여 주며, /v3/audio/generate 또는 /v3/audio/stream에서 음성을 재생하고, 캐릭터가 돌려준 행동을 실행합니다.

-- Server realm only: the key stays in garrysmod/data and never reaches players.
local apiKey = string.Trim(file.Read("neocortex_key.txt", "DATA") or "")
local function AskNPC(ply, text, sessionId, onReply)
    HTTP({
        url = "https://api.neocortex.link/v3/chat",
        method = "POST", type = "application/json",
        headers = { ["x-api-key"] = apiKey },
        body = util.TableToJSON({
            characterIds = { "CHARACTER_ID" },
            message = text,
            playerId = ply:SteamID64(),
            sessionId = sessionId or ""
        }),
        success = function(code, body)
            local data = util.JSONToTable(body)
            if code == 200 and data then onReply(data) end -- data.sessionId, data.messages
        end,
        failed = function(reason) print("[Neocortex] " .. reason) end
    })
end

AI NPC를 위한 운영 원칙

Garry's Mod 서버는 자체 규칙을 정하므로, AI NPC 애드온은 여러분이 운영하는 서버나 운영자가 동의한 서버에서만 실행하세요. 그리고 플레이어에게 AI와 대화하고 있다고 알려 주세요. 게시할 때는 Steam 워크숍 규칙을 따르고, 각 서버 운영자가 자신의 Neocortex API 키를 쓰도록 하세요. 플레이어별 쿨다운을 두면 한 명이 NPC를 도배하지 못합니다.

서버 운영자를 위한 핵심 정리

빈 폴더에서 말하는 NPC까지는 다섯 단계면 됩니다.

  1. 애드온 폴더 만들기. 서버 측 Lua 파일과 소환 가능한 NPC 엔티티를 넣습니다.
  2. Neocortex 대시보드에서 캐릭터 설계하기. 상점 주인, 질문 세트가 있는 퀴즈 진행자, 도우미의 명령 세트.
  3. 서버에서 HTTP()로 /v3/chat과 /v3/quiz 호출하기. 플레이어에게 응답은 net 라이브러리로 보냅니다.
  4. API 키는 서버 측 설정 파일에 보관하기. 클라이언트 Lua나 워크숍 업로드에는 절대 넣지 마세요.
  5. 공개 서버에 올리기 전에 친구와 로컬 listen 서버에서 테스트하기.

상점 주인부터 시작하세요. 캐릭터 하나, HTTP() 호출 하나, 채팅 훅 하나면 플레이어에게 Neocortex NPC가 무엇을 할 수 있는지 보여 주기에 충분합니다. 퀴즈 쇼는 같은 서버 코드를 기반으로 합니다. 음성 명령이 플레이어의 기기에서 어떻게 동작하는지는 게임 모드용 기기 내 음성 명령 글에서 확인하세요. 엔진 수준의 Source 모드는 Half-Life 2 AI NPC 모드 가이드를 보세요.

도구 버전과 링크는 2026년 10월 기준 확인. 모딩 도구는 자주 바뀌므로 각 프로젝트 페이지에서 최신 릴리스를 확인하세요.

자주 묻는 질문

Garry's Mod에 AI NPC를 추가할 수 있나요?

네. Garry's Mod 애드온은 Lua로 작성되며, 게임에는 내장 HTTP() 함수가 있습니다. 따라서 서버 측 애드온이 플레이어의 말을 AI 캐릭터에게 보내고, 그 답에 따라 행동할 수 있습니다. Neocortex는 캐릭터, 음성, 돌려주는 행동을 제공합니다.

Garry's Mod 애드온이 웹 API를 호출할 수 있나요?

네. 전역 HTTP() 함수와 http.Fetch, http.Post 도우미가 서버나 클라이언트에서 비동기 요청을 보냅니다. AI NPC 애드온이라면 Neocortex API 키가 플레이어에게 전달되지 않도록 호출은 서버에서 하세요.

Garry's Mod 서버에서 퀴즈 쇼는 어떻게 여나요?

진행자 NPC를 소환하고, 플레이어의 채팅 답을 퀴즈 엔진으로 보내고, 점수를 HUD 패널에 보여 주세요. Neocortex 퀴즈 엔진이 질문, 점수, 리더보드를 처리하므로 애드온은 무대와 채팅만 다루면 됩니다.

Garry's Mod NPC가 음성 명령을 따를 수 있나요?

클라이언트 측 구성 요소를 쓰면 가능합니다. Neocortex Voice Commands는 각 플레이어의 PC에서 실행되며, "나를 따라와"나 "문을 지켜"처럼 말한 구문을 애드온이 즉시 받는 명령으로 바꿉니다. 인터넷 없이 동작합니다. 음성 부분은 플레이어의 기기에서 실행되므로, 플레이어는 워크숍 애드온과 함께 음성 부분도 설치해야 합니다.

Garry's Mod 서버에서 API 키는 어디에 두나요?

서버에만 두세요. 예를 들어 서버 데이터 폴더의 파일에 넣고, 애드온이 시작할 때 읽게 합니다. 클라이언트 Lua나 워크숍 업로드에 키를 넣으면 안 됩니다. 모든 플레이어가 그 파일을 내려받기 때문입니다.

비슷한 글

더 읽어 보기