replicate

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 15, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package replicate 提供状态同步的增量投影原语:DirtySet + AOI diff + Delta。 与 pkg/gameloop + pkg/spatial/aoi 组合;序列化与 entity 字段由业务决定。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Ack

type Ack struct {
	LastFrame uint64 `json:"last_ack_frame"`
}

Ack 是客户端经可靠通道确认已收到的最高帧号。

type CatchUpBatch

type CatchUpBatch struct {
	From      uint64  `json:"from"`
	To        uint64  `json:"to"`
	Deltas    []Delta `json:"deltas"`
	Truncated bool    `json:"truncated,omitempty"` // journal 深度不足,补发不完整
}

CatchUpBatch 补发 (From, To] 区间内缺失的 Delta(From 不含, To 含)。

type Config

type Config struct {
	// BaselineRatio 当 enter+leave 占当前可见集比例超过此值时发 baseline(默认 0.3)。
	BaselineRatio float64
}

Config 控制 baseline 切换阈值等。

type Delta

type Delta struct {
	Frame    uint64        `json:"frame"`
	Baseline bool          `json:"baseline,omitempty"`
	Spawn    []EntityState `json:"spawn,omitempty"`
	Update   []EntityState `json:"update,omitempty"`
	Despawn  []string      `json:"despawn,omitempty"`
}

Delta 是一帧增量(或 baseline 全量)。

type DirtySet

type DirtySet[ID comparable] struct {
	// contains filtered or unexported fields
}

DirtySet 记录本帧变更/删除的实体 ID(tick goroutine 写入,出口只读消费)。

func NewDirtySet

func NewDirtySet[ID comparable]() *DirtySet[ID]

NewDirtySet 创建 DirtySet。

func (*DirtySet[ID]) Consume

func (d *DirtySet[ID]) Consume() (dirty, removed []ID)

Consume 取走并清空本帧 dirty/removed 集合(每 tick 出口调用一次)。

func (*DirtySet[ID]) Lookup

func (d *DirtySet[ID]) Lookup(id ID) bool

Lookup 返回 id 是否在本帧 dirty 集合中(Consume 前)。

func (*DirtySet[ID]) Mark

func (d *DirtySet[ID]) Mark(id ID)

Mark 标记实体在本帧有变更。

func (*DirtySet[ID]) Remove

func (d *DirtySet[ID]) Remove(id ID)

Remove 标记实体已删除(本帧 despawn)。

type EntityState

type EntityState struct {
	ID      string  `json:"id"`
	X       float64 `json:"x"`
	Y       float64 `json:"y"`
	Version uint64  `json:"version"`
	Payload any     `json:"payload,omitempty"`
}

EntityState 是可下发的实体快照(业务可嵌入更多字段到 Payload)。

type Journal

type Journal struct {
	// contains filtered or unexported fields
}

Journal 保存最近 depth 帧的 Delta(按 viewer 独立),供丢包后 CatchUp。

func NewJournal

func NewJournal(depth int) *Journal

NewJournal 创建 Journal。depth<=0 时取 128。

func (*Journal) CatchUp

func (j *Journal) CatchUp(after, through uint64) CatchUpBatch

CatchUp 返回 frame ∈ (after, through] 的 Delta 列表。

func (*Journal) Latest

func (j *Journal) Latest() uint64

Latest 返回 journal 中最高帧号(无条目时为 0)。

func (*Journal) Record

func (j *Journal) Record(d Delta)

Record 追加一帧 Delta;超出 depth 时丢弃最旧帧。同帧重复写入时覆盖最新条目。

type Lookup

type Lookup[ID comparable] func(id ID) (EntityState, bool)

Lookup 读取实体快照;由业务在 tick 内提供。

type Projector

type Projector[ID comparable] struct {
	// contains filtered or unexported fields
}

Projector 把 spatial 可见集 + dirty 投影为 per-viewer Delta。

func NewProjector

func NewProjector[ID comparable](cfg Config) *Projector[ID]

NewProjector 创建投影器。viewer 为连接/玩家 ID。

func (*Projector[ID]) DropViewer

func (p *Projector[ID]) DropViewer(viewer ID)

DropViewer 移除 viewer 状态(断线时)。

func (*Projector[ID]) Interest

func (p *Projector[ID]) Interest(viewer ID) *aoi.Set[ID]

Interest 返回 viewer 的 AOI 集合(不存在则创建)。

func (*Projector[ID]) Project

func (p *Projector[ID]) Project(
	frame uint64,
	viewer ID,
	visible []spatial.Entity[ID],
	dirty []ID,
	removed []ID,
	lookup Lookup[ID],
) Delta

Project 为 viewer 生成本帧 Delta。 visible 为 spatial.Nearby 结果;lookup 读取权威态;dirty/removed 来自 DirtySet.Consume。

func (*Projector[ID]) Versions

func (p *Projector[ID]) Versions() *Versions[ID]

Versions 返回共享版本表(Bump 在 tick 内对 dirty 实体调用)。

type Versions

type Versions[ID comparable] struct {
	// contains filtered or unexported fields
}

Versions 维护实体版本号(每次 Mark 时由 Replicator 递增)。

func NewVersions

func NewVersions[ID comparable]() *Versions[ID]

NewVersions 创建版本表。

func (*Versions[ID]) Bump

func (v *Versions[ID]) Bump(id ID) uint64

Bump 递增并返回新版本;实体首次出现从 1 开始。

func (*Versions[ID]) Delete

func (v *Versions[ID]) Delete(id ID)

Delete 删除实体版本记录。

func (*Versions[ID]) Get

func (v *Versions[ID]) Get(id ID) uint64

Get 返回当前版本(不存在为 0)。

type ViewerTrack

type ViewerTrack struct {
	// contains filtered or unexported fields
}

ViewerTrack 跟踪单个连接的发送/确认进度,并生成 CatchUp。

func NewViewerTrack

func NewViewerTrack(journal *Journal) *ViewerTrack

NewViewerTrack 创建 viewer 追踪器。

func (*ViewerTrack) Gap

func (v *ViewerTrack) Gap() uint64

Gap 返回 lastSent - lastAck(未确认帧数)。

func (*ViewerTrack) LastAck

func (v *ViewerTrack) LastAck() uint64

LastAck 返回已确认帧号。

func (*ViewerTrack) OnAck

func (v *ViewerTrack) OnAck(ack Ack) CatchUpBatch

OnAck 处理客户端 Ack;若存在缺口则返回需补发的 CatchUpBatch。

func (*ViewerTrack) RecordSent

func (v *ViewerTrack) RecordSent(d Delta)

RecordSent 在不可靠通道发送 delta 后调用。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL