虚幻4中显示鼠标并自定义样式的蓝图配置：TaoToken统一Key接入Player Controller与UMG

1. 虚幻4鼠标显示与自定义样式的真实场景在虚幻4里做 UI 交互尤其是背包、设置面板、技能轮盘这类需要精确点击的界面时默认的鼠标光标往往不够用。引擎自带的箭头样式在深色背景上几乎看不见或者和你的美术风格完全不搭。更麻烦的是很多新手会遇到「鼠标能点但看不见」或者「鼠标样式改了但只在编辑器里生效打包后失效」的问题。这篇内容就是围绕虚幻4中显示鼠标并自定义样式的完整蓝图配置流程来写的。核心涉及三个东西Player Controller 里启用鼠标、UMG 控件蓝图里做光标贴图、以及项目设置里把两者串起来。适合正在做 UE4 UI 交互、需要把鼠标样式换成自己美术资源的开发者。我会把蓝图节点配置和 settings.json 骨架都给出来你照着连就能跑。先说一个我踩过的坑鼠标指针的真实坐标点永远在图片的正中心不是左上角。所以你的光标图片必须把「针尖」位置放在画布正中间否则点击位置和视觉位置会对不上。这个细节后面会展开。另外如果你在项目里同时用了 TaoToken 这类统一 Key 接入服务来管理多个模型的 API 调用鼠标样式这种 UI 层的配置和网络层是解耦的不用担心互相影响。下面从环境准备开始。2. TaoToken 前置统一 Key 与项目配置骨架在进入蓝图之前先把接入层的东西理清楚。TaoToken 的作用是让你用一个统一的 Key 去调用不同模型的 API不用在每个模型平台单独注册和切换。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。如果你只是做鼠标样式配置这一步可以跳过。但如果你后续要在 UE4 里接 AI 对话、代码生成或者 Agent 能力建议先把 Key 和配置文件准备好。下面是一个 settings.json 骨架放在项目 Config 目录或者你自己的插件配置目录下都行{ TaoToken: { api_base: https://taotoken.net/api, api_key: sk-your-unified-key-here, default_model: claude-sonnet, timeout_seconds: 30, retry: { max_attempts: 3, backoff_ms: 800 }, models: { chat: claude-sonnet, coding: claude-code, agent: coding-plan } }, UMG: { cursor_widget_path: /Game/UI/WBP_Cursor.WBP_Cursor_C, cursor_size: [100, 100] } }这个骨架里 UMG 部分是我自己加的方便你在蓝图里读取光标控件路径。实际项目里你可以把 api_key 放到环境变量或者加密配置里不要硬编码进仓库。拿到 Key 的流程很简单进控制台创建一个 API Key然后复制到配置文件。控制台地址是 https://taotoken.net/console API Keys 管理页是 https://taotoken.net/api-keys 。如果你要用 Claude Code 或者 Anthropic 风格的接口文档在 https://taotoken.net/doc 和 https://taotoken.net/claude-code-anthropic 都有说明。注意API Key 只显示一次创建后立刻保存。如果泄露了去控制台吊销重新生成。3. 可复制配置Player Controller 启用鼠标 UMG 光标控件3.1 Player Controller 里勾选 Show Mouse Cursor打开你的 Player Controller 蓝图在 Details 面板搜索「Show Mouse Cursor」勾上。这一步是最基础的勾上之后运行游戏就能看到默认鼠标。如果你不想在 Details 里勾也可以在蓝图里用节点控制。在 Event BeginPlay 后面接一个Show Mouse Cursor节点Target 连 Self也就是 Player Controller勾选 Show。这样你可以在运行时动态开关鼠标。同时建议把Enable Click Events和Enable Mouse Over Events也勾上否则 UMG 按钮的点击和悬停可能不响应。这三个选项在 Player Controller 的 Mouse Interface 分类下。3.2 创建 UMG 光标控件蓝图新建一个 Widget Blueprint命名为 WBP_Cursor。打开后在 Canvas Panel 里放一个 Image设置如下Size Box 或者直接设 Image 的 Size 为 100 x 100Image 的 Brush 设置为你自己的光标贴图锚点设为屏幕中心或者跟随鼠标具体看你的使用方式填充模式设为 Fill不要用 Box 或者 Nine Slice否则会拉伸变形关键点你的光标图片里针尖必须位于图片的正中心。比如一张 100x100 的图针尖应该在 (50, 50) 这个像素位置。如果你直接把一个左上角带箭头的图丢进去点击位置会偏到右下角用户会觉得「点不准」。我试过用一张 128x128 的图针尖放在 (64, 64)运行后点击位置完全吻合。如果你美术给的图针尖不在中心用 PS 或者任何图片工具把画布扩展一下把针尖移到中心。3.3 项目设置里指定光标控件打开 Project Settings找到 User Interface 分类里面有一个「Cursor」或者「Default Cursor Widget」的选项不同 UE4 小版本位置略有差异一般在 Engine - User Interface 下。把 WBP_Cursor 选上。这一步做完运行游戏时引擎就会用你的 UMG 控件来绘制鼠标而不是默认的硬件光标。3.4 蓝图节点串联示例如果你要在运行时切换光标样式可以在 Player Controller 里写这样的逻辑Event BeginPlay - Show Mouse Cursor (Show true) - Set Input Mode Game and UI - Create Widget (Class WBP_Cursor) - Add to Viewport - Set Mouse Position (可选用于初始化位置)Set Input Mode Game and UI这个节点很重要它让鼠标既能点 UI 又能控制游戏输入。如果你只用 UI Only游戏内的视角旋转会失效只用 Game OnlyUI 点不了。4. 验证请求与成功结果运行后鼠标样式生效的具体操作配置完成后按 Play 运行。你应该能看到鼠标光标变成了你 WBP_Cursor 里设置的图片样式点击 UI 按钮时点击位置和视觉位置一致鼠标移动到屏幕边缘时坐标不会突然变成 0这是 HUD 绘制方案常见的 bugUMG 方案不会有这个问题如果你要验证 TaoToken 的 API 是否连通可以在 UE4 里用 Http 节点发一个测试请求。下面是一个简单的验证流程Event BeginPlay - Http Get (URL https://taotoken.net/api/models) - Bind Event On Request Complete - Print String (Response)或者在外部用 curl 先测curl -X POST https://taotoken.net/api/chat/completions \ -H Authorization: Bearer sk-your-key \ -H Content-Type: application/json \ -d {model:claude-sonnet,messages:[{role:user,content:ping}]}返回 200 并且有 JSON 内容说明 Key 和网络都正常。模型对话的入口在 https://taotoken.net/chat 你可以在那里直接测试模型是否可用。成功结果的标准鼠标样式在打包后的 exe 里也生效不只是编辑器里生效。这一点很多教程没提打包后失效通常是因为光标控件路径没被正确引用或者项目设置里的 Cursor Widget 在打包时被裁剪了。解决办法是在 Project Settings - Packaging 里把 WBP_Cursor 所在的目录加到「Additional Asset Directories to Cook」。5. 本篇常见错排查5.1 鼠标看不见先检查 Player Controller 的 Show Mouse Cursor 是否勾上。如果勾了还看不见检查 Input Mode 是不是被设成了 Game Only。Game Only 模式下鼠标会被隐藏。5.2 鼠标样式改了但没生效检查 Project Settings 里的 Cursor Widget 是否指向了正确的 WBP_Cursor。如果指向了默认的你的自定义样式不会显示。另外确认 WBP_Cursor 里的 Image 的 Brush 确实设置了贴图而不是空的。5.3 点击位置偏移九成是光标图片的针尖不在正中心。把图片画布扩展让针尖位于 (width/2, height/2)。另外检查 Image 的 Alignment 是不是 (0.5, 0.5)如果是 (0, 0) 也会偏。5.4 鼠标到达屏幕边缘坐标变 0这是用 HUD 绘制鼠标时的经典问题。UMG 方案不会有这个问题因为 UMG 的鼠标位置是引擎统一管理的。如果你非要用 HUD 绘制需要在边缘做 clamp 处理比较麻烦。建议直接用 UMG。5.5 打包后鼠标样式丢失前面提过把 WBP_Cursor 加到 Additional Asset Directories to Cook。另外检查打包日志里有没有「Cursor widget not found」之类的警告。5.6 TaoToken 请求返回 401检查 api_key 是否正确复制有没有多余空格。去 https://taotoken.net/api-keys 重新生成一个再试。如果还是 401检查请求头里的 Authorization 格式是不是Bearer sk-xxx。6. 语义一致 CTA按场景分流如果你是在做 UI 接入和排障建议先去 API Keys 页面把 Key 管好再看接入文档https://taotoken.net/api-keys 和 https://taotoken.net/doc 。如果你要验证模型是否可用直接去模型对话页面发一条消息https://taotoken.net/chat 。如果你是要长期做编码或者 Agent 开发比如在 UE4 里接 Claude Code 做自动化脚本生成建议看 Coding Planhttps://taotoken.net/coding-plan 。Claude Code 和 Anthropic 风格的接入说明在 https://taotoken.net/claude-code-anthropic 。最后说一个实用技巧UE4 的 UMG 光标控件可以做成动态的比如根据当前交互状态切换不同样式默认箭头、可点击手型、加载中。你只需要在 WBP_Cursor 里放多个 Image用 Visibility 切换然后在 Player Controller 里根据状态调用。这样比做多个 Widget 再替换要轻量得多。