BattleStore

简介
PK 功能实现主播之间的实时互动对战。BattleStore 提供了一套全面的 API 来管理整个 PK 生命周期。
重要：
请始终使用工厂方法 create(liveID:) 并提供有效的直播间 ID 来创建 BattleStore 实例。不要尝试直接初始化。
说明：
PK 状态更新通过 state 发布者传递。订阅它以接收有关 PK 信息、参与用户和分数的实时更新。
警告：
如果 PK 请求在指定的超时时间内未收到响应，将触发超时事件。请始终在 UI 中处理超时场景。
功能特性
PK 请求管理：主播可以发起 PK 请求，被邀请方可以接受或拒绝。
状态管理：实时跟踪 PK 信息、参与用户和分数。
事件驱动架构：提供完整的 PK 事件回调。
超时处理：为 PK 请求提供内置超时机制。
可订阅数据
BattleState 的字段描述如下：
属性名
类型
描述
currentBattleInfo
BattleInfo?
当前 PK 信息。
battleUsers
[SeatUserInfo]
PK 用户列表。
battleScore
[String: UInt]
PK 分数的映射。
API 列表
函数名
描述
create
创建 BattleStore 实例。
battleEventPublisher
PK 事件发布者。
removeBattleListener
移除 PK 事件回调。
requestBattle
发起 PK 请求。
cancelBattleRequest
取消 PK 请求。
acceptBattle
接受 PK 请求。
rejectBattle
拒绝 PK 请求。
exitBattle
退出 PK。
创建实例
create
创建 BattleStore 实例
public static func create(liveID: String) -> BattleStore {
    let store: BattleStoreImpl = StoreFactory.shared.getStore(liveId: liveID)
    return store
}
版本信息
从 3.5 版本开始支持。
参数说明
参数名
类型
是否必填
描述
liveID
String
必填
直播间ID。
观察状态和事件
battleEventPublisher
PK 事件发布者
removeBattleListener
移除 PK 事件回调
PK 操作
requestBattle
发起 PK 请求
public func requestBattle(config: BattleConfig, userIDList: [String], timeout: TimeInterval, completion: BattleRequestClosure?) {
    fatalError("\(#function) must be overridden by subclass")
}
版本信息
从 3.5 版本开始支持。
参数说明
参数名
类型
是否必填
描述
config
BattleConfig
必填
PK 配置。
userIDList
[String]
必填
需要进入PK的用户 ID 列表。
timeout
TimeInterval
必填
请求超时时间。
completion
BattleRequestClosure?
必填
发起请求成功的回调。
cancelBattleRequest
取消PK请求
public func cancelBattleRequest(battleId: String, userIdList: [String], completion: CompletionClosure?) {
    fatalError("\(#function) must be overridden by subclass")
}
版本信息
从 3.5 版本开始支持。
参数说明
参数名
类型
是否必填
描述
battleId
String
必填
PK ID。
userIdList
[String]
必填
用户ID列表。
completion
CompletionClosure?
必填
取消请求成功的回调。
acceptBattle
接受PK请求
public func acceptBattle(battleID: String, completion: CompletionClosure?) {
    fatalError("\(#function) must be overridden by subclass")
}
版本信息
从 3.5 版本开始支持。
参数说明
参数名
类型
是否必填
描述
battleID
String
必填
PK ID。
completion
CompletionClosure?
必填
接受成功的回调。
rejectBattle
拒绝PK请求
public func rejectBattle(battleID: String, completion: CompletionClosure?) {
    fatalError("\(#function) must be overridden by subclass")
}
版本信息
从 3.5 版本开始支持。
参数说明
参数名
类型
是否必填
描述
battleID
String
必填
PK ID。
completion
CompletionClosure?
必填
拒绝成功的回调。
exitBattle
退出PK
public func exitBattle(battleID: String, completion: CompletionClosure?) {
    fatalError("\(#function) must be overridden by subclass")
}
版本信息
从 3.5 版本开始支持。
参数说明
参数名
类型
是否必填
描述
battleID
String
必填
PK ID。
completion
CompletionClosure?
必填
退出 PK 成功的回调。
数据结构
BattleEndedReason
正在 PK 中用户收到 PK 结束的原因。
枚举值
值
说明
timeOver
0
PK 倒计时结束。
allMemberExit
1
所有 PK 成员退出。
BattleEvent
收到 PK 相关的回调事件。
枚举值
说明
onBattleStarted
当 PK 正式开始时触发此回调，通知所有参与者 PK 已经开始。
onBattleEnded
当 PK 结束时触发此回调。
onUserJoinBattle
当有用户加入 PK 时触发此回调。
onUserExitBattle
当有用户退出 PK 时触发此回调。
onBattleRequestReceived
当收到 PK 请求时触发此回调。
onBattleRequestCancelled
当 PK 请求被取消时触发此回调。
onBattleRequestTimeout
当 PK 请求超时时触发此回调。
onBattleRequestAccept
当 PK 请求被接受时触发此回调。
onBattleRequestReject
当 PK 请求被拒绝时触发此回调。
BattleConfig
发送 PK 请求时，设置的 PK 配置信息。
属性
类型
说明
duration
TimeInterval
PK 持续时间（单位：秒）。
needResponse
Bool
被邀请用户是否需要回复同意/拒绝。
extensionInfo
String
扩展信息。
BattleInfo
PK 信息。
属性
类型
说明
battleID
String
PK ID。
config
BattleConfig
发送 PK 请求时，设置的 PK 配置信息。
startTime
UInt
PK 开始标记时间戳（单位：秒）。
endTime
UInt
PK 结束标记时间戳（单位：秒）。
BattleState
BattleStore 对外提供的 PK 相关状态数据。
属性
类型
说明
currentBattleInfo
BattleInfo?
当前 PK 信息。
battleUsers
[SeatUserInfo]
PK 用户列表。
battleScore
[String: UInt]
PK 分数的映射。
BattleRequestCallback
PK 请求回调。
PK 请求的回调接口，用于处理 PK 请求的成功或失败结果。
方法
onSuccess: 成功回调。
fun onSuccess(battleInfo: BattleInfo, resultMap: Map<String, Int>)
参数名
类型
说明
battleInfo
BattleInfo
PK 信息，包含 PK 的详细配置和状态。
resultMap
Map<String, Int>
PK 请求的响应结果回调。
onError: 失败回调。
fun onError(code: Int, desc: String)
参数名
类型
说明
code
Int
错误码。
desc
String
错误描述。
使用示例
// 创建 store 实例
let store = BattleStore.create(liveID: "live_room_123")
﻿
// 订阅状态变化
store.state.subscribe { state in
    if let battleInfo = state.currentBattleInfo {
        print("当前 PK ID: \(battleInfo.battleID)")
    }
    print("PK 用户数: \(state.battleUsers.count)")
}
﻿
// 订阅 PK 事件
store.battleEventPublisher.sink { event in
    switch event {
    case .onBattleStarted(let battleInfo, let inviter, let invitees):
        print("PK 开始，发起者: \(inviter.userName)")
    case .onBattleEnded(let battleInfo, let reason):
        print("PK 结束，原因: \(reason)")
    default:
        break
    }
}
﻿
// 发起 PK 请求
let config = BattleConfig(duration: 300, needResponse: true)
store.requestBattle(config: config, userIDList: ["user_456"], timeout: 30) { result in
    switch result {
    case .success(let (battleInfo, resultMap)):
        print("PK 请求成功: \(battleInfo.battleID)")
    case .failure(let error):
        print("PK 请求失败: \(error)")
    }
}
﻿

