游戏 AI / 系统课时

把玩家输入接到 NPC 回复

把玩家输入接到 NPC 回复

玩家在游戏中输入一句话后,需要经过事件触发、网络请求、模型生成和界面更新,才能看到 NPC 的回复。本篇使用 Node.js 和一个简单的浏览器对话界面完成真实调用,验证一轮对话从发送到结束的完整过程,并为后续接入游戏引擎建立可复用的接口边界。

学习目标

  • 理解玩家输入事件、游戏客户端、后端服务和 LLM 之间的请求与返回关系。
  • 编写可以调用真实模型的服务端接口,并在界面中展示 NPC 回复。
  • 验证等待、成功、失败和输入恢复四种基本行为,避免重复发送和界面卡住。

确定一次对话的请求边界

一轮 NPC 对话可以定义为:玩家提交一段非空文本,服务端使用 NPC 身份约束调用模型,模型返回文本后,客户端将结果展示在当前对话框中。请求应当有明确的开始和结束,不能让渲染循环直接等待远程接口。

最小闭环包含以下步骤:

  1. 玩家点击发送按钮,客户端读取输入框文本并进行基本校验。
  2. 客户端进入等待状态,通过 HTTP POST 将文本发送给自己的后端服务。
  3. 后端读取服务端保存的 API Key,调用 LLM,并提取回复文本。
  4. 后端返回包含 reply 字段的 JSON,客户端将其更新到 NPC 对话框。
  5. 无论成功还是失败,客户端都退出等待状态,恢复发送按钮。

玩家输入到 NPC 回复的请求与返回数据流

API Key 必须放在可信服务端,不能写进 Unity、Unreal 或浏览器客户端的发布包中。本例用浏览器模拟游戏对话 UI,未来接入引擎时替换输入和展示部分即可,后端接口可以保留。

本例只处理单轮对话,每次发送当前输入文本,不会自动保留之前的聊天记录。NPC 的输出也只作为台词展示,不负责直接改变金币、背包或任务状态。

实现服务端 NPC 接口

准备 Node.js 20 或更新版本、可用的 OpenAI API Key,以及能够访问模型接口的网络。创建一个空目录,在终端执行以下命令。这里使用 Bash,Windows PowerShell 可以使用 $env:OPENAI_API_KEY='真实密钥' 设置对应环境变量。

bash
npm init -y
npm install openai
export OPENAI_API_KEY='<YOUR_API_KEY>'

预期结果:当前目录生成 package.json,并安装 openai 依赖。将 <YOUR_API_KEY> 替换成真实密钥后,启动的 Node.js 进程可以从 OPENAI_API_KEY 读取凭证。不要将真实密钥提交到代码仓库。

在该目录创建 server.mjs。服务端同时提供静态网页和 /api/npc 接口,使用 OpenAI Node SDK 的 Responses API 获取文本回复。代码为完整文件,创建下一节的 index.html 后即可运行。

js
import OpenAI from 'openai';
import { createServer } from 'node:http';
import { readFileSync } from 'node:fs';

const page = readFileSync(new URL('./index.html', import.meta.url), 'utf8');
const client = new OpenAI({ maxRetries: 0 });

function sendJson(res, status, data) {
  res.writeHead(status, {
    'Content-Type': 'application/json; charset=utf-8'
  });
  res.end(JSON.stringify(data));
}

createServer(async (req, res) => {
  if (req.method === 'GET' && req.url === '/') {
    res.writeHead(200, {
      'Content-Type': 'text/html; charset=utf-8'
    });
    res.end(page);
    return;
  }

  if (req.method !== 'POST' || req.url !== '/api/npc') {
    sendJson(res, 404, { error: '路由不存在' });
    return;
  }

  try {
    const parts = [];
    let bytes = 0;

    // 限制请求体大小,避免任意长度的玩家输入进入模型接口。
    for await (const part of req) {
      bytes += part.length;
      if (bytes > 4096) {
        sendJson(res, 413, { error: '请求内容过长' });
        return;
      }
      parts.push(part);
    }

    let data;
    try {
      data = JSON.parse(Buffer.concat(parts).toString('utf8'));
    } catch {
      sendJson(res, 400, { error: '请求必须是合法 JSON' });
      return;
    }

    const text = data?.text;
    if (typeof text !== 'string' || !text.trim() || text.length > 200) {
      sendJson(res, 400, { error: '请输入 1~200 个字符' });
      return;
    }

    // NPC 人设放在服务端指令中,玩家输入仅作为本轮对话内容。
    const response = await client.responses.create({
      model: 'gpt-4.1-mini',
      instructions: '你是港口守卫。使用中文回复玩家,最多两句话。不要声称改变金币、背包或任务状态。',
      input: text,
      max_output_tokens: 120
    });

    const reply = response.output_text?.trim() || '我暂时无话可说。';
    sendJson(res, 200, { reply });
  } catch (error) {
    console.error('NPC 调用失败:', error.status || error.name);
    sendJson(res, 502, { error: 'NPC 暂时无法回复' });
  }
}).listen(3000, '127.0.0.1', () => {
  console.log('NPC demo: http://127.0.0.1:3000');
});

