stream-unreal

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stream Unreal - docs orchestrator for Unreal Engine

Stream Unreal - Unreal Engine文档编排工具

Chat only. There is no Stream Video or Stream Feeds SDK for Unreal (

/video/docs/unreal

and the Feeds Unreal index both 404). If the user asks for calling or feeds in Unreal, say so up front and offer the alternatives (a platform SDK on a companion mobile app, or the REST/server API) rather than inventing an API.

The SDK is in beta.

IsBetaVersion: true

in the

.uplugin

; the surface can change between releases, and C++ and Blueprint coverage differ per operation. State this whenever the user pins a version or plans an upgrade.

This skill orchestrates: it gates the request against engine support and feature support, routes to the exact docs page, fetches it live, and applies it - while carrying the curated Unreal-specific knowledge the docs do not have (the

ApiKey

BeginPlay

ordering trap, the UMG widget layer, cooking, and the per-platform config that decides whether a packaged build is usable).

Rules (read once per session):

RULES.md

- non-negotiable rules + Unreal pitfalls. Read before writing any code.

仅支持聊天功能。目前没有适用于Unreal的Stream Video或Stream Feeds SDK（

/video/docs/unreal

和Feeds Unreal索引均返回404）。如果用户询问Unreal中的通话或信息流功能，请直接告知此情况，并提供替代方案（配套移动应用使用平台SDK，或使用REST/服务器API），切勿自行编造API。

该SDK处于测试版。

.uplugin

文件中

IsBetaVersion: true

；不同版本间接口可能发生变化，且C++与Blueprint的功能覆盖范围因操作而异。每当用户锁定版本或计划升级时，都需告知此情况。

本技能负责编排协调：它会根据引擎支持情况和功能支持情况筛选请求，路由至准确的文档页面，实时获取内容并应用——同时承载官方文档未涵盖的Unreal专属知识（

ApiKey

BeginPlay

调用顺序陷阱、UMG组件层、烘焙操作，以及决定打包构建是否可用的各平台配置）。

规则（每次会话阅读一次）：

RULES.md

——不可协商的规则+Unreal常见陷阱。编写任何代码前请先阅读。

Step 0: Three gates, before any code

步骤0：编写代码前的三道检查关卡

Resolve all three from the user's words plus a read-only probe. Each one can change the answer from "here is the code" to "that is not possible" - so none of them is optional, and none of them belongs in a compile error later.

结合用户描述和只读探测结果完成所有三项检查。每一项都可能将答案从“这是代码”变为“无法实现”——因此所有检查均为必填项，不能留到编译阶段再发现问题。

Gate 1: engine version (picks the release asset, or stops the task)

关卡1：引擎版本（选择对应的发布资源，或终止任务）

Target engine	What to do
5.7 or 5.8	Supported. Download the matching release asset - see `setup.md` 2.
4.27 / 5.0 / 5.1	Only v1.3.0 (Dec 2022) covers these. Say so: the API predates v2.0.0, `BlockUser` / `UnblockUser` / `GetBlockedUsers` do not exist, and none of this skill's v2 guidance is guaranteed to apply.
5.2 through 5.6	Hard stop - no release supports these. Say it immediately. The options are: upgrade the project to 5.7/5.8, or build the plugin from source against an unsupported engine (unverified, not recommended). Do not download an asset and hope.

Detect the version from the

.uproject

rather than asking:

bash

find . -maxdepth 2 -name "*.uproject" -exec sh -c 'echo "== $1"; grep -m1 EngineAssociation "$1"' _ {} \;

There is one release archive per engine version (

StreamChat-5.7.zip

StreamChat-5.8.zip

) and picking the wrong one is a silent mismatch, not a clean error. Resolve the version first, then download.

目标引擎版本	操作说明
5.7或5.8	支持。下载匹配的发布资源——参见 `setup.md` 第2节。
4.27 / 5.0 / 5.1	仅v1.3.0（2022年12月版本）支持这些版本。需告知用户：该API早于v2.0.0， `BlockUser` / `UnblockUser` / `GetBlockedUsers` 不存在，且本技能中所有v2相关指导均无法保证适用。
5.2至5.6	完全不支持——无对应发布版本。请立即告知用户。可选方案为：将项目升级至5.7/5.8，或针对不支持的引擎版本从源码构建插件（未经验证，不推荐）。切勿下载资源尝试兼容。

通过

.uproject

文件检测版本，而非询问用户：

bash

