合成队列

队列的条目状态, 队列长度从哪来, 排在最前面的条目怎么推进, 取消时怎么退还, 以及怎么领取产物

你在一个工作站拥有一条队列. 队列是串行单线的, 也就是一条线依次推进: 同一时刻只有排在最前面的条目在动, 后面的条目排队等待

条目状态

状态	是否占用队列长度	说明
WAITING	是	已提交, 排在队列中等待
RUNNING	是	队首, 正在推进耗时
PENDING_CLAIM	否	已完成, 但产物没能送进仓库或背包, 等待玩家领取

PENDING_CLAIM 刻意不占用队列长度: 否则仓库和背包同时满的你, 会被自己没领走的产物锁死队列, 什么都排不进去. 待领取的条目由 limits.max_pending_claim 单独限制, 默认 100

队列长度的三个来源

来源	与基础长度的关系	配置位置
基础长度	起点	config.yml 的 queue.base_length, 工作站可覆盖
权限档	取代	emakistation.queue.<n>, 需 queue.permission_tiers: true
付费购买	叠加	队列页购买, 见 付费队列位

权限档取数字最大的一档生效, 你没有任何该前缀权限时就保持基础长度. 付费额度叠加在生效档之上, 最终统一被 queue.max_length 截断

之所以权限档是「取代」而付费是「叠加」, 是为了你事后给某个玩家补权限档时, 不会把他花钱买的额度吞掉

推进方式

queue.progress_mode 决定队首如何计时:

值	行为
offline	按真实时间推进, 玩家离线期间继续走时
online	仅在玩家在线时累计

offline 只表示「计时继续」, 不表示「离线发货」. EmakiStorage 拒绝对离线玩家做任何写操作, 所以离线期间到点的条目只是「已到期」, 真正结算发生在你下次上线时

整个服务器只有一个队列推进定时器, 间隔由 queue.tick_interval 控制, 默认 20 tick, 不是每条队列各配一个定时器

旧队列存档边界

QueueStore 对缺失的材料标识字段有一套源码内置的备用值, 但这一版没有在真实的 Paper 或 Folia 服务器上验证过旧队列 YAML / 旧存档跨版本恢复. 升级前请备份 data/, 并在要用的服务端上抽样检查队列, 材料标识和待领取产物

耗时

单次耗时来自配方的 duration_seconds, 再乘工作站或全局的 speed_multiplier. 你把 duration_seconds 填 0 或者干脆省略, 就表示立即完成, 根本不进队列

取消与退还

/emakistation cancel <工作站> <序号>

你按命令与界面操作时, 序号从 1 开始 (API 的 index 参数从 0 开始)

退还比例来自工作站的 queue.cancel_refund_rate, 材料与已付货币按同一比例折算. 退还总是回到材料原本来自的通道, 与工作站的产物路由无关

退还不按进度折算, 这是刻意的简化: 队列是一条线依次推进, 只有排在最前面的条目有进度; 为了一个几乎不会出现的情况去给每个条目记进度不值得

部分退还仍然会报告成功, 缺少的部分会作为 Partial 原因键带出来

PENDING_CLAIM 状态的条目不能取消, 会被拒绝并返回 station.cancel_pending_claim

领取产物

/emakistation claim

一次领走你在所有工作站里全部能送出去的待领取产物. 仍然送不出去的条目会保持待领取状态, 而不是让整个操作失败, 所以这条命令随时都可以执行

管理员操作

/emakistation admin queue <...>

需要 emakistation.admin

取消与领取的失败原因键

取消失败时会返回下面这些原因键 (命令, 界面或 API 路径相同): station.queue_not_loaded (队列数据尚未加载), station.queue_entry_missing (序号不存在), station.cancel_pending_claim (条目处于待领取), station.cancel_vetoed (被 StationCraftCancelEvent 否决), station.refund_partial (部分退还被拒, 消息按成功处理但带出缺少的部分)

领取失败会返回 station.queue_not_loaded; 成功时返回实际清理掉的条目数, 送不出去的条目继续保持待领取