Cocos on Last Stand

3D球场项目 (一)

Fri, 29 May 2026 08:54:50 +0800

介绍

2025 H2，我们开始进行技术规划。体育的现状是版权不够丰富，关注对于非版权比赛，只有两种方式:

图文直播: 就只有一个气泡文字展示
文字直播：类似消息板的文字滚动

这两个形式提现都很一般，完全激不起用户的任何兴趣。竞品如爱奇艺，对于非版权赛事，也是类似的效果：

我们脑暴了一个使用 3D 来展示的计划。

规划阶段

最初我们计划在图文直播的基础上做一个增强，在特定情境下，如进球、得分等场景下，播放一个固定的 3D 动画。起初我们打算使用 PAG 形式，这个是最简单的，而且我们之前也有了一定的了解，PAG 文件支持一定程度的自定义，PAG 里面的文字、颜色，图片等等都可以替换。但是交互性相对使用 3D 模型差一些，无法实现调整视角、旋转等等，这个方案技术挑战也不足，所以很快放弃了。

我后来又想使用 Filament 来播 3D 模型，腾讯视频 NBA 直播间曾经使用这个项目做过球员专属的进场特效，支持用户调整视角，互动性更强。

但是我们想到了几个问题：

谁来做这些动画呢？我们没有 3D 资产库，这意味着我们要让设计给每个球队设计一个球队，还有动画，我们的设计团队支持不了；
做到最后还是只是一个播动画，虽然交互比 PAG 提高了，但还是很单调，这个想作为一个卖点，还是有点单薄；

我们决定扩展一下这个项目，不再是图文项目的一个增强项目，而是构建一个图文直播的平替：

构建一套端到端的 AI 文生 3D 动画直播生成系统;
实现输入一段自然语言文本描述（如剧情、场景、动作、情感等），或标准序列化的 event数据（如网球 opta 数据），自动生成对应的3D动画内容，包括：剧本情节、3D角色与场景模型，以及带有镜头、动作与交互，可在客户端高性能展示的完整动画展示；

我们最后选择网球来落地这个项目，是基于以下的几点考量：

腾讯体育是釆买了 WTA 以及澳网 OPTA 数据的版权，相比原来的图文直播，3D 直播显然能给用户提供更好的临场感；
与篮球、足球相比，网球球员较少，场面没有那么复杂，不需要投入很多的额外精力进行性能优化（虽然我们后面还是做了一些）；

实际上国外已经有这种动画直播了：

澳网 3D 动画直播：

索尼体育 NFL 直播方案：

3D球场项目 (二)

Sat, 30 May 2026 10:00:00 +0800

在3D球场项目 (一)中，我们搞定了 3D 资产，也选定了落地框架。但是这不代表我们可以直接使用，这个作为的弹幕引擎的一部引入的 Cocos，是有一些定制逻辑在的。我们需要抽丝剥茧的先了解这个弹幕系统做了什么，再来制定具体的实施方案。

视频弹幕引擎

腾讯视频的弹幕引擎作为一个悠久的项目，支撑了腾讯视频大量的互动活动。弹幕引擎框架也是几经迭代，从最早的原生版本，到 PAG，再到现在的 Cocos Creator版本。

之所以想要使用 Cocos 来替换原来的方案，是因为有以下两大优势：

能力强： 支持完善的图形渲染、运动、物理、粒子、3D、光照等游戏引擎能力，充分利用游戏引擎所提供的这些能力，可以在弹幕上实现丰富的玩法。
跨平台： Cocos Creator 是一款高效、清凉、免费开源的跨平台图形引擎，支持所有主流平台支持，真正实现一次开发，全平台运行。框架迭代几乎都是使用 Cocos Creator 开发，少部分业务，如数据上报、客户端交互等，才需要做做少量适配工作，这极大的节省了人力;
动态化： 动态发布新特性和配置能力，更方便配合运营做活动，不需要等 app 发版铺量；

弹幕引擎的工程划分，大致如下：

3D球场项目 (三)

Sat, 30 May 2026 17:30:28 +0800

在3D球场项目 (二)中，我们梳理了视频弹幕引擎的整体架构、引擎初始化流程。现在，3D 球场部分基本已经探索完毕，我们接下来就是要解决这个项目的数据驱动部分了。

我们现在研究一下下发数据的来源：Opta，它是全球顶级的体育数据公司，1996 年创立于英国伦敦，现隶属于 Stats Perform，是行业公认的足球数据金标准。

