Dynamic Lantern

Dynamic Lantern is a Forge 1.20.1 mod that renders supported Curios lantern items as visible waist lanterns and lets compatible shader packs recognize them for held-item lighting.

动态灯笼是一个 Forge 1.20.1 模组，可以把支持的 Curios 灯笼物品渲染成腰间灯笼，并让兼容的光影包识别这些物品的手持发光效果。

English

Features

• Renders supported Curios lantern items on the player's waist.
• Adds an optional dedicated Curios Lantern slot controlled by Dynamic Lantern's common config.
• Supports vanilla lanterns, soul lanterns, configured custom items, and built-in optional compatibility items.
• Supports item-model rendering for non-block waist items.
• Provides left-side and back-side placement options.
• Adds configurable pendulum-style swing physics.
• Lets Iris/Oculus shader held-item lighting use supported Curios light-emitting waist items, even when they are not in the user whitelist.
• Supports legacy SEUS v11-style shader held-light uniforms by promoting Curios waist light to the main-hand light path when needed.
• Includes built-in shader lighting support for cold_sweat:soulspring_lamp, mapped as a soul lantern for shader held-item IDs.
• Includes internal Epic Fight model positioning, so EpicFightCuriosCompat is not required for the lantern position.
• Avoids duplicate lantern rendering when EpicFightCuriosCompat is installed together with Dynamic Lantern.
• Honors the Curios render visibility toggle, hiding both the waist model and shader held-item lighting when the slot display is disabled.
• Adds Dynamic Lantern's own Curios validator, so newly configured waist items can be equipped and show the Curios slot tooltip without re-entering the world.
• When both the dedicated Lantern slot and the Belt slot contain renderable lanterns, the dedicated Lantern slot is rendered first and the Belt lantern is ignored.
• Keeps Curios scans and optional compatibility hooks cached where possible to reduce render-thread and server-thread overhead.
• Does not add a dynamic light source.

Built-In Defaults

The config screen only shows player-added item IDs. Built-in defaults are hidden from that list but are enabled automatically when their owning mod is installed.

• minecraft:lantern
• minecraft:soul_lantern
• under_the_moon:moon_lamp
• cold_sweat:soulspring_lamp
• Skinned Lanterns lantern variants

Optional item IDs are declared with required: false, so the game still loads normally when the optional mod is not installed.

Custom Waist Items

Additional item IDs can be added from the Dynamic Lantern config screen. After an item is added:

• It can render from the dedicated Curios Lantern slot or the Curios Belt slot.
• Curios can recognize it as valid for supported Dynamic Lantern slots through Dynamic Lantern's runtime validator.
• The Curios item tooltip can show supported slots immediately, without requiring the player to leave and re-enter the world.
• Light-emitting block items can participate in shader held-item lighting when equipped in Curios.

Cold Sweat Soulspring Lamp

cold_sweat:soulspring_lamp receives dedicated support:

• It can be equipped in the Curios Belt slot by default, or in the dedicated Lantern slot when that slot is enabled.
• When equipped in Curios, it can use the same attack fuel behavior as the hand-held Soulspring Lamp.
• It participates in shader held-item lighting like a soul lantern while equipped in hand or Curios.
• It does not spoof hand rendering or hand animation, so normal held-item rendering is not disturbed.

Configuration

The client config screen includes:

• Waist rendering toggle
• Dedicated Lantern slot toggle
• Swing physics toggle
• Swing strength
• Left-side placement
• Back placement
• Curios shader lighting override
• Additional waist display item whitelist

The common config file includes enableLanternSlot, which controls whether the dedicated Curios Lantern slot is added to players, and soulspringLampDebugLog for Soulspring Lamp diagnostics. Both are disabled by default.

Requirements

• Minecraft 1.20.1
• Forge 47+
• Official Curios 5.8.0+1.20.1 or newer

Dynamic Lantern 1.20.1 supports the official Curios mod only. Accessories and Accessories Curios Compat Layer are not supported. If accessories_cclayer is installed, Dynamic Lantern stops during mod loading with an actionable message instead of calling unsupported Curios handler methods.

Optional Compatibility

• Oculus / Iris-compatible shader pipeline for held-item shader lighting
• Epic Fight
• EpicFightCuriosCompat, with Dynamic Lantern taking over lantern rendering while leaving other Curios compatibility behavior intact
• Cold Sweat
• Under the Moon
• Skinned Lanterns

中文

功能

• 将支持的 Curios 灯笼物品渲染在玩家腰间。
• 新增可选的专用 Curios 灯笼槽位，由 Dynamic Lantern 的 common 配置控制。
• 默认支持原版灯笼、灵魂灯笼、玩家配置的自定义物品，以及内置的可选兼容物品。
• 支持非方块物品使用物品模型进行腰间渲染。
• 提供左侧悬挂和靠后悬挂选项。
• 提供可配置的摆动物理效果。
• Iris/Oculus 的 shader held-item lighting 可以识别受支持的 Curios 腰间发光物品，即使该物品没有加入玩家自定义白名单。
• 内置支持 cold_sweat:soulspring_lamp 的 shader 发光识别，并按灵魂灯笼交给光影处理。
• 内置 Epic Fight 模型定位，不再依赖 EpicFightCuriosCompat 来修正灯笼位置。
• 与 EpicFightCuriosCompat 同时安装时，会避免灯笼重复渲染。
• 遵守 Curios 的显示开关；关闭槽位显示时，腰间模型和 shader held-item lighting 都会一起关闭。
• 添加 Dynamic Lantern 自己的 Curios validator，玩家新增的腰间显示物品可以立刻放入受支持槽位并显示 Curios 槽位 tooltip，不需要重新进入世界。
• 当专用灯笼槽位和腰带槽位同时放入可渲染灯笼时，优先渲染专用灯笼槽位，忽略腰带灯笼。
• 尽量缓存 Curios 扫描和可选兼容逻辑，降低渲染线程和服务器线程上的额外开销。
• 本模组不添加动态光源。

内置默认物品

设置界面只显示玩家手动添加的物品 ID。内置默认物品不会显示在该列表中，但在对应模组安装时会自动启用。

• minecraft:lantern
• minecraft:soul_lantern
• under_the_moon:moon_lamp
• cold_sweat:soulspring_lamp
• Skinned Lanterns 的灯笼变体

可选物品 ID 使用 required: false 声明，因此未安装对应模组时游戏也可以正常加载。

自定义腰间物品

可以从 Dynamic Lantern 设置界面添加额外物品 ID。添加后：

• 该物品可以从专用 Curios 灯笼槽位或 Curios 腰带槽位渲染。
• Curios 会通过 Dynamic Lantern 的运行时 validator 识别它可以放入受支持槽位。
• 物品 tooltip 可以立刻显示受支持槽位，不再需要玩家退出并重新进入世界。
• 如果它本身是会发光的方块物品，放在受支持 Curios 槽位中时可以参与 shader held-item lighting。

Cold Sweat Soulspring Lamp

cold_sweat:soulspring_lamp 拥有专门适配：

• 默认可以放入 Curios 腰带槽位；启用专用灯笼槽位后，也可以放入该槽位。
• 放在 Curios 中时，可以触发与手持 Soulspring Lamp 类似的攻击充能行为。
• 放在手中或 Curios 中时，会像灵魂灯笼一样参与 shader held-item lighting。
• 不伪造手部渲染或手部动画，因此不会影响玩家正常拿着其他物品时的渲染。

配置

客户端设置界面包含：

• 腰间渲染开关
• 专用灯笼槽位开关
• 摆动物理开关
• 摆动强度
• 左侧悬挂
• 靠后位置
• Curios 光影发光识别
• 额外腰间显示物品白名单

common 配置文件包含 enableLanternSlot 和 soulspringLampDebugLog：前者控制是否为玩家添加专用 Curios 灯笼槽位，后者用于 Soulspring Lamp 诊断日志，两者默认关闭。

需求

• Minecraft 1.20.1
• Forge 47+
• 官方 Curios 5.8.0+1.20.1 或更高版本

Dynamic Lantern 1.20.1 仅支持官方 Curios，不支持 Accessories 和 Accessories Curios Compat Layer。安装 accessories_cclayer 时，Dynamic Lantern 会在模组加载阶段给出明确提示，而不是继续调用兼容层未实现的 Curios 槽位方法。

可选兼容

• Oculus / Iris 兼容光影管线，用于 shader held-item lighting
• Epic Fight
• EpicFightCuriosCompat，灯笼渲染由 Dynamic Lantern 接管，其他 Curios 兼容逻辑保持不变
• Cold Sweat
• Under the Moon
• Skinned Lanterns

Version / 版本

Current version / 当前版本：1.8.1

See CHANGELOG.md for release notes.