本文仅给出“怎么组合”的示例思路,便于业务侧快速拼装查询。
说明:本模块强调复用
SearchContext的服务和数据来注入能力与动态参数。
- 候选提供者:
ExplicitListCandidateProvider(ids) - 规则:可选(如
RequireValidIdRule、ExcludeEntityRule) - 评分器:
ZeroScorer或距离评分器 - 选择器:
StreamingTopKByScoreSelector(若只要前若干个结果) - 映射器:
EntitasUnitFacadeMapper
组合要点:
SearchContext注入IUnitResolver(用于映射器)- 若包含形状/距离规则,还要注入
IPositionProvider
候选来源(两种常见方式):
IEntityIdIndex+IndexedListCandidateProvider(key)
IEntityIdCollectionIndex+IndexedCollectionCandidateProvider(key)
过滤与排序:
- 规则:
ResolvedCircleRule2D(frameResolver, circleParams)或CircleShapeRule- 可选
ExcludeEntityRule(self)
- 评分器:
DistanceToEntityScorer2D(self)(返回负距离平方,最近分数最高) - 选择器:
StreamingTopKByScoreSelector,设置MaxCount为需要的数量
参考系解析器(圆心/朝向来源):
- 圆心来自施法者:可用自定义参考系解析器(或把
origin写入SearchContext上下文数据,再实现一个数据参考系解析器) - 圆心来自两实体中点:
EntityToEntityFrameResolver2D(a, b, useMidPointAsOrigin:true)
需求:
- 矩形沿来源实体到目标实体的方向
- 宽固定
- 长度动态:来源实体到目标实体的距离乘以缩放值再加偏移值
- 锚点:从来源实体开始向前延伸
- 再叠加局部偏移(例如向前推 1m、向右偏 0.5m)
组合:
- 参考系解析器:
EntityToEntityFrameResolver2D(source, target, useMidPointAsOrigin:false)OffsetFrameResolver2D(inner, offsetLocal: (rightOffset, forwardOffset))
- 参数解析器:
RectLengthFromEntityDistanceResolver2D(source, target, width, scale, add, minLength, maxLength) - 规则:
ResolvedOrientedRectRule2D(frame, rectParams, pivot: Start)
注意:
- 这类组合对
IPositionProvider是强依赖(严格模式下缺失直接无结果)。
- 参考系解析器:
EntityToEntityFrameResolver2D(source, target, useMidPointAsOrigin:false) - 扇形参数:
SectorParamsConstantResolver2D(radius, halfAngleDeg) - 规则:
ResolvedSectorRule2D(frame, sectorParams) - 选择器:
StreamingTopKByScoreSelector(或在线前若干个结果选择器)
需求:
- 圆心是技能落点(Vector2)
- 半径来自技能计算结果(float)
做法:
- 把
originXZ、radius写入SearchContext上下文数据 - 参考系解析器使用
DataFrameResolver2D(originKey) - 圆形参数使用
DataCircleParamsResolver2D(radiusKey) - 规则使用
ResolvedCircleRule2D(frame, circleParams)
顶层 Rule 列表和 AndRule 都按声明顺序执行,并在首个 false 处短路;OrRule 在首个 true 处短路;NotRule 反转一个非空 Rule。空 AndRule 为 true,空 OrRule 为 false,因此动态组装时不需要额外伪造恒真或恒假规则。
例如 (存活 AND 可选中) AND (低血量 OR 距离近) AND NOT 已命中:
var eligibility = new AndRule(
aliveRule,
selectableRule,
new OrRule(lowHealthRule, nearSourceRule),
new NotRule(alreadyHitRule));把 eligibility 作为一个顶层 Rule 加入查询即可。组合器会在构造时复制输入数组,仍建议长期复用组合结果,并把便宜、高淘汰率的子规则放在前面。黑白名单集合实现放业务层,框架层只要求 IEntityIdSet.Contains(EntityId id);业务层可在实现内部把中性标识映射到自己的实体模型。逐候选黑名单判定不等同于 Provider 集合差集。
需求:
- 同一帧/同一次技能释放在相同种子下随机结果稳定
做法:
- 将种子(整数)写入
SearchContext上下文数据 - 使用
SeededHashRandomScorer(seedKey)作为评分器 - 配合
StreamingTopKByScoreSelector,并设置MaxCount=1或需要的数量
需求:先选择距离最近的候选;距离相同时,再选择威胁最高的候选。
var builder = SearchPipelineBuilder.Create()
.From(provider)
.ScoreBy(
distanceScorer,
SearchSortDirection.ScoreAscending)
.ThenScoreBy(
threatScorer,
SearchSortDirection.ScoreDescending)
.Select(new StreamingTopKByScoreSelector())
.Take(3);
var query = builder.Build();
builder.Dispose();ScoreBy() 设置或替换主排序项,ThenScoreBy() 按调用顺序追加次级排序项。比较采用严格字典序:只有距离同分才读取威胁排序结果,全部排序项同分后由稳定键升序决胜。每个排序项都可独立指定升序或降序;这与把多个分数乘权重后相加不是同一种语义。
做法:
- 创建一个
SearchStats并注入SearchContext:ctx.SetService<ISearchStats>(stats) - 一次查询完成后读取:
stats.Candidates / stats.Hits / stats.Results
-
多阵营/多类型:
- 高频:建立复合索引
(camp,type)->set,由一个项目 Provider 直接遍历目标索引 - 资格组合:优先用多个顶层 Rule 或
AndRule、OrRule、NotRule逐候选求值,避免中间候选集合 - 顺序拼接:使用
ConcatCandidateProvider(sourceA, sourceB),按来源顺序推送并保留重复 - 集合组合:使用
UnionDistinctCandidateProvider、IntersectCandidateProvider、ExceptCandidateProvider;三者按IEntityKeyProvider的稳定键判断成员,保留首次代表项和契约规定的顺序 - 成本边界:并、交、差会使用池化键集合,交集还会暂存第一来源中的唯一候选;高频路径能直接查询复合索引时仍优先单一项目 Provider
- 查询级
DistinctByEntityKey只能消除最终 Provider 已推送的重复 ID,不替代来源级交集或差集
- 高频:建立复合索引
-
动态参数来源:
- 来自实体:用参考系解析器和参数解析器通过
IPositionProvider获取位置 - 来自上下文数据:使用
SearchContext.SetData写入参数,再实现对应的数据参数解析器
- 来自实体:用参考系解析器和参数解析器通过
-
确定性:
- 使用
IEntityKeyProvider保证同分时稳定排序
- 使用