Translate Component

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

Important: This component handles smooth translation animations frame-by-frame, not instant position changes. It can move objects to specific target positions with full control over speed, delays, and multi-axis movement.

Download Component

What Does It Do?

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

• Move objects smoothly along X, Y, and Z axes with configurable speed
• Create elevator systems for vertical movement
• Build sliding doors and moving platforms
• Control animation timing with delays and speed settings
• Sync movements across all players in multiplayer environments
• Chain actions by triggering other components when movements complete
• Pause and resume animations for interactive control

Important: This component creates smooth, frame-by-frame translation animations. It moves objects from their current position to target positions with configurable speed. The animations are synchronized with physics collision when enabled.

Video Demo

Watch the Translate component in action: smooth movement animations, elevator systems, sliding doors, 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 movement changes at the same time?
Use Delay	toggle	false	Add a wait time before starting movements?
Delay (sec)	number	0	How many seconds to wait before starting movement (0.1 to 60)
Enable Translation	toggle	true	Enable translation animations
Accept Any Event	toggle	false	Listen to any signal sent to this component?

Translation Settings

Property	Type	Default	Description
Translation Speed	number	0.1	Speed of animation in units per frame (0.05 to 0.5)
X Translation	number	0	Target X position in units
Y Translation	number	0	Target Y position in units
Z Translation	number	0	Target Z position in units
Event Listeners	textarea	[]	List of events that trigger movement changes

How Events Work

The Translate component listens for "signals" (events) from other components. When it receives a signal, it can start, pause, resume, or reset translation 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-translation",
        "params": {
          "translationY": 5,
          "translationSpeed": 0.2,
          "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-translation	Start movement to target position	translationX, translationY, translationZ, translationSpeed, delay
pause-translation	Pause current movement animation	None
resume-translation	Resume paused movement animation	None
reset-translation	Reset to initial position	resetSpeed (optional)

Event Parameters

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

Parameter	Type	Description
translationX	number	Target X position in units
translationY	number	Target Y position in units
translationZ	number	Target Z position in units
translationSpeed	number	Animation speed (units/frame)
delay	number	Seconds to wait before starting movement

Common Use Cases

1. Moving Platforms

• Object: A platform that moves when activated
• Event: Player touches a button
• Action: Platform smoothly moves up 10 units

2. Elevator Systems

• Object: An elevator platform
• Event: Player steps on elevator
• Action: Elevator moves to different floors

3. Sliding Doors

• Object: A door that slides open
• Event: Player approaches door
• Action: Door slides horizontally to open

4. Interactive Puzzles

• Object: Moving puzzle pieces
• Event: Player solves puzzle step
• Action: Pieces move to correct positions

5. Environmental Mechanics

• Object: Bridges, platforms, or barriers
• Event: Timer or player action
• Action: Objects move to create new paths or obstacles

Step-by-Step Setup

1. Add the Component

• Drag the Translate component into your scene
• Select the 3D object you want to move

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 Movement Parameters

• Configure Translation Speed (start with 0.1 for smooth movement)
• Set target X Translation, Y Translation, Z Translation positions
• Enable Sync Changes if all players should see movements

4. Configure Events

• In Event Listeners, add the events that should trigger movements
• 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 move
• Check that all players see the same movements

Tips for Designers

Choosing Movement Speeds

• Start with slow speeds (0.05-0.1) for smooth animations
• Use faster speeds (0.2-0.5) for quick movements
• Test different speeds to find the right feel for your object

Planning Movement Sequences

• Consider the object's initial position 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

• Translation animations run every frame - avoid too many simultaneous animations
• Higher translation speeds require more CPU per frame
• Consider the impact on mobile devices

Troubleshooting

Movement Not Starting

• Check that Enable Translation 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

Movement Too Fast/Slow

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

Object Not Moving Smoothly

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

Collision Issues

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

Delay Not Working

• Ensure Use Delay is enabled
• Check that Delay (sec) is greater than 0
• Verify the delay value in your event parameters

Best Practices

• Start Simple: Test with basic movements before adding complexity
• Use Appropriate Speeds: Choose movement speeds that feel natural
• Plan for Multiplayer: Consider how movements 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 movement configurations
• Consider Performance: Limit simultaneous animations for optimal performance
• Provide Control: Always provide ways to stop or reset movements
• Test Collision: Verify collision works correctly with moving objects