覆盖：20+ 运动、3900+ 赛事、每年 6 万 + 场比赛
规模：7.2PB 历史数据、年采集超 10 亿数据点
精度：单场足球2 万 + 事件点，事件识别准确率 99.8%

腾讯体育采买了 Opta WTA 网球比赛的数据，我们可以通过 Opta 的 API 来获取数据。

根据他们官网的介绍，一个 MA3 网球赛事数据中 typeId 对应的意义如下：

点击展开 / 折叠 Event TypeId 完整对照表

Event TypeId	Event Name	Description
20	STOP_GAME	Indicates that the game has finished.
41	START_SET_1	Start 1st Set
42	START_SET_2	Start 2nd Set
43	START_SET_3	Start 3rd Set
44	START_SET_4	Start 4th Set
45	START_SET_5	Start 5th Set
46	STOP_SET	Stop Set
47	T_WO1	w.o. Player 1
48	T_WO2	w.o. Player 2
128	SAFE	Safe (No longer used)
129	DANGER	Danger (Technical/connection issue at venue)
132	INJ_BREAK	Game suspended - Player injured
133	PLAYERS_COMING_OUT	Players coming out
141	GAME_ABOUT_TO_START	Game about to start
149	GAME_SUSPENDED	Game suspended
160	PLAYERS_WARMING_UP	Players warming up
162	SHAKE_HANDS_WITH_REFEREE	Players shake hands with referee
163	COIN_FLIPPING_FOR_FIRST_SERVER	Coin flip to choose first server
164	PLAYERS_TALKING_TO_REFEREE	Player(s) talking to the referee
165	REFEREE_CHECKING_POINTMARK	Referee checking pointmark
166	BOTH_PLAYERS_SEATED	Both players seated
167	PLAYER1_RECEIVING_TREATMENT	Player 1 receiving treatment
168	PLAYER2_RECEIVING_TREATMENT	Player 2 receiving treatment
169	PLAYERS_GOING_TO_COURT	Players going back to court
170	NEXT_GAME_ABOUT_TO_START	Next game is about to start
180	T_MORE_THAN_5	Rally, over five shots
181	T_MORE_THAN_10	Rally over ten shots
182	T_MORE_THAN_15	Rally over fifteen shots
187	T_POINT_UNDER_INVESTIGATION	Point under investigation
188	T_START_TIE_BREAK	Start tie break
191	T_POINT_STOPPED_BY_REF	Point stopped by referee
197	UPDATE_SCORE_START	Start score update
198	UPDATE_SCORE_FINISHED	Score update finished
200	SIDE_CHANGE	Side change
206	SHOT_CNT	Shot count
216	STATISTIC_VERIFICATION	Statistics confirmation
240	NEW_BALLS	New balls
241	UMPIRE_ON_COURT	UMPIRE ON COURT
242	WARMING_UP_VOLLEY	Warming up - volley
243	WARMING_UP_SERVICE	Warming up - service
244	ONE_MINUTE	One minute
245	TIME	Time
246	SHOT_DETAILS	Shot details
256	CLS	Cancel last sent event
257	CLR	Clear events
258	GCC	Game conditions changed.
261	SCORER	Event details for %RELATED_EVENT% in the %MIN%. minute changed
262	BP	Ball position event
264	ODD	Odds event (deprecated)
266	TIME_CORRECTION_EVENT	Correct timestamp for a missed event
276	START_GAME_CLOCK	The (stopped) game clock is (re)started the game is running
277	STOP_GAME_CLOCK	The game clock is stopped. Time will not change until Start Game Clock is sent again
278	ADJUST_GAME_CLOCK	Game clock value is adjusted manually
279	CSTAT	A statistical value is cleared and an additional event with the correct action is sent (e.g. an invalid Ace Home event is replaced by a Service Winner Home)
280	CONF_PERIOD_SCORE	Period score confirmed
282	TIME_ADAPTION	Time for event %RELATED_EVENT% was adapted by %SEC% seconds
285	PLAYER_DATA_CONFIRMED	Player data for %RELATED_EVENT% in the %MIN% confirmed
513	SYS_MSG	System Message
514	SCOUT_IN_STADION	Scout in Stadium
515	CONNECTION_PROBLEMSSCOUT_OFFLINE	Connection problems Scout offline
516	CONNECTION_PROBLEMS	Connection problems
517	TRANSMISSION_ONLINE	Transmission online
520	LINEUP_CHANGED	Line-up changed
524	JERSEY_CHANGED	Jersey colors updated
782	GAME CANCELLED	Automatic “Game cancelled” event after first “cancellation” System message is sent
1152	T_SERVE1	Service Player 1
1153	T_1ST_SERVICE1	1st service Player 1
1154	T_2ND_SERVICE1	2nd service Player 1
1155	T_NA1	Net approach player 1
1156	T_W_FH1	Winner (forehand) Player 1
1157	T_W_BH1	Winner (backhand) Player 1
1158	T_FE_FH1	Forced error (forehand) Player 1
1159	T_FE_BH1	Forced error (backhand) Player 1
1160	T_UE_FH1	Unforced error (forehand) Player 1
1161	T_UE_BH1	Unforced error (backhand) Player 1
1162	T_HE1	Hawkeye Player 1
1163	T_WBR1	Warning by referee Player 1
1164	T_CBR1	Cautioned by referee Player 1
1165	T_SRV_NET1	Net Player 1
1166	T_SRV_OUT1	Out Player 1
1167	T_SRV_FF1	Foot fault Player 1
1168	T_SRV_DF1	Double fault Player 1
1169	T_SRV_A1	Ace Player 1
1170	T_SRV_SW1	Service winner Player 1
1171	T_SRV_RW_FH1	Return winner (forehand) Player 1
1172	T_SRV_IN1	Serve in Player 1
1173	T_POINT1	Point Player 1
1174	T_CONF1	Confirm Point Player 1
1175	T_GAME1	Game Player 1
1176	T_SET1	Set Player 1
1177	T_BL1	Baseline Player 1
1178	T_SRV_NR1	Net/Retake Player 1
1179	T_W1	Winner Player 1
1180	T_FE1	Forced error Player 1
1181	T_UE1	Unforced error Player 1
1182	T_SRV_RW_BH1	Return winner (backhand) Player 1
1183	T_V_FH1	Volley (forehand) Player 1
1184	T_V_BH1	Volley (backhand) Player 1
1185	T_BB1	Break ball Player 1
1186	T_B1	Break Player 1
1187	T_HES1	Hawk eye successful Player 1
1188	T_ITO1	Injury Timeout Player 1
1189	T_START_SRV1	Start Service Player 1
1190	T_WARNING1	1st offence - warning Player 1
1191	T_PENALTY_POINT1	2nd offence - penalty point Player 1
1192	T_PENALTY_GAME1	3rd offence - penalty game Player 1
1193	T_DISQUALIFICATION1	Disqualification Player 1
1194	T_UE_NET1	Unforced error net Player 1
1195	T_FE_NET1	Forced error net Player 1
1196	T_SUCCESSFUL_NET_APPROACH1	Successful net approach Player 1
1197	T_TIME_VIOLATION1	Time violation Player 1
1198	T_PENALTY_POINT1 T_UNSUCCESSFUL_NET_APPROACH1	Unsuccessful net approach Player 1
1199	T_AT_NET1	At net Player 1
1200	T_AT_BASELINE1	At baseline Player 1
1201	T_SET_BALL1	Set ball Player 1
1202	T_MATCH_BALL1	Match ball Player 1
2176	T_SERVE2	Service Player 2
2177	T_1ST_SERVICE2	1st service Player 2
2178	T_2ND_SERVICE2	2nd service Player 2
2179	T_NA2	Net approach player 2
2180	T_W_FH2	Winner (forehand) Player 2
2181	T_W_BH2	Winner (backhand) Player 2
2182	T_FE_FH2	Forced error (forehand) Player 2
2183	T_FE_BH2	Forced error (backhand) Player 2
2184	T_UE_FH2	Unforced error (forehand) Player 2
2185	T_UE_BH2	Unforced error (backhand) Player 2
2186	T_HE2	Hawkeye Player 2
2187	T_WBR2	Warning by referee Player 2
2188	T_CBR2	Cautioned by referee Player 2
2189	T_SRV_NET2	Net Player 2
2190	T_SRV_OUT2	Out Player 2
2191	T_SRV_FF2	Foot fault Player 2
2192	T_SRV_DF2	Double fault Player 2
2193	T_SRV_A2	Ace Player 2
2194	T_SRV_SW2	Service winner Player 2
2195	T_SRV_RW_FH2	Return winner (forehand) Player 2
2196	T_SRV_IN2	Serve in Player 2
2197	T_POINT2	Point Player 2
2198	T_CONF2	Confirm Point Player 2
2199	T_GAME2	Game Player 2
2200	T_SET2	Set Player 2
2201	T_BL2	Baseline Player 2
2202	T_SRV_NR2	Net/Retake Player 2
2203	T_W2	Winner Player 2
2204	T_FE2	Forced error Player 2
2205	T_UE2	Unforced error Player 2
2206	T_SRV_RW_BH2	Return winner (backhand) Player 2
2207	T_V_FH2	Volley (forehand) Player 2
2208	T_V_BH2	Volley (backhand) Player 2
2209	T_BB2	Break ball Player 2
2210	T_B2	Break Player 2
2211	T_HES2	Hawk eye successful Player 2
2212	T_ITO	Injury Timeout Player 2
2213	T_START_SRV2	Start Service Player 2
2214	T_WARNING2	1st offence - warning Player 2
2215	T_PENALTY_POINT2	2nd offence - penalty point Player 2
2216	T_PENALTY_GAME2	3rd offence - penalty game Player 2
2217	T_DISQUALIFICATION2	Disqualification Player 2
2218	T_UE_NET2	Unforced error net Player 2
2219	T_FE_NET2	Forced error net Player 2
2220	T_SUCCESSFUL_NET_APPROACH2	Successful net approach Player 2
2221	T_TIME_VIOLATION2	Time violation Player 2
2222	T_AT_NET2	Unsuccessful net approach Player 2
2223		At net Player 2
2224	T_AT_BASELINE2	At baseline Player 2
2225	T_SET_BALL2	Set ball Player 2
2226	T_MATCH_BALL2	Match ball Player 2

