OptiPiston
作者 wo55555
Client-side smooth piston animation with configurable duration and singleplayer world speed.
- 401 次下載
- 2 個星標
- 更新於
- 技術與紅石piston redstone
README0.3.2
OptiPiston
活塞更顺滑,时间可调节。
面向 Windows LeviLamina 的 Minecraft 基岩版纯客户端模组,提供平滑活塞动画和单人世界变速。
Warning
OptiPiston 目前处于早期开发阶段,配置和 API 细节在版本之间仍可能变化。
OptiPiston 按可配置的平滑时间线重新绘制活塞臂及其推动的方块。它只改变客户端的渲染结果,原生活塞进度、方块状态和红石时序都保持不变。在单人世界中,它还能整体加快或放慢世界运行速度,声音和粒子会随之变化。
快速开始
Important
建议尽量使用干净的 LeviLamina 客户端实例;目前不保证与其他模组广泛兼容。
使用 LeviLauncher 安装(推荐)
- 在 LeviLauncher 左侧边栏选择 Download(下载),找到兼容性中所列的 Minecraft 版本,创建使用 LeviLamina 加载器的实例。
- 选择 Launch(启动),选中该实例,然后在内容下载区域选择 lip。
- 搜索 OptiPiston,打开由
wo55555发布的软件包。 - 选择最新版本,并按兼容性选择与实例 Minecraft 版本线对应的变体(例如
client_mc26_20),然后点击安装。Lip 不会根据已安装的 LeviLamina 版本自动选择变体。 - 启动游戏并进入世界。活塞动画默认开启,可用
/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.presets | speed 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 版本线 | LeviLamina | Lip 变体 | 状态 |
|---|---|---|---|
| 26.10 | 26.10.* | client_mc26_10 | 预发布,已在 0.3.0 之后的构建上实机测试 |
| 26.20 | 26.20.* | client_mc26_20 | 预发布,已在 0.3.0 之后的构建上实机测试 |
| 26.30 | 26.32.* | client_mc26_30 | 预发布,已在 0.3.1 之后的构建上实机测试 |
| 26.40 | 26.40.* | client_mc26_40 | 预发布,已在 0.3.0 之后的构建上实机测试 |
| 26.50 | 26.51.* | client_mc26_50 | 预发布,已在 0.3.2 上实机测试 |
| 26.60 | 26.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 工作流用同一个标签发布所有版本线:
-
修改
xmake.lua中的optipiston_version,运行xmake f同步tooth.json,在CHANGELOG.md中添加## [<版本>]章节,并推送到main。 -
运行工作流:
gh workflow run publish.yml -
工作流为
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,并提供对应源代码。第三方组件保留各自许可证。