> For the complete documentation index, see [llms.txt](https://unknown-56-works.gitbook.io/luigiscreen/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unknown-56-works.gitbook.io/luigiscreen/screens-and-streaming/how-it-works.md).

# How It Works

LuigiScreen separates media loading from Minecraft screen rendering.

```mermaid
flowchart LR
    A["RTMP, MJPEG, video, image or GIF"] --> B["Shared media worker"]
    B --> C["Shared latest frame"]
    C --> D["Independent screen queues"]
    D --> E["MapEngine renderers"]
    E --> F["Minecraft map walls"]
```

## Media workers

RTMP, MJPEG, local videos and GIFs use FFmpeg through JavaCV. Local and URL images use the Java image loader.

The current artifact includes Windows x64 and Linux x64 FFmpeg natives.

## Optional RTMP pipeline

OBS and MediaMTX are only part of the RTMP setup:

```mermaid
flowchart LR
    A["Desktop, game or camera"] --> B["OBS Studio"]
    B -->|RTMP publish| C["MediaMTX"]
    C -->|RTMP read| D["LuigiScreen"]
```

OBS captures and encodes video. MediaMTX receives it and provides a reader endpoint. LuigiScreen does not communicate with OBS directly.

## Shared source and latest-frame queues

One worker exists per unique normalized source type and value. Its reference-counted latest frame is offered to every enabled screen in that source group without copying the decoded image for each clone.

Each screen has its own one-frame queue and render pacing. If loading or decoding is faster than that screen's FPS, an older queued frame is replaced instead of building latency.

The MapEngine render image wraps the screen's pixel array directly and is reused for later frames. Delta comparison storage is also reused. This avoids allocating a new raster, color model and full-size delta buffer for every rendered frame.

## MapEngine

MapEngine creates the client-side map display and sends map updates to nearby players.

## Main-thread safety

Media loading and decoding run on dedicated worker threads. Map frame preparation runs on a separate scheduled executor. Bukkit player and screen lifecycle operations are coordinated with the server thread.

Worker settings are captured before their background thread starts, so the decoder does not read Bukkit configuration concurrently. One snapshot of online player positions is built on the server thread and shared by all screen viewer checks.

## Viewer pause

By default, an FFmpeg worker disconnects when no players are within the individual distance of any enabled screen using that source. When a viewer returns to any clone, LuigiScreen reconnects or reopens the source.

Static images keep their loaded frame and do not continuously decode.

## Offline frames

Instead of leaving a frozen video frame, LuigiScreen can show states such as:

* Connecting
* Loading source
* Waiting for source
* Source offline
* Source stopped

## Screen persistence

Every screen's source type, source value, FPS, distance, world, location, dimensions, facing and enabled state are stored under `screens` in `config.yml`. LuigiScreen recreates all valid screens after a normal restart.

## Update checker

The optional update checker asks the public Modrinth API for project versions asynchronously. It compares semantic alpha, beta and release version numbers. When a newer version exists, the console is logged once and players with `luigiscreen.update` receive one clickable message for that version.

An unpublished project returns `404`; LuigiScreen treats that as no available public update and does not spam the console.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://unknown-56-works.gitbook.io/luigiscreen/screens-and-streaming/how-it-works.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.