PBP = Play-by-Play（逐回合 / 逐事件数据），就是把一场比赛里每一次事件都按时间线秒级记录下来的最细粒度原始数据流。口语里也叫 “逐帧数据 / 流水账数据”。网球赛事的数据，都是以这个形式下发的，一段数据可能下发的数据是这样的：

3D球场项目 (四)

Sat, 30 May 2026 20:23:44 +0800

项目终于来到了落地环节。在3D球场项目 (三)里，我们用一段离线 PBP 数据 + 一次 LLM 调用，把"导演 Agent"的雏形跑了起来。Demo 阶段的脚本是离线生成、整段导入的；那时的 LLM 既负责"想象画面"，又顺手把动作、镜头、音效、解说词都打包了。

但项目一旦从 Demo 推到线上，导演 Agent 立刻面对三件事：

Opta 数据是按 Point 持续推过来的，不会一次性把一场比赛喂给大模型；
大模型 会失败、会延迟，一旦卡住，球员就只能停在 idle；
客户端会断流、会重连，需要一个"刚才那一拍发生了什么"的回放接口。

上一章末尾提到的三个坑——player 卡 idle、两人一直来回发球、长链断了客户端不知道怎么补——本质都来自这三件事。线上版本的 livecast 服务（基于 tRPC-Go）做了一次完整的工程化：导演 Agent 不再是单一 LLM，而是 确定性脚本层 + LLM 解说层 + 双重下发保险 的组合。本篇就讲这套组合怎么搭起来。

一、网球数据是怎么进来的

NBA 那边的 PBP 是单条投递：上游每发生一个篮球事件，就经 Kafka 推一条消息过来。但网球数据天然是 按回合聚合 的——Opta 在一个 Point（一个回合）结束之后才会一次性把这一拍涉及的所有事件下发，所以服务端也用了批量消费通道：

Kafka topic: pbp_flow
 └─ FlowConsumer.BatchHandle(msgs []*sarama.ConsumerMessage)
 └─ livecastSvc.ProcessBatchPBPFlow(payloads [][]byte)

进入 ProcessBatchPBPFlow 之后，先按 mid（match id）做二级分组、过滤掉非网球的批次，再交给真正的 pipeline。两道闸门决定一场比赛的事件能不能走 3D 流水线：

3D球场项目 (五)

Sat, 30 May 2026 22:40:08 +0800

3D球场项目 (四) 把服务端推到了线上：导演 Agent 把每个 Point 切成 SERVE / RALLY / CONCLUSION 三段，配齐了动作、机位、位置、比分、解说，按 seq 单调下发到客户端。本篇回到客户端，看 Cocos 这一侧拿到 Script 之后，是怎么把它变成屏幕上一拍接一拍的比赛画面的。

整个客户端改造分四层落地，本篇只讲和 3D 球场主干业务直接相关的内容：

CocosEngine 层：场景加载架构升级（进度 / 传参 / Delegate¹ 回调 / JSBridge² 内存语义）；
MagicDanmaku 层：3D 球场的核心业务代码（数据流、状态机、动画 / 球轨迹 / 相机 / 观众）；
MagicDanmaku iOS 层：场景加载回调的演化，以及 CocosPlayer 在调用链里的角色；
业务层：腾讯体育 App 的 SwiftUI³ 视图把上面三层包成一个标准组件。

每一层和业务流程脱钩的内容（性能优化、稳定性 / crash 修复、构建工程化）统一抽到了 3D球场项目 (六)：客户端工程化与优化。

下面这张图先把四层的位置关系和数据流向摆出来，读者可以把它当作整篇文章的导航—— 箭头是数据流方向（服务端 Script 自顶向下灌进引擎、引擎事件自底向上回到 SwiftUI），每个节点旁标了对应章节：

3D球场项目 (六)：客户端工程化与优化

Sun, 31 May 2026 09:00:00 +0800

3D球场项目 (五) 把客户端的核心业务流讲完了：Native 推送 → DataManager 队列 → ScenePlayer 章节调度 → GameController 状态机 → Handler → 渲染层。功能闭环跑通之后，真正的硬仗是 “工程化"和"性能”——前者保证项目能稳定上线（编译跑通、退出不崩、Swift 调用顺手），后者保证在中低端机上画面流畅。

第一版上线时遇到了两类问题：

稳定性 / 工程化：modulemap 编译报错、lipo 架构冲突、A11 设备启动 crash、 Cocos 退出期 OpenAL 资源竞争 crash……这些都不是"画面卡"，但每一个都能让用户体验归零；
性能：中端 iPhone 在比赛回合渲染期间，GPU 和 CPU 都偶尔抖到 80%+，帧率掉到 30 fps 出头。

本篇按这两类拆成两部分，所有改动都遵循一条原则：不动玩法，只把工程问题和帧时间解决掉。

架构改动一览

3D球场项目 (二) 介绍过弹幕引擎的四层架构（腾讯视频 APP / MagicDanmakuiOS / MagicDanmaku / cocos-engine）。这一阶段 每一层都动了——3D 球场不是单点改造，而是一次自上而下的纵贯。下面这张图是把 PartTwo 那张原始架构图重画一遍，改动的节点用蓝色、新增的节点用绿色，没动的节点保持白色：

Cocos 引擎 iOS 渲染管线深度解析：从 CADisplayLink 到屏幕呈现

Wed, 08 Jul 2026 19:00:15 +0800

Cocos 引擎 iOS 渲染管线深度解析：从 CADisplayLink 到屏幕呈现

引言

在移动端图形开发中，理解渲染管线的底层实现是走向高级工程师的必经之路。Cocos Creator 作为主流的跨平台游戏引擎，其 iOS Metal 后端的渲染实现采用了现代化的 FrameGraph 架构，结合脏状态追踪、资源池化等优化手段，是一份极佳的学习样本。

本文基于对 Cocos 引擎 gfx-metal 模块的源码分析，梳理从 CADisplayLink 帧回调触发到最终 GPU 呈现的完整渲染链路，并深入解读各阶段的关键实现细节。

整体架构概览

在深入时序之前,先理清核心模块的职责分工：

模块	文件	职责
IOSPlatform	`IOSPlatform.mm`	iOS 平台入口，持有 `CADisplayLink` 驱动渲染循环
RenderPipeline	`RenderPipeline.cpp`	管线编排器，遍历相机并调度 Flow/Stage
ForwardFlow	`ForwardFlow.cpp`	前向渲染流程，决定渲染策略
ForwardStage	`ForwardStage.cpp`	前向渲染阶段，收集渲染对象并填充 UBO
RenderQueue	`RenderQueue.cpp`	渲染队列，对可渲染对象排序
FrameGraph	`FrameGraph.cpp`	帧图调度器，负责 Pass 编译、排序、合并和执行
CCMTLDevice	`MTLDevice.mm`	Metal 设备抽象，管理 Swapchain 和 Queue
CCMTLSwapchain	`MTLSwapchain.mm`	交换链，管理 `CAMetalLayer` 和 drawable
CCMTLCommandBuffer	`MTLCommandBuffer.mm`	命令缓冲区封装，核心渲染编码入口
CCMTLRenderCommandEncoder	`MTLRenderCommandEncoder.h`	渲染编码器，含脏状态追踪优化

完整渲染时序图

以下 Mermaid 时序图展示了从屏幕刷新信号到最终呈现的五个阶段：