属性名	类型	描述
currentBattleInfo	BattleInfo?	当前 PK 信息。
battleUsers	[SeatUserInfo]	PK 用户列表。
battleScore	[String: UInt]	PK 分数的映射。

函数名	描述
create	创建 BattleStore 实例。
battleEventPublisher	PK 事件发布者。
removeBattleListener	移除 PK 事件回调。
requestBattle	发起 PK 请求。
cancelBattleRequest	取消 PK 请求。
acceptBattle	接受 PK 请求。
rejectBattle	拒绝 PK 请求。
exitBattle	退出 PK。

参数名	类型	是否必填	描述
liveID	String	必填	直播间ID。

枚举值	值	说明
timeOver	0	PK 倒计时结束。
allMemberExit	1	所有 PK 成员退出。

枚举值	说明
onBattleStarted	当 PK 正式开始时触发此回调，通知所有参与者 PK 已经开始。
onBattleEnded	当 PK 结束时触发此回调。
onUserJoinBattle	当有用户加入 PK 时触发此回调。
onUserExitBattle	当有用户退出 PK 时触发此回调。
onBattleRequestReceived	当收到 PK 请求时触发此回调。
onBattleRequestCancelled	当 PK 请求被取消时触发此回调。
onBattleRequestTimeout	当 PK 请求超时时触发此回调。
onBattleRequestAccept	当 PK 请求被接受时触发此回调。
onBattleRequestReject	当 PK 请求被拒绝时触发此回调。

属性	类型	说明
duration	TimeInterval	PK 持续时间（单位：秒）。
needResponse	Bool	被邀请用户是否需要回复同意/拒绝。
extensionInfo	String	扩展信息。