A BlockBench plugin for exporting arbitrary 3D models into Minecraft resource packs using custom core shaders.

Forked from Godlander's objmc — the original Python-based tool that pioneered the technique of encoding OBJ mesh data into textures and decoding it in vanilla Minecraft shaders.

obj^3 replaces the Python script + CLI workflow with a single BlockBench plugin.

Model geometry (vertex positions, UVs, face indices) is encoded into a specially formatted PNG texture. A set of core shaders included in the resource pack reads this texture at render time, reconstructing the 3D mesh from the pixel data. The vanilla Minecraft renderer displays the result — no mods required.

• Direct BlockBench export — File > Export as obj^3
• Keyframe animation baking — BB animations are baked frame-by-frame into the encoded texture
• Armature & bone skinning — weighted vertex skinning from BB Generic Model rigs
• Multi-texture atlas — combine multiple textures into one atlas automatically
• Datapack generation — animation control functions (play, stop, play_once, etc.) with GameTime sync
• Display transforms — per-slot rotation/translation (thirdperson, head, ground, fixed)
• Custom PNG encoder — bypasses browser alpha premultiplication to preserve exact RGB values

• BlockBench 4.8.0+ (desktop variant)
• Minecraft 1.21+ (core shaders)
• Compatible with 26.1-snapshot-9 and later

Modded compatibility is not guaranteed. Core shaders are a vanilla resource pack feature.

1. Download objcubed.js
2. In BlockBench: File > Plugins > Load Plugin from File > select objcubed.js
3. Copy the objcubed/ resource pack folder to your Minecraft resourcepacks/ directory

1. Open or create a model in BlockBench (Generic Model or any format with mesh/cube elements)
2. File > Export > Export as obj^3...
3. Configure settings in the export dialog:
   • Texture — select texture or enable atlas for multiple textures
   • Transform — scale and offset the model
   • Animation — select animation, set FPS and time range
   • Display — rotation/translation per display slot (sliders)
   • Advanced — easing, interpolation, color behavior, autorotate
4. Click Export — saves a PNG (encoded model) and JSON (Minecraft model) to your chosen location

When animation is enabled, you can generate a datapack for controlling animation via commands:

• play — start autoplay loop synced to GameTime
• stop — freeze at current frame
• set — freeze at a specific frame (set score before calling)
• play_from — autoplay starting from frame N
• play_once — play one cycle then freeze at last frame (shader-driven, no tick function needed)

Target types: equipment entity, item_display, or player (via temporary armor stand).

Example:

execute as @e[type=armor_stand] run function mypack:animations/walk/play

objcubed/
  pack.mcmeta
  assets/minecraft/
    shaders/
      core/
        terrain.vsh / terrain.fsh    — placed blocks
        block.vsh / block.fsh        — falling blocks, pistons
        entity.vsh / entity.fsh      — entities, armor
        item.vsh / item.fsh          — items in hand + GUI
      include/
        objmc_main.glsl              — core model decoding
        objmc_tools.glsl             — vertex math utilities
        objmc_light.glsl             — lightmap sampling
    models/custom/                   — your exported JSON models
    textures/block/                  — your exported PNG textures

objmc models add minimal overhead — mostly extra texture fetches. Performance scales linearly with face count. A 20K-face block model performs similarly to rendering ~3300 regular blocks without culling. Block models are significantly more performant than entity models.

High face counts (50K+) in a single chunk section can hit the UberGpuBuffer 2MB limit and crash the game. Use blockstate overrides to redirect high-poly block models if needed.

Items with overlay color (potions, dyed leather armor) can pass data to the shader through RGB bytes. The colorbehavior setting defines what each byte controls:

• direct — passes the channel value directly as model color (tint). With all three channels set to direct, custom_color is used as an RGB tint multiplied with the texture. White (0xFFFFFF) preserves the original texture; other values tint it.
• time — animation time offset
• scale — model scale
• overlay — overlay color hue (converts value to HSV palette color)
• hurt — hurt flash (red tint)

Default is direct/direct/direct.

Example — tint a model red:

give @s minecraft:potion[potion_contents={custom_color:16711680}]

When colorbehavior = time/time/time (set automatically when generating a datapack), the shader uses potion_contents.custom_color as a 24-bit animation control value. Values below 8388608 are autoplay offsets; values above are manual frame indices.

• Flipped UV — BlockBench OBJ export sometimes flips UVs. Use the Flip UV option if the model looks wrong.
• Alpha preservation — The plugin uses a custom PNG encoder (Node.js zlib) instead of canvas to avoid alpha premultiplication corrupting RGB data.
• Texture size — Minimum 8px wide. Wider textures are recommended for high vertex counts or animations.
• Frame count — More FPS and longer animations = larger texture. The shader interpolates between frames, so fewer keyframes are often sufficient.

Godlander — original objmc concept, Python tool, and core shaders

JagerMeistars — obj^3 BlockBench plugin (this fork)

• vilder50 — original concept of mesh models
• Onnowhere — formatting and testing
• DartCat25 — early development help
• The Der Discohund — matrix operations
• Suso — controlled interpolated animation concept
• Dominexis — spline math
• Barf Creations — Minecraft Pose rotation matrix replication
• kumitatepazuru — CLI arguments for original script
• Daminator — tkinter GUI
• thebbq — edge case debugging and stability
• midorikuma — concept of using player heads to encode arbitrary models

MIT License (c) 2022 Godlander. See LICENSE.