{"url":"https://levimc.org/mods/github.com/wo55555/OptiPiston/","id":"github.com/wo55555/OptiPiston","name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","owner":"wo55555","logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png","repository":"https://github.com/wo55555/OptiPiston","issues":"https://github.com/wo55555/OptiPiston/issues","releases":"https://github.com/wo55555/OptiPiston/releases","stars":2,"downloads":401,"updated":"2026-11-12T18:49:40Z","published":"2026-09-29T17:22:23Z","created":"2026-09-29T16:27:06Z","license":"AGPL-3.0","side":["client"],"platform":["win-x64"],"gameVersions":["1.26.60","1.26.51","1.26.40","1.26.32","1.26.20","1.26.10"],"tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"latest":{"variant":"client_mc26_10","version":"0.3.2","install":"lip install github.com/wo55555/OptiPiston#client_mc26_10@0.3.2"},"readmes":[{"file":"README.md","lang":"en","text":"<div align=\"center\">\n  <img src=\"assets/icon.png\" alt=\"OptiPiston icon\" width=\"160\">\n  <h1>OptiPiston</h1>\n  <p><strong>Smooth pistons, adjustable time.</strong></p>\n  <p>A client-only LeviLamina mod for Minecraft Bedrock on Windows that smooths piston animation and adds singleplayer world speed control.</p>\n\n  <p>\n    <img src=\"https://img.shields.io/badge/version-v0.3.2-4c8bf5?style=flat-square\" alt=\"OptiPiston v0.3.2\">\n    <img src=\"https://img.shields.io/badge/Minecraft%20Bedrock-Windows%20x64-62b47a?style=flat-square\" alt=\"Minecraft Bedrock for Windows x64\">\n    <img src=\"https://img.shields.io/badge/LeviLamina-26.10%E2%80%9326.60-7b68ee?style=flat-square\" alt=\"LeviLamina 26.10 to 26.60\">\n    <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square\" alt=\"AGPL-3.0 license\"></a>\n  </p>\n\n  <p>\n    <a href=\"#quick-start\">Get started</a>\n    ·\n    <a href=\"https://github.com/wo55555/OptiPiston/releases\">Releases</a>\n    ·\n    <a href=\"CHANGELOG.md\">Changelog</a>\n    ·\n    <a href=\"https://github.com/wo55555/OptiPiston/issues\">Report an issue</a>\n    ·\n    <a href=\"README_ZH.md\">简体中文</a>\n  </p>\n</div>\n\n> [!WARNING]\n> OptiPiston is in early development. Configuration and API details may still change between releases.\n\nOptiPiston redraws piston arms and the blocks they push on a smooth, configurable timeline. It only changes what the client renders: native piston progress, block states, and redstone timing stay untouched. In singleplayer it can also speed up or slow down the whole world, including sounds and particles.\n\n## Quick Start\n\n> [!IMPORTANT]\n> Use a clean LeviLamina client instance when possible. Broad compatibility with other mods is not currently guaranteed.\n\n### Install with LeviLauncher (recommended)\n\n1. In LeviLauncher, select **Download**, find a Minecraft version listed in [Compatibility](#compatibility), and install it as an instance with the **LeviLamina** loader.\n2. Select **Launch**, choose that instance, then select **lip** under **Content Download**.\n3. Search for **OptiPiston** and open the package published by `wo55555`.\n4. Choose the latest version and the variant for your instance's Minecraft line from [Compatibility](#compatibility) (for example `client_mc26_20`), then select **Install**. Lip does not pick a variant from the installed LeviLamina version.\n5. Launch the game and open a world. Piston animation is on by default; use `/optipiston status` to check the current state.\n\n### Install with the Lip CLI\n\nRun this from the instance root, with `<variant>` taken from your instance's Minecraft line in [Compatibility](#compatibility):\n\n```powershell\nlip install github.com/wo55555/OptiPiston#<variant>@<version>\n\n# Example: Minecraft 26.20 / LeviLamina 26.20.*\nlip install github.com/wo55555/OptiPiston#client_mc26_20@<version>\n```\n\nThe variant is required. Installs from `0.1.2` or earlier used `#client`; uninstall that first with `lip uninstall github.com/wo55555/OptiPiston#client`, then install the new variant.\n\n### Manual Installation\n\nDownload `OptiPiston-mc<line>-windows-x64.zip` for your line (for example `OptiPiston-mc26.20-windows-x64.zip`) from the latest release, extract its `OptiPiston` directory into the instance's `mods` directory, and restart the client.\n\n## Features\n\n- **Smooth piston animation**: Arms and pushed blocks move over 2–4 game ticks, fractions included. Rendering only; game logic keeps its native timing.\n- **Clean hand-off**: A pushed block stays drawn until its real block has been re-meshed, which avoids gaps, ghost copies, and overlap where it lands.\n- **Stable heads**: Each cell draws exactly one piston head, and a piston that is itself being pushed follows its moving body.\n- **World speed**: Runs a singleplayer world at 0.01x–100x, with optional sound pitch and particle scaling.\n- **External clock API**: Replay and recording mods can drive the animation clock through a small C API, so pause, seek, and speed changes stay in sync.\n- **Bilingual**: English and Simplified Chinese command output.\n\n## Commands\n\n| Command                                | Description                                                                  |\n| -------------------------------------- | ---------------------------------------------------------------------------- |\n| `/optipiston status`                   | Show piston animation state and requested/applied world speed.               |\n| `/optipiston piston on`                | Turn piston animation on.                                                    |\n| `/optipiston piston off`               | Turn piston animation off.                                                   |\n| `/optipiston piston duration <ticks>`  | Set the animation length, from `2` to `4` game ticks.                        |\n| `/optipiston piston redirect diagonal` | A block pushed again mid-push moves diagonally.                              |\n| `/optipiston piston redirect corner`   | A block pushed again mid-push finishes its first push, then turns (default). |\n| `/optipiston piston lighting on`       | Light a moving block like the block it carries (default).                    |\n| `/optipiston piston lighting off`      | Leave a moving block's light to the game.                                    |\n| `/optipiston speed <value>`            | Set world speed, from `0.01` to `100`.                                       |\n| `/optipiston speed next`               | Switch to the next world speed preset.                                       |\n| `/optipiston speed prev`               | Switch to the previous world speed preset.                                   |\n| `/optipiston speed reset`              | Return to normal speed (`1x`).                                               |\n\nPiston settings are saved to the configuration file. With `Corner`, a block that another piston pushes before its first push has finished speeds up to finish that push, then turns at a right angle; it still lands at the same time. Pushes along the same axis always play as before. World speed applies only in a local world with no other players connected and while no other mod drives the clock; `/optipiston status` shows the reason when it is not applied.\n\n## Configuration\n\nThe configuration lives at `mods/OptiPiston/config/config.json` and is kept across Lip updates.\n\n```json\n{\n    \"version\": 1,\n    \"locateName\": \"zh_CN\",\n    \"piston\": {\n        \"enabled\": true,\n        \"durationTicks\": 4.0,\n        \"redirectType\": \"Corner\",\n        \"movingBlockLighting\": true\n    },\n    \"worldSpeed\": {\n        \"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],\n        \"audio\": true,\n        \"particles\": true\n    },\n    \"command\": {\n        \"enabled\": true,\n        \"command\": \"optipiston\"\n    }\n}\n```\n\n| Key                          | Description                                                    |\n| ---------------------------- | -------------------------------------------------------------- |\n| `piston.enabled`             | Turn piston animation on or off.                               |\n| `piston.durationTicks`       | Animation length in game ticks, from `2` to `4`.               |\n| `piston.redirectType`        | Path of a block pushed again mid-push: `Diagonal` or `Corner`. |\n| `piston.movingBlockLighting` | Light a moving block like the block it carries.                |\n| `worldSpeed.presets`         | Speeds cycled by `speed next` / `speed prev`.                  |\n| `worldSpeed.audio`           | Scale sound playback with world speed.                         |\n| `worldSpeed.particles`       | Scale particles with world speed.                              |\n| `command.command`            | Name of the client command.                                    |\n\n## For Mod Developers\n\nOptiPiston exports a C API named `optipiston_get_api`. Include [`include/optipiston/api.hpp`](include/optipiston/api.hpp) and look it up at runtime, so OptiPiston stays an optional dependency:\n\n```cpp\n#include \"optipiston/api.hpp\"\n\nif (auto const* api = optipiston::Api::find()) {\n    optipiston::ExternalClockLease clock{api};\n    // Bump epoch on every jump: seek, clock switch, or export start.\n    clock.push(tick, epoch);\n    api->set_external_partial(partialTick);\n}\n```\n\nAPI v1 also reads and writes the piston toggle and duration. Setters clamp to the supported range and persist to the configuration.\n\n## Compatibility\n\n| Minecraft line | LeviLamina | Lip variant      | Status                                   |\n| -------------- | ---------- | ---------------- | ---------------------------------------- |\n| 26.10          | `26.10.*`  | `client_mc26_10` | Prerelease; tested in game after `0.3.0` |\n| 26.20          | `26.20.*`  | `client_mc26_20` | Prerelease; tested in game after `0.3.0` |\n| 26.30          | `26.32.*`  | `client_mc26_30` | Prerelease; tested in game after `0.3.1` |\n| 26.40          | `26.40.*`  | `client_mc26_40` | Prerelease; tested in game after `0.3.0` |\n| 26.50          | `26.51.*`  | `client_mc26_50` | Prerelease; tested in game on `0.3.2`    |\n| 26.60          | `26.60.*`  | `client_mc26_60` | Prerelease; not yet tested in game       |\n\n`0.3.2` has the same features on every line, including the arm lighting fix (no black arm or head after retracting with a block); in `0.3.0` that fix is active on 26.50 only. One step is specific to 26.50 and 26.60: there the game shows a rebuilt chunk a few frames after building it, and the animation waits for that handover. The older lines showed no such gap in testing.\n\nEvery line ships in the same release, [`v0.3.2`](https://github.com/wo55555/OptiPiston/releases/tag/v0.3.2), as its own asset `OptiPiston-mc<line>-windows-x64.zip`; each build only loads on the listed LeviLamina version. All currently published releases are prereleases. OptiPiston targets Minecraft Bedrock for Windows x64 and is distributed as a client-only mod.\n\n## Build From Source\n\nOptiPiston builds on Windows x64 with xmake, LLVM (clang-cl, CI uses LLVM 22), and Git. `--mc` selects the release line from [Compatibility](#compatibility): `26.10`, `26.20`, `26.30`, `26.40`, `26.50`, or `26.60`. The `26.10` build uses MSVC (Visual Studio 2022) instead, because the rapidjson bundled with LeviLamina 26.10 does not compile under current clang.\n\n```powershell\nxmake f -c -y -p windows -a x64 -m release --target_type=client --mc=<line>\nxmake -y\nxmake build optipiston-tests\nxmake run optipiston-tests\n```\n\nFor example, `--mc=26.20` builds the MC 26.20 / LeviLamina 26.20 line. The mod is written to `bin/OptiPiston/`; switching `--mc` needs a fresh configure (`-c`) and overwrites the previous build there.\n\n### Packaging a Release\n\nThe package version is `optipiston_version` in `xmake.lua`; the mod manifest adds the line, for example `0.3.2-mc26.20`. `tooth.json` has one variant per line. Configuring syncs its version and fails if any variant's LeviLamina range or asset name does not match `xmake.lua`. Lip installs from the `tooth.json` at the release tag, so commit it before publishing. The **Publish** workflow releases every line under one tag:\n\n1. Bump `optipiston_version` in `xmake.lua`, run `xmake f` to sync `tooth.json`, add a `## [<version>]` section to `CHANGELOG.md`, and push to `main`.\n2. Run the workflow:\n\n   ```powershell\n   gh workflow run publish.yml\n   ```\n\n3. It tags `main` as `v<version>` (for example `v0.3.2`), builds and tests every line in `tooth.json`, and publishes one prerelease with its notes from `CHANGELOG.md` and an `OptiPiston-mc<line>-windows-x64.zip` per line. Nothing is published unless every line builds.\n\n## Known Limitations\n\n- 26.30 and 26.60 have not been run in game. They are ported from the LeviLamina headers, build, and pass the unit tests.\n- The lines reach the same steps through different entry points. Outside 26.20 the frame counter follows `LevelRenderer::renderLevel` and the arm's visual progress applies only while the arm is drawn; 26.10 intercepts both piston renderers where the game dispatches them. These paths may differ slightly at the start or end of a move.\n- Tested in local worlds and Playback replays; multiplayer servers are not yet verified.\n- Blocks moved by a piston can flicker darker while moving. Vanilla does the same; it is not fixed yet.\n- World speed is singleplayer only and does not persist across restarts.\n\n[Open an issue](https://github.com/wo55555/OptiPiston/issues) with logs and version details to report a reproducible problem.\n\n## Acknowledgements\n\nSpecial thanks to the [LeviLamina](https://github.com/LiteLDev/LeviLamina) maintainers and community for the native modding platform and tooling that make OptiPiston possible. OptiPiston grew out of the piston rendering work in [Playback](https://github.com/wo55555/Playback), and its core tests use [doctest](https://github.com/doctest/doctest).\n\n## License\n\nCopyright (C) 2026 [wo555](https://github.com/wo55555)\n\nOptiPiston is released under the [GNU Affero General Public License v3.0](LICENSE). Distributed modifications must remain under AGPL-3.0 and provide their corresponding source code. Third-party components retain their own licenses.\n"},{"file":"README_ZH.md","lang":"zh-Hans","text":"<div align=\"center\">\n  <img src=\"assets/icon.png\" alt=\"OptiPiston 图标\" width=\"160\">\n  <h1>OptiPiston</h1>\n  <p><strong>活塞更顺滑，时间可调节。</strong></p>\n  <p>面向 Windows LeviLamina 的 Minecraft 基岩版纯客户端模组，提供平滑活塞动画和单人世界变速。</p>\n\n  <p>\n    <img src=\"https://img.shields.io/badge/version-v0.3.2-4c8bf5?style=flat-square\" alt=\"OptiPiston v0.3.2\">\n    <img src=\"https://img.shields.io/badge/Minecraft%20Bedrock-Windows%20x64-62b47a?style=flat-square\" alt=\"Windows x64 Minecraft 基岩版\">\n    <img src=\"https://img.shields.io/badge/LeviLamina-26.10%E2%80%9326.60-7b68ee?style=flat-square\" alt=\"LeviLamina 26.10 至 26.60\">\n    <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square\" alt=\"AGPL-3.0 许可证\"></a>\n  </p>\n\n  <p>\n    <a href=\"#快速开始\">开始使用</a>\n    ·\n    <a href=\"https://github.com/wo55555/OptiPiston/releases\">发行版本</a>\n    ·\n    <a href=\"CHANGELOG.md\">更新日志</a>\n    ·\n    <a href=\"https://github.com/wo55555/OptiPiston/issues\">问题反馈</a>\n    ·\n    <a href=\"README.md\">English</a>\n  </p>\n</div>\n\n> [!WARNING]\n> OptiPiston 目前处于早期开发阶段，配置和 API 细节在版本之间仍可能变化。\n\nOptiPiston 按可配置的平滑时间线重新绘制活塞臂及其推动的方块。它只改变客户端的渲染结果，原生活塞进度、方块状态和红石时序都保持不变。在单人世界中，它还能整体加快或放慢世界运行速度，声音和粒子会随之变化。\n\n## 快速开始\n\n> [!IMPORTANT]\n> 建议尽量使用干净的 LeviLamina 客户端实例；目前不保证与其他模组广泛兼容。\n\n### 使用 LeviLauncher 安装（推荐）\n\n1. 在 LeviLauncher 左侧边栏选择 **Download（下载）**，找到[兼容性](#兼容性)中所列的 Minecraft 版本，创建使用 **LeviLamina** 加载器的实例。\n2. 选择 **Launch（启动）**，选中该实例，然后在**内容下载**区域选择 **lip**。\n3. 搜索 **OptiPiston**，打开由 `wo55555` 发布的软件包。\n4. 选择最新版本，并按[兼容性](#兼容性)选择与实例 Minecraft 版本线对应的变体（例如 `client_mc26_20`），然后点击**安装**。Lip 不会根据已安装的 LeviLamina 版本自动选择变体。\n5. 启动游戏并进入世界。活塞动画默认开启，可用 `/optipiston status` 查看当前状态。\n\n### 使用 Lip 命令行安装\n\n在实例根目录运行下面的命令，`<variant>` 取自[兼容性](#兼容性)中与实例版本线对应的变体：\n\n```powershell\nlip install github.com/wo55555/OptiPiston#<variant>@<version>\n\n# 示例：Minecraft 26.20 / LeviLamina 26.20.*\nlip install github.com/wo55555/OptiPiston#client_mc26_20@<version>\n```\n\n必须带上变体。`0.1.2` 及更早版本使用 `#client` 安装；请先运行 `lip uninstall github.com/wo55555/OptiPiston#client` 卸载，再安装新变体。\n\n### 手动安装\n\n从最新发行版本下载对应版本线的 `OptiPiston-mc<版本线>-windows-x64.zip`（例如 `OptiPiston-mc26.20-windows-x64.zip`），将其中的 `OptiPiston` 目录解压到实例的 `mods` 目录，然后重启客户端。\n\n## 功能\n\n- **平滑活塞动画**：活塞臂和被推方块在 2–4 游戏刻内完成移动，支持小数。仅影响渲染，游戏逻辑保持原生时序。\n- **平滑衔接**：被推方块在真实方块完成重新建网格前持续绘制，避免落位时出现空洞、重影或重叠。\n- **稳定的活塞头**：每格只绘制一个活塞头；被推动的活塞会随其移动中的机身一起绘制。\n- **世界变速**：单人世界以 0.01x–100x 运行，可选同步缩放声音音调和粒子。\n- **外部时钟 API**：回放、录制类模组可以通过简单的 C API 驱动动画时钟，使暂停、跳转和倍速保持同步。\n- **双语**：命令输出提供英文和简体中文。\n\n## 命令\n\n| 命令                                   | 说明                                                   |\n| -------------------------------------- | ------------------------------------------------------ |\n| `/optipiston status`                   | 显示活塞动画状态，以及请求/实际世界速度。              |\n| `/optipiston piston on`                | 开启活塞动画。                                         |\n| `/optipiston piston off`               | 关闭活塞动画。                                         |\n| `/optipiston piston duration <ticks>`  | 设置动画时长，范围 `2` 到 `4` 游戏刻。                 |\n| `/optipiston piston redirect diagonal` | 推动中被再次推动的方块斜向移动。                       |\n| `/optipiston piston redirect corner`   | 推动中被再次推动的方块先加速到位，再直角拐弯（默认）。 |\n| `/optipiston piston lighting on`       | 移动中的方块按它搬运的方块计算光照（默认）。           |\n| `/optipiston piston lighting off`      | 移动中的方块光照交给游戏原生处理。                     |\n| `/optipiston speed <value>`            | 设置世界速度，范围 `0.01` 到 `100`。                   |\n| `/optipiston speed next`               | 切换到下一个世界速度预设。                             |\n| `/optipiston speed prev`               | 切换到上一个世界速度预设。                             |\n| `/optipiston speed reset`              | 恢复正常速度（`1x`）。                                 |\n\n活塞相关设置会写入配置文件。选择 `Corner` 时，方块在第一次推动结束前被另一个活塞推动，会先加速完成第一次推动，再直角拐弯，落位时间不变；同一轴向上的推动保持原样。世界变速仅在本地世界、没有其他玩家连接且没有其他模组驱动时钟时生效；未生效时 `/optipiston status` 会显示原因。\n\n## 配置\n\n配置文件位于 `mods/OptiPiston/config/config.json`，通过 Lip 更新时会保留。\n\n```json\n{\n    \"version\": 1,\n    \"locateName\": \"zh_CN\",\n    \"piston\": {\n        \"enabled\": true,\n        \"durationTicks\": 4.0,\n        \"redirectType\": \"Corner\",\n        \"movingBlockLighting\": true\n    },\n    \"worldSpeed\": {\n        \"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],\n        \"audio\": true,\n        \"particles\": true\n    },\n    \"command\": {\n        \"enabled\": true,\n        \"command\": \"optipiston\"\n    }\n}\n```\n\n| 键                           | 说明                                                   |\n| ---------------------------- | ------------------------------------------------------ |\n| `piston.enabled`             | 开启或关闭活塞动画。                                   |\n| `piston.durationTicks`       | 动画时长（游戏刻），范围 `2` 到 `4`。                  |\n| `piston.redirectType`        | 推动中被再次推动的方块的路径：`Diagonal` 或 `Corner`。 |\n| `piston.movingBlockLighting` | 移动中的方块按它搬运的方块计算光照。                   |\n| `worldSpeed.presets`         | `speed next` / `speed prev` 循环的速度。               |\n| `worldSpeed.audio`           | 声音播放随世界速度缩放。                               |\n| `worldSpeed.particles`       | 粒子随世界速度缩放。                                   |\n| `command.command`            | 客户端命令名。                                         |\n\n## 模组开发者\n\nOptiPiston 导出名为 `optipiston_get_api` 的 C API。引入 [`include/optipiston/api.hpp`](include/optipiston/api.hpp) 并在运行时查找，OptiPiston 即可保持为可选依赖：\n\n```cpp\n#include \"optipiston/api.hpp\"\n\nif (auto const* api = optipiston::Api::find()) {\n    optipiston::ExternalClockLease clock{api};\n    // Bump epoch on every jump: seek, clock switch, or export start.\n    clock.push(tick, epoch);\n    api->set_external_partial(partialTick);\n}\n```\n\nAPI v1 还可以读写活塞动画开关和时长；设置值会限制在支持范围内并写入配置。\n\n## 兼容性\n\n| Minecraft 版本线 | LeviLamina | Lip 变体         | 状态                                      |\n| ---------------- | ---------- | ---------------- | ----------------------------------------- |\n| 26.10            | `26.10.*`  | `client_mc26_10` | 预发布，已在 `0.3.0` 之后的构建上实机测试 |\n| 26.20            | `26.20.*`  | `client_mc26_20` | 预发布，已在 `0.3.0` 之后的构建上实机测试 |\n| 26.30            | `26.32.*`  | `client_mc26_30` | 预发布，已在 `0.3.1` 之后的构建上实机测试 |\n| 26.40            | `26.40.*`  | `client_mc26_40` | 预发布，已在 `0.3.0` 之后的构建上实机测试 |\n| 26.50            | `26.51.*`  | `client_mc26_50` | 预发布，已在 `0.3.2` 上实机测试           |\n| 26.60            | `26.60.*`  | `client_mc26_60` | 预发布，尚未实机测试                      |\n\n`0.3.2` 在所有版本线上功能一致，包括回缩带方块后活塞臂和活塞头发黑的光照修复；在 `0.3.0` 中该修复只在 26.50 上启用。只有一步是 26.50 和 26.60 特有的：这两个版本的游戏会在区块重建完成几帧之后才显示它，动画会等到这次交接完成。更早的版本线在测试中没有出现这种间隔。\n\nOptiPiston 面向 Windows x64 平台的 Minecraft 基岩版，以纯客户端模组形式发布。所有版本线都在同一个发行版 [`v0.3.2`](https://github.com/wo55555/OptiPiston/releases/tag/v0.3.2) 中发布，每条版本线一个资产 `OptiPiston-mc<版本线>-windows-x64.zip`，各自只能在所列 LeviLamina 版本上加载。目前已发布的都是预发布版本。\n\n## 从源码构建\n\nOptiPiston 使用 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 下编译。\n\n```powershell\nxmake f -c -y -p windows -a x64 -m release --target_type=client --mc=<版本线>\nxmake -y\nxmake build optipiston-tests\nxmake run optipiston-tests\n```\n\n例如 `--mc=26.20` 构建 MC 26.20 / LeviLamina 26.20 版本线。构建产物输出到 `bin/OptiPiston/`；切换 `--mc` 需要重新配置（`-c`），并会覆盖该目录中之前的构建。\n\n### 打包发布\n\n包版本是 `xmake.lua` 中的 `optipiston_version`；模组清单中的版本会再加上版本线，例如 `0.3.2-mc26.20`。`tooth.json` 为每条版本线提供一个变体。配置时会同步其中的版本号，并在任一变体的 LeviLamina 版本范围或资产名与 `xmake.lua` 不一致时报错。Lip 按发布标签处的 `tooth.json` 安装，因此发布前要先提交它。**Publish** 工作流用同一个标签发布所有版本线：\n\n1. 修改 `xmake.lua` 中的 `optipiston_version`，运行 `xmake f` 同步 `tooth.json`，在 `CHANGELOG.md` 中添加 `## [<版本>]` 章节，并推送到 `main`。\n2. 运行工作流：\n\n   ```powershell\n   gh workflow run publish.yml\n   ```\n\n3. 工作流为 `main` 打 `v<版本>` 标签（例如 `v0.3.2`），构建并测试 `tooth.json` 中的每条版本线，然后发布一个预发布版本，附带 `CHANGELOG.md` 中的说明和每条版本线各自的 `OptiPiston-mc<版本线>-windows-x64.zip`。任一版本线构建失败都不会发布。\n\n## 已知限制\n\n- 26.30 和 26.60 尚未实机运行。它们依据 LeviLamina 头文件移植，可以构建并通过单元测试。\n- 各版本线通过不同的入口完成相同的步骤。在 26.20 以外的版本上，帧计数跟随 `LevelRenderer::renderLevel`，活塞臂的视觉进度只在绘制期间生效；26.10 在游戏分发渲染的位置拦截两个活塞渲染器。这些路径在移动开始或结束时可能有细微差异。\n- 已在本地世界和 Playback 回放中测试；多人服务器尚未验证。\n- 被活塞推动的方块在移动时可能明暗闪烁。原版同样如此，目前尚未修复。\n- 世界变速仅限单人，重启后不保留。\n\n如需报告可复现问题，请附带日志和版本信息[创建 Issue](https://github.com/wo55555/OptiPiston/issues)。\n\n## 致谢\n\n特别感谢 [LeviLamina](https://github.com/LiteLDev/LeviLamina) 的维护者与社区提供原生模组开发平台和工具，使 OptiPiston 得以实现。OptiPiston 源自 [Playback](https://github.com/wo55555/Playback) 的活塞渲染工作，核心测试使用 [doctest](https://github.com/doctest/doctest)。\n\n## 许可证\n\nCopyright (C) 2026 [wo555](https://github.com/wo55555)\n\nOptiPiston 采用 [GNU Affero 通用公共许可证 v3.0](LICENSE) 发布。分发修改版本时必须继续使用 AGPL-3.0，并提供对应源代码。第三方组件保留各自许可证。\n"}],"gallery":[],"versions":[{"version":"0.3.2","prerelease":true,"released":"2026-11-12T18:49:40Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.3.2","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.3.2/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client_mc26_10":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.10.*"}}],"client_mc26_20":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.20.*"}}],"client_mc26_30":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.32.*"}}],"client_mc26_40":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.40.*"}}],"client_mc26_50":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.51.*"}}],"client_mc26_60":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.60.*"}}]}},{"version":"0.3.1","prerelease":true,"released":"2026-11-11T06:35:44Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.3.1","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.3.1/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client_mc26_10":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.10.*"}}],"client_mc26_20":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.20.*"}}],"client_mc26_30":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.32.*"}}],"client_mc26_40":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.40.*"}}],"client_mc26_50":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.51.*"}}],"client_mc26_60":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.60.*"}}]}},{"version":"0.3.0","prerelease":true,"released":"2026-11-10T06:06:09Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.3.0","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.3.0/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client_mc26_10":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.10.*"}}],"client_mc26_20":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.20.*"}}],"client_mc26_30":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.32.*"}}],"client_mc26_40":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.40.*"}}],"client_mc26_50":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.51.*"}}],"client_mc26_60":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.60.*"}}]}},{"version":"0.2.0","prerelease":true,"released":"2026-10-22T05:45:09Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.2.0","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.2.0/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client_mc26_10":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.10.*"}}],"client_mc26_20":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.20.*"}}],"client_mc26_30":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.32.*"}}],"client_mc26_40":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.40.*"}}],"client_mc26_50":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.51.*"}}]}},{"version":"0.1.4","prerelease":true,"released":"2026-10-01T14:18:26Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.4","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.4/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client_mc26_10":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.10.*"}}],"client_mc26_20":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.20.*"}}],"client_mc26_30":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.32.*"}}],"client_mc26_40":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.40.*"}}],"client_mc26_50":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.51.*"}}]}},{"version":"0.1.3","prerelease":true,"released":"2026-10-01T09:18:05Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.3","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.3/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client_mc26_10":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.10.*"}}],"client_mc26_20":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.20.*"}}],"client_mc26_30":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.32.*"}}],"client_mc26_40":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.40.*"}}],"client_mc26_50":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.51.*"}}]}},{"version":"0.1.2-mc26.50","prerelease":true,"released":"2026-09-30T13:32:32Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.2-mc26.50","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.2-mc26.50/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.51.*"}}]}},{"version":"0.1.2-mc26.40","prerelease":true,"released":"2026-09-30T13:29:51Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.2-mc26.40","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.2-mc26.40/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.40.*"}}]}},{"version":"0.1.2-mc26.30","prerelease":true,"released":"2026-09-30T13:30:51Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.2-mc26.30","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.2-mc26.30/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.32.*"}}]}},{"version":"0.1.2-mc26.20","prerelease":true,"released":"2026-09-30T13:29:34Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.2-mc26.20","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.2-mc26.20/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.20.*"}}]}},{"version":"0.1.2-mc26.10","prerelease":true,"released":"2026-09-30T13:29:04Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.2-mc26.10","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.2-mc26.10/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.10.*"}}]}},{"version":"0.1.1-mc26.50","prerelease":true,"released":"2026-09-30T03:51:56Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.1-mc26.50","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.1-mc26.50/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.51.*"}}]}},{"version":"0.1.1-mc26.40","prerelease":true,"released":"2026-09-30T03:52:00Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.1-mc26.40","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.1-mc26.40/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.40.*"}}]}},{"version":"0.1.1-mc26.30","prerelease":true,"released":"2026-09-30T03:52:09Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.1-mc26.30","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.1-mc26.30/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.32.*"}}]}},{"version":"0.1.1-mc26.20","prerelease":true,"released":"2026-09-30T03:51:06Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.1-mc26.20","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.1-mc26.20/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.20.*"}}]}},{"version":"0.1.1-mc26.10","prerelease":true,"released":"2026-09-30T03:51:59Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.1-mc26.10","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.1-mc26.10/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.10.*"}}]}},{"version":"0.1.0-mc26.50","prerelease":true,"released":"2026-09-29T18:22:07Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.0-mc26.50","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.0-mc26.50/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.51.*"}}]}},{"version":"0.1.0-mc26.40","prerelease":true,"released":"2026-09-29T18:10:32Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.0-mc26.40","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.0-mc26.40/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.40.*"}}]}},{"version":"0.1.0-mc26.30","prerelease":true,"released":"2026-09-29T18:02:35Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.0-mc26.30","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.0-mc26.30/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.32.*"}}]}},{"version":"0.1.0-mc26.20","prerelease":true,"released":"2026-09-29T17:26:19Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.0-mc26.20","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.0-mc26.20/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.20.*"}}]}},{"version":"0.1.0-mc26.10","prerelease":true,"released":"2026-09-29T17:22:23Z","releaseUrl":"https://github.com/wo55555/OptiPiston/releases/tag/v0.1.0-mc26.10","manifestUrl":"https://github.com/wo55555/OptiPiston/blob/v0.1.0-mc26.10/tooth.json","info":{"name":"OptiPiston","description":"Client-side smooth piston animation with configurable duration and singleplayer world speed.","tags":["platform:levilamina","type:mod","minecraft-bedrock","piston","redstone"],"logo":"https://raw.githubusercontent.com/wo55555/OptiPiston/main/assets/icon.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.10.*"}}]}}],"dependencies":{"github.com/liteldev/levilamina":{"id":"github.com/LiteLDev/LeviLamina","name":"LeviLamina","owner":"LiteLDev","url":"https://levimc.org/mods/github.com/LiteLDev/LeviLamina/"}},"requiredBy":[]}