Skip to content

README.md

Latest commit

 

History

History
191 lines (146 loc) · 6.05 KB

README.md

File metadata and controls

191 lines (146 loc) · 6.05 KB

YTChat

A Paper/Spigot plugin that bridges YouTube Live Chat into Minecraft. Each player can connect to their own YouTube live stream and receive chat messages directly in-game — per-player, not server-wide.

Features

  • Per-player YouTube chat — each player connects to their own stream
  • Persistent sessions — video IDs are saved, survives disconnects and restarts
  • Auto-reconnect — players automatically reconnect to their last stream on join
  • Customizable format — players can set their own chat format with /ytchat format
  • Role badges — owner, moderator, and verified users get colored names and badge icons
  • Hex color support — full &#RRGGBB hex colors alongside &c legacy codes
  • Configurable messages — every plugin message is editable in message.yml
  • Configurable sounds — start/stop sounds, or disable them
  • Emoji filtering — strips YouTube emoji shortcodes from messages
  • Custom events — developers can listen to YTChatStartEvent, YTChatStopEvent, and YouTubeChatMessageEvent
  • Tab completion — sub-commands and format placeholders auto-complete

Requirements

  • Java 21+
  • Paper 1.21+ (or Spigot 1.21+)

Installation

  1. Download the latest ytchat-*-jar-with-dependencies.jar from Releases
  2. Place it in your server's plugins/ folder
  3. Start or restart the server
  4. Config files will be generated in plugins/YTChat/

Commands

Command Description
/ytchat start <videoId> Connect to a YouTube live stream
/ytchat start Reconnect to your last saved stream
/ytchat stop Disconnect from YouTube chat
/ytchat format <format> Set a custom chat message format
/ytchat format reset Reset format to default
/ytchat status Check your connection status
/ytchat reload Reload all config files (OP only)

Permissions

Permission Description Default
ytchat.cmd Allows using all /ytchat commands Everyone
ytchat.reload Allows using /ytchat reload OP only

Configuration

config.yml

# Polling interval in seconds
poll-interval: 5

# Auto-reconnect players to their last video on join
auto-reconnect: true

message.yml

All plugin messages, chat format, role colors, badges, and sounds are configured here.

Chat format placeholders:

Placeholder Description
%prefix% The chat prefix (default: &#FF0000[YTChat])
%author% YouTube author name (auto-colored by role)
%badge% Role badge icons (owner/moderator/verified)
%message% The chat message content

Role colors and badges (configurable in message.yml):

Role Default Color Badge
Owner Gold (&#FFD700) Crown
Moderator Blue (&#5555FF) Hammer
Verified Green (&#55FF55) Checkmark
Default Gray (&7) None

Sounds:

sound:
  start: BLOCK_NOTE_BLOCK_BELL  # on successful connect
  stop: BLOCK_NOTE_BLOCK_BASS   # on disconnect
  volume: 1.0
  pitch: 1.0

Set any sound to '' (empty) to disable it.

Command messages use %prefix% which auto-resolves to the chat.prefix value — change the prefix once, it updates everywhere.

Building from Source

git clone https://github.com/FewPz/YTChat.git
cd YTChat
mvn clean package

The built JAR will be at target/ytchat-*-jar-with-dependencies.jar.

Project Structure

src/com/peeranat/ytchat/
├── YTChatPlugin.java                 # Entry point — wiring only
├── command/
│   ├── YTChatCommand.java            # /ytchat command handler
│   └── YTChatTabCompleter.java       # Tab completion
├── event/
│   ├── YTChatStartEvent.java         # Fired before connecting (cancellable)
│   ├── YTChatStopEvent.java          # Fired after disconnecting
│   └── YouTubeChatMessageEvent.java  # Fired per chat message
├── listener/
│   ├── ChatMessageListener.java      # Formats and sends YT messages to player
│   └── PlayerConnectionListener.java # Auto-reconnect on join, cleanup on quit
├── model/
│   └── ChatMessage.java              # Data model with role flags
├── repository/
│   ├── ChatConfigRepository.java     # Reads config.yml
│   ├── MessageRepository.java        # Reads message.yml
│   └── PlayerDataRepository.java     # Per-player persistent data (playerdata.yml)
├── service/
│   └── YouTubeChatService.java       # YouTube API polling, per-player connections
└── util/
    ├── ColorUtil.java                # Hex + legacy color parsing
    ├── EmojiUtil.java                # YouTube emoji shortcode stripping
    └── SoundUtil.java                # Sound playback via Registry API

Developer API

Other plugins can listen to YTChat events:

YouTubeChatMessageEvent

Fired for every YouTube chat message received. Async event.

@EventHandler
public void onYouTubeChat(YouTubeChatMessageEvent event) {
    ChatMessage msg = event.getChatMessage();
    UUID playerUUID = msg.getOwnerUUID();
    String author = msg.getAuthorName();
    String message = msg.getMessage();
    boolean isOwner = msg.isOwner();
    boolean isModerator = msg.isModerator();
    boolean isVerified = msg.isVerified();

    // Cancel to prevent the message from being sent
    event.setCancelled(true);
}

YTChatStartEvent

Fired on the main thread before a player connects. Cancellable.

@EventHandler
public void onStart(YTChatStartEvent event) {
    UUID playerUUID = event.getPlayerUUID();
    String videoId = event.getVideoId();

    // Cancel to prevent the connection
    event.setCancelled(true);
}

YTChatStopEvent

Fired on the main thread when a connection stops. Not cancellable.

@EventHandler
public void onStop(YTChatStopEvent event) {
    UUID playerUUID = event.getPlayerUUID();
    YTChatStopEvent.Reason reason = event.getReason();
    // Reasons: COMMAND, DISCONNECT, PLUGIN_DISABLE, REPLACED
}

License

This project is open source.