Resource Pack Generation

How BetterModel automatically generates and serves resource packs

Overview

BetterModel automatically generates resource packs from your BlockBench models, including all necessary textures, model files, and metadata. This guide explains how the system works and how to customize it.

Automatic Generation

How It Works

When BetterModel loads:

1. Scans models: Reads all .bbmodel files from models/ and players/
2. Extracts assets: Pulls textures, geometries, and animations
3. Generates pack: Creates a complete resource pack structure
4. Builds pack file: Zips everything into a .zip file
5. Serves pack: Hosts the pack for players to download

The resource pack is regenerated on every plugin reload or server restart. Changes to models require a reload to take effect.

Pack Structure

BetterModel generates a standard Minecraft resource pack:

BetterModel-Pack.zip
├── pack.mcmeta
├── pack.png (optional)
└── assets/
    └── bettermodel/
        ├── models/
        │   └── item/
        │       ├── demon_knight_head.json
        │       ├── demon_knight_body.json
        │       └── ...
        └── textures/
            ├── demon_knight_texture.png
            └── ...

Pack Metadata

The pack.mcmeta file is automatically generated:

{
  "pack": {
    "pack_format": 48,
    "description": "BetterModel auto-generated resource pack"
  }
}

The pack format is automatically adjusted based on your Minecraft version.

Pack Distribution

Built-in Server

BetterModel includes a built-in HTTP server to distribute packs:

# config.yml
resource-pack:
  enabled: true
  port: 8080
  host: "0.0.0.0"

Players automatically download the pack when joining.

External Hosting

For production servers, host the pack externally:

If using a public file host, ensure the direct download link is used, not a preview page.

Pack Builder API

Understanding PackBuilder

The PackBuilder class lets you add custom resources:

import kr.toxicity.model.api.pack.PackBuilder;
import kr.toxicity.model.api.BetterModel;

// Access during pack generation
PackBuilder builder = // obtained during pack build

Adding Custom Resources

Add custom files to the pack:

import kr.toxicity.model.api.pack.PackBuilder;

PackBuilder builder = // your pack builder

// Add a custom texture
builder.resolve("textures", "custom")
    .add("my_texture.png", () -> readTextureBytes());

// Add a custom model
builder.resolve("models", "item")
    .add("custom_item.json", () -> generateModelJson());

// Add with estimated size (for optimization)
builder.add("custom_file.png", 4096, () -> readFileBytes());

Pack Path Resolution

Navigate pack paths:

// Resolve nested paths
PackBuilder itemModels = builder.resolve("models", "item");
PackBuilder textures = builder.resolve("textures", "entity");

// Add resources at resolved paths
itemModels.add("sword.json", () -> swordModel);
textures.add("dragon.png", () -> dragonTexture);

Resource Obfuscation

BetterModel includes name obfuscation to prevent conflicts:

import kr.toxicity.model.api.pack.PackObfuscator;

PackObfuscator obfuscator = builder.obfuscator();

// Generate obfuscated names
String obfuscatedName = obfuscator.next(); // "a", "b", "c", ...

Obfuscation prevents namespace conflicts when multiple plugins add resources to the pack.

Pack Events

Pack Build Events

Listen for pack generation:

import kr.toxicity.model.api.event.pack.*;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class PackListener implements Listener {
    
    @EventHandler
    public void onPackBuild(PackBuildEvent event) {
        PackBuilder builder = event.builder();
        
        // Add custom resources
        builder.resolve("models", "custom")
            .add("my_model.json", () -> generateModel());
        
        System.out.println("Custom resources added to pack");
    }
}

Advanced Customization

Custom Pack Icon

Add a custom pack.png:

@EventHandler
public void onPackBuild(PackBuildEvent event) {
    PackBuilder builder = event.builder();
    
    // Add pack icon
    builder.add("pack.png", () -> {
        try {
            return Files.readAllBytes(Path.of("plugins/BetterModel/pack_icon.png"));
        } catch (IOException e) {
            return new byte[0];
        }
    });
}

Custom Pack Metadata

Modify pack.mcmeta:

import kr.toxicity.model.api.pack.PackMeta;
import com.google.gson.JsonObject;

