Skip to content

Texturepack-BE/Texturepack.BE-Bot

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

3 Commits
README.md
README.md
 
 

Repository files navigation

Minecraft Texture Pack Converter Bot

A Discord bot that automatically converts Minecraft Java Edition texture packs to Bedrock Edition (.mcpack), handling complex image transformations and format differences between the two platforms.

Project Overview

This project solves a real problem in the Minecraft community: Java and Bedrock editions use incompatible texture pack formats. Manual conversion is tedious and error-prone. This bot automates the entire process, handling hundreds of edge cases and format differences.

Live Usage: The bot serves a Discord community, processing texture pack conversions on-demand with a trial system for new users and unlimited access for community members.

Technical Highlights

Architecture

  • Parallelized Pipeline System: Custom-built conversion pipeline that processes independent steps concurrently, significantly reducing conversion time
  • Modular Step-Based Design: 30+ discrete conversion steps, each handling a specific transformation, making the system maintainable and extensible
  • Resource Inventory System: Automatically detects what resources exist in a pack and only runs relevant conversion steps
  • Event-Driven Design: Discord gateway events trigger appropriate handlers for member joins, messages, and interactions

Image Processing

The converter performs sophisticated image manipulations using Sharp (libvips):

Feature Description
Texture Atlas Generation Combines separate texture files into unified sprite sheets (beds, potions)
GUI Reconstruction Extracts and repositions UI elements (hotbar, buttons, XP bars, crosshairs)
Animation Detection Parses .mcmeta files to identify animated textures and generates Bedrock flipbook definitions
Animated Item Conversion Detects frame-based animations and generates Bedrock attachables with render controllers
Resolution Scaling Handles texture packs from 16x to 512x with proper nearest-neighbor interpolation
Transparency Fixes Corrects alpha channel issues in armor and item textures
Skybox Conversion Converts OptiFine/MCPatcher custom skies to Bedrock format with subpack support
Pixel-Level Manipulation Custom alpha blending and compositing for totem generation

Example: Bed Texture Generation

Java Edition stores bed textures as 6 separate images. Bedrock requires a single atlas per color. The converter:

  1. Loads all 6 source textures (head_top, feet_top, head_end, feet_end, head_side, feet_side)
  2. Applies rotations and flips to match Bedrock's UV mapping
  3. Extracts specific regions and composites them onto a 64x64 canvas
  4. Mirrors side areas and generates leg geometry
  5. Outputs 16 color variants (one per wool color)

Example: Totem Generation from Skin

The /totem command transforms a 64x64 Minecraft skin into a 16x16 "Mini Me" totem:

┌─────────────────┐          ┌──────────┐
│   Minecraft     │          │  Totem   │
│   Skin (64x64)  │    ──►   │  (16x16) │
├─────────────────┤          ├──────────┤
│ ┌───┐           │          │  ┌────┐  │
│ │ H │ Head      │          │  │Head│  │
│ └───┘           │          │  ├────┤  │
│ ┌───┐           │          │  │Body│  │
│ │ B │ Body      │          │  │+Arm│  │
│ └───┘           │          │  ├────┤  │
│ ┌─┐ ┌─┐         │          │  │Legs│  │
│ │A│ │A│ Arms    │          │  └────┘  │
│ └─┘ └─┘         │          └──────────┘
│ ┌─┐ ┌─┐         │
│ │L│ │L│ Legs    │     Z-Order Rendering:
│ └─┘ └─┘         │     1. Body + Overlay
└─────────────────┘     2. Arms (same level)
                        3. Legs & Feet
                        4. Head (top layer)

Technical Details:

  • Extracts specific UV regions from skin atlas
  • Bilinear interpolation for scaling
  • Custom blendPixels() for alpha compositing
  • Supports both 32-height (legacy) and 64-height skin formats
  • Outputs ready-to-use .mcpack with manifest

Example: Animated Items System

Java texture packs can include animated item textures (swords, tools, etc.). The bot automatically detects and converts these:

Detection Phase                    Conversion Phase
─────────────────                  ──────────────────
┌─────────────────┐               ┌─────────────────────────┐
│ Vertical Stack  │               │ Bedrock Attachable JSON │
│ ┌───┐           │               │ ├── textures[]          │
│ │ 1 │ Frame 1   │               │ │   ├── frame_0.png     │
│ ├───┤           │    Extract    │ │   ├── frame_1.png     │
│ │ 2 │ Frame 2   │    ──────►    │ │   └── frame_N.png     │
│ ├───┤           │               │ ├── render_controller   │
│ │ 3 │ Frame 3   │               │ │   └── query.life_time │
│ └───┘           │               │ └── animations[]        │
└─────────────────┘               └─────────────────────────┘

