轮播（Slideshow）

基本信息

属性 值
源码类 lumien.custommainmenu.configuration.elements.Slideshow（继承 Element）
使用方 背景（Background） 与 图片（Image） 共用
默认 displayDuration 60 tick（3 秒，Slideshow.java:18）
默认 fadeDuration 20 tick（1 秒，Slideshow.java:21）

可配置项

字段 类型 默认值 说明
images 字符串数组 必填 每一项独立走贴图来源 解析
displayDuration int 60 每帧完整显示的 tick 数
fadeDuration int 20 交叉淡变的 tick 数
shuffle bool false 打乱图片顺序
synced bool false 仅背景支持，见下

Image 的轮播只读 images/displayDuration/fadeDuration/shuffle（GuiConfig.java:311-325）；synced 只在 Background 分支被读取（GuiConfig.java:184）。

计时模型

总周期 P = displayDuration + fadeDuration。update() 每 tick 自增 counter，并按 counter % P > displayDuration 判定是否处于淡变段（Slideshow.java:32-35）：

counter = 0 ............ displayDuration-1 | displayDuration ... P-1
         [ 当前帧稳定显示 ][ 与下一帧交叉淡变 ]
方法 返回 计算
getCurrentResource1() 底层帧 counter / P % 数量
getCurrentResource2() 叠加帧 非淡变段返回 null；否则 (counter + fadeDuration) / P % 数量
getAlphaFade(partial) 叠加层 alpha (((counter + partial) % P) - displayDuration) / fadeDuration

⚠️ fadeDuration = 0 会除零：getAlphaFade 里 1.0f / (float) this.fadeDuration（Slideshow.java:44）。此时若 counter % P 恰好 > displayDuration（即进入淡变段），浮点除零得到 Infinity/NaN，alpha 状态不可控。

⚠️ Images 数组为空时，getCurrentResource1() 会对 0 取模 → 抛 ArithmeticException（Slideshow.java:50）。

shuffle() 实现说明

Collections.shuffle(Arrays.asList(this.ressources))（Slideshow.java:25-27）——Arrays.asList 返回的是直接包装原数组的固定长度列表，set() 会写穿回 this.ressources，因此打乱确实生效（这里不是 bug）。

synced 语义

Background 侧 synced: true 表示"本界面的轮播就是主菜单那个轮播对象本身"（GuiConfig.java:184-186），而非复制一份；因此主菜单轮播推进时其他界面同步换帧。

相关条目