Logs Component

The Logs component provides a centralized logging system that handles debug messages across all components in your Hyperfy world. Think of it as a unified logging interface that can collect, display, and synchronize log messages from any source with support for different log levels and server-client coordination.

Important: This component acts as a central hub for all logging activities. It receives log events from any component or script and displays them in the console with proper formatting and categorization. It supports server-client synchronization for multiplayer debugging.

Download Component

What Does It Do?

The Logs component is like having a centralized logging system for your 3D world. You can:

• Collect log messages from any component or script
• Categorize logs by different levels (info, warn, error, debug)
• Synchronize server logs to client for multiplayer debugging
• Format log output with timestamps and source information
• Control log visibility with configurable settings
• Debug multiplayer issues with server-client log sync
• Monitor system health across all components

Important: This component receives log events from any source and displays them in the console. It doesn't generate logs itself - other components and scripts emit log events to this component for centralized handling.

Video Demo

Watch the Logs component in action: centralized logging, server-client synchronization, log categorization, and debugging across all components.

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?

Logs Settings

Property	Type	Default	Description
Server Logs in Client	toggle	false	Show server logs in client console for debugging

How Events Work

The Logs component listens for "log" events from any source. When it receives a log event, it processes the message and displays it in the console with proper formatting. The component uses its unique App ID (generated by Hyperfy) to identify itself in the event system.

Event Format

Any component or script can emit log events like this:

// Emit a log event from any script or component
world.emit('log', {
  message: 'Script initialized successfully',
  type: 'info'
});

// Different log levels
world.emit('log', { message: 'Debug information', type: 'debug' });
world.emit('log', { message: 'Warning message', type: 'warn' });
world.emit('log', { message: 'Error occurred', type: 'error' });

Supported Log Types

Log Type	Description	Use Case
log	General log messages	General information
info	Informational messages	Status updates, successful operations
warn	Warning messages	Potential issues, deprecated features
error	Error messages	Failures, exceptions, critical issues
debug	Debug messages	Development information, detailed tracing

Event Parameters

When emitting log events, you can control:

Parameter	Type	Description
message	string	Required: The log message content
type	string	Required: Log level (log, info, warn, error, debug)

Common Use Cases

1. Component Debugging

• Source: Any component with debug mode enabled
• Event: Component emits debug information
• Action: Logs appear in centralized console

2. Error Tracking

• Source: Components encountering errors
• Event: Error conditions are detected
• Action: Error logs are displayed with details

3. System Monitoring

• Source: Multiple components and scripts
• Event: Status updates and health checks
• Action: Centralized monitoring of system health

4. Multiplayer Debugging

• Source: Server-side components
• Event: Server logs are generated
• Action: Server logs appear in client console

5. Development Logging

• Source: Development scripts and tools
• Event: Development information is logged
• Action: Development logs are centralized

Step-by-Step Setup

1. Add the Component

• Drag the Logs component into your scene
• Select any 3D object (position doesn't matter)

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 Logging Behavior

• Enable Server Logs in Client for multiplayer debugging
• Configure any additional logging settings

4. Configure Other Components

• Enable debug mode in other components
• Ensure other components emit log events to this component
• Test log emission from different sources

5. Test Your Setup

• Enable Debug Logs to see what's happening
• Trigger events in other components
• Check that logs appear in the console

Tips for Designers

Using Log Levels Appropriately

• Use info for successful operations and status updates
• Use warn for potential issues that don't break functionality
• Use error for failures that need attention
• Use debug for development information only

Planning Your Logging System

• Think about what information you need to track
• Consider timing and frequency of log messages
• Plan for both single-player and multiplayer scenarios
• Design clear log messages for easy debugging

Testing Your Setup

• Always test with multiple players
• Use debug logs to troubleshoot issues
• Test edge cases (what happens if players disconnect?)
• Verify log messages are clear and helpful

Performance Considerations

• Logging has minimal performance impact
• Avoid excessive logging in production
• Use appropriate log levels for different environments
• Consider the impact on console output

Troubleshooting

Logs Not Appearing

• Check that the Logs component is properly attached
• Verify that other components are emitting log events
• Ensure the log event format is correct
• Enable Debug Logs to see what's happening

Server Logs Not Showing in Client

• Enable Server Logs in Client in the Logs component
• Verify that the script is running on the server side
• Check network connectivity in multiplayer environments
• Test with simple log messages first

Log Format Issues

• Ensure log events include both message and type parameters
• Verify that log types are valid (log, info, warn, error, debug)
• Check that log messages are strings
• Test with different log levels

Console Methods Not Working

• The component automatically falls back to console.log if specific methods are unavailable
• This ensures logging works across different environments
• Check browser console for any JavaScript errors
• Verify that the logging system is properly initialized

Multiplayer Logging Issues

• Check that server-client synchronization is working
• Verify that all players have the Logs component
• Test with simple log messages first
• Check network connectivity

Best Practices

• Use Appropriate Log Levels: Choose the right log level for your message
• Keep Messages Concise: Use clear, descriptive log messages
• Include Context: Add relevant context to help with debugging
• Use Debug Sparingly: Only use debug logs for development, not production
• Enable Server Logs: Use server logs in client for debugging multiplayer issues
• Test Logging: Always test logging functionality during development
• Document Log Messages: Keep notes on what different log messages mean
• Monitor Log Volume: Avoid excessive logging that clutters the console
• Use Consistent Format: Maintain consistent log message formatting
• Test Multiplayer: Always test logging in multiplayer environments

Integration Examples

Component Integration

// In any component
if (props.enableDebugMode) {
  world.emit('log', {
    message: 'Component initialized successfully',
    type: 'info'
  });
}

Error Handling

// Error logging
try {
  // Some operation
} catch (error) {
  world.emit('log', {
    message: `Operation failed: ${error.message}`,
    type: 'error'
  });
}

Status Updates

// Status logging
world.emit('log', {
  message: 'Player position updated',
  type: 'info'
});

Debug Information

// Debug logging
world.emit('log', {
  message: `Current state: ${JSON.stringify(state)}`,
  type: 'debug'
});