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.

PreviousEntitlements User GuideNextRewards System