matchmaker

package
v0.7.8 Latest Latest
Warning

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

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

Documentation

Overview

Package matchmaker 提供基于属性匹配的组队原语。

玩家/会话携带 string + numeric 属性注册一张 ticket,匹配器按"桶(bucket, 如 region+mode)+ 最低共同属性"策略聚合候选,凑齐队伍即成匹配。

与基于 Bluge 全文索引的做法不同,本包用纯标准库实现一个 倒排索引 + 桶分组的轻量匹配器,适合中小规模(单机万级 ticket)。 超过此规模建议接入专用检索引擎。

零值不可用,用 New 构造。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Handler

type Handler func(ctx context.Context, m Match) error

Handler 由业务实现,在匹配成功时被调用(在工作池 goroutine 中)。 返回 error 会让相关 ticket 重新进入候选池。

type Match

type Match struct {
	Tickets []*Ticket
	Pool    string
}

Match 是一次成功匹配的结果。

type Matchmaker

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

Matchmaker 管理候选池并周期性尝试匹配。

func New

func New(h Handler, opts ...Option) *Matchmaker

New 创建匹配器。h 在每次匹配成功时被调用。

func (*Matchmaker) Add

func (m *Matchmaker) Add(t Ticket, pool, bucketKey string) (string, error)

Add 注册一张 ticket 进候选池。pool 用于隔离不同匹配类型(如 "5v5"/"3v3")。 bucketKey 由 string 属性拼成(如 "eu|ranked"),决定同桶匹配优先级。

func (*Matchmaker) Count

func (m *Matchmaker) Count() int

Count 返回当前候选 ticket 数。

func (*Matchmaker) QueryNearBySkill

func (m *Matchmaker) QueryNearBySkill(pool string, val float64, n int) []*Ticket

QueryNearBySkill 返回 pool 中 skill 最接近 val 的 n 个 ticket(用于调试/扩展)。

func (*Matchmaker) Remove

func (m *Matchmaker) Remove(ticketID string) bool

Remove 移除一张 ticket(如玩家取消)。

func (*Matchmaker) Start

func (m *Matchmaker) Start(ctx context.Context)

Start 启动匹配循环。幂等。ctx 取消时停止。

func (*Matchmaker) Stop

func (m *Matchmaker) Stop()

Stop 停止匹配循环。幂等。

func (*Matchmaker) Wait

func (m *Matchmaker) Wait()

Wait 阻塞直到循环退出。

type Option

type Option func(*config)

Option 配置 Matchmaker。

func WithMaxWaitSec

func WithMaxWaitSec(sec int) Option

WithMaxWaitSec 设置 ticket 最长等待秒数:超时后放宽桶约束(忽略 string 属性差异)强匹配。 默认 30。<=0 不放宽。

func WithTickInterval

func WithTickInterval(d time.Duration) Option

WithTickInterval 设置匹配扫描周期,默认 500ms。

type Presence

type Presence struct {
	UserID    string
	SessionID string
	Node      string
	Username  string
}

Presence 表示一个待匹配的参与者。

type Properties

type Properties struct {
	String  map[string]string  // 如 {"region":"eu","mode":"ranked"}
	Numeric map[string]float64 // 如 {"skill":1200,"latency":45}
}

Properties 是 ticket 的属性集合:string 类(用于桶分组、精确匹配)与 numeric 类(用于范围/排序)。

type Ticket

type Ticket struct {
	ID         string
	Presence   Presence
	Properties Properties
	CreateTime int64 // unix nano
	MinCount   int   // 最小成队人数
	MaxCount   int   // 最大成队人数
}

Ticket 是一次匹配请求的句柄。

Jump to

Keyboard shortcuts

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