跳到正文
返回搜尋

OptiPiston

作者 wo55555

Client-side smooth piston animation with configurable duration and singleplayer world speed.

client_mc26_10 · 0.3.2

README0.3.2

OptiPiston 图标

OptiPiston

活塞更顺滑,时间可调节。

面向 Windows LeviLamina 的 Minecraft 基岩版纯客户端模组,提供平滑活塞动画和单人世界变速。

OptiPiston v0.3.2 Windows x64 Minecraft 基岩版 LeviLamina 26.10 至 26.60 AGPL-3.0 许可证

开始使用 · 发行版本 · 更新日志 · 问题反馈 · English

Warning

OptiPiston 目前处于早期开发阶段,配置和 API 细节在版本之间仍可能变化。

OptiPiston 按可配置的平滑时间线重新绘制活塞臂及其推动的方块。它只改变客户端的渲染结果,原生活塞进度、方块状态和红石时序都保持不变。在单人世界中,它还能整体加快或放慢世界运行速度,声音和粒子会随之变化。

快速开始

Important

建议尽量使用干净的 LeviLamina 客户端实例;目前不保证与其他模组广泛兼容。

使用 LeviLauncher 安装(推荐)

  1. 在 LeviLauncher 左侧边栏选择 Download(下载),找到兼容性中所列的 Minecraft 版本,创建使用 LeviLamina 加载器的实例。
  2. 选择 Launch(启动),选中该实例,然后在内容下载区域选择 lip。
  3. 搜索 OptiPiston,打开由 wo55555 发布的软件包。
  4. 选择最新版本,并按兼容性选择与实例 Minecraft 版本线对应的变体(例如 client_mc26_20),然后点击安装。Lip 不会根据已安装的 LeviLamina 版本自动选择变体。
  5. 启动游戏并进入世界。活塞动画默认开启,可用 /optipiston status 查看当前状态。

使用 Lip 命令行安装

在实例根目录运行下面的命令,<variant> 取自兼容性中与实例版本线对应的变体:

lip install github.com/wo55555/OptiPiston#<variant>@<version>

# 示例:Minecraft 26.20 / LeviLamina 26.20.*
lip install github.com/wo55555/OptiPiston#client_mc26_20@<version>

必须带上变体。0.1.2 及更早版本使用 #client 安装;请先运行 lip uninstall github.com/wo55555/OptiPiston#client 卸载,再安装新变体。

手动安装

从最新发行版本下载对应版本线的 OptiPiston-mc<版本线>-windows-x64.zip(例如 OptiPiston-mc26.20-windows-x64.zip),将其中的 OptiPiston 目录解压到实例的 mods 目录,然后重启客户端。

功能

  • 平滑活塞动画:活塞臂和被推方块在 2–4 游戏刻内完成移动,支持小数。仅影响渲染,游戏逻辑保持原生时序。
  • 平滑衔接:被推方块在真实方块完成重新建网格前持续绘制,避免落位时出现空洞、重影或重叠。
  • 稳定的活塞头:每格只绘制一个活塞头;被推动的活塞会随其移动中的机身一起绘制。
  • 世界变速:单人世界以 0.01x–100x 运行,可选同步缩放声音音调和粒子。
  • 外部时钟 API:回放、录制类模组可以通过简单的 C API 驱动动画时钟,使暂停、跳转和倍速保持同步。
  • 双语:命令输出提供英文和简体中文。

命令

命令说明
/optipiston status显示活塞动画状态,以及请求/实际世界速度。
/optipiston piston on开启活塞动画。
/optipiston piston off关闭活塞动画。
/optipiston piston duration <ticks>设置动画时长,范围 2 到 4 游戏刻。
/optipiston piston redirect diagonal推动中被再次推动的方块斜向移动。
/optipiston piston redirect corner推动中被再次推动的方块先加速到位,再直角拐弯(默认)。
/optipiston piston lighting on移动中的方块按它搬运的方块计算光照(默认)。
/optipiston piston lighting off移动中的方块光照交给游戏原生处理。
/optipiston speed <value>设置世界速度,范围 0.01 到 100。
/optipiston speed next切换到下一个世界速度预设。
/optipiston speed prev切换到上一个世界速度预设。
/optipiston speed reset恢复正常速度(1x)。

活塞相关设置会写入配置文件。选择 Corner 时,方块在第一次推动结束前被另一个活塞推动,会先加速完成第一次推动,再直角拐弯,落位时间不变;同一轴向上的推动保持原样。世界变速仅在本地世界、没有其他玩家连接且没有其他模组驱动时钟时生效;未生效时 /optipiston status 会显示原因。

配置

配置文件位于 mods/OptiPiston/config/config.json,通过 Lip 更新时会保留。

{
    "version": 1,
    "locateName": "zh_CN",
    "piston": {
        "enabled": true,
        "durationTicks": 4.0,
        "redirectType": "Corner",
        "movingBlockLighting": true
    },
    "worldSpeed": {
        "presets": [0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.0, 4.0, 10.0, 20.0, 50.0, 100.0],
        "audio": true,
        "particles": true
    },
    "command": {
        "enabled": true,
        "command": "optipiston"
    }
}
键说明
piston.enabled开启或关闭活塞动画。
piston.durationTicks动画时长(游戏刻),范围 2 到 4。
piston.redirectType推动中被再次推动的方块的路径:Diagonal 或 Corner。
piston.movingBlockLighting移动中的方块按它搬运的方块计算光照。
worldSpeed.presetsspeed next / speed prev 循环的速度。
worldSpeed.audio声音播放随世界速度缩放。
worldSpeed.particles粒子随世界速度缩放。
command.command客户端命令名。