@EventHandler
public void onPackBuild(PackBuildEvent event) {
    PackBuilder builder = event.builder();
    
    // Create custom metadata
    JsonObject packMeta = new JsonObject();
    JsonObject pack = new JsonObject();
    pack.addProperty("pack_format", 48);
    pack.addProperty("description", "My Custom Pack");
    packMeta.add("pack", pack);
    
    // Add to pack
    builder.add("pack.mcmeta", () -> 
        packMeta.toString().getBytes()
    );
}

Multiple Namespaces

Organize resources under multiple namespaces:

// BetterModel namespace
builder.resolve("assets", "bettermodel", "models")
    .add("model1.json", () -> model1Data);

// Custom namespace
builder.resolve("assets", "myplugin", "models")
    .add("model2.json", () -> model2Data);

Pack Overlays

BetterModel supports version-specific overlays:

import kr.toxicity.model.api.pack.PackOverlay;

// Pack overlays allow version-specific resources
// This is handled automatically by BetterModel

Performance Optimization

Pack Size

Keep pack size reasonable:

• Texture resolution: Use 512x512 or lower
• Model complexity: Optimize polygon count
• Animation data: Remove unused keyframes
• Compression: BetterModel automatically compresses

Large resource packs (>50MB) can cause:

• Long download times
• Client lag during loading
• Memory issues on low-end clients

Pack Caching

BetterModel caches pack data:

• Pack hash: Generated once per reload
• Resource data: Loaded on-demand
• Texture processing: Cached after first access

Async Pack Building

Pack generation is asynchronous:

// Pack builds in background thread
// Server continues running normally
// Players can join during pack generation

Pack Configuration

Server Configuration

# config.yml
resource-pack:
  # Enable automatic pack generation
  enabled: true
  
  # HTTP server settings
  server:
    enabled: true
    port: 8080
    host: "0.0.0.0"
  
  # Pack metadata
  description: "BetterModel Resource Pack"
  
  # Require pack
  required: true
  
  # Custom pack URL (overrides built-in server)
  url: ""
  
  # SHA-1 hash (auto-generated if empty)
  sha1: ""

Client-Side Requirements

Players must have:

• Resource packs enabled
• Sufficient memory (for large packs)
• Network connection to download

Troubleshooting

Pack Not Loading

Symptoms: Players don’t see models

Solutions:

1. Check server logs for pack generation errors
2. Verify pack file exists: plugins/BetterModel/pack/
3. Test pack download URL manually
4. Check firewall settings for HTTP server
5. Verify server.properties settings

Textures Missing

Symptoms: Models appear with missing textures

Solutions:

1. Ensure textures are in the same directory as .bbmodel
2. Check texture paths in BlockBench
3. Verify texture files are valid PNG format
4. Reload the plugin to regenerate pack

Pack Size Too Large

Symptoms: Slow downloads, client lag

Solutions:

1. Reduce texture resolution
2. Optimize model complexity
3. Remove unused animations
4. Use external hosting with CDN
5. Split models across multiple plugins

Version Mismatch

Symptoms: “Incompatible pack” error

Solutions:

1. Check Minecraft version compatibility
2. Verify pack_format in pack.mcmeta
3. Update BetterModel to latest version
4. Use pack overlays for multi-version support

Manual Pack Management

Extracting the Pack

cd plugins/BetterModel/pack
unzip BetterModel-Pack.zip -d extracted/

Modifying the Pack

1. Extract the pack
2. Make changes to files
3. Re-zip the pack
4. Update server.properties with new URL/hash

Testing Pack Changes

# Generate SHA-1 hash
sha1sum BetterModel-Pack.zip

# Update server.properties
resource-pack-sha1=<new-hash>

# Restart or reload

Best Practices

Production Recommendations:

• Host packs externally for better performance
• Use CDN for global distribution
• Version your pack files
• Keep pack size under 20MB when possible
• Test packs on different client versions
• Monitor pack download success rate

Development Workflow

1. Create model in BlockBench
2. Export to plugins/BetterModel/models/
3. Run /bettermodel reload
4. Test in-game
5. Iterate on model/textures
6. Export final pack for production

Version Control

# Track generated packs
git add plugins/BetterModel/pack/BetterModel-Pack.zip
git commit -m "Update resource pack v1.2.3"
git tag pack-v1.2.3

Next Steps

API Reference

Explore the complete API

Installation

Install and configure BetterModel