预期行为:合法请求调用模型并返回 HTTP 200,响应体包含 reply 字符串;空文本或超过长度限制的文本返回 HTTP 400;模型调用失败时返回 HTTP 502,并且不向客户端泄露 API Key 或详细服务错误。

这里使用 response.output_text,它是 SDK 提供的文本聚合属性,不需要假设模型输出数组的第一个元素必定是文本消息。max_output_tokens 限制回复的输出预算,实际文字长度仍由模型生成结果决定。

连接输入事件与 NPC 文本展示

在同一目录创建 index.html。为了专注于对话闭环,页面只保留输入框、发送按钮、玩家台词和 NPC 台词。游戏引擎中的输入事件、HUD 文本组件可以对应替换这些元素。

html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>NPC 对话测试</title>
</head>
<body>
  <label>对守卫说:<input id="input" maxlength="200"></label>
  <button id="send">发送</button>
  <p id="player">玩家:尚未发言</p>
  <p id="npc" aria-live="polite">守卫:你好。</p>

  <script>
    const input = document.querySelector('#input');
    const send = document.querySelector('#send');
    const player = document.querySelector('#player');
    const npc = document.querySelector('#npc');

    send.addEventListener('click', async () => {
      const text = input.value.trim();
      if (!text) return;

      // 请求未结束前禁止再次提交,避免同一轮对话重复发送。
      send.disabled = true;
      player.textContent = '玩家:' + text;
      npc.textContent = '守卫:思考中…';

      try {
        const response = await fetch('/api/npc', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ text })
        });

        const data = await response.json();
        if (!response.ok) {
          throw new Error(data.error || '请求失败');
        }

        // 使用文本赋值,不把模型回复作为 HTML 执行。
        npc.textContent = '守卫:' + data.reply;
      } catch (error) {
        npc.textContent = '守卫:' + error.message;
      } finally {
        send.disabled = false;
        input.focus();
      }
    });
  </script>
</body>
</html>

预期结果:点击发送按钮后,玩家文本立即显示,NPC 文本先显示“思考中…”,随后被真实模型回复替换。如果服务端返回错误,NPC 区域显示可读的错误信息。请求结束后发送按钮重新启用。

send.disabled 是防止重复提交的最小措施;finally 确保成功和失败都能恢复交互。textContent 将回复当作普通文本显示,避免模型生成的内容被浏览器当作 HTML 执行。

真实项目还应在服务器入口检查玩家身份、会话归属与请求频率,不能仅依赖浏览器上的长度限制和禁用按钮。

启动服务并验收对话闭环

确认两个文件位于同一目录,且当前终端已经配置 OPENAI_API_KEY,然后执行:

bash
node server.mjs

预期输出:

text
NPC demo: http://127.0.0.1:3000

打开浏览器访问 http://127.0.0.1:3000,输入“你好,城门什么时候关?”并点击发送。成功时应依次看到玩家台词、等待提示和守卫的中文回复。具体回复由模型实时生成,不应把某一句固定台词当成验收依据。

按以下条件检查:

  1. 正常发送:浏览器开发者工具的 Network 面板中出现一次 POST /api/npc,成功时 HTTP 状态为 200,响应 JSON 包含 reply。
  2. 空输入:清空输入框后点击发送,界面不发起 HTTP 请求。
  3. 等待期间重复点击:按钮处于禁用状态,同一轮不会再次发起发送。
  4. 服务错误:临时停止 Node.js 服务后再次发送,界面出现错误提示且按钮能够恢复。
  5. 下一轮输入:上一轮结束后修改文本再次发送,可以独立得到新的回复。

验收通过后,客户端的职责已经明确:采集输入、管理等待状态、发送请求和显示回复。服务端负责凭证、模型调用与输入校验。将来改成 Unity 或 Unreal 时,保留 /api/npc 的请求与响应协议,就可以更换前端实现而不需要重写整条调用链。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

把玩家输入接到 NPC 回复

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通