find . -maxdepth 2 -name "*.uproject" -exec sh -c 'echo "== $1"; grep -m1 EngineAssociation "$1"' _ {} \;

每个引擎版本对应一个发布压缩包（

StreamChat-5.7.zip

、

StreamChat-5.8.zip

），选择错误版本会导致静默不兼容，而非明确报错。请先确定版本，再下载资源。

Gate 2: feature support (say no in the plan, not in a compile error)

关卡2：功能支持（在计划阶段明确告知不可行，而非等到编译报错）

Not implemented in the Unreal SDK as of v2.0.0. If the request needs one of these, say so before writing code:

Attachments and file/image uploads
Sending threaded replies, and the thread list
Quoted messages, mentions, pinning messages
Offline persistence and optimistic sending
Channel archiving and channel pinning
Polls, draft messages, message reminders, location sharing

Implemented: messaging (send / edit / fetch / full-text search / soft delete, hard delete from C++, C++ pagination both directions), channels (query / watch / create / update / truncate / hide+show / freeze / members), reactions (score + enforce-unique, remove, C++ pagination), read state and unread counts, typing indicators, moderation (ban, shadow ban, mute users, mute channels, block and unblock users, flag messages and users, query banned users), slow mode, push device registration, presence + watchers + own-capabilities, real-time events, and preview UI widgets.

The docs contradict the SDK here. The Unreal introduction page still lists "User blocking" as not implemented, but
BlockUser
,
UnblockUser
, and
GetBlockedUsers
all ship on
UStreamChatClientComponent
in v2.0.0. Trust the SDK. The repo README feature list is the accurate one.

截至v2.0.0，Unreal SDK尚未实现以下功能。如果用户的请求涉及这些功能，请在编写代码前告知：

附件与文件/图片上传
发送线程回复及线程列表展示
引用消息、提及、消息置顶
离线持久化与乐观发送
频道归档与频道置顶
投票、草稿消息、消息提醒、位置共享

已实现功能：消息（发送/编辑/获取/全文搜索/软删除、C++硬删除、双向分页）、频道（查询/监听/创建/更新/清空/隐藏+显示/冻结/成员管理）、 reactions（评分+强制唯一、移除、C++分页）、已读状态与未读计数、输入状态提示、 moderation（封禁、影子封禁、静音用户、静音频道、拉黑与解除拉黑用户、标记消息与用户、查询封禁用户）、慢模式、推送设备注册、在线状态+观察者+自身权限、实时事件、预览UI组件。

官方文档与SDK存在矛盾。Unreal介绍页面仍将“用户拉黑”列为未实现功能，但v2.0.0版本的
UStreamChatClientComponent
已包含
BlockUser
、
UnblockUser
和
GetBlockedUsers
。请以SDK为准。仓库README功能列表是准确的参考来源。

Gate 3: C++ or Blueprint

关卡3：使用C++还是Blueprint

Ask only if genuinely unclear; otherwise infer (a

Source/

dir with a

.Build.cs

means C++ is available).

C++ is the full surface. Callback-based (
```
TFunction<void(...)>
```
),
```
TOptional<>
```
parameters, and all pagination.
Blueprint covers the common operations as latent nodes, with
```
...BP
```
-suffixed variants where the C++ signature takes
```
TOptional
```
(
```
SendMessageBP
```
,
```
BanUserBP
```
,
```
ShadowBanUserBP
```
,
```
MuteUserBP
```
,
```
BanMemberBP
```
).
Pagination and the lower-level APIs are C++ only. If the user wants a Blueprint-only integration, say up front which parts will need C++ - and note the naming trap:
```
BanUserBP(User, FTimespan, FString, bool)
```
takes required args where
```
BanUser(User, TOptional<FTimespan>, TOptional<FString>, bool)
```
takes optional ones. A zero
```
FTimespan
```
means "unlimited", not "already expired".

仅当确实无法判断时才询问用户；否则可通过项目结构推断（包含

.Build.cs

的

Source/

目录表示支持C++）。

**C++**提供完整功能接口。基于回调（
```
TFunction<void(...)>
```
）、
```
TOptional<>
```
参数，支持所有分页操作。
Blueprint通过延迟节点覆盖常见操作，对于C++签名中包含
```
TOptional
```
的操作，提供后缀为
```
...BP
```
的变体（
```
SendMessageBP
```
、
```
BanUserBP
```
、
```
ShadowBanUserBP
```
、
```
MuteUserBP
```
、
```
BanMemberBP
```
）。
分页操作和底层API仅支持C++。如果用户希望仅使用Blueprint集成，请提前告知哪些部分需要C++——同时注意命名陷阱：
```
BanUserBP(User, FTimespan, FString, bool)
```
接收必填参数，而
```
BanUser(User, TOptional<FTimespan>, TOptional<FString>, bool)
```
接收可选参数。
```
FTimespan
```
为0表示“永久”，而非“已过期”。

The docs convention - and the coverage caveat that matters here

文档约定——以及至关重要的覆盖范围说明

Every Stream docs page has a Markdown twin: take the page URL, drop the trailing
/
, add
.md
.

https://getstream.io/chat/docs/unreal/query-channels/   ->   https://getstream.io/chat/docs/unreal/query-channels.md

Always fetch the

.md

variant - clean Markdown, verbatim code, no page chrome. The live index that lists every Unreal page:

https://getstream.io/cli/docs/chat-unreal.md

Now the caveat, and it is the single most important thing about this docs tree. The

/chat/docs/unreal/

tree is largely the shared cross-SDK prose. Only about 26 of its 61 pages carry an
Unreal
code tab; the rest show JavaScript, Node, Kotlin - even a C#/Unity sample on the rate-limits page. Several pages document features the Unreal SDK does not have at all (

file-uploads

threads

pinned-messages

polls-api

drafts

message-reminders

location-sharing

archiving-channels

pinning-channels

) with working JavaScript and no per-page warning. And some pages for features the SDK does have carry no Unreal code (

send-reaction

moderation

search

message-delivery-and-read-status

freezing-channels

So:

Never translate a JavaScript snippet into C++.
```
channel.sendReaction(...)
```
does not tell you the shape of
```
UChatChannel::SendReaction
```
. A JS-only page is a page whose concepts apply and whose code does not.
When the page has no Unreal tab, get the API from the source of truth ladder below instead, and say where you got it.
```
docs-map.md
```
marks per-page Unreal coverage. Use it - it saves a wasted fetch and a wrong signature.

每个Stream文档页面都有对应的Markdown版本：取页面URL，去掉末尾的
/
，添加
.md
。

https://getstream.io/chat/docs/unreal/query-channels/   ->   https://getstream.io/chat/docs/unreal/query-channels.md

请始终获取

.md

版本——格式整洁的Markdown、原文代码、无页面装饰。列出所有Unreal页面的实时索引：

https://getstream.io/cli/docs/chat-unreal.md

。

现在是关键说明，也是关于此文档树最重要的一点。

/chat/docs/unreal/

文档树大部分为跨SDK共享内容。61个页面中仅约26个包含
Unreal
代码标签；其余页面展示JavaScript、Node、Kotlin代码——甚至在速率限制页面出现C#/Unity示例。部分页面记录的功能是Unreal SDK完全不具备的（

file-uploads

、

threads

、

pinned-messages

、

polls-api

、

drafts

、

message-reminders

、

location-sharing

、

archiving-channels

、

pinning-channels

），仅提供可运行的JavaScript代码，且无页面级警告。还有一些页面记录的是SDK已具备的功能，但未提供Unreal代码（

send-reaction

、

moderation

、

search

、

message-delivery-and-read-status

、

freezing-channels

）。

因此：

切勿将JavaScript代码片段翻译成C++。
```
channel.sendReaction(...)
```
无法告知你
```
UChatChannel::SendReaction
```
的接口结构。仅含JS代码的页面，其概念适用，但代码不适用。
当页面无Unreal标签时，请从下方的权威来源阶梯获取API，并说明来源。
```
docs-map.md
```
标记了各页面的Unreal代码覆盖情况。请使用该文件——可避免无效获取和错误签名。

Source-of-truth ladder

权威来源阶梯

Walk it in order. Stop at the first rung that answers the question, and cite which rung you used.

Rung	Source	Use for
1	The page's `Unreal` code tab ( `docs-map.md` says which pages have one)	Anything covered. Copy verbatim.
2	Plugin headers - `Plugins/StreamChat/Source/StreamChat/Public/*.h` in the user's project, else `raw.githubusercontent.com/GetStream/stream-chat-unreal/<tag>/...`	Exact signatures, defaults, `UFUNCTION` metadata, Blueprint availability. The final authority.
3	Doxygen C++ reference - https://getstream.github.io/stream-chat-unreal/	Browsing the class surface when you do not know the header name.
4	The sample project - the repo root is the sample: `Source/StreamChatSample/` , `Source/DocsSamples/`	Real wiring end to end. `StreamChatSampleHud.cpp` is a working connect + query + show-UI in 40 lines.

Read the headers from the version the project actually vendors (the plugin is copied into

Plugins/

, so it is right there - prefer it over GitHub

main

URL grounding: only fetch a page URL you got from

docs-map.md

or from a live index fetch in this conversation. Do not invent doc paths from memory.

按顺序查找。找到第一个能解答问题的来源后停止，并注明使用的来源层级。

层级	来源	适用场景
1	页面的 `Unreal` 代码标签（ `docs-map.md` 标注了哪些页面具备该标签）	所有已覆盖的功能。直接复制代码。
2	插件头文件——用户项目中的 `Plugins/StreamChat/Source/StreamChat/Public/*.h` ，否则使用 `raw.githubusercontent.com/GetStream/stream-chat-unreal/<tag>/...`	获取精确签名、默认值、 `UFUNCTION` 元数据、Blueprint可用性。最终权威来源。
3	Doxygen C++参考文档——https://getstream.github.io/stream-chat-unreal/	当不知道头文件名时，浏览类接口。
4	示例项目——仓库根目录即为示例： `Source/StreamChatSample/` 、 `Source/DocsSamples/`	完整的端到端实现示例。 `StreamChatSampleHud.cpp` 仅用40行代码实现了连接+查询+显示UI的完整流程。

请从项目实际引入的版本读取头文件（插件已复制到

Plugins/

目录中，直接读取即可——优先于GitHub

main

分支）。

URL规范：仅获取从

docs-map.md

或本次对话中实时索引获取的页面URL。切勿凭记忆编造文档路径。

Step 1: Classify the request

步骤1：对请求进行分类

With the gates passed, pick the mode:

How-to / reference ("how do I query channels?", "what does
```
EChannelFlags::Watch
```
do?") -> go straight to Docs lookup. No setup, no credentials.
Integrate ("add chat to my game", "wire Stream into this project") -> run
```
setup.md
```
, then Docs lookup per feature.
New project ("build me an Unreal chat app") ->
```
setup.md
```
then Docs lookup, scoped to the requested screens. If there is no Unreal project, tell the user to create it in the Epic launcher / Unreal Editor first - do not try to scaffold a
```
.uproject
```
by hand.
Chat UI ("show a channel list", "put chat on the HUD", "style the message bubbles") -> run
```
widgets.md
```
. This layer has no official documentation at all, so the runbook is the source: the
```
WBP_*
```
inventory, the
```
LoadClass
```
-by-path pattern, the
```
Setup()
```
-before-
```
AddToViewport()
```
rule, the context-ancestor model, theming, and the cook directive that path-loading requires.
Package / ship / run on device ("build for iOS", "why is it frozen on my phone?", "package for Android") -> run
```
platforms.md
```
. The per-platform config there is load-bearing, not polish: without it a packaged mobile build is variously unreadably small, frozen a few frames in, or deaf to touch.

If the user asks for a chat UI and has not said which, prefer the shipped
WBP_*
widgets over hand-built UMG for a first integration - they carry the safe-area handling, theming, and list pagination that is tedious to reproduce.

通过所有检查关卡后，选择对应模式：

操作指南/参考（“如何查询频道？”、“
```
EChannelFlags::Watch
```
的作用是什么？”）-> 直接进入文档查询。无需设置，无需凭证。
集成（“为我的游戏添加聊天功能”、“将Stream接入此项目”）-> 执行
```
setup.md
```
，然后针对各功能进行文档查询。
新项目（“帮我构建一个Unreal聊天应用”）-> 执行
```
setup.md
```
，然后进行文档查询，范围限定为请求的界面。如果没有Unreal项目，请告知用户先通过Epic启动器/Unreal Editor创建项目——切勿手动生成
```
.uproject
```
文件。
聊天UI（“显示频道列表”、“在HUD上添加聊天功能”、“设置消息气泡样式”）-> 执行
```
widgets.md
```
。该层无官方文档，因此运行手册即为权威来源：
```
WBP_*
```
组件清单、按路径
```
LoadClass
```
的模式、
```
Setup()
```
需在
```
AddToViewport()
```
之前调用的规则、上下文祖先模型、主题定制，以及路径加载所需的烘焙指令。
打包/发布/设备运行（“为iOS构建”、“为什么在我的手机上运行卡顿？”、“为Android打包”）-> 执行
```
platforms.md
```
。其中的各平台配置是核心要求，而非优化项：没有这些配置，打包后的移动构建可能出现显示过小、运行几帧后卡顿、无法响应触摸等问题。

如果用户请求聊天UI但未指定类型，优先使用内置的
WBP_*
组件而非手动构建UMG——这些组件包含安全区域处理、主题定制、列表分页等功能，手动实现会非常繁琐。

Step 2: Docs lookup (every request ends here)

步骤2：文档查询（所有请求最终都会进入此步骤）

Open
```
docs-map.md
```
. Find the row for the feature; it gives the exact
```
.md
```
URL and whether that page has Unreal code.
If the feature is not in the map, fetch the live index (
```
https://getstream.io/cli/docs/chat-unreal.md
```
) and pick from it.
Fetch the
.md
page(s) with WebFetch. At most 3 per request; beyond that, hand the user the index URL.
If the page has an Unreal tab, use its code verbatim, adapting only to the project's actor/lifecycle shape. If it does not, drop to rung 2 of the ladder and read the header.
Cite what you used:
```
Source: [Title](https://getstream.io/...)
```
, or
```
Source: Plugins/StreamChat/Source/StreamChat/Public/Channel/ChatChannel.h
```
for a header. Never answer SDK specifics from training data - if you did not read it this conversation, read it now or say you could not find it.
Apply best practices - one
```
QueryChannels
```
with a filter, then
```
Watch
```
plus WebSocket events; no per-tick queries; connect once. See
```
RULES.md
```
"Mindful API usage".

打开
```
docs-map.md
```
。找到对应功能的条目，它会提供精确的
```
.md
```
URL以及该页面是否包含Unreal代码。
如果功能未在映射表中，获取实时索引（
```
https://getstream.io/cli/docs/chat-unreal.md
```
）并从中选择。
获取
.md
页面，使用WebFetch。每次请求最多获取3个页面；超过3个时，请将索引URL提供给用户。
如果页面有Unreal标签，直接使用其代码，仅根据项目的Actor/生命周期结构进行调整。如果没有，则进入阶梯的第2层，读取头文件。
注明来源：
```
Source: [标题](https://getstream.io/...)
```
，或对于头文件使用
```
Source: Plugins/StreamChat/Source/StreamChat/Public/Channel/ChatChannel.h
```
。切勿根据训练数据回答SDK细节——如果本次对话中未读取相关内容，请立即读取或告知用户无法找到。
应用最佳实践——一次
```
QueryChannels
```
查询加过滤器，然后
```
Watch
```
加WebSocket事件；避免每帧查询；仅连接一次。参见
```
RULES.md
```
中的“合理使用API”部分。

What this skill carries

本技能包含的内容

The official docs cover the low-level client well where they have Unreal tabs, so this skill does not restate them. The curated, non-doc content is:

File	What it is
`RULES.md`	Non-negotiable rules + the Unreal pitfalls that break builds or fail silently. Every rule is stated once, here.
`setup.md`	Engine-version-aware plugin install, `Build.cs` module deps, CLI credentials, and the verified minimal client wiring.
`widgets.md`	The UMG widget layer - undocumented upstream. Inventory, path-loading, `Setup` ordering, contexts, theming, cooking.
`platforms.md`	iOS / Android / desktop config, signing, and the build-vs-package distinction. Includes deploy + log-reading commands.
`docs-map.md`	Intent -> exact docs page, annotated with per-page Unreal-code coverage, plus the source-code fallback.

官方文档在有Unreal标签的页面中对底层客户端的覆盖较好，因此本技能不会重复这些内容。本技能包含的是经过整理、官方文档未涵盖的内容：

文件	说明
`RULES.md`	不可协商的规则+会导致构建失败或静默错误的Unreal陷阱。所有规则仅在此处说明一次。
`setup.md`	适配引擎版本的插件安装、 `Build.cs` 模块依赖、CLI凭证，以及经过验证的最小客户端连接配置。
`widgets.md`	UMG组件层——上游未提供文档。包含组件清单、路径加载、 `Setup` 调用顺序、上下文、主题定制、烘焙操作。
`platforms.md`	iOS/Android/桌面端配置、签名，以及构建与打包的区别。包含部署+日志读取命令。
`docs-map.md`	功能意图->精确文档页面，标注各页面的Unreal代码覆盖情况，以及源码 fallback 方案。

Support

支持

If the user asks for support or how to contact someone, direct them to getstream.io/contact. SDK gaps and feature requests go to the repo issues.

如果用户询问支持方式或联系渠道，请引导至getstream.io/contact。SDK缺陷和功能请求请提交至仓库issues。