Documentation
¶
Overview ¶
Package questlog 提供任务 / 成就的进度追踪:定义一组带目标值的任务,累加进度, 达标后可领取(一次),支持前置依赖与周期重置。纯内存、并发安全。
覆盖:每日任务、成就、活动进度、新手引导、通行证(battle pass)。这类系统的共性是 "目标 + 进度 + 状态机(进行中→已达成→已领取)+ 依赖 + 重置",questlog 把它抽象成 一个原语,业务只需定义任务与推进进度,状态流转和领取幂等由本包保证。
与相邻原语的区别:
- counter 是"窗口内计数"(会过期、无目标/状态);questlog 是"朝目标累加 + 领取状态机", 进度不因时间流逝而减少(除非显式 Reset);
- fsm 是通用状态机;questlog 内建了任务专用的三态流转与依赖门控,无需自己接线。
模型:一个 Log 持有任务定义(所有 owner 共享)+ 每个 owner 的进度快照。 任务状态:Locked(前置未完成)< InProgress(进行中)< Achieved(达标待领)< Claimed(已领)。 进度推进用 Advance(按任务专属计数器累加)或 Set(直接设定当前值)。
泛型 ID 为任务标识(comparable)。并发安全(单锁,任务数与 owner 数中等规模适用)。 零值不可用,用 New 构造。
Index ¶
- type Log
- func (l *Log[ID]) Advance(owner string, id ID, delta int64) (State[ID], bool)
- func (l *Log[ID]) Claim(owner string, id ID) bool
- func (l *Log[ID]) ClaimAll(owner string) []ID
- func (l *Log[ID]) Claimable(owner string) []ID
- func (l *Log[ID]) List(owner string) []State[ID]
- func (l *Log[ID]) Reset(owner string, ids ...ID)
- func (l *Log[ID]) Set(owner string, id ID, v int64) (State[ID], bool)
- func (l *Log[ID]) StateOf(owner string, id ID) (State[ID], bool)
- type Option
- type Quest
- type State
- type Status
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Log ¶
type Log[ID comparable] struct { // contains filtered or unexported fields }
Log 任务日志:持有任务定义 + 各 owner 进度。零值不可用,用 New 构造。并发安全。
func New ¶
func New[ID comparable](quests []Quest[ID], opts ...Option[ID]) *Log[ID]
New 创建任务日志并注册任务定义。重复 ID 后者覆盖前者。
func (*Log[ID]) Advance ¶
Advance 给 owner 的任务 id 累加 delta 进度(delta 可为负,进度夹在 [0, Target])。 任务不存在或被锁定(前置未完成)时不生效。返回推进后的状态快照与是否发生变化。
func (*Log[ID]) Claim ¶
Claim 领取 owner 的任务 id 奖励。仅当状态为 Achieved 时成功(返回 true), 幂等:已领取或未达标返回 false。成功时触发 OnClaim 回调(锁外)。
type Option ¶
type Option[ID comparable] func(*Log[ID])
Option 配置 Log。
func WithOnClaim ¶
func WithOnClaim[ID comparable](fn func(owner string, q Quest[ID])) Option[ID]
WithOnClaim 设置领取回调:Claim 成功时触发(用于发奖/打点)。回调在锁外执行。
type Quest ¶
type Quest[ID comparable] struct { // ID 唯一标识。 ID ID // Target 目标进度值(达到即视为完成,须 > 0)。 Target int64 // Requires 前置任务:这些任务全部 Claimed 后本任务才解锁(可空)。 Requires []ID // Meta 业务自定义元数据(奖励内容、描述等),questlog 不解释。 Meta any }
Quest 一个任务/成就的定义(所有 owner 共享)。
type State ¶
type State[ID comparable] struct { ID ID Status Status Progress int64 // 当前进度(<= Target) Target int64 }
State 某 owner 在某任务上的状态快照。
Source Files