随机物品生成
QI 能像 MMOItems 一样随机生成装备：按品质权重抽 Tier → 按容量算词缀槽位 → 从词缀池抽词缀 → 拼成物品。命令入口 /qi generate。
1. 命令用法
| 命令 | 说明 |
|---|---|
/qi generate [tier] [type] [amount] | 随机生成物品并放进背包 |
/qi generate preview [tier] [type] | 只预览生成结果，不真正造 |
/qi generate pools | 列出可用词缀池 |
参数都可省略（不填则随机 Tier、默认池）。见 命令。
2. 生成流程
1. 抽 Tier ItemTierRarityRoller —— 按各 tier 的 generation.chance 加权随机
2. 算容量 TierCapacityCalculator —— 由 tier 的 capacity 参数算出槽位数
3. 分配容量 AffixRoller.distributeCapacity —— 容量均分到各词缀池
4. 抽词缀 AffixRoller.rollFromPool —— 每个池按容量抽词缀
5. 合并 前缀取第一个、后缀取第一个、Lore 全合并
6. 造物品 生成 amount 件，写入种子 / tier / 品质 / 模板标签
7. 发放 若指定玩家则进背包，溢出自然掉落3. 容量计算
容量参数来自 Tier 的 generation.capacity（见 品质）：
容量 = base + (scale × rand) + (spread × rand) + (maxSpread × rand)
（各 rand 是独立的 [0,1) 随机；结果向下取整，不小于 0）例：
COMMON { base:2, scale:3 } → 2 + rand(0~3) = [2,4]
LEGENDARY{ base:10, scale:5, spread:3, maxSpread:2 } → 10 + 各项随机 = [10,20]4. Tier 加权抽取
候选 = 所有 generation.chance > 0 的 tier
total = 各 chance 之和
r = random × total
逐个减去 chance，r < 0 时命中该 tier例：COMMON=50、UNCOMMON=30、RARE=15、EPIC=4、LEGENDARY=1，r=45 → 命中 EPIC。
5. 词缀池抽取
每个池（一个段）按其类型抽取：
| 段类型 | 抽法 |
|---|---|
weight_join / affix_pool | 加权不放回，抽 amount 个 |
quality_pool | 按当前 tier 找子池，再当 weight_join 抽 |
| 其它 | 当单条目池，取其 prefix/suffix/lore |
词缀池默认是 affix_pool，可用 /qi generate pools 查看全部。
品质池的两级路由
yaml
quality_pool_damage:
type: quality_pool
common: "pool_damage_common" # tier=COMMON → 用这个子池
rare: "pool_damage_rare"
pool_damage_rare:
type: weight_join
values:
- "3::+8 伤害"
- "5::+10 伤害"生成 RARE 物品时，quality_pool_damage 找到 rare → pool_damage_rare → 从中加权抽。
6. 开发者 API
kotlin
RandomItemGenerator.generate(random, Options(
tierId = "LEGENDARY", // 强制 tier（不填则随机）
itemType = "sword", // 强制类型
templateId = "legendary_sword", // 用模板物品
poolIds = listOf("affix_pool"), // 词缀池
amount = 3, // 数量
giveTo = player, // 直接发放（溢出掉落）
)): GenerationResult
RandomItemGenerator.preview(random, options): String // 文本预览返回：
kotlin
data class GenerationResult(
val items: List<ItemStack>,
val tier: ItemTier?,
val affixResults: List<AffixRoller.AffixResult>,
val summary: String, // 人类可读摘要
)7. 物品刷新服务
随机生成相关的一个配套能力：当你改了套装 / Tier / 模板配置后，让玩家身上已有的物品重新渲染。QinhItemRefreshService：
kotlin
QinhItemRefreshService.refreshOnlinePlayers(): RefreshReport
QinhItemRefreshService.refreshPlayer(player): RefreshReport
QinhItemRefreshService.refreshEquipment(player): RefreshReport
QinhItemRefreshService.refreshItems(items): RefreshReport对应命令 /qi refresh（及 all / inventory / armor / equipment / hand），见 命令。刷新 = 对每件 QI 物品调 assembly().rebuild() + variables().refresh()，保留实例 / 种子、只更新显示。