《MMO 服务器开发》9.3 离线推进与体力

// file: internal/attr/offline.go
// tier: L1
// verify: go test ./internal/attr/
package attr

import "errors"

var (
	ErrStaminaNotEnough = errors.New("attr: 体力不足")
)

// Stamina 是体力/行动力：随时间回复、有上限、消耗要原子。
type Stamina struct {
	Cur      int32
	Max      int32
	RegenSec int64 // 每回复 1 点所需秒数
	LastTick int64 // 上次结算的 unix 秒
}

func NewStamina(cur, max int32, regenSec, now int64) *Stamina {
	return &Stamina{Cur: cur, Max: max, RegenSec: regenSec, LastTick: now}
}

// Apply 把体力结算到 now，返回本次回复的点数。
// 关键：只按「完整回复周期」推进 LastTick，余数留到下次，避免多次短会话丢点。
func (s *Stamina) Apply(now int64) int32 {
	if s.RegenSec <= 0 || now <= s.LastTick {
		return 0 // 时钟回拨或零间隔：不回复
	}
	ticks := (now - s.LastTick) / s.RegenSec
	if ticks <= 0 {
		return 0 // 不足一个周期，余数保留
	}
	s.LastTick += ticks * s.RegenSec // 只推进整数个周期
	if s.Cur >= s.Max {
		return 0 // 满体力时不攒，超出的周期直接作废
	}
	gained := int32(ticks)
	if room := s.Max - s.Cur; gained > room {
		gained = room
	}
	s.Cur += gained
	return gained
}

// Consume 原子扣体力：不够就整体失败，不做部分扣减。
func (s *Stamina) Consume(n int32) error {
	if n <= 0 {
		return nil
	}
	if s.Cur < n {
		return ErrStaminaNotEnough
	}
	s.Cur -= n
	return nil
}

// Add 直接发放体力（道具/购买），超过上限的部分丢弃。
func (s *Stamina) Add(n int32) {
	if n <= 0 {
		return
	}
	s.Cur += n
	if s.Cur > s.Max {
		s.Cur = s.Max
	}
}

// OfflineConfig 决定离线推进的结算规则。
type OfflineConfig struct {
	MaxOfflineSec int64 // 离线结算上限，如 12 小时
	PerSecReward  int64 // 每秒产出的资源（示例：金币）
}

// OfflineResult 是一次离线推进的结算结果。
type OfflineResult struct {
	Elapsed int64 // 被采纳的有效秒数（已封顶）
	Clamped bool  // 是否被上限截断
	Reward  int64 // 结算得到的资源
}

// SettleOffline 结算离线收益，now 与 lastLogout 都是 unix 秒。
// 三处必须处理：时钟回拨（now < lastLogout）、上限封顶、产出按有效秒数算。
func SettleOffline(lastLogout, now int64, cfg OfflineConfig) OfflineResult {
	var res OfflineResult
	if now <= lastLogout {
		return res // 时钟回拨或零间隔：不产出，也绝不产出负收益
	}
	elapsed := now - lastLogout
	if cfg.MaxOfflineSec > 0 && elapsed > cfg.MaxOfflineSec {
		elapsed = cfg.MaxOfflineSec
		res.Clamped = true
	}
	res.Elapsed = elapsed
	res.Reward = elapsed * cfg.PerSecReward
	return res
}

// LoginSettle 汇总一次登录结算：离线收益与体力各算各的，但共用同一个 now。
type LoginSettle struct {
	Offline       OfflineResult
	StaminaGained int32
}

// OnLogin 在玩家上线时调用一次。体力走 Apply（保留余数），
// 离线收益走 SettleOffline（带封顶），两者互不影响，也不共用 LastTick。
func OnLogin(st *Stamina, lastLogout, now int64, cfg OfflineConfig) LoginSettle {
	return LoginSettle{
		Offline:       SettleOffline(lastLogout, now, cfg),
		StaminaGained: st.Apply(now),
	}
}

        lastLogout                                now（登录）
            |                                      |
            |<------------- elapsed -------------->|
            |                                      |
   离线收益 |<---- min(elapsed, MaxOfflineSec) ---->|  超出部分丢弃，Clamped=true
   体力回复 |  tick   tick   tick   tick  ...  tick |  只数完整周期，余数留在 LastTick

// snippet: internal/attr/offline_test.go（摘录）
func TestStaminaNoDrift(t *testing.T) {
	const regen = 60 // 每 60 秒 1 点
	long := NewStamina(0, 100, regen, 0)
	if got := long.Apply(600); got != 10 {
		t.Fatalf("长会话回复 = %d, 期望 10", got)
	}
	// 10 次 60 秒的短会话，应回满同样的 10 点
	short := NewStamina(0, 100, regen, 0)
	total := int32(0)
	for i := int64(1); i <= 10; i++ {
		total += short.Apply(i * 60)
	}
	if total != 10 || short.Cur != long.Cur {
		t.Fatalf("短会话合计 = %d cur=%d, 期望 10 / %d", total, short.Cur, long.Cur)
	}
	// 不足一个周期时余数保留：再等 30 秒不回复
	if got := short.Apply(600 + 30); got != 0 {
		t.Fatalf("余数期回复 = %d, 期望 0", got)
	}
}

stamina:
  max: 100
  regen_sec: 360         # 每 6 分钟回 1 点
offline:
  max_offline_sec: 43200 # 12 小时封顶
  per_sec_reward: 1

$ go vet ./...
（无输出）

$ go test ./internal/attr/
ok  	aegis/internal/attr	0.4s     （15 个 test 全绿）