《MMO 服务器开发》9.3 世界时钟与 Tick 预算

   墙钟：   |---45ms---|--10ms--|----60ms----|--50ms--|
   累加器： 45          55        115          165
   步长 50ms，每帧步数：
           0           1         2            1
   逻辑时间：0          50        150          200   ← 只由「跑了几步」决定

// snippet: 典型逻辑帧主循环（示意，非完整文件）

ticker := time.NewTicker(framePeriod) // 例如 20ms 一帧
for {
	select {
	case <-ticker.C:
		n := clock.Advance(framePeriod) // 墙钟只在这里出现
		for i := 0; i < n; i++ {
			world.Step() // 纯逻辑：不读墙钟、不读随机，遍历顺序固定
		}
		flushOutbound() // 帧末统一发包，保证同一帧的推送顺序一致
	case <-stop:
		return
	}
}

// file: internal/timing/worldclock.go
// tier: L1
// verify: go test ./internal/timing/

package timing

import "time"

// Policy 决定「墙钟落后于逻辑时间」时怎么处理。
type Policy int

const (
	// CatchUp 追帧：一帧内补齐所有落后步数（上限 maxSteps），逻辑可重放时首选。
	CatchUp Policy = iota
	// Drop 丢弃：一帧最多执行 maxSteps 步，其余积压直接丢掉，逻辑时间会跳跃。
	Drop
	// SlowDown 降频：不补步，但把有效步长向实际帧时间靠拢，让逻辑频率跟随真实帧率。
	SlowDown
)

// WorldClock 是服务器逻辑帧时钟：把不稳定的墙钟时间折算成固定步长的逻辑时间。
// 调用方每帧调用一次 Advance，按返回的步数执行逻辑；逻辑时间只由「执行了多少步」
// 决定，因此与墙钟抖动解耦，可重放、可确定性回放。
type WorldClock struct {
	policy   Policy
	step     time.Duration
	baseStep time.Duration
	maxSteps int
	scale    float64

	acc     time.Duration // 尚未折算成逻辑步的墙钟余量
	ticks   uint64        // 已执行的逻辑步总数
	dropped time.Duration // 因超预算被丢弃的逻辑时间
}

// NewWorldClock 建一个逻辑帧时钟。step 是逻辑步长，policy 决定积压处理策略。
func NewWorldClock(step time.Duration, policy Policy) *WorldClock {
	return &WorldClock{policy: policy, step: step, baseStep: step, maxSteps: 8, scale: 1}
}

// Step 返回当前有效步长（SlowDown 下会动态变化）。
func (c *WorldClock) Step() time.Duration { return c.step }

// Ticks 返回已执行的逻辑步数。
func (c *WorldClock) Ticks() uint64 { return c.ticks }

// LogicTime 返回逻辑时间 = 步数 × 步长。
func (c *WorldClock) LogicTime() time.Duration { return time.Duration(c.ticks) * c.step }

// Dropped 返回累计被丢弃的逻辑时间。
func (c *WorldClock) Dropped() time.Duration { return c.dropped }

// SetMaxSteps 设置单帧逻辑步数上限。
func (c *WorldClock) SetMaxSteps(n int) {
	if n > 0 {
		c.maxSteps = n
	}
}

// SetScale 设置时间缩放：>1 加速，<1 减速。s <= 0 时忽略。
func (c *WorldClock) SetScale(s float64) {
	if s > 0 {
		c.scale = s
	}
}

// Advance 吸收一段真实墙钟时间，返回本帧应执行的逻辑步数。
//
// 超预算处理：当一帧折算出超过 maxSteps 步时，多余部分按策略被丢弃（Drop）
// 或截断（CatchUp），并累加到 dropped。这是防「死亡螺旋」的关键——若每步逻辑
// 都比 step 还慢，无上限追帧会让积压雪球越滚越大。
func (c *WorldClock) Advance(wall time.Duration) int {
	if wall < 0 {
		wall = 0
	}
	scaled := time.Duration(float64(wall) * c.scale)

	if c.policy == SlowDown {
		// 有效步长向实际帧时间靠拢，上限 4× 基准步长，避免一次卡顿把步长拉爆。
		target := c.step
		if scaled > target {
			target = scaled
		}
		if limit := 4 * c.baseStep; target > limit {
			target = limit
		}
		c.step = target
	}

	c.acc += scaled
	steps := int(c.acc / c.step)
	if steps > c.maxSteps {
		over := time.Duration(steps-c.maxSteps) * c.step
		c.dropped += over
		c.acc -= over
		steps = c.maxSteps
	}
	c.acc -= time.Duration(steps) * c.step
	c.ticks += uint64(steps)
	return steps
}

// snippet: internal/timing/worldclock_test.go（节选）

// simulate 模拟真实帧循环：每帧吸收墙钟时间、执行 n 步逻辑，逻辑本身又要花 work
// 的墙钟时间，因此下一帧的墙钟间隔至少是上帧逻辑耗时。用来暴露「死亡螺旋」。
func simulate(c *WorldClock, frames int, step, work time.Duration) (steps int, dropped time.Duration) {
	wall := step
	for i := 0; i < frames; i++ {
		n := c.Advance(wall)
		steps += n
		wall = time.Duration(n) * work
		if wall < step {
			wall = step
		}
	}
	return steps, c.Dropped()
}

func TestDeathSpiralAndDropBreaksIt(t *testing.T) {
	const (
		step = 20 * time.Millisecond
		work = 25 * time.Millisecond // 每步逻辑比步长还慢
	)

	catch := NewWorldClock(step, CatchUp)
	catch.SetMaxSteps(1000)
	catchSteps, _ := simulate(catch, 100, step, work)
	if catchSteps <= 100 {
		t.Fatalf("catch-up ran %d steps in 100 frames, expected the backlog to snowball", catchSteps)
	}

	drop := NewWorldClock(step, Drop)
	drop.SetMaxSteps(1)
	dropSteps, dropDropped := simulate(drop, 100, step, work)
	if dropSteps != 100 {
		t.Fatalf("drop ran %d steps in 100 frames, want exactly 1/frame", dropSteps)
	}
	if dropDropped == 0 {
		t.Fatal("drop policy never discarded backlog, death spiral not broken")
	}
}