Turn a Minecraft wall into a media screen

LuigiScreen is a server-side Paper/Bukkit plugin that displays live streams, videos, images, GIFs, playlists and event scenes across configurable walls of Minecraft maps.

IN ALPHA STAGE A lot of stuff is not done and finished!

Select an RTMP or MJPEG stream, a local video, a local or remote image, or an animated GIF. LuigiScreen loads the latest frame and MapEngine renders it for nearby players.

No client mod is required. Players join with a normal Minecraft client.

Features

• In-game Control Studio with role-based access
• Secure browser Web Studio with one-time login links and revocable sessions
• Beginner-first Web Studio workflow: Media Library -> Playlist Editor -> Screen Automation
• Direct browser playlist builder with visible add, delete, duplicate and assign controls
• Direct browser playlist item editor for media, duration, weight and enabled state
• Direct browser event builder with visible add step, delete, duplicate, start and stop controls
• Direct browser event step editor for type, value, text, duration and enabled state
• Direct browser automation builder with readable WHEN / IF / THEN rules
• Searchable bundled picker controls for long screen, media, event and playlist lists
• Preview/Program Live Studio with bounded live source thumbnails
• Clean hover help and accessible descriptions without permanent info icons
• Dashboard, Live Control Room, queues and playback explanations
• Watched Media Library with validation and generated map thumbnails
• Draft/Publish editing, audit history, snapshots and undo
• Screen groups, schedules, templates and audience voting
• Playlist simulation, advanced anti-repeat and eligibility diagnostics
• RTMP and MJPEG live streams
• Looping local videos and GIFs
• Local and URL images
• Per-screen playlists with weighted random media rotation
• Manual event scenes that temporarily interrupt normal playback
• Random media folder items for videos, images and GIFs
• Multiple named screens with independent settings
• One shared loader for screens using the same source type and value
• Configurable screen dimensions, worlds, locations and orientation
• Automatic reconnect with exponential backoff
• Viewer-distance detection
• Decoder pause while nobody is near the screen
• Adaptive FPS protection for larger screens
• Delta map updates to reduce unnecessary traffic
• Optional guided MediaMTX configuration for RTMP
• Editable Czech and English localization
• English default configuration with optional Czech localization
• Granular permissions for every management command
• Optional luigiscreen.see.<screen> protection per display
• Live performance boss bar and debug sidebar
• Optional asynchronous Modrinth update notifications
• Persistent screen configuration across restarts
• Masked remote-source credentials in commands and plugin logs
• Bundled FFmpeg natives for Windows x86_64 and Linux x86_64

Requirements

• Paper 1.21.11
• Java 21
• MapEngine 1.8.12
• MediaMTX and OBS Studio only when using RTMP
• Windows x86_64 or Linux x86_64 server

LuigiScreen belongs to the Bukkit plugin ecosystem but currently targets Paper APIs. Use Paper 1.21.11, not a plain Spigot or CraftBukkit server.

MapEngine is a required dependency.

Source types

rtmp       rtmp:// or rtmps:// live stream
mjpeg      HTTP(S) MJPEG camera stream
video      looping local video file
image      local static image
url-image  remote HTTP(S) image
gif        looping local or remote GIF

Relative local paths use plugins/LuigiScreen/media/. Screens using the same source type and value share one loader while keeping independent FPS, distance, location, dimensions and permissions.

Playlists and events

Screens can also run configured playlists:

/screen playlist set main spawn_rotation

Playlist items can use RTMP, MJPEG, video, image, URL image, GIF, text frames or a random folder of local media files. Items support weights, durations, cooldowns and simple conditions such as viewer count, online players, viewer permission and TPS.

Manual event scenes can interrupt the normal playlist and then return to it:

/screen event play main update_reveal

Events are useful for announcements, update reveals, countdowns or temporary live streams.

For RTMP, MediaMTX and OBS do not have to run on the Minecraft server computer. LuigiScreen includes guided setup profiles for the same computer, LAN, public IP, VPN and external hosting.

Installation

1. Stop the Paper server completely.
2. Install MapEngine 1.8.12.
3. Put the LuigiScreen JAR in plugins/.
4. Start the server.
5. Create the screen while looking at the upper-left block of a vertical wall.
6. Select its source.

Example:

/screen create main 7 4
/screen source main video intro.mp4
/screen start main

Use /screen mediamtx <situation> only for an RTMP setup. Read the complete step-by-step documentation before exposing MediaMTX to the internet.

Commands

Command	Description
/screen create <name> [width] [height]	Create a named screen on the wall you are looking at
/screen clone <source> <new-name>	Clone a screen and share its typed source
/screen list	List screens and safe source values
/screen start <name|all>	Enable one or every screen
/screen stop <name|all>	Disable screens without deleting them
/screen remove <name>	Remove one screen
/screen status [name]	Show registry or detailed screen state
/screen source <name> <type> <value>	Switch RTMP, MJPEG, video, image, URL image or GIF
/screen playlist list|set|clear ...	Assign or clear configured media playlists
/screen event list|play|stop ...	Play or stop configured manual event scenes
/screen set <name> <url|fps|distance|enabled|permission> <value>	Update one screen
/screen reload	Reload configuration without destroying screens
/screen debug	Toggle live performance statistics
/screen mediamtx <situation>	Generate a guided MediaMTX configuration

luigiscreen.admin is granted to operators and includes every command. Individual nodes such as luigiscreen.create, luigiscreen.start, luigiscreen.stop, luigiscreen.remove and luigiscreen.status can be assigned separately. Screens are public by default and can optionally require luigiscreen.see.<screen-name>.

Performance safeguards

The default public configuration limits each screen to 10x6 maps and 60 maps. Adaptive FPS and map-update limits protect the server and connected clients.

Large screens can still consume significant CPU, memory and network bandwidth. Increase the limits only after testing /screen debug with real players.

Screens with an identical normalized source type and value share one loader and one decoded image. MapEngine scaling, rendering and packets still run independently for every screen because their sizes, FPS and viewers may differ.

Current alpha limitations

• Video only; Minecraft does not receive stream audio
• No ARM or macOS native libraries
• No Folia support
• MediaMTX and OBS remain separate applications when RTMP is used
• A publisher must stay online for live RTMP capture
• URL images are loaded once after a successful request
• Advanced automation conditions still use configuration rather than a visual condition builder

Alpha notice

LuigiScreen is currently an alpha project. Back up the server before updating and test new builds away from production.

Bug reports should include the output of /screen status, relevant console logs and the diagnostic information described in the wiki. Remove passwords, tokens and public addresses before posting logs.

Documentation

• Complete wiki
• Installation
• Network setup
• Troubleshooting
• Czech quick start