# darksavci/minecraft-video-player architecture

> Architecture diagram of the GitHub repository darksavci/minecraft-video-player, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/darksavci/minecraft-video-player
- Repository: https://github.com/darksavci/minecraft-video-player

## Overview

##### Project Type and Purpose
- This is a server-side Minecraft plugin (for Paper/Spigot 1.19.4) written in Java using Maven.

##### File Structure
- src/main/java/dev/bdinc/minecraft_video_player: all Java source.
– Main.java: plugin entry point, registers commands.
– *Command.java classes: handle `/processvideo`, `/processimage`, `/processstream`, `/setres`, `/undo`.
– VideoFrameProcessor.java & StreamFrameProcessor.java: abstract the mechanics of reading and iterating through frames.
- src/main/resources/plugin.yml: plugin descriptor used by the server to detect commands, permissions, and plugin metadata.
- pom.xml: declares JavaCV (ffmpeg-based) dependencies and build targets.

##### Extract Key Insights from the README
- Uses JavaCPP/JavaCV presets to decode video/stream on a separate thread.
- Supports dynamic FPS changes and configurable resolution via commands.
- Deploys as a .jar inside a plugins directory on a Paper/Spigot server.

##### Main Components
a. Minecraft Server (Paper/Spigot)
b. Plugin Loader (Bukkit API)
c. Plugin Core
– Command Handlers
– Processing Engine
d. External Dependencies
– JavaCV/FFmpeg native libraries
e. Data Stores/Config
– plugin.yml (static metadata)
– (Future) config file for max FPS/resolution

##### Relationships & Data Flow
1) Player issues a chat command → 2) Bukkit calls the corresponding Command class → 3) Command starts or configures a Processing Thread → 4) Processing Engine uses JavaCV to fetch and decode frames → 5) For each frame:
- ColorManager maps pixels → Minecraft Block data
- Plugin invokes Bukkit World API to place/update blocks → rendering in-game
6) `/undo` rolls back placed blocks.

##### Architectural Patterns & Design Principles
- Separation of Concerns:
– Command Layer (Bukkit command interface)
– Processing Layer (frame decoding & iteration)
– Mapping Layer (pixel→block)
– Rendering Layer (world updates)
- Concurrency: video/stream processing offloaded to dedicated threads to avoid blocking the server main thread.

##### Relevant Technologies/Frameworks
- Java 17+ (or Java 11)
- Maven build lifecycle (pom.xml)
- Bukkit/Paper API
- JavaCPP/JavaCV (FFmpeg) native bindings

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    Player(["Player"]):::external
    MinecraftServer(["Minecraft Server<br/>(Paper/Spigot API)"]):::external

    %% Plugin Metadata and Build
    pluginYML(["plugin.yml"]):::data
    pomXML(["pom.xml"]):::data
    JavaCV(["JavaCV/FFmpeg<br/>Native Libs"]):::external

    %% Plugin Core
    subgraph "Plugin Loader & Core"
        direction TB
        Main(["Main"]):::module
        subgraph "Command Handlers"
            direction TB
            PVC(["ProcessVideoCommand"]):::module
            PIC(["ProcessImageCommand"]):::module
            PSC(["ProcessStreamCommand"]):::module
            SRC(["SetResCommand"]):::module
            UC(["UndoCommand"]):::module
        end
        subgraph "Processing Engine"
            direction TB
            VFP(["VideoFrameProcessor"]):::module
            SFP(["StreamFrameProcessor"]):::module
        end
        CM(["ColorManager"]):::module
    end

    %% Thread Boundary Annotation
    subgraph "Processing Thread" 
        direction TB
        VFP
        SFP
    end

    %% Relationships
    Player -->|"chat command"| MinecraftServer
    MinecraftServer -->|invokes| Main
    Main -->|registers commands| PVC
    Main -->|registers commands| PIC
    Main -->|registers commands| PSC
    Main -->|registers commands| SRC
    Main -->|registers commands| UC
    PVC -->|starts| VFP
    PIC -->|starts| VFP
    PSC -->|starts| SFP
    SRC -->|updates config| Main
    UC -->|undo blocks| MinecraftServer
    VFP -->|"decode frame"| JavaCV
    SFP -->|"decode frame"| JavaCV
    VFP -->|"frame data"| CM
    SFP -->|"frame data"| CM
    CM -->|"map colors"| MinecraftServer

    %% Config & Build Flow
    pluginYML -->|loaded at startup| Main
    pomXML -.->|build deps| JavaCV

    %% Click Events
    click Main "https://github.com/darksavci/minecraft-video-player/blob/main/src/main/java/dev/bdinc/minecraft_video_player/Main.java"
    click PVC "https://github.com/darksavci/minecraft-video-player/blob/main/src/main/java/dev/bdinc/minecraft_video_player/ProcessVideoCommand.java"
    click PIC "https://github.com/darksavci/minecraft-video-player/blob/main/src/main/java/dev/bdinc/minecraft_video_player/ProcessImageCommand.java"
    click PSC "https://github.com/darksavci/minecraft-video-player/blob/main/src/main/java/dev/bdinc/minecraft_video_player/ProcessStreamCommand.java"
    click SRC "https://github.com/darksavci/minecraft-video-player/blob/main/src/main/java/dev/bdinc/minecraft_video_player/SetResCommand.java"
    click UC "https://github.com/darksavci/minecraft-video-player/blob/main/src/main/java/dev/bdinc/minecraft_video_player/UndoCommand.java"
    click VFP "https://github.com/darksavci/minecraft-video-player/blob/main/src/main/java/dev/bdinc/minecraft_video_player/VideoFrameProcessor.java"
    click SFP "https://github.com/darksavci/minecraft-video-player/blob/main/src/main/java/dev/bdinc/minecraft_video_player/StreamFrameProcessor.java"
    click CM "https://github.com/darksavci/minecraft-video-player/blob/main/src/main/java/dev/bdinc/minecraft_video_player/ColorManager.java"
    click pluginYML "https://github.com/darksavci/minecraft-video-player/blob/main/src/main/resources/plugin.yml"
    click pomXML "https://github.com/darksavci/minecraft-video-player/blob/main/pom.xml"

    %% Styles
    classDef external fill:#D0E8FF,stroke:#0066CC,color:#003366
    classDef module fill:#E6FFE6,stroke:#009900,color:#006600
    classDef data fill:#FFF2CC,stroke:#CC9900,color:#996600
```
