Create_MechanicalPiston

A mechanical piston (regular or sticky). Exposes the same surface a player has — assemble/disassemble via right-click empty hand, the movement-mode scroll option — plus read-only state visible through goggles or block state.

Like the bearing, the piston is driven by kinetic input: positive rotation extends, negative retracts, zero stops. There's no setpoint either in vanilla or here. To program timed extensions, drive the piston via a Create_SequencedGearshift upstream and use its move() / setInstructions().

This peripheral covers both the regular and sticky variants — they share a block-entity class. Use isSticky to distinguish.

isAssembled()Source

Check whether the piston has assembled a contraption (i.e. is running).

Returns

1. boolean True if running.

assemble()Source

Assemble the piston's contraption. Equivalent to a player right-clicking the piston with an empty hand. No-op if already assembled.

disassemble()Source

Disassemble the piston's contraption.

getOffset()Source

Get the piston's current extension distance, in blocks. Continuous; visual position is interpolated to the current tick.

Returns

1. number The current offset in blocks.

getMovementSpeed()Source

Get the piston's current movement speed (blocks per tick). Signed: positive means extending, negative means retracting, 0 when stopped (either at a limit or when kinetic input is zero).

Returns

1. number The movement speed.

getMotionVector()Source

Get the piston's current motion vector in world frame. Magnitude equals getMovementSpeed; direction is the piston's facing axis (positive direction when extending).

Returns

1. { number... } A three-element list {x, y, z} in blocks/tick.

getState()Source

Get the piston's block-state machine position. One of retracted, moving, extended (matches the block-state state property).

Returns

1. string The state string.

isSticky()Source

Check whether this piston is the sticky variant (slimeball-converted). Sticky pistons pull their attached contraption back on retraction; non-sticky leave it where it ended up. Visually distinguished by the slime-coated head.

Returns

1. boolean True if sticky.

getMovementMode()Source

Get the piston's movement mode — what happens to the contraption blocks when motion stops.

One of:

• move_place — place blocks back on stop
• move_place_returned — place blocks back only when stopped at the starting offset
• move_never_place — never place blocks back (contraption stays as an entity)

Returns

1. string The mode string.

setMovementMode(mode)Source

Set the piston's movement mode. Matches the in-game scroll option.

Parameters

1. mode string move_place, move_place_returned, or move_never_place.

getLastAssemblyError()Source

Get the last assembly error message, or nil if the last attempt succeeded or no attempt has been made. Same text the goggles show on a piston whose last assembly failed.

Returns

1. string The error message, or nil.

getContraption()Source

Get everything known about the assembled contraption in one read: whether it's stalled, its current velocity (world-frame blocks/tick — a rate of change, not a location, so it's exempt from the local-only rule below), block count, seat count, hasBlockBreakers (can it destroy blocks in its path, e.g. a saw in cutting mode — relevant context for a stall: is it expected to grind through an obstacle or just sit blocked by one), local bounding box, the local position (an offset from the contraption's own anchor, not a world coordinate) and block id of every block making it up, its active mechanical implements (actors — drills, saws, harvesters, deployers, mechanical arms, mixers, each with disabled/stalled), every seat with whoever's riding it (seats), every entity being carried along without a seat — standing on an elevator cabin, walking a moving platform (riders) — every block supporting right-click interaction while riding (interactors), the actor types currently switched off via the Contraption Controls filter (disabledActorTypes), and mounted-storage counts. Both seats and riders are anonymous by design: an occupant is only isPlayer and its entity type, never a name or UUID.

Anything mounted so it protrudes in the contraption's own direction of travel — a drill facing fore or aft on a gantry carriage, say — will collide with whatever it's moving past on every block of motion, not just once. That reads as a stall repeating at a regular position interval rather than a single jam. On a gantry shaft, Create_GantryShaft.getAxis names that travel axis and shares this method's local coordinate frame exactly, so a block/actor position with only that axis nonzero is the one to suspect.

Returns

1. any... The contraption table, or nil plus a reason.

size()Source

Get the number of slots in the contraption's combined inventory — every mounted chest, barrel, depot, etc. summed together. 0 when unassembled.

Returns

1. number The slot count.

list()Source

List every non-empty slot in the contraption's combined inventory. Empty when unassembled.

Returns

1. { [number] = { [string] = any } } A map of slot to item detail.

getItemDetail(slot)Source

Get the item in a specific slot of the contraption's combined inventory.

Parameters

1. slot number The slot to inspect.

Returns

1. { [string] = any } The item detail, or nil if empty.

getItemLimit(slot)Source

Get the maximum number of items a slot in the contraption's combined inventory can hold.

Parameters

1. slot number The slot to inspect.

Returns

1. number The item limit.

tanks()Source

List every tank in the contraption's combined fluid storage. Empty when unassembled.

Returns

1. { [number] = { [string] = any } } A map of tank index to fluid detail.

getSelfId()Source

Get this block's id. Other peripherals' getSourceId or getSubnetworkAnchorId return this same id when they refer to this block.

Returns

1. string The block's id.

getSourceId()Source

Get the id of the block immediately driving this one, or nil if this block has no source.

Returns

1. string The parent's id, or nil.

getSubnetworkAnchorId()Source

Get the id of this block's speed-zone anchor — the gearshift / clutch / speed controller / generator that defines the start of this speed zone. Two blocks share an anchor iff they're in the same speed zone. A generator or split-shaft returns its own getSelfId.

Returns

1. string The anchor block's id, or nil.

getNetworkId()Source

Get the id of this block's kinetic network. Same value for every block on the same network regardless of how many speed zones lie between them. Nil if this block isn't on a network.

Returns

1. string The network id, or nil.

getKind()Source

Get this block's role on the kinetic graph: one of "generator", "split_shaft", "consumer", or "passthrough".

Returns

1. string The role string.

getSpeed()Source

Get the local rotational speed at this block. Signed; same value across a speed zone, changes across a split-shaft.

Returns

1. number The local speed.

hasSource()Source

Check whether this block is connected to a kinetic source.

Returns

1. boolean True if a source is connected.

isOverstressed()Source

Check whether the block's network is overstressed.

Returns

1. boolean True if overstressed.

getStressImpact()Source

Get the stress impact of this block on its network — how much stress it draws while running. Speed-dependent; zero for sources and pure conduit blocks. Matches the "Stress Impact" value shown by goggles.

Returns

1. number The stress impact.

getStressContribution()Source

Get this block's contribution to its network's stress capacity. Non-zero for sources only. Parallel to getStressImpact (per-block draw) and distinct from Create_Stressometer#getStressCapacity, which reports the network total.

Returns

1. number The per-block stress contribution.