Keyboard Component

The Keyboard component provides a virtual keyboard interface that displays on-screen keypads for text input in your Hyperfy world. Think of it as a virtual input system that can show letter or number keypads with customizable appearance and event-driven interactions.

Important: This component creates a floating virtual keyboard UI that appears when activated. It supports both letter and number keypads with customizable appearance and emits events when keys are pressed. It's designed to work seamlessly with other components that need text input.

Download Component

What Does It Do?

The Keyboard component is like having a virtual input system for your 3D world. You can:

• Display virtual keypads for text input
• Support both letters and numbers with different keypad layouts
• Emit key press events for other components to handle
• Customize keypad appearance with colors and styling
• Sync keypad visibility across all players in multiplayer environments
• Integrate with other components like password managers or text inputs
• Provide accessible input for players who prefer virtual keyboards

Important: This component creates a floating virtual keyboard interface that appears when activated. Players can click on virtual buttons to input text, and the component emits events for each key press that other components can listen to.

Video Demo

Watch the Keyboard component in action: virtual keypads, text input, customizable appearance, 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?

Keypad Settings

Property	Type	Default	Description
Designer Mode	toggle	false	Show keypad in designer mode for testing
Keypad Type	select	Letters	Choose between Letters or Numbers keypad

Signal Settings

Property	Type	Default	Description
Receiver ID	text	""	ID for receiving visibility control events

How Events Work

The Keyboard component emits events when keys are pressed and listens for visibility control events. It uses its unique App ID (generated by Hyperfy) to identify itself in the event system.

Emitted Events

The component automatically emits these events when keys are pressed:

Event	Description	Payload
keypad-character-<appID>	Emitted when a character key is pressed	{ character: 'a' }
keypad-backspace-<appID>	Emitted when backspace key is pressed	None
keypad-enter-<appID>	Emitted when enter key is pressed	None
keypad-scape-<appID>	Emitted when escape key is pressed	None

Received Events

The component listens for these events to control visibility:

Event	Description	Parameters
visibility-<receiverID>	Controls keypad visibility	{ isVisible: true/false }

Common Use Cases

1. Password Input

• Object: A password input system
• Event: Player needs to enter password
• Action: Virtual keyboard appears for secure input

2. Text Input Fields

• Object: Text input areas
• Event: Player needs to enter text
• Action: Virtual keyboard provides text input

3. Numeric Input

• Object: Number input systems
• Event: Player needs to enter numbers
• Action: Number keypad appears for numeric input

4. Accessibility Support

• Object: Any input system
• Event: Player prefers virtual keyboard
• Action: Virtual keyboard provides accessible input

5. Mobile-Friendly Input

• Object: Input systems for mobile users
• Event: Player on mobile device
• Action: Virtual keyboard provides touch-friendly input

Step-by-Step Setup

1. Add the Component

• Drag the Keyboard component into your scene
• Select the 3D object you want to associate with the keyboard

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 Keypad Type

• Choose Keypad Type (Letters for text input, Numbers for numeric input)
• Enable Designer Mode for testing during development
• Configure any additional keypad settings

4. Configure Signal Settings

• Set Receiver ID for visibility control events
• This ID will be used by other components to control the keyboard

5. Integrate with Other Components

• Configure other components to listen for keyboard events
• Set up visibility control from other components
• Test the integration between components

6. Test Your Setup

• Enable Debug Logs to see what's happening
• Test keypad visibility and key press events
• Check that all players see the same keypad interface

Tips for Designers

Choosing Keypad Types

• Use Letters keypad for text input (names, messages, etc.)
• Use Numbers keypad for numeric input (prices, quantities, etc.)
• Test both types to ensure they meet your needs

Planning Your Input System

• Think about when players should see the virtual keyboard
• Consider timing and delays for smooth user experience
• Plan for both single-player and multiplayer scenarios
• Design clear visual cues for when keyboard should appear

Testing Your Setup

• Always test with multiple players
• Use debug logs to troubleshoot issues
• Test edge cases (what happens if players disconnect?)
• Verify keypad events are being received correctly

Performance Considerations

• Virtual keyboards are lightweight - minimal performance impact
• Consider the impact on player experience
• Test with different screen sizes and devices

Troubleshooting

Keypad Not Showing

• Check that the node is visible
• Verify Receiver ID configuration
• Ensure proper event emission for visibility control
• Test with Designer Mode enabled

Key Press Events Not Working

• Verify that event listeners are set up correctly
• Check that the Receiver ID is configured properly
• Ensure the component is running in the correct context
• Test keypad events independently

UI Layout Issues

• Adjust the keypad type (letters vs numbers) for your use case
• Check that the node has sufficient space for the keypad UI
• Verify that the keypad dimensions are appropriate for your scene
• Test with different screen sizes

Integration Issues

• Verify keyboard component is properly configured
• Check event naming consistency between components
• Test keyboard events independently
• Ensure proper event flow between components

Visibility Control Not Working

• Check that the Receiver ID matches what other components are using
• Verify that visibility events are being sent correctly
• Test with simple visibility events first
• Use debug logs to see event reception

Best Practices

• Use Appropriate Keypad Type: Choose letters for text input, numbers for numeric input
• Handle All Events: Listen for all keypad events to provide complete functionality
• Test in Designer Mode: Use designer mode to preview and test the keypad layout
• Configure Receiver ID: Set a unique receiver ID for proper event handling
• Use Debug Mode: Enable debug logs during development for troubleshooting
• Test Integration: Always test keyboard integration with other components
• Consider Accessibility: Ensure keypad is accessible to all players
• Test Multiplayer: Always test with multiple players and scenarios
• Document Events: Keep notes on keyboard event configurations
• Provide Fallbacks: Consider fallback input methods for different devices

Integration Examples

Password Manager Integration

// Listen for keyboard events
app.on('keypad-character-keyboard123', ({ character }) => {
  // Add character to password input
  passwordInput += character;
});

app.on('keypad-backspace-keyboard123', () => {
  // Remove last character
  passwordInput = passwordInput.slice(0, -1);
});

app.on('keypad-enter-keyboard123', () => {
  // Validate password
  validatePassword(passwordInput);
});

Visibility Control

// Show keypad
world.emit('visibility-keyboard123', { isVisible: true });

// Hide keypad
world.emit('visibility-keyboard123', { isVisible: false });

Text Input Integration

// Listen for character input
app.on('keypad-character-keyboard123', ({ character }) => {
  textInput += character;
  updateTextDisplay(textInput);
});