Supported Layouts:
• Vertical:   height > width  (frames stacked)
• Horizontal: width > height  (frames side-by-side)
• Grid:       2x2 to 8x8      (frames in matrix)

Supported Items: Swords, pickaxes, axes, shovels, hoes (all materials), plus special items like mace, trident, ender pearl, and more.

Backend Integration

  • Supabase Database: Tracks user trials, usage statistics, and cooldowns
  • Discord.js v14: Modern slash command interface with deferred replies for long operations
  • Trial System: Non-members get 3 free conversions; server members get unlimited access
  • Real-time API Integration: Fetches live statistics from texturepack.be API
  • Partner Reward System: Tracks server claims and verification for community rewards

Commands

Command Description
/port Convert a Java Edition texture pack to Bedrock Edition (.mcpack)
/totem Generate custom totem textures from Minecraft skins or images
/pack Browse random texture packs from the Texturepack.BE collection
/sky Convert an equirectangular panorama image to a Bedrock skybox pack
/recolor-beta Recolor a Bedrock texture pack to a custom HEX color
/claim Partner program: claim servers for rewards (Partner Managers)
/config Manage allowed bot channels (Admin only)
/help Show all available commands and server invite

/port

The main conversion command. Upload a Java Edition texture pack (.zip, .jar, or .rar) and receive a converted Bedrock Edition .mcpack file.

Features:

  • Comprehensive error handling (cooldown, trial limits, validation, size limits)
  • Detailed success response with conversion stats (size, file count, duration)
  • Trial tracking for non-members

/totem

Generate custom totem of undying textures with two modes:

Skin Mode:

  • Upload a Minecraft skin (64x64 or 64x32 PNG)
  • Extracts body parts and composites them into a "Mini Me" totem
  • Z-ordered rendering ensures proper layering

Random Mode:

  • Upload any image (PNG/JPG/WebP)
  • Crops to center-square and converts to totem texture

/pack

Discover texture packs from the database. Shows pack details including resolution, download count, and tags. Use the "Next" button to browse through the collection.

/sky

Create custom skybox overlays for Bedrock Edition. Upload an equirectangular panorama image (PNG/JPG/WebP) and receive a ready-to-use .mcpack with the converted cubemap faces.

/recolor-beta

