movementEngineMk2 Documentation

A turtle movement engine for Minecraft Computercraft that provides advanced movement capabilities with relative and absolute positioning, coordinate system management, and GPS orientation.

Overview

The movementEngineMk2 is a Lua module designed to simplify turtle movement in Minecraft Computercraft. It provides:

• Relative and absolute movement in 3D space (x, y, z)
• Angle-based rotation and facing
• Coordinate system management with nested centers
• GPS-based orientation for recovery after crashes
• Transformation matrices for coordinate calculations

Coordinate System

The engine uses an arbitrary coordinate system with a fixed orientation reference:

• x-axis: Forward/backward direction (positive = forward)
• y-axis: Up/down direction (positive = up)
• z-axis: Right/left direction (positive = right)

Relative to the starting point of the turtle:

• x is forwards
• y is up
• z is right

Important: Movement coordinates are always interpreted relative to the fixed coordinate system's orientation, not the turtle's current physical facing direction. The turtle's facing (angle) does not affect how movement coordinates are interpreted.

The coordinate system can be reset using setCenter(), allowing you to define new origins for movement calculations.

API Reference

Basic Movement Functions

down()

Moves the turtle down one block.

up()

Moves the turtle up one block.

forward()

Moves the turtle forward one block.

left()

Turns the turtle left 90 degrees.

right()

Turns the turtle right 90 degrees.

Movement Functions

move(x, y, z)

Moves the turtle relative to its current position.

Parameters:

• x (number): Movement along x-axis (forward/backward)
• y (number): Movement along y-axis (up/down)
• z (number): Movement along z-axis (right/left)

Example:

absMove(x, y, z)

Moves the turtle to absolute coordinates.

Parameters:

• x (number, optional): Absolute x position (defaults to current x)
• y (number, optional): Absolute y position (defaults to current y)
• z (number, optional): Absolute z position (defaults to current z)

Example:

linearMove(scalar, forefunc)

Moves the turtle linearly in the forward direction.

Parameters:

• scalar (number): Number of blocks to move
• forefunc (function): Function to call for each forward move (typically engine.forward)

Note: Internal function, typically not called directly.

zMove(scalar, forefunc)

Moves the turtle in the z-axis direction.

Parameters:

• scalar (number): Number of blocks to move
• forefunc (function): Function to call for each move

Note: Internal function, typically not called directly.

Rotation Functions

turn(angle)

Turns the turtle by the specified angle in degrees.

Parameters:

• angle (number): Angle to turn (positive = right, negative = left)

Example:

faceAngle(angle)

Faces the turtle toward the specified angle.

Parameters:

• angle (number): Target angle (0, 90, 180, or 270)

Example:

frontFace()

Faces the turtle forward (0 degrees).

rearFace()

Faces the turtle backward (180 degrees).

Position Management

setPosition(x, y, z)

Sets the absolute position coordinates.

Parameters:

• x (number, optional): X coordinate (defaults to current x)
• y (number, optional): Y coordinate (defaults to current y)
• z (number, optional): Z coordinate (defaults to current z)

Example:

setCenter(x, y, z, angle)

Sets a new coordinate center, creating a nested coordinate system.

Parameters:

• x (number, optional): X coordinate of new center (defaults to current x)
• y (number, optional): Y coordinate of new center (defaults to current y)
• z (number, optional): Z coordinate of new center (defaults to current z)
• angle (number, optional): Facing angle of the new center (defaults to 0)

Important: The angle parameter defines the orientation of the new coordinate system. This creates a local coordinate system where the x-axis aligns with the specified angle. For example, if you set a center with angle 180, positive x steps in this local system will move in the backward direction relative to the original coordinate system.

Example:

popCenter()

Reverts to the previous coordinate center, undoing the most recent setCenter() call.

Note: The position stack is internal and should not be manipulated manually.

Example:

orient()

Orients the turtle using GPS to recover position and angle after a crash or shutdown.

Functionality:

1. Uses GPS to determine absolute position
2. Finds a solid block below to establish reference
3. Aligns with cardinal directions (0, 90, 180, 270 degrees)
4. Resets internal position tracking

Use Case: Essential for recovering from crashes where the turtle's internal state is lost.

Note: Requires a working GPS peripheral and a solid block below the turtle.

Public Variables

engine.angle

Current facing angle of the turtle (0-359 degrees).

engine.x, engine.y, engine.z

Current position coordinates in the active coordinate system.

engine.matrix

2x2 rotation matrix used for coordinate transformations.

engine.positionStack

Internal stack that tracks nested coordinate centers. Do not modify manually.

Usage Examples

Basic Movement

Absolute Positioning

Nested Coordinate Systems

Advanced Topics

Coordinate System Transformations

The engine uses transformation matrices to handle coordinate rotations. When you call setCenter() with a specific angle, it creates a local coordinate system where:

• The origin is at the specified (x, y, z) position
• The x-axis of this local system points in the direction of the specified angle
• Movement in positive x direction in this local system follows this new orientation
• Important: This local coordinate system is independent of the turtle's current physical facing. The turtle's facing direction does not affect how movement coordinates are interpreted.

Performance Considerations

• The orient() function can be slow as it uses GPS and may require multiple movements
• Complex coordinate transformations add overhead, but are generally negligible for most operations
• Minimize frequent changes to coordinate centers in performance-critical sections

Best Practices

1. Use setCenter() strategically: Reset coordinate centers when starting new operations or reaching significant waypoints
2. Handle errors: Wrap movement operations in error handling, especially when using orient()
3. Document transformations: Keep track of coordinate system changes in your code comments
4. Test recovery: Always test the orient() functionality in your deployment environment
5. Use absolute positioning: When precise positioning is critical, use absMove() instead of relative movement

See Also

• Coordinate System Details - In-depth explanation of the coordinate transformation system
• Examples - Additional usage patterns and code snippets