Piston API
by jbredwards
Piston API lets block developers and modpack makers control how pistons push, pull and stick blocks, for Forge on 1.12.2.
What it does
Piston API gives blocks position- and world-sensitive interactions with pistons. A block can implement a small interface with one method that returns a push reaction for the piston and its surroundings, and a second interface that decides whether a block is sticky on a given side. Blocks that do not implement either interface fall back to the vanilla or Forge behavior. Tile entities can be made pushable, and pistons move them along with the blocks around them. Pistons also keep fluid states when they push, and chests can be set to stick to other pushed blocks.
Mod developers can use the API directly, while modpack developers can override a block's push or stick reaction through GroovyScript during postInit, without editing the original mod. A configurable push limit sets how many blocks a piston moves at once. Piston API is a Forge library and ships with examples for GroovyScript. Quark compatibility is listed as a supported integration, and the API is an addition to the game rather than a separate piston mod.
A server running it needs every connecting player to have it too. Files exist for Forge 1.12.2 only, and the latest file is 1.0.2 for 1.12.2, published 2024-04-14. The source code, an issue tracker and a wiki are public. The code is under All rights reserved, so the license does not allow redistribution as open source.
Key features
Push reaction interface
A block can implement one method that returns how a piston should treat it, depending on the piston and its position.
Stickiness interface
A second method decides whether a block sticks to a neighbor on a given side, with results for each neighbor tested.
Overrides for existing blocks
Push and stick results of a block can be replaced through GroovyScript during postInit, without changing the mod that adds the block.
Pushable tile entities
Tile entities can be pushed by pistons, and the API handles their movement with the blocks around them.
Configurable push limit
The number of blocks a piston can push at once is set in the config file.
Breaking sounds and particles
Blocks destroyed by pistons play their breaking sounds and particles.
Compatibility
Latest build for each game version and loader.
Only full game releases are shown. This mod publishes no snapshot builds.
How it compares
Fluid Interaction Tweaker is a Forge mod for 1.12.2 that is open source under the MIT License and runs on client and server, so it changes fluid behavior without a piston API. Advanced Jukebox is a Forge mod for 1.12.2 with All rights reserved, not open source, also on client and server. GroovyScript is a Forge mod for 1.12.2, open source under the GNU Lesser General Public License v3.0 only, and is the scripting tool that Piston API examples are written for.
| Mod | Loaders | Game versions | Environment | Updated |
|---|---|---|---|---|
| Piston API | Forge | 1.12.2 | Client and server | 2024-04-14 |
| Fluid Interaction Tweaker | Forge | 1.12.2 | Client and server | 2025-07-04 |
| Advanced Jukebox | Forge | 1.12.2 | Client and server | 2025-12-18 |
| GroovyScript | Forge | 1.12.2 | Client and server | 2026-04-14 |
Questions
Does Piston API need GroovyScript to work?
Which Minecraft versions does Piston API support?
Does the server need Piston API?
In the catalog
Piston API is one of 3,514 Library mods on ModsFinder, and one of 1,576 Library mods for Forge. 2,920 mods support Minecraft 1.12.2.
More from jbredwards
Similar mods
What the author says
API Features: Give custom blocks advanced piston interactions Piston API gives blocks a way to have position & world sensitive interactions with pistons! Mainly the block's pushability, and its stickiness.
Official listing
- Modrinth page
- modrinth.com/mod/piston-api
- Owner
- jbredwards
- Published
- 2023-06-16
- Updated on Modrinth
- 2024-04-14
- Facts verified
- 2026-10-15