Create_GantryShaft

A gantry shaft — the rail along which a gantry carriage slides. The natural place to wire kinetic input, and the right peripheral for the whole gantry: the carriage block is consumed into a contraption entity the moment the gantry moves, so a shaft is the only mount point that survives operation.

Driving programmatically goes via an upstream Create_SequencedGearshift's move(distance), just like for pistons. This peripheral deliberately exposes no setpoint — a gantry is positioned by asking the drive for a distance and then observing the rail, not by commanding a coordinate.

Positions are rail indices measured from the start shaft: whole numbers while parked, fractional while moving. That origin shifts if a player extends the rail at the start end, so store waypoints in world space via getRailStart and convert.

Events

• gantry_departed(position) — the carriage assembled and began moving
• gantry_arrived(position) — it stopped and became a block again
• gantry_stalled(position) — it is blocked and will not proceed
• gantry_assembly_failed(error) — an assembly attempt failed

getPart()Source

Get this shaft's role in the rail. One of start, middle, end, single.

Returns

1. string The part string.

getAxis()Source

Get the rail's axis.

Gantry contraptions never rotate — applyRotation is a hard no-op — so this is also the coordinate axis getContraption's blocks/actors positions live in, with no transform needed to compare them. A block or actor whose position has this axis nonzero and both other axes at 0 sits directly in line with the rail: since a rail is a contiguous run of shaft blocks immediately beside the carriage's whole path, anything protruding on this axis will collide with a shaft block every time the carriage advances — visible as a stall repeating roughly once per block, not a one-off jam. Off-axis placement (as the carriage's own attachment point already is) is safe.

Returns

1. string The axis as "x", "y", or "z".

isPowered()Source

Check whether this shaft is currently powered (redstone).

Powering does not reverse the carriage. A powered gantry shaft stops translating its carriage and instead transmits rotation into the carriage's output shaft. A powered rail will neither start a carriage (canAssembleOn is false) nor keep one moving — an in-flight contraption disassembles where it stands.

Power spreads along the whole rail: powering any shaft powers every same-facing shaft on the axis.

Returns

1. boolean True if powered.

getMovementSpeed()Source

Get the linear speed at which a carriage on this rail will move.

Signed: positive moves the carriage along the rail's facing direction, negative moves it opposite. Derived from kinetic input alone — redstone is not a factor, see isPowered. 0 when the shaft is stalled or has no kinetic source.

Clamped upstream to ±0.49 blocks per tick, so a sufficiently fast gantry saturates and this stops tracking getSpeed().

Returns

1. number The movement speed in blocks per tick.

canAssembleOn()Source

Check whether a carriage may currently assemble and move on this shaft.

Answers for this shaft, not the rail, and the two ends disagree by design: a start shaft needs positive movement speed, an end shaft negative, a middle shaft any non-zero, and a single shaft can never assemble at all. Always false while the rail is powered.

Returns

1. boolean True if assembly conditions are met here.

getRailLength()Source

Get the total length of the rail this shaft is part of (number of contiguous same-facing shaft blocks along the rail axis).

Returns

1. number The rail length in blocks.

getRailIndex()Source

Get this shaft's index along the rail, counted from the start end. The start shaft is index 0; the end shaft is getRailLength() - 1.

Returns

1. number The 0-based index.

getRailStart()Source

Get the world position of the rail's start shaft — the origin every rail index is measured from.

Exposed so positions can be anchored in world space: the origin moves if a player extends the rail at the start end, which would silently shift every index recorded before.

Returns

1. { [string] = any } A table with x, y and z.

getCarriage()Source

Get everything known about this rail's carriage in one read.

Preferred over the individual getters in a control loop: all fields come from a single observation, so they cannot disagree the way separate polls straddling a tick boundary can.

Fields: position (rail index, fractional while moving), state (see getState), stalled, moving, and where applicable id, error and remaining.

Returns

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

getState()Source

Get the rail's state.

One of empty (no carriage), parked, moving, stalled (assembled but blocked), or failed (present, but its last assembly attempt errored — see getLastAssemblyError).

Returns

1. string The state string.

getCarriagePosition()Source

Get the carriage's index along the rail, or nil if there is none.

Same units as getRailIndex — 0 at the start end, getRailLength() - 1 at the end. Fractional while the carriage is moving, so compare with a tolerance rather than for equality.

Returns

1. number The carriage's rail index, or nil.

hasCarriage()Source

Check whether a carriage is currently on this rail, parked or moving.

Returns

1. boolean True if a carriage is found.

getCarriageId()Source

Get the id of the carriage block attached to this rail, or nil.

Same opaque-token flavor as getSelfId on a peripheral wrapping the carriage. Nil while the gantry is moving — there is no carriage block then, only a contraption entity.

Returns

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

isAssembled()Source

Check whether this rail's carriage is currently an assembled contraption — that is, moving or stalled rather than sitting as a block.

Returns

1. boolean True if assembled.

isStalled()Source

Check whether this rail's carriage is stalled — assembled, but blocked by the world or another contraption and making no progress.

Returns

1. boolean True if stalled.

getRemainingMovement()Source

Get how far an in-flight sequenced movement still has to travel, in blocks, or nil if the carriage is not moving under a sequenced instruction.

This is the budget a Create_SequencedGearshift's move(distance) handed the carriage on assembly, decremented as it travels.

Returns

1. number The remaining distance in blocks, or nil.

getLastAssemblyError()Source

Get the carriage's last assembly error message, or nil if its last attempt succeeded, none has been made, or there is no carriage.

Same text the goggles show on a carriage whose last assembly failed.

Returns

1. string The error message, or nil.

disassemble()Source

Stop the carriage immediately, dropping its contraption back into the world where it stands.

The emergency stop a Lua program otherwise cannot express — the only alternative is cutting rotation upstream and waiting. This does not move the carriage back; it disassembles in place, mid-rail if need be.

Returns

1. any... True, or nil plus a reason if there was nothing to stop.

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.