lockstep

README

Lockstep 锁步（帧）同步

它是一个不限制网络类型的实现，仅需要对应连接实现 lockstep.Client 接口即可。

该包提供了一个并发安全的锁步（帧）同步实现，其中内置了频率设置、帧上限、序列化、初始帧、追帧等功能。可使用其来快速构建和管理锁步（帧）同步。

锁步（帧）同步是一种特殊的同步，它可以并发安全地将数据同步到底层连接。

Documentation

Index

• type Client
• type Lockstep
  • func NewLockstep[ClientID comparable, Command any](options ...Option[ClientID, Command]) *Lockstep[ClientID, Command]
  • func (slf *Lockstep[ClientID, Command]) AddCommand(command Command)
  • func (slf *Lockstep[ClientID, Command]) AddCommands(commands []Command)
  • func (slf *Lockstep[ClientID, Command]) DropCache(handler func(frame int64) bool)
  • func (slf *Lockstep[ClientID, Command]) GetClientCount() int
  • func (slf *Lockstep[ClientID, Command]) GetClientCurrentFrame(clientId ClientID) int64
  • func (slf *Lockstep[ClientID, Command]) GetCurrentCommands() []Command
  • func (slf *Lockstep[ClientID, Command]) GetCurrentFrame() int64
  • func (slf *Lockstep[ClientID, Command]) GetFrameLimit() int64
  • func (slf *Lockstep[ClientID, Command]) IsRunning() bool
  • func (slf *Lockstep[ClientID, Command]) JoinClient(client Client[ClientID])
  • func (slf *Lockstep[ClientID, Command]) JoinClientWithFrame(client Client[ClientID], frameIndex int64)
  • func (slf *Lockstep[ClientID, Command]) LeaveClient(clientId ClientID)
  • func (slf *Lockstep[ClientID, Command]) OnLockstepStoppedEvent()
  • func (slf *Lockstep[ClientID, Command]) RegLockstepStoppedEvent(handle StoppedEventHandle[ClientID, Command])
  • func (slf *Lockstep[ClientID, Command]) StartBroadcast()
  • func (slf *Lockstep[ClientID, Command]) StopBroadcast()
• type Option
  • func WithFrameLimit[ClientID comparable, Command any](frameLimit int64) Option[ClientID, Command]
  • func WithFrameRate[ClientID comparable, Command any](frameRate int64) Option[ClientID, Command]
  • func WithInitFrame[ClientID comparable, Command any](initFrame int64) Option[ClientID, Command]
  • func WithSerialization[ClientID comparable, Command any](handle func(frame int64, commands []Command) []byte) Option[ClientID, Command]
• type StoppedEventHandle

Types

type Client

type Client[ID comparable] interface {
	// GetID 用户玩家ID
	GetID() ID
	// Write 写入数据包
	Write(packet []byte, callback ...func(err error))
}

Client 帧同步客户端接口定义

• 客户端应该具备ID及写入数据包的实现

type Lockstep

type Lockstep[ClientID comparable, Command any] struct {
	// contains filtered or unexported fields
}

Lockstep 锁步（帧）同步默认实现

• 支持最大帧上限 WithFrameLimit
• 自定逻辑帧频率，默认为每秒15帧(帧/66ms) WithFrameRate
• 自定帧序列化方式 WithSerialization
• 从特定帧开始追帧
• 兼容各种基于TCP/UDP/Unix的网络类型，可通过客户端实现其他网络类型同步

func NewLockstep

func NewLockstep[ClientID comparable, Command any](options ...Option[ClientID, Command]) *Lockstep[ClientID, Command]

NewLockstep 创建一个锁步（帧）同步默认实现的组件(Lockstep)进行返回

func (*Lockstep[ClientID, Command]) AddCommand

func (slf *Lockstep[ClientID, Command]) AddCommand(command Command)

AddCommand 添加命令到当前帧

func (*Lockstep[ClientID, Command]) AddCommands

func (slf *Lockstep[ClientID, Command]) AddCommands(commands []Command)

AddCommands 添加命令到当前帧

func (*Lockstep[ClientID, Command]) DropCache

func (slf *Lockstep[ClientID, Command]) DropCache(handler func(frame int64) bool)

DropCache 丢弃特定帧的缓存，当 handler 返回 true 时将丢弃缓存

func (*Lockstep[ClientID, Command]) GetClientCount

func (slf *Lockstep[ClientID, Command]) GetClientCount() int

GetClientCount 获取客户端数量