模组开发者

OptiPiston 导出名为 optipiston_get_api 的 C API。引入 include/optipiston/api.hpp 并在运行时查找,OptiPiston 即可保持为可选依赖:

#include "optipiston/api.hpp"

if (auto const* api = optipiston::Api::find()) {
    optipiston::ExternalClockLease clock{api};
    // Bump epoch on every jump: seek, clock switch, or export start.
    clock.push(tick, epoch);
    api->set_external_partial(partialTick);
}

API v1 还可以读写活塞动画开关和时长;设置值会限制在支持范围内并写入配置。

兼容性

Minecraft 版本线LeviLaminaLip 变体状态
26.1026.10.*client_mc26_10预发布,已在 0.3.0 之后的构建上实机测试
26.2026.20.*client_mc26_20预发布,已在 0.3.0 之后的构建上实机测试
26.3026.32.*client_mc26_30预发布,已在 0.3.1 之后的构建上实机测试
26.4026.40.*client_mc26_40预发布,已在 0.3.0 之后的构建上实机测试
26.5026.51.*client_mc26_50预发布,已在 0.3.2 上实机测试
26.6026.60.*client_mc26_60预发布,尚未实机测试

0.3.2 在所有版本线上功能一致,包括回缩带方块后活塞臂和活塞头发黑的光照修复;在 0.3.0 中该修复只在 26.50 上启用。只有一步是 26.50 和 26.60 特有的:这两个版本的游戏会在区块重建完成几帧之后才显示它,动画会等到这次交接完成。更早的版本线在测试中没有出现这种间隔。

OptiPiston 面向 Windows x64 平台的 Minecraft 基岩版,以纯客户端模组形式发布。所有版本线都在同一个发行版 v0.3.2 中发布,每条版本线一个资产 OptiPiston-mc<版本线>-windows-x64.zip,各自只能在所列 LeviLamina 版本上加载。目前已发布的都是预发布版本。

从源码构建

OptiPiston 使用 xmake、LLVM(clang-cl,CI 使用 LLVM 22)和 Git 在 Windows x64 上构建。--mc 选择兼容性中的版本线:26.10、26.20、26.30、26.40、26.50 或 26.60。26.10 改用 MSVC(Visual Studio 2022)构建,因为 LeviLamina 26.10 自带的 rapidjson 无法在当前 clang 下编译。

xmake f -c -y -p windows -a x64 -m release --target_type=client --mc=<版本线>
xmake -y
xmake build optipiston-tests
xmake run optipiston-tests

例如 --mc=26.20 构建 MC 26.20 / LeviLamina 26.20 版本线。构建产物输出到 bin/OptiPiston/;切换 --mc 需要重新配置(-c),并会覆盖该目录中之前的构建。

打包发布

包版本是 xmake.lua 中的 optipiston_version;模组清单中的版本会再加上版本线,例如 0.3.2-mc26.20。tooth.json 为每条版本线提供一个变体。配置时会同步其中的版本号,并在任一变体的 LeviLamina 版本范围或资产名与 xmake.lua 不一致时报错。Lip 按发布标签处的 tooth.json 安装,因此发布前要先提交它。Publish 工作流用同一个标签发布所有版本线:

  1. 修改 xmake.lua 中的 optipiston_version,运行 xmake f 同步 tooth.json,在 CHANGELOG.md 中添加 ## [<版本>] 章节,并推送到 main。

  2. 运行工作流:

    gh workflow run publish.yml
    
  3. 工作流为 main 打 v<版本> 标签(例如 v0.3.2),构建并测试 tooth.json 中的每条版本线,然后发布一个预发布版本,附带 CHANGELOG.md 中的说明和每条版本线各自的 OptiPiston-mc<版本线>-windows-x64.zip。任一版本线构建失败都不会发布。

已知限制

  • 26.30 和 26.60 尚未实机运行。它们依据 LeviLamina 头文件移植,可以构建并通过单元测试。
  • 各版本线通过不同的入口完成相同的步骤。在 26.20 以外的版本上,帧计数跟随 LevelRenderer::renderLevel,活塞臂的视觉进度只在绘制期间生效;26.10 在游戏分发渲染的位置拦截两个活塞渲染器。这些路径在移动开始或结束时可能有细微差异。
  • 已在本地世界和 Playback 回放中测试;多人服务器尚未验证。
  • 被活塞推动的方块在移动时可能明暗闪烁。原版同样如此,目前尚未修复。
  • 世界变速仅限单人,重启后不保留。

如需报告可复现问题,请附带日志和版本信息创建 Issue。

致谢

特别感谢 LeviLamina 的维护者与社区提供原生模组开发平台和工具,使 OptiPiston 得以实现。OptiPiston 源自 Playback 的活塞渲染工作,核心测试使用 doctest。

许可证

Copyright (C) 2026 wo555

OptiPiston 采用 GNU Affero 通用公共许可证 v3.0 发布。分发修改版本时必须继续使用 AGPL-3.0,并提供对应源代码。第三方组件保留各自许可证。

安裝 OptiPiston

執行端
  • 用戶端
平台
  • win-x64

在用戶端上,請透過以下方式安裝: LeviLauncher

從 GitHub 下載