Marquee System

Overview

The Marquee System provides a scrolling notification system that displays important game information at the top of the screen. Messages scroll horizontally from right to left, providing users with real-time updates about game events, join confirmations, and other important notifications.

This document covers the technical implementation, architecture, and API for engineers working with or extending the marquee system.

---

Technical Architecture

Core Components

MarqueeManager Class (client/src/ui/MarqueeManager.js)

The central manager for the marquee system with the following key features:

Configuration Properties:

this.scrollSpeed = 30;        // Pixels per second
this.messageSpacing = 100;    // Minimum gap between messages (pixels)
this.messageDuration = 12000; // Display duration (milliseconds)
this.maxMessages = 1;         // Only one message displays at a time

Priority Queue System:

this.queues = {
  high: [],    // Game-critical messages
  medium: [],  // Join confirmations
  low: []      // General notifications
};

Key Methods

Public API:

• queueMessage(text, options, priority) - Add a message to the queue

• clearQueues() - Clear all pending messages

Internal Methods:

• addMessage(text, options) - Display a message immediately

• tryShowNextMessage() - Check queue and display next message if possible

• canShowNextMessage() - Check spacing conditions

• animateMessage() - Handle scroll animation

Priority System

Messages are processed in priority order:

1. High Priority (game messages) - Processed first

2. Medium Priority (join messages) - Processed second

3. Low Priority (general) - Processed last

Timing System

The system uses periodic checking (every 500ms) rather than event-driven updates:

// Start periodic queue checking
this.startQueueChecking() {
  this.queueCheckTimer = this.scene.time.addEvent({
    delay: 500, // Check every half second
    callback: () => this.tryShowNextMessage(),
    loop: true
  });
}

Scene Integration

The marquee manager is initialized globally in the InstructionsScene and persists across all game scenes:

// In InstructionsScene.create()
if (!this.game.marqueeManager) {
  this.game.marqueeManager = new MarqueeManager(this);
  this.game.marqueeManager.init();
}

Cross-Scene Compatibility

The system automatically detects the active scene when displaying messages:

// Get currently active scene
let activeScene = this.scene;
if (this.game && this.game.scene) {
  const activeScenes = this.game.scene.getScenes(true);
  if (activeScenes.length > 0) {
    activeScene = activeScenes[0]; // Use active scene
  }
}

---

API Reference

Static Methods (Global Access)

MarqueeManager.addMessage(text, options, priority)

Add a message to the marquee system.

Parameters:

• text (string): The message text to display

• options (object, optional): Display options

  • color (string): Text color (default: '#FFFFFF')

  • fontSize (string): Font size (default: '16px')

  • fontFamily (string): Font family (default: 'Arial')

  • stroke (string): Text outline color (default: '#000000')

  • strokeThickness (number): Outline thickness (default: 3)

• priority (string): Queue priority ('high', 'medium', 'low')

Example:

MarqueeManager.addMessage('Player joined!', { color: '#10B981' }, 'medium');

MarqueeManager.clearQueues()

Clear all pending messages from all priority queues.

---

Utility Functions

showMarqueeMessage(text, options, priority)

Convenience function for displaying marquee messages.

Parameters: Same as MarqueeManager.addMessage

Example:

import { showMarqueeMessage } from '../Utils.js';
showMarqueeMessage('Welcome!', { color: '#F59E0B' }, 'low');

clearMarqueeQueues()

Convenience function to clear all queues.

---

Integration Examples

Adding Join Confirmations

// In GlobalChatHandler.js
MarqueeManager.addMessage(`✅ ${username} joined the battle!`, {
  color: '#10B981'
}, 'medium');

Adding Game Notifications

// In game logic
MarqueeManager.addMessage('Battle starting in 10 seconds!', {
  color: '#EF4444'
}, 'high');

Adding General Messages

// In UI components
showMarqueeMessage('Tip: Use special abilities wisely!', {
  color: '#8B5CF6',
  fontSize: '14px'
}, 'low');

---

Configuration

Adjusting Scroll Speed:

// In MarqueeManager constructor
this.scrollSpeed = 30; // Pixels per second (higher = faster)

Adjusting Message Duration:

// In MarqueeManager constructor
this.messageDuration = 12000; // Milliseconds (12 seconds)

Adjusting Spacing:

// In MarqueeManager constructor
this.messageSpacing = 100; // Minimum pixels between messages

---

Performance Considerations

• Memory Management: Messages are properly destroyed after animation completes

• Queue Limits: Maximum of 3 simultaneous messages prevents overflow

• Efficient Checking: Periodic polling (500ms) balances responsiveness with performance

• Scene Cleanup: Timer is properly destroyed when scenes shut down

---

Testing

The system includes built-in test messages that can be enabled in development:

// In InstructionsScene.startMarqueeTest()
this.time.delayedCall(100, () => {
  this.showRandomMarqueeMessage(); // Shows test messages
});

---

Future Enhancements

1

Rich Text Support

HTML/markdown formatting in messages

2

Animation Variants

Different scroll patterns (bounce, fade, etc.)

3

Position Options

Configurable positioning (top, bottom, sides)

4

Sound Integration

Audio cues for different message types

5

Persistence

Save undelivered messages across sessions

---

Troubleshooting

Common Issues

Messages not appearing:

• Check that InstructionsScene has initialized the marquee manager

• Verify priority queue isn't full (max 3 messages)

• Check console for initialization errors

Messages appearing too fast/slow:

• Adjust scrollSpeed property (pixels per second)

• Modify messageDuration for display time

Messages overlapping:

• Increase messageSpacing value

• Check canShowNextMessage() logic

Cross-scene issues:

• Verify scene detection is working correctly

• Check that UI camera is properly configured

Debug Information

Enable debug logging by checking console output:

• [MarqueeManager] Initialized - Manager startup

• [MarqueeManager] Queued [priority] message - Message added to queue

• [MarqueeManager] Scrolling message - Message display details

---

Maintenance

Regular Tasks

• Monitor message queue lengths for performance

• Update color schemes for accessibility

• Test across different screen resolutions

• Verify timing works on various devices

Code Organization

• client/src/ui/MarqueeManager.js - Core marquee logic

• client/src/scenes/InstructionsScene.js - Initialization

• client/src/chat/GlobalChatHandler.js - Join confirmations

• client/src/Utils.js - Utility functions

---

The marquee system provides a robust, performant way to deliver important information to players without disrupting gameplay flow.