Experimental feature to recolor an entire Bedrock texture pack. Upload a .mcpack or .zip file along with a target HEX color (e.g., #FF0000), and the bot will shift all textures to match.

/claim

Partner program for community growth:

  • Claim server IDs before inviting the bot
  • Claims verified when bot joins servers with 75+ members
  • 7-day expiry for unverified claims

/config

Server administrators can restrict the bot to specific channels:

  • /config add [channel] - Add a channel to the allowed list
  • /config remove [channel] - Remove a channel from the allowed list
  • /config list - View all configured channels

/help

Displays all available commands with descriptions and provides a button to join the Texturepack.BE Discord server.

Community Features

Welcome System

Automated welcome messages for new members joining the main server:

┌────────────────────────────────────────┐
│  Welcome to Texturepack.BE!            │
│  ──────────────────────────────────    │
│  👤 @NewUser                           │
│  📊 Member #1,234                      │
│                                        │
│  ┌──────────────────────────────────┐  │
│  │ Custom fields & information     │  │
│  └──────────────────────────────────┘  │
│                                        │
│  [User Avatar]              [Timestamp]│
└────────────────────────────────────────┘

Configurable Options:

  • Enable/disable system
  • Embed or plain text mode
  • Custom image attachments
  • Dynamic placeholders: {user}, {username}, {server}, {memberCount}
  • Custom embed colors, fields, footer

Status Dashboard (Owner)

Real-time bot statistics with auto-refresh every 10 minutes:

Metric Source
Packs texturepack.be API
Downloads texturepack.be API
Servers Discord client cache
Users Aggregated guild members
Commands Bot command collection

Tech Stack

Technology Purpose
Node.js 18+ Runtime
Discord.js v14 Bot framework with gateway intents
Sharp (libvips) High-performance image processing
Archiver/Unzipper Pack compression/extraction
Supabase Database & authentication
REST APIs External service integration

Conversion Pipeline

Input (.zip/.jar/.rar)
    │
    ├─► Extract Archive
    ├─► Validate Structure
    ├─► Parse pack.mcmeta
    │
    ├─► [Parallel] Scan Resolutions
    ├─► [Parallel] Inventory Resources
    │
    ├─► [Parallel] Copy & Transform Textures
    ├─► [Parallel] Copy Additional Resources (sounds, fonts, colormaps)
    │
    ├─► Detect Animated Textures
    │
    ├─► [Parallel] Generate UI Elements
    │   ├── Buttons
    │   ├── Hotbar
    │   ├── XP Bars
    │   ├── Crosshair
    │   └── Effect Icons
    │
    ├─► [Parallel] Generate Entity Textures
    │   ├── Beds (16 colors)
    │   ├── Potions
    │   └── Particles
    │
    ├─► [Parallel] Environment
    │   ├── Title Screen
    │   └── Skybox (with subpacks)
    │
    ├─► [Parallel] Fix Transparency Issues
    │   ├── Armor Layers
    │   └── Item Textures
    │
    ├─► [NEW] Port Animated Items
    │   ├── Detect animation layouts (vertical/horizontal/grid)
    │   ├── Extract individual frames
    │   ├── Generate Bedrock attachables
    │   └── Create render controllers
    │
    ├─► Write Bedrock Configs
    │   ├── manifest.json
    │   ├── flipbook_textures.json
    │   └── _global_variables.json
    │
    └─► Create .mcpack
            │
            ▼
      Output (Bedrock-compatible pack)

Project Structure

src/
├── commands/              # Discord slash commands
│   ├── port/              # Main conversion command
│   ├── totem/             # Totem generator (skin & random modes)
│   ├── claim/             # Partner reward system
│   ├── sky/               # Skybox converter
│   ├── pack/              # Pack browser
│   ├── recolor/           # Color shifting
│   ├── config/            # Channel management
│   └── help/              # Help menu
│
├── events/                # Discord event handlers
│   ├── interactionCreate.js   # Slash command routing
│   ├── messageCreate.js       # Prefix commands & status
│   └── guildMemberAdd.js      # Welcome system
│
├── services/
│   ├── converter/
│   │   ├── optimizedConverter.js   # Main conversion orchestrator
│   │   ├── pipeline.js             # Pipeline runner
│   │   └── steps/                  # 30+ conversion steps
│   │       ├── generateBeds.step.js
│   │       ├── generateHotbar.step.js
│   │       ├── detectAnimations.step.js
│   │       ├── portAnimatedItems.step.js   # [NEW] Animated items
│   │       └── ...
│   │
│   └── database/          # Supabase integration
│
├── data/                  # Persistent JSON storage
│   └── claims.json        # Partner claims tracking
│
├── utils/
│   ├── trialCheck.js      # Trial system logic
│   ├── validation.js      # Input validation
│   └── fileSystem.js      # File operations
│
├── config/
│   └── index.js           # Centralized configuration
│
└── templates/
    └── bedrock-base/      # Base Bedrock pack template

Key Engineering Decisions

  1. Pipeline over Monolith: Each conversion step is isolated, testable, and can be parallelized where dependencies allow

  2. Resource Detection: Rather than attempting all conversions, the system first inventories what exists and only runs relevant steps

  3. Scale-Aware Processing: All image operations use a scale factor derived from the source resolution, ensuring correct output at any texture pack size

  4. Memory Efficiency: Uses Sharp's streaming capabilities and cleans up temporary files immediately after use

  5. Batch Processing: Animated items are processed in batches of 20 to avoid file handle limits and memory issues

  6. Graceful Degradation: Comprehensive error handling with user-friendly messages for every failure scenario

  7. Configurable Systems: Welcome messages, reward tiers, and channel restrictions are highly customizable without code changes

System Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                         Discord Gateway                              │
└─────────────────────────────────────────────────────────────────────┘
                                    │
         ┌──────────────────────────┼──────────────────────────┐
         ▼                          ▼                          ▼
┌─────────────────┐    ┌─────────────────────┐    ┌─────────────────┐
│  Slash Commands │    │   Message Events    │    │  Member Events  │
│  ─────────────  │    │   ──────────────    │    │  ────────────   │
│  /port          │    │  tpbe status        │    │  guildMemberAdd │
│  /totem         │    │  (owner prefix)     │    │  └─► Welcome    │
│  /sky           │    │                     │    │      System     │
│  /pack          │    │                     │    │                 │
│  /claim         │    │                     │    │                 │
└────────┬────────┘    └──────────┬──────────┘    └─────────────────┘
         │                        │
         ▼                        ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         Services Layer                               │
├─────────────────┬─────────────────────┬─────────────────────────────┤
│   Converter     │     Database        │        External APIs         │
│   ─────────     │     ────────        │        ─────────────        │
│   Pipeline      │     Supabase        │     texturepack.be/api      │
│   30+ Steps     │     - Trials        │     - Pack stats            │
│   Image Proc.   │     - Cooldowns     │     - Download counts       │
└─────────────────┴─────────────────────┴─────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        Output Generation                             │
│   ─────────────────────────────────────────────────────────────     │
│   .mcpack files │ Embed responses │ Status updates │ File uploads   │
└─────────────────────────────────────────────────────────────────────┘

License

ISC

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors