Rotate Component

The Rotate component provides smooth 3D object rotation animations with configurable speed, delays, and event-driven control for creating dynamic rotation effects in your Hyperfy world. Think of it as a precision rotation controller that can smoothly animate objects around any axis with customizable timing and synchronization.

Important: This component handles smooth rotation animations frame-by-frame, not instant rotation changes. It can rotate objects continuously or to specific target angles, with full control over speed, delays, and multi-axis rotation.

Download Component

What Does It Do?

The Rotate component is like having a precision rotation controller for your 3D objects. You can:

• Rotate objects smoothly around X, Y, and Z axes with configurable speed
• Create continuous rotation for spinning objects like fans or wheels
• Set target rotations for precise angular positioning
• Control animation timing with delays and speed settings
• Sync rotations across all players in multiplayer environments
• Chain actions by triggering other components when rotations complete
• Pause and resume animations for interactive control

Important: This component creates smooth, frame-by-frame rotation animations. It can handle both target-based rotations (rotate to specific angles) and continuous rotations (spin indefinitely). The animations are synchronized with physics collision when enabled.

Video Demo

Watch the Rotate component in action: smooth rotation animations, continuous spinning, multi-axis rotation, and synchronized effects across all players.

Properties

Basic Settings

Property	Type	Default	Description
App ID	text	Auto	Unique name for this component (auto-generated)
Node Name	text	""	Required: Name of the 3D object in your scene
Debug Logs	toggle	false	Show detailed information for troubleshooting
Add Collision	toggle	true	Make the object solid (players can't walk through)
Start Visible	toggle	true	Should the object be visible when the scene loads?

Animation Settings

Property	Type	Default	Description
Sync Changes	toggle	false	Should all players see rotation changes at the same time?
Use Delay	toggle	false	Add a wait time before starting rotations?
Delay (sec)	number	0	How many seconds to wait before starting rotation (0.1 to 60)
Enable Rotation	toggle	true	Enable rotation animations
Accept Any Event	toggle	false	Listen to any signal sent to this component?

Rotation Settings

Property	Type	Default	Description
Rotation Speed	number	0.01	Speed of animation in radians per frame (0.005 to 0.1)
X Rotation	number	0	Target X rotation in degrees
Y Rotation	number	0	Target Y rotation in degrees
Z Rotation	number	0	Target Z rotation in degrees
Event Listeners	textarea	[]	List of events that trigger rotation changes

How Events Work

The Rotate component listens for "signals" (events) from other components. When it receives a signal, it can start, pause, resume, or reset rotation animations. The component uses its unique App ID (generated by Hyperfy) to identify itself in the event system.

Event Format

In the Event Listeners field, you can specify events like this:

[
  {
    "id": "a1b2c3d4e",
    "actions": [
      {
        "type": "set-rotation",
        "params": {
          "rotationY": 90,
          "rotationSpeed": 0.02,
          "delay": 1.5
        }
      }
    ]
  }
]

Note: When referencing this component in events from other components, use the App ID that Hyperfy generated for this component. Also, when duplicating components, be sure you make the app unique, so it has a new AppID.

Action Types

Action	Description	Parameters
set-rotation	Start rotation to target angles	rotationX, rotationY, rotationZ, rotationSpeed, delay
pause-rotation	Pause current rotation animation	None
resume-rotation	Resume paused rotation animation	None
reset-rotation	Reset to initial rotation	resetSpeed (optional)
continuous-rotation	Start continuous rotation	continuousSpeedX, continuousSpeedY, continuousSpeedZ, delay
stop-continuous-rotation	Stop continuous rotation	None

Event Parameters

When an event triggers a rotation change, you can control:

Parameter	Type	Description
rotationX	number	Target X rotation in degrees
rotationY	number	Target Y rotation in degrees
rotationZ	number	Target Z rotation in degrees
rotationSpeed	number	Animation speed (radians/frame)
delay	number	Seconds to wait before starting rotation
continuousSpeedX	number	Continuous X rotation speed (radians/frame)
continuousSpeedY	number	Continuous Y rotation speed (radians/frame)
continuousSpeedZ	number	Continuous Z rotation speed (radians/frame)

Common Use Cases

1. Rotating Platforms

• Object: A platform that rotates when activated
• Event: Player touches a button
• Action: Platform smoothly rotates 90 degrees

2. Spinning Wheels

• Object: A wheel or fan that spins continuously
• Event: Player activates a switch
• Action: Wheel starts spinning continuously until stopped

3. Door Mechanisms

• Object: A rotating door or gate
• Event: Player solves a puzzle
• Action: Door rotates to open position

4. Interactive Puzzles

• Object: Rotating puzzle pieces
• Event: Player interacts with puzzle
• Action: Pieces rotate to correct positions

5. Environmental Effects

• Object: Windmills, turbines, or decorative spinning elements
• Event: Timer or proximity trigger
• Action: Objects start continuous rotation for atmosphere

Step-by-Step Setup

1. Add the Component

• Drag the Rotate component into your scene
• Select the 3D object you want to rotate

2. Configure Basic Settings

• Set the Node Name to match your 3D object's name
• Choose if the object should Start Visible
• Decide if it should Add Collision (be solid)

3. Set Up Rotation Parameters

• Configure Rotation Speed (start with 0.01 for smooth rotation)
• Set target X Rotation, Y Rotation, Z Rotation angles
• Enable Sync Changes if all players should see rotations

4. Configure Events

• In Event Listeners, add the events that should trigger rotations
• Use the JSON format shown above
• Replace event names with actual events from other components

5. Test Your Setup

• Enable Debug Logs to see what's happening
• Trigger your events and watch the object rotate
• Check that all players see the same rotations

Tips for Designers

Choosing Rotation Speeds

• Start with slow speeds (0.005-0.01) for smooth animations
• Use faster speeds (0.02-0.05) for quick rotations
• Test different speeds to find the right feel for your object

Planning Rotation Sequences

• Consider the object's initial rotation when setting targets
• Use delays to create dramatic timing effects
• Plan for both single-player and multiplayer scenarios

Testing Your Setup

• Always test with multiple players
• Use debug logs to troubleshoot issues
• Test edge cases (what happens if players disconnect?)

Performance Considerations

• Continuous rotation runs every frame - use sparingly
• Higher rotation speeds require more CPU per frame
• Consider the impact on mobile devices

Troubleshooting

Rotation Not Starting

• Check that Enable Rotation is set to true
• Verify that the event id matches exactly
• Ensure the Event Listeners JSON is valid
• Enable Debug Logs to see what's happening

Rotation Too Fast/Slow

• Adjust Rotation Speed (lower = slower, higher = faster)
• Use rotationSpeed parameter in events for runtime control
• Typical range: 0.005 (very slow) to 0.05 (fast)

Object Not Rotating Smoothly

• Check that Rotation Speed is not too high
• Verify the target rotation is different from current rotation
• Enable Debug Mode to see rotation progress

Continuous Rotation Issues

• Use continuous-rotation action for indefinite spinning
• Provide a way to stop continuous rotation when needed
• Remember: continuous rotation runs every frame

Collision Issues

• Enable Add Collision if the object needs physics
• Check that both mesh and rigidbody are rotating together
• Verify collision setup in Debug Mode logs

Best Practices

• Start Simple: Test with basic rotations before adding complexity
• Use Appropriate Speeds: Choose rotation speeds that feel natural
• Plan for Multiplayer: Consider how rotations affect all players
• Add Delays: Use delays for smoother, more professional sequences
• Test Thoroughly: Always test with multiple players and scenarios
• Use Debug Logs: Enable debug mode during development
• Document Your Setup: Keep notes on your rotation configurations
• Consider Performance: Limit continuous rotations for optimal performance
• Provide Control: Always provide ways to stop or reset rotations
• Test Collision: Verify collision works correctly with rotated objects