func (*Lockstep[ClientID, Command]) GetClientCurrentFrame

func (slf *Lockstep[ClientID, Command]) GetClientCurrentFrame(clientId ClientID) int64

GetClientCurrentFrame 获取客户端当前帧

func (*Lockstep[ClientID, Command]) GetCurrentCommands

func (slf *Lockstep[ClientID, Command]) GetCurrentCommands() []Command

GetCurrentCommands 获取当前帧还未结束时的所有指令

func (*Lockstep[ClientID, Command]) GetCurrentFrame

func (slf *Lockstep[ClientID, Command]) GetCurrentFrame() int64

GetCurrentFrame 获取当前帧

func (*Lockstep[ClientID, Command]) GetFrameLimit

func (slf *Lockstep[ClientID, Command]) GetFrameLimit() int64

GetFrameLimit 获取帧上限

• 未设置时将返回0

func (*Lockstep[ClientID, Command]) IsRunning

func (slf *Lockstep[ClientID, Command]) IsRunning() bool

IsRunning 是否正在广播

func (*Lockstep[ClientID, Command]) JoinClient

func (slf *Lockstep[ClientID, Command]) JoinClient(client Client[ClientID])

JoinClient 将客户端加入到广播队列中，通常在开始广播前使用

• 如果客户端在开始广播后加入，将丢失之前的帧数据，如要从特定帧开始追帧请使用 JoinClientWithFrame

func (*Lockstep[ClientID, Command]) JoinClientWithFrame

func (slf *Lockstep[ClientID, Command]) JoinClientWithFrame(client Client[ClientID], frameIndex int64)

JoinClientWithFrame 加入客户端到广播队列中，并从特定帧开始追帧

• 可用于重连及状态同步、帧同步混用的情况
• 混用：服务端记录指令时同时做一次状态计算，新客户端加入时直接同步当前状态，之后从特定帧开始广播

func (*Lockstep[ClientID, Command]) LeaveClient

func (slf *Lockstep[ClientID, Command]) LeaveClient(clientId ClientID)

LeaveClient 将客户端从广播队列中移除

func (*Lockstep[ClientID, Command]) OnLockstepStoppedEvent

func (slf *Lockstep[ClientID, Command]) OnLockstepStoppedEvent()

func (*Lockstep[ClientID, Command]) RegLockstepStoppedEvent

func (slf *Lockstep[ClientID, Command]) RegLockstepStoppedEvent(handle StoppedEventHandle[ClientID, Command])

RegLockstepStoppedEvent 当广播停止时将触发被注册的事件处理函数

func (*Lockstep[ClientID, Command]) StartBroadcast

func (slf *Lockstep[ClientID, Command]) StartBroadcast()

StartBroadcast 开始广播

• 在开始广播后将持续按照设定的帧率进行帧数推进，并在每一帧推进时向客户端进行同步，需提前将客户端加入广播队列 JoinClient
• 广播过程中使用 AddCommand 将该帧数据追加到当前帧中

func (*Lockstep[ClientID, Command]) StopBroadcast

func (slf *Lockstep[ClientID, Command]) StopBroadcast()

StopBroadcast 停止广播

type Option

type Option[ClientID comparable, Command any] func(lockstep *Lockstep[ClientID, Command])

func WithFrameLimit

func WithFrameLimit[ClientID comparable, Command any](frameLimit int64) Option[ClientID, Command]

WithFrameLimit 通过特定逻辑帧上限创建锁步（帧）同步组件

• 当达到上限时将停止广播

func WithFrameRate

func WithFrameRate[ClientID comparable, Command any](frameRate int64) Option[ClientID, Command]

WithFrameRate 通过特定逻辑帧率创建锁步（帧）同步组件

• 默认情况下为 15/s

func WithInitFrame

func WithInitFrame[ClientID comparable, Command any](initFrame int64) Option[ClientID, Command]

WithInitFrame 通过特定的初始帧创建锁步（帧）同步组件

• 默认情况下为 0，即第一帧索引为 0

func WithSerialization

func WithSerialization[ClientID comparable, Command any](handle func(frame int64, commands []Command) []byte) Option[ClientID, Command]

WithSerialization 通过特定的序列化方式将每一帧的数据进行序列化

• 默认情况下为将被序列化为以下结构体的JSON字符串

  type Frame struct { Frame int `json:"frame"` Commands []Command `json:"commands"` }

type StoppedEventHandle

type StoppedEventHandle[ClientID comparable, Command any] func(lockstep *Lockstep[ClientID, Command])