Transform2D
January 10, 2026 · View on GitHub
GMR Docs > Engine > Scene > Transform2D
Transform2D
2D transform with position, rotation, scale, and hierarchy.
Table of Contents
- Instance Methods
- #Transform2D.lerp_position
- #Transform2D.lerp_rotation
- #Transform2D.lerp_scale
- #center_origin
- #forward
- #initialize
- #origin_x
- #origin_x=
- #origin_y
- #origin_y=
- #parallax
- #parallax=
- #parent
- #parent=
- #position
- #position=
- #right
- #rotation
- #rotation=
- #round_to_pixel!
- #scale_x
- #scale_x=
- #scale_y
- #scale_y=
- #snap_to_grid!
- #to_h
- #world_position
- #world_rotation
- #world_scale
- #x
- #x=
- #y
- #y=
Instance Methods
#initialize
Create a new Transform2D with optional initial values.
Parameters:
| Name | Type | Description |
|---|---|---|
x | Float | Initial X position (default: 0) |
y | Float | Initial Y position (default: 0) |
rotation | Float | Initial rotation in degrees (default: 0) |
scale_x | Float | Initial X scale (default: 1.0) |
scale_y | Float | Initial Y scale (default: 1.0) |
origin_x | Float | Pivot point X (default: 0) |
origin_y | Float | Pivot point Y (default: 0) |
Returns: Transform2D - The new transform
Example:
t = Transform2D.new(x: 100, y: 50, rotation: 45)
#x
Get the X position of the transform.
Returns: Float - The X position
Example:
x_pos = transform.x
#y
Get the Y position of the transform.
Returns: Float - The Y position
Example:
y_pos = transform.y
#position
Get the position as a Vec2.
Returns: Vec2 - The position vector
Example:
pos = transform.position
#rotation
Get the rotation in degrees.
Returns: Float - The rotation angle in degrees
Example:
angle = transform.rotation
#scale_x
Get the X scale factor.
Returns: Float - The X scale (1.0 = normal size)
Example:
sx = transform.scale_x
#scale_y
Get the Y scale factor.
Returns: Float - The Y scale (1.0 = normal size)
Example:
sy = transform.scale_y
#origin_x
Get the X origin (pivot point) for rotation and scaling.
Returns: Float - The X origin offset in pixels
Example:
ox = transform.origin_x
#origin_y
Get the Y origin (pivot point) for rotation and scaling.
Returns: Float - The Y origin offset in pixels
Example:
oy = transform.origin_y
#x=
Set the X position of the transform.
Parameters:
| Name | Type | Description |
|---|---|---|
value | Float | The new X position |
Returns: Float - The value that was set
Example:
transform.x += 5 # Move right by 5 pixels
#y=
Set the Y position of the transform.
Parameters:
| Name | Type | Description |
|---|---|---|
value | Float | The new Y position |
Returns: Float - The value that was set
Example:
transform.y += 10 # Move down by 10 pixels
#position=
Set the position using a Vec2.
Parameters:
| Name | Type | Description |
|---|---|---|
value | Vec2 | The new position vector |
Returns: Vec2 - The value that was set
Example:
transform.position = player.position # Copy another position
#rotation=
Set the rotation in degrees. Positive values rotate clockwise.
Parameters:
| Name | Type | Description |
|---|---|---|
value | Float | The new rotation angle in degrees |
Returns: Float - The value that was set
Example:
transform.rotation += 90 * dt # Rotate 90 degrees per second
#scale_x=
Set the X scale factor. Values greater than 1 stretch horizontally, less than 1 shrink. Negative values flip horizontally.
Parameters:
| Name | Type | Description |
|---|---|---|
value | Float | The new X scale (1.0 = normal size) |
Returns: Float - The value that was set
Example:
transform.scale_x = -1.0 # Flip horizontally
#scale_y=
Set the Y scale factor. Values greater than 1 stretch vertically, less than 1 shrink. Negative values flip vertically.
Parameters:
| Name | Type | Description |
|---|---|---|
value | Float | The new Y scale (1.0 = normal size) |
Returns: Float - The value that was set
Example:
transform.scale_y = -1.0 # Flip vertically
#origin_x=
Set the X origin (pivot point) for rotation and scaling. The origin is the point around which the transform rotates and scales.
Parameters:
| Name | Type | Description |
|---|---|---|
value | Float | The X origin offset in pixels from top-left |
Returns: Float - The value that was set
Example:
transform.origin_x = 16 # Pivot 16px from left edge
#origin_y=
Set the Y origin (pivot point) for rotation and scaling. The origin is the point around which the transform rotates and scales.
Parameters:
| Name | Type | Description |
|---|---|---|
value | Float | The Y origin offset in pixels from top-left |
Returns: Float - The value that was set
Example:
transform.origin_y = 16 # Pivot 16px from top edge
#parallax
Get the parallax scrolling factor. Controls how the object moves relative to the camera: - 1.0 = moves with the world (default, normal objects) - 0.0 = fixed to screen (doesn't move with camera) - 0.5 = moves at half camera speed (distant background) - 0.1 = moves at 10% camera speed (very distant mountains)
Returns: Float - The parallax factor (0.0 to 1.0)
Example:
factor = transform.parallax
#parallax=
Set the parallax scrolling factor for camera-relative movement. When rendered inside a camera, objects with parallax < 1.0 will appear to move slower than the camera, creating depth.
Parameters:
| Name | Type | Description |
|---|---|---|
value | Float | The parallax factor (0.0 = fixed, 1.0 = normal world) |
Returns: Float - The value that was set
Example:
transform.parallax = 0.0 # Fixed to screen (HUD elements)
#center_origin
Set the origin to the center of the given dimensions, so the transform rotates and scales around its center point. Useful for sprites, images, or any rectangular object.
Parameters:
| Name | Type | Description |
|---|---|---|
w | Float | The width of the object in pixels |
h | Float | The height of the object in pixels |
Returns: Transform2D - self for chaining
Example:
Transform2D.new(x: 100, y: 100).center_origin(64, 64) # Method chaining
#parent
Get the parent transform. Returns nil if no parent is set. When a transform has a parent, its position, rotation, and scale are relative to the parent's world transform.
Returns: Transform2D, nil - The parent transform, or nil if none
Example:
if transform.parent
puts "Has a parent!"
end
#parent=
Set the parent transform for hierarchical transformations. When parented, this transform's position, rotation, and scale become relative to the parent. Set to nil to remove the parent.
Parameters:
| Name | Type | Description |
|---|---|---|
value | Transform2D, nil | The parent transform, or nil to clear |
Returns: Transform2D, nil - The value that was set
Example:
transform.parent = nil # Remove parent
#world_position
Get the final world position after applying all parent transforms. For transforms without a parent, this equals the local position. For parented transforms, this returns the actual screen position after parent transformations.
Returns: Vec2 - The world position after parent hierarchy composition
Example:
# Get world position of a child transform
parent = Transform2D.new(x: 100, y: 100)
parent.rotation = 90
child = Transform2D.new(x: 50, y: 0)
child.parent = parent
pos = child.world_position # Position after rotation by parent
#world_rotation
Get the final world rotation after applying all parent transforms. For transforms without a parent, this equals the local rotation. For parented transforms, this returns the combined rotation of the entire hierarchy.
Returns: Float - The world rotation in degrees
Example:
child_world_rot = transform.world_rotation
#world_scale
Get the final world scale after applying all parent transforms. For transforms without a parent, this equals the local scale. For parented transforms, this returns the combined scale of the entire hierarchy.
Returns: Vec2 - The world scale
Example:
world_s = transform.world_scale
#forward
Get the forward direction vector after world rotation. The forward vector points in the direction the transform is facing (0 degrees = right).
Returns: Vec2 - The normalized forward direction
Example:
forward = transform.forward
transform.x += forward.x * speed * dt # Move forward
#right
Get the right direction vector after world rotation. The right vector points perpendicular to forward (90 degrees clockwise).
Returns: Vec2 - The normalized right direction
Example:
right = transform.right
transform.x += right.x * strafe_speed * dt # Strafe right
#snap_to_grid!
Snap the position to the nearest grid cell. Useful for tile-based games or ensuring pixel-perfect alignment.
Parameters:
| Name | Type | Description |
|---|---|---|
grid_size | Float | The size of each grid cell in pixels |
Returns: nil
Example:
transform.snap_to_grid!(16) # Snap to 16x16 grid
#round_to_pixel!
Round the position to the nearest integer pixel coordinates. Useful for pixel-art games to avoid sub-pixel rendering artifacts.
Returns: nil
Example:
transform.round_to_pixel! # Ensure crisp pixel alignment
#Transform2D.lerp_position
Linearly interpolate between two positions.
Parameters:
| Name | Type | Description |
|---|---|---|
a | Vec2 | Start position |
b | Vec2 | End position |
t | Float | Interpolation factor (0.0 to 1.0) |
Returns: Vec2 - The interpolated position
Example:
pos = Transform2D.lerp_position(start_pos, end_pos, 0.5)
#Transform2D.lerp_rotation
Interpolate between two rotation angles using shortest path. Automatically handles wrapping (e.g., 350° to 10° goes through 0°, not 340°).
Parameters:
| Name | Type | Description |
|---|---|---|
a | Float | Start rotation in degrees |
b | Float | End rotation in degrees |
t | Float | Interpolation factor (0.0 to 1.0) |
Returns: Float - The interpolated rotation in degrees
Example:
rot = Transform2D.lerp_rotation(0, 270, 0.5) # Returns 315 (shortest path)
#Transform2D.lerp_scale
Linearly interpolate between two scale vectors.
Parameters:
| Name | Type | Description |
|---|---|---|
a | Vec2 | Start scale |
b | Vec2 | End scale |
t | Float | Interpolation factor (0.0 to 1.0) |
Returns: Vec2 - The interpolated scale
Example:
scale = Transform2D.lerp_scale(Vec2.new(1, 1), Vec2.new(2, 2), 0.5)
#to_h
Convert Transform2D to a hash for JSON serialization. Includes a "_type" field for automatic deserialization. Only includes local transform values (not world transform).
Example:
transform = Transform2D.new(x: 100, y: 50, rotation: 45)
data = transform.to_h
json = GMR::JSON.stringify(data)