3D球场项目 (五)

// cocos-engine/cocos/game/director.ts:429
public loadScene (sceneName: string, onLaunched?: OnSceneLaunched, onUnloaded?: OnUnload): boolean;
public loadScene (
    sceneName: string,
    onProgress: OnLoadSceneProgress,           // ★ 新增进度回调
    onLaunched?: OnSceneLaunched,
    onUnloaded?: OnUnload,
): boolean;
public loadScene (sceneName, onProgressOrOnLaunched?, onLaunchedOrOnUnloaded?, onUnloaded?): boolean {
    // 通过 onProgressOrOnLaunched 的 arity 区分两种重载——
    // 进度回调签名是 (finished, total, item)，length === 3
    // ...
    if (onProgress) {
        bundle.loadScene(sceneName, onProgress, onComplete);
    } else {
        bundle.loadScene(sceneName, onComplete);
    }
}

// cocos-engine/native/cocos/platform/ios/Headers/CocosView.h:46
@protocol CocosViewSceneDelegate <NSObject>
@optional
/// 场景即将加载
- (void)cocosView:(CocosView *)cocosView willLoadScene:(NSString *)sceneName;

/// 场景加载进度更新
- (void)cocosView:(CocosView *)cocosView
  sceneLoadProgress:(NSString *)sceneName
           finished:(NSInteger)finished
              total:(NSInteger)total;

/// 场景加载完成
- (void)cocosView:(CocosView *)cocosView didLoadScene:(NSString *)sceneName;

/// 场景加载失败
- (void)cocosView:(CocosView *)cocosView
   didFailLoadScene:(NSString *)sceneName
              error:(NSError * _Nullable)error;
@end

@interface CocosView : UIView<CocosMetalUIView>
#if __has_feature(objc_arc)
@property (nonatomic, weak,   nullable) id<CocosViewSceneDelegate> sceneDelegate;
#else
@property (nonatomic, assign, nullable) id<CocosViewSceneDelegate> sceneDelegate;
#endif
// ...
@end

// cocos-engine/native/cocos/platform/ios/CocosCreator.mm:46（loadScript 拼接）
- (NSString *)loadScript {
    NSMutableString *script = [NSMutableString stringWithFormat:@"SceneManager.load('%@'", self.sceneName];
    if (self.bundleNameOrPath.length > 0) [script appendFormat:@", '%@'", self.bundleNameOrPath];
    if (self.params.count > 0) {
        NSData *jsonData = [NSJSONSerialization dataWithJSONObject:self.params
                                                           options:kNilOptions error:&error];
        NSString *jsonString = [[NSString alloc] initWithData:jsonData
                                                     encoding:NSUTF8StringEncoding];
        [script appendFormat:@", '%@'", jsonString];   // ★ 拼成第三个参数
    }
    [script appendString:@")"];
    return [script copy];
}

// cocos-engine/native/cocos/platform/apple/JsbBridgeWrapper.mm:35
@interface JsbScriptListenerHolder : NSObject
@property (nonatomic, copy, readonly)   OnScriptEventListener callback;  // 拷贝后用于回调
@property (nonatomic, assign, readonly) OnScriptEventListener original; // 原始指针，仅做去重比较
- (instancetype)initWithOriginal:(OnScriptEventListener)listener;
@end

- (void)addScriptEventListener:(NSString*)eventName listener:(OnScriptEventListener)listener {
    if (!eventName || !listener) return;
    NSMutableArray* arr = [cbDictionary objectForKey:eventName];
    if (!arr) {
        NSMutableArray* newArr = [[NSMutableArray alloc] init];
        [cbDictionary setObject:newArr forKey:eventName];
        arr = newArr;
        [newArr release];                          // 字典持有
    }
    for (JsbScriptListenerHolder* h in arr) {
        if (h.original == listener) return;       // 同一原始 block 不重复加
    }
    JsbScriptListenerHolder* h = [[JsbScriptListenerHolder alloc] initWithOriginal:listener];
    [arr addObject:h];
    [h release];
}

- (void)triggerEvent:(NSString*)eventName arg:(NSString*)arg {
    NSMutableArray* arr = [cbDictionary objectForKey:eventName];
    if (!arr) return;
    // ★ 拷贝一份快照，避免回调过程中修改数组导致崩溃
    NSArray* snapshot = [[arr copy] autorelease];
    for (JsbScriptListenerHolder* h in snapshot) h.callback(arg);
}

// assets/tennis/scripts/bundle/TennisBundleConfig.ts
export const TENNIS_BUNDLE_CONFIGS: BundleConfig[] = [
  { key: TennisBundleKey.PLAYER,    path: 'tennis-player',    priority: 0, autoLoad: true },
  { key: TennisBundleKey.ANIMATION, path: 'tennis-animation', priority: 1, autoLoad: true },
  { key: TennisBundleKey.AUDIO,     path: 'tennis-audio',     priority: 2, autoLoad: true },
  { key: TennisBundleKey.AUDIENCE,  path: 'tennis-audience',  priority: 3, autoLoad: true },
];

// assets/tennis/resources/src/scripts/Model/ScenePlayer.ts
public start(): void {
  this._detectFirstFrameRender();
  TennisBundleManager.startBackgroundLoading(() => {
    this._onBundlesLoaded();
  });
}

private async _onBundlesLoaded(): Promise<void> {
  await TennisAssetBinder.bindAllAssets();
  JSBridge.send('onBundlesLoaded', { success: true });
}

// Model/DataManager.ts:387
public receiveRawData(rawData: RawServerData): void {
    // 1. 已有 newScript 的"补齐"——优先合并到 _pendingRounds 里那条占位回合上
    if (rawData.scriptCompletions?.length) {
        this._processScriptCompletions(rawData.scriptCompletions, ts, seq);
    }
    // 2. 一次到齐的完整回合（一段式）
    if (rawData.completedScripts?.length) {
        this._processCompletedScripts(rawData.completedScripts, ts, seq);
    }
    // 3. 占位回合（先 SERVE + RALLY_LOOP，等 scriptCompletions 收尾）
    if (rawData.newScripts?.length) {
        this._processNewScripts(rawData.newScripts, ts, seq);
    }
    // 4. 全局指令（换边/盘末/暂停）——按 seq 插队
    if (rawData.commands?.length) {
        this._addCommandsToQueue(rawData.commands, ts, seq);
    }
    this._restoreLoopingRounds();
    this._cleanupOldRounds();
}

// Model/ScenePlayer.ts:594 / 672 / 775
private _playNextRound(): void {
    const item = this._dataManager.getNextItem();
    if (!item) { this._changeState(WAITING_DATA); return; }
    if (item.itemType === QueueItemType.ROUND) this._executeRound(item.roundData);
    else                                       this._executeCommand(item.command);
}

private _executeRound(round: RoundData): void {
    this._currentRound = round;
    this._currentChapterIndex = 0;
    this._startRoundTimeOutCheckTimer();   // §2.1.4 会讲
    this._playCurrentChapter();
}

private _playCurrentChapter(): void {
    const chapter = this._currentRound.sequence[this._currentChapterIndex];
    switch (chapter.chapter) {
        case ChapterType.SERVE:
            this._playServeChapter(chapter as ServeChapter);       break;
        case ChapterType.RALLY:
            this._playRallyChapter(chapter as RallyChapter);       break;
        case ChapterType.RALLY_LOOP:
            this._playRallyChapter(chapter as RallyLoopChapter);   break;
        case ChapterType.CONCLUSION:
            /* 跳过：Rally 结束时已统一处理 Conclusion */          break;
    }
}

// Game/GameController.ts:750-782
public changeState(stateType: GameStateType, context?: any): void {
    if (this._currentState && !this._currentState.canTransitionTo(stateType)) {
        warn(`无法从 ${this._currentState.stateType} 切换到 ${stateType}`);
        return;
    }
    if (this._currentState) this._currentState.onExit();

    let newState = this._stateInstances.get(stateType);
    if (!newState) {
        newState = this._createState(stateType);
        this._stateInstances.set(stateType, newState);  // 实例缓存
    }
    this._currentState = newState;
    this._currentState.onEnter(context);
}

// Game/Handlers/ServeHandler.ts:89
public startServe(server, receiver, context): void {
    this._server = server;
    this._receiver = receiver;
    this._isServing = true;
    this._serverWalkCompleted = false;
    this._receiverWalkCompleted = false;
    this._walkPlayersToPosition();   // ① 走位
    // ② 走位回调里 → _initializeHandlers() → BallTossHandler.startToss()  抛球
    // ③ 抛球到顶 → ServeAnimationHandler 触发发球动画
    // ④ 发球动画 hit 关键帧 → ball 飞出 → _handleServeComplete()
}

// Game/GameController.ts:1510
public calculateBallFlightTime(receiver, receivePosition, animationName): {...} {
    const { moveTime } = receiver.controller.calculateMoveTimeAndSpeed(receivePosition);

    let hitKeyframeTime = receiver.hitKeyframeTime || 0.5;
    if (animationName) {
        const cfg = AnimationConfigManager.getAnimationConfigFromNode(receiver.node, animationName, false);
        hitKeyframeTime = (cfg.hitKeyframeTime ?? 0) / (cfg.speed || 1.0);  // 归一化
    }

    let ballFlightTime = moveTime + 0.05 + hitKeyframeTime;
    if (ballFlightTime < this._ballMinFlightTime) {
        ballFlightTime = this._ballMinFlightTime;  // 太短的球补齐到底线
    }
    return { ballFlightTime, moveTime, idleTime: 0.05, hitKeyframeTime };
}

// Model/DataManager.ts:572
private _upsertRound(pointId, sequence, ts, seq, isLooping): void {
    const existing = this._findExistingRound(pointId);
    if (existing) {
        const round = existing.roundData;
        round.sequence = sequence;
        if (isLooping) {
            round.markLooping();
            this._pendingRounds.set(pointId, round);
        } else {
            // newScript → completedScript：退出循环 + 抽 conclusion + 填充
            round.isLooping = false;
            this._extractConclusionInfo(round);
            this._fillRoundData(round);
            this._pendingRounds.delete(pointId);
        }
    } else {
        const round = new RoundData(pointId, sequence, ts, seq);
        this._setLastRoundMatchState(round, seq);     // 把上一回合比分挂上来
        if (isLooping) {
            round.markLooping();
            this._pendingRounds.set(pointId, round);
        } else {
            this._extractConclusionInfo(round);
            this._fillRoundData(round);
        }
        this._addRoundToQueue(round, ts, seq);
    }
}

// Model/ScenePlayer.ts:2050
private _checkRoundTimeOut(): void {
    if (this._currentRound.getConclusionChapter()) {
        this._sendLoadingEnd();                        // 数据已到，退出
        return;
    }
    const elapsed = (Date.now() - this._currentRoundStartTime) / 1000;
    if (elapsed >= this.roundTimeOutThreshold) {       // 默认 120s
        this._roundTimeOutCheckCount++;
        if (!this._isLoadingStartSent) this._sendLoadingStart();   // 通知 Native：拉数据
        if (this._roundTimeOutCheckCount >= this._roundTimeOutCheckMaxCount) {
            this._clearRoundTimeOutCheckTimer();       // 5 次重试后放弃
            return;
        }
        this._handleCurrentRoundNotCompleted(this._currentRound.pointId);
    }
}

// 后向恢复：Native 拉到新数据进队列后
private _handleQueueUpdated(queueLength: number): void {
    if (this._isLoadingStartSent) {
        this._resyncFromLatestRound();   // 不补中间，直接跳到最新一回合
        this._sendLoadingEnd();
    }
}

// MagicDanmakuiOS/Classes/CocosPlayer.m:382（创建路径精简）
- (void)configCocosView:(CGRect)frame bundlePath:(NSString *)bundlePath {
    [[CocosCreator sharedInstance] setIsSingletonMetalLayer:[self isSingletonMetalLayer]];
    self.cocosView = [[CocosView alloc] initWithFrame:frame];
    if (![CocosCreator sharedInstance].running) {
        [[CCNativeChannel shareInstance] resetChannel];
    }
    [self initStartUpConfig];
    [[CocosCreator sharedInstance] createWithRenderView:(CocosView *)self.cocosView];
    [CocosMessageInvoker sendLiveDeltaTimeConfigToCC];        // ★ 时间同步配置
    [CocosMessageInvoker sendInitCCLoggerToCC];               // ★ 日志通道初始化
    [CocosPlayer recordCocosCreatorBeenInited:YES];
    [self sendCCBundleInfo:bundlePath bundleName:[bundlePath lastPathComponent]];  // ★ 资源包指纹
}

// 3DCourt/QS3DCourtSwiftUIView.swift:39
struct QS3DCourtSwiftUIView: UIViewControllerRepresentable {
    private let sceneName: String
    private let resHubKey: String?
    private let mainBundleName: String?
    private let bundleNameOrPath: String?
    private let params: [AnyHashable: Any]?

    /// ★ 通过 EnvironmentObject[^environmentobject] 注入，避免在每个 init 都传一遍
    @EnvironmentObject private var eventBroker: QS3DCourtEventBroker

    public func makeUIViewController(context: Context) -> QS3DCourtViewController {
        let viewController: QS3DCourtViewController
        if let resHubKey = resHubKey {
            // ResHub 远程包加载
            viewController = QS3DCourtViewController(
                sceneName: sceneName, resHubKey: resHubKey,
                mainBundleName: mainBundleName, params: params)
        } else if let bundleNameOrPath = bundleNameOrPath {
            // 本地 Bundle 加载
            viewController = QS3DCourtViewController(
                sceneName: sceneName, bundleNameOrPath: bundleNameOrPath, params: params)
        } else {
            // 内置默认
            viewController = QS3DCourtViewController(sceneName: sceneName, params: params)
        }
        // ★ 双向绑定：viewController.delegate = broker；broker 弱持有 viewController
        eventBroker.bind(to: viewController)
        return viewController
    }

    static func dismantleUIViewController(_ vc: QS3DCourtViewController, coordinator: ()) {
        vc.delegate = nil   // SwiftUI 卸载时解引用
    }
}

// 3DCourt/InMatchTop3DLiveView.swift:62
var body: some View {
    VStack(spacing: 0) {
        QS3DCourtSwiftUIView(sceneName: sceneName,
                             resHubKey: resHubKey,
                             mainBundleName: mainBundleName,
                             bundleNameOrPath: bundleNameOrPath,
                             params: initParams)         // ← mid / playerName / voiceId 都塞 initParams
            .overlay(makeBigEventIndicator(), alignment: .topLeading)
            .overlay(makeControlOverlay())               // ← 悬浮控件层
            .overlay(makeGameResultOverlay())
            .overlay(makeGuideOverlay())
            .overlay(makeLoadingMask())
        TennisBillboard()                                 // ← 解说滚条
            .frame(height: Constants.billboardHeight)
    }
    .onReceive(eventBroker.$loadingStatus, perform: handleLoadingStatusChange)
    .onReceive(eventBroker.eventPublisher, perform: handleCourtEvent)
    .valueChanged(isLoadCompleted) { _ in sendPendingDataIfNeeded() }
    .valueChanged(lifecyclePhase, onChange: handleLifeCyclePhaseChanged)
}

// 3DCourt/InMatchTop3DLiveView.swift:318
private func handleCourtEvent(_ event: QS3DCourtEventBroker.CocosEvent) {
    guard case .receivedEvent(let name, let params) = event else { return }
    guard let eventType = CocosListenableEvent(rawValue: name) else { return }

    switch eventType {
    case .onRoundStart:                  handleRoundStartEvent(params: params)
    case .onCurrentRoundNotCompleted:    complementaryRequest(params as? [AnyHashable: Any])
    case .loadingStart:                  shouldShowInterruptionLoading = true
    case .loadingEnd:                    shouldShowInterruptionLoading = false
    case .onMatchEnd:                    isGameEnd = true; requestMatchEndModel()
    case .onFirstFrameRendered:          isLoadCompleted = true
    default:                             break
    }
}

// 3DCourt/TennisMatchUtils.swift:15
enum CocosListenableEvent: String, CaseIterable {
    case onRoundStart                   // 回合开始（带 RoundEventModel）
    case onRoundEnd                     // 回合结束
    case onTouchMove                    // 用户在球场上拖动了视角
    case onTouchMoveEnd                 // 拖动结束（用于"恢复默认机位"按钮显隐）
    case onCurrentRoundNotCompleted     // §二 §2.1.4 (c) 超时通知
    case loadingStart                   // §二 §2.1.4 (c) 进入 loading
    case loadingEnd                     //                  退出 loading
    case onMatchEnd                     // 比赛结束
    case errorLogs                      // 错误日志上报
    case normalLogs                     // 普通日志上报
    case onFirstFrameRendered           // 首帧渲染完成（业务层"loading 蒙层"消失的信号）
}

// 3DCourt/QS3DCourtEventBroker.swift:65
class QS3DCourtEventBroker: NSObject, ObservableObject, QS3DCourtViewControllerDelegate {
    enum CocosEvent {
        case willLoadScene
        case sceneLoaded(error: Error?)
        case loadingProgressUpdate(progress: Progress)
        case loadingStatusChanged(status: LoadingStatus)
        case receivedEvent(name: String, params: Any?)               // ← 一般事件
        case receivedRequest(name: String, params: [String: Any]?,   // ← 同步请求
                             callback: (Error?, Any?) -> Void)
        case performanceReport(CocosProfileInfo)
    }
    @Published var loadingStatus: LoadingStatus = .loading(progress: 0)
    private let eventSubject = PassthroughSubject<CocosEvent, Never>()
    var eventPublisher: AnyPublisher<CocosEvent, Never> { eventSubject.eraseToAnyPublisher() }
    // ...
}

// 3DCourt/QS3DCourtEventBroker.swift:347
func onEvent(_ eventName: String,
             on queue: DispatchQueue = .main,
             handler: @escaping (Any?) -> Void) -> AnyCancellable {
    eventPublisher
        .compactMap { event -> Any?? in
            if case .receivedEvent(let name, let params) = event, name == eventName {
                return params
            }
            return nil
        }
        .receive(on: queue)
        .sink { handler($0) }
}

// 3DCourt/TennisMatchUtils.swift:43
enum CourtEventType: String {
    // ↓ 业务侧主动推给 Cocos 的事件
    case onSceneHide                    // 业务页隐藏（Cocos 暂停渲染）
    case onSceneShow                    // 业务页显示（Cocos 恢复渲染）
    case onScriptMessage                // §二 §2.1.1 数据流入口：补偿/TCP 拉到的脚本
    case onVoiceIdChanged               // 切换解说音色

    // ↓ 业务内部使用的事件（不发给 Cocos）
    case toggleVoiceControl             // 拉起音色面板（控件层 → SwiftUI 层）
    case setMute                        // 静音 / 取消静音
    case restoreDefaultCameraView       // 一键恢复默认机位
}

// 3DCourt/QS3DCourtEventBroker.swift:686
func dispatch(event: CourtEventType, param: [AnyHashable: Any]? = nil) {
    viewController?.dispatchEvent(event.rawValue, arg: param)
}

// 3DCourt/CourtContainerControlOverlay.swift:147
override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
    let hitView = super.hitTest(point, with: event)
    guard hitView == self else {
        // 点击命中了某个子视图（按钮），重置自动隐藏倒计时
        if hitView?.isDescendant(of: self) == true, isOverlayVisible {
            scheduleAutoHide()
        }
        return hitView    // ★ 子视图正常响应
    }
    // ★ 命中的是覆盖层自身（空白区域）→ 触发"显隐切换"，并返回 nil 让事件穿透到 Cocos
    togglePublisher.send(())
    return nil
}

// 3DCourt/CourtContainerControlOverlay.swift:225
@objc private func onMuteBtnClicked(_ sender: UIButton) {
    sender.isSelected.toggle()
    eventBroker?.dispatch(event: .setMute, param: ["mute": sender.isSelected])
}

@objc private func onAIVoiceBtn(_ sender: UIButton) {
    eventBroker?.dispatch(event: .toggleVoiceControl)
}

@objc private func restoreAngle(_ sender: UIButton) {
    eventBroker?.dispatch(event: .restoreDefaultCameraView)
    sender.isSelected = false
}

// Cocos/QS3DCourtViewController.swift:188
required init(sceneName: String = "main",
              resHubKey: String? = nil,
              mainBundleName: String? = nil,
              bundleNameOrPath: String? = nil,
              params: [AnyHashable: Any]? = nil) {
    self.sceneName = sceneName
    self.resHubKey = resHubKey
    self.mainBundleName = mainBundleName
    self.bundleNameOrPath = bundleNameOrPath
    self.extParams = params
    self.creator = CocosCreator.sharedInstance()       // ★ §一 引擎单例
    self.jsb = JsbBridgeWrapper.sharedInstance()       // ★ §一 §1.4 修过内存语义
    self.progress = Progress(totalUnitCount: 100)
    self.statistics = QS3DCourtStaticsModel()
    super.init(nibName: nil, bundle: nil)
    commonInit()
}

// Cocos/QS3DCourtViewController.swift:241
override func viewDidLoad() {
    super.viewDidLoad()
    let cocos = CocosView(frame: view.bounds)
    cocos.isMultipleTouchEnabled = true
    view.addSubview(cocos)
    self.contentView = cocos
    cocos.sceneDelegate = self                         // ★ §一 §1.2 协议
    self.cocosView = cocos

    load()                                             // 三种加载方式之一
    addRequestEventListener()                          // 订阅 JSBridge "request" 事件

    NotificationCenter.default.addObserver(self,
        selector: #selector(applicationWillResignActive(_:)),
        name: UIApplication.willResignActiveNotification, object: nil)
    NotificationCenter.default.addObserver(self,
        selector: #selector(applicationDidBecomeActive(_:)),
        name: UIApplication.didBecomeActiveNotification, object: nil)
}

// Cocos/QS3DCourtViewController.swift:414
private func loadScene(_ path: String?, isRemote: Bool) {
    var params = extParams
    var scenePath = path
    if isRemote, let remotePath = path {
        if params == nil { params = [:] }
        params?["bundleFolderPath"] = URL(fileURLWithPath: remotePath).absoluteString
        if let mainBundle = mainBundleName, !mainBundle.isEmpty {
            scenePath = (remotePath as NSString).appendingPathComponent(mainBundle)
        }
    }
    // 把 [AnyHashable: Any] 折成 [String: Any]
    var stringKeyParams: [String: Any]?
    if let params = params {
        var converted: [String: Any] = [:]
        for (k, v) in params {
            if let s = k as? String { converted[s] = v } else { converted["\(k)"] = v }
        }
        stringKeyParams = converted
    }
    // ★ 拼出引擎的 SceneConfig，最终走到 SceneManager.load(name, bundle, jsonString)
    let config = CocosLoadSceneConfig(sceneName: sceneName,
                                      bundleNameOrPath: scenePath,
                                      params: stringKeyParams)
    guard let cocos = cocosView else { return }
    creator.create(withRenderView: cocos, sceneConfig: config)
    creator.viewWillClip(to: view.size)
    creator.resume(withRenderView: cocos)
}

// Cocos/QS3DCourtViewController.swift:648
extension QS3DCourtViewController: CocosViewSceneDelegate {
    func cocosView(_ cocosView: CocosView, willLoadScene sceneName: String) {
        guard self.cocosView == cocosView else { return }
        statistics?.sceneLoadTime = CFAbsoluteTimeGetCurrent()        // 计时起点
    }
    func cocosView(_ cocosView: CocosView, didLoadScene sceneName: String) {
        guard self.cocosView == cocosView else { return }
        isSceneHasBeenLoaded = true
        sceneLoadProgress?.completedUnitCount = totalProgressUnit
        showContent()
        delegate?.viewController?(self, sceneLoadedWithError: nil)    // ★ 通知 Broker
        if enablePerfSampling {
            creator.setProfileToggle(true)
            setupPerformanceTimerIfNeeded()                            // 启动性能采样
        }
    }
    func cocosView(_ cocosView: CocosView,
                   sceneLoadProgress sceneName: String,
                   finished: Int, total: Int) {
        // 远程包阶段在 progress 里只占 20 单位，其余 80 给前置下载
        let totalUnit: Int64 = (resHubKey ?? "").isEmpty ? 100 : 20
        // ... 更新进度
    }
    func cocosView(_ cocosView: CocosView,
                   didFailLoadScene sceneName: String, error: (any Error)?) {
        delegate?.viewController?(self, sceneLoadedWithError: error)
    }
}

// Cocos/QS3DCourtViewController.swift:467
@objc open func addCocosEventListener(_ event: String) {
    guard !event.isEmpty else { return }
    let cb: ScriptEventCallback = { [weak self] data in
        MainActor.assumeIsolated {
            guard let self = self else { return }
            let ret = (data as NSString?)?.jsonValueDecoded()           // JSON 解出来
            self.delegate?.viewController?(self, onReceiveEvent: event, params: ret)
        }
    }
    jsb.addScriptEventListener(event, listener: cb)                     // ★ §一 §1.4 修过的 API
    eventCbMap[event] = cb                                              // 记下来好取消
}

// Cocos/QS3DCourtViewController.swift:517
@objc open func dispatchEvent(_ event: String, arg param: [AnyHashable: Any]?) {
    guard isSceneHasBeenLoaded else { return }                          // 场景没加载好就吞掉
    let jsonString: String? = if let dict = param, !dict.isEmpty {
        (dict as NSDictionary).jsonStringEncoded() ?? ""
    } else { nil }
    let dispatch = { @Sendable [weak self] in
        MainActor.assumeIsolated {
            guard let self = self, !self.cleaned else { return }
            if let s = jsonString { self.jsb.dispatchEvent(toScript: event, arg: s) }
            else                    { self.jsb.dispatchEvent(toScript: event) }
        }
    }
    if Thread.isMainThread { dispatch() } else { DispatchQueue.main.async(execute: dispatch) }
}

// Cocos/QS3DCourtViewController.swift:630
private func cleanUp() {
    cleaned = true
    destroyPerformanceTimer()
    for (event, cb) in eventCbMap {
        if let listener = cb as? ScriptEventCallback {
            JsbBridgeWrapper.sharedInstance().removeScriptEventListener(event, listener: listener)
        }
    }
    if let cocos = cocosView {
        creator.pause(withRenderView: cocos)        // 先 pause 定时器
        creator.close(withRenderView: cocos)        // 再 close 渲染视图
    }
}