Hunyuan GLB Generator for Codex

Turn local reference images into GLB assets from Codex using a local Hunyuan3D portable install.

This repository is a Codex plugin marketplace. It packages one plugin, hunyuan-glb-generator, with:

• a Codex skill that teaches the agent the image-to-GLB workflow
• an MCP server that exposes generation tools to Codex
• scripts for starting/stopping the local Hunyuan3D API
• background batch generation with status polling
• low-poly and textured low-poly example manifests and reference images

Why This Is Useful

Hunyuan3D can turn images into 3D models, but managing the local server, settings, output files, and repeated batches is tedious. This plugin lets Codex handle that loop:

1. collect or create reference images
2. start the local Hunyuan3D backend
3. enqueue image-to-GLB jobs
4. poll until they finish
5. save GLBs and metadata into a project asset folder
6. report results, errors, and file sizes

The Hunyuan/Gradio frontend does not need to be open. The plugin uses the backend API. Textured batches can set request_timeout_sec and stop_api_on_item_error so one stalled texture request does not freeze the entire queue.

Requirements

• Windows
• Codex with plugin support
• Python 3 on PATH
• Git, if installing from GitHub
• Local Hunyuan3D portable install containing:
  • python_standalone\python.exe
  • Hunyuan3D-2\api_server.py

If Hunyuan3D is not installed yet, install it from the official project first: Tencent-Hunyuan/Hunyuan3D-2. This plugin does not redistribute Hunyuan3D, model weights, or runtime files.

Quick Install

Clone the repository, then run:

powershell -ExecutionPolicy Bypass -File .\install.ps1 -Gui

The GUI installer asks for the Hunyuan3D portable root, writes per-user config, registers this folder as a Codex marketplace, and installs the plugin when the Codex CLI is available. Before prompting, the installer checks common folders such as C:\AI, D:\AI, the user's AI, Downloads, and Desktop folders for a valid Hunyuan3D portable root.

Noninteractive install:

powershell -ExecutionPolicy Bypass -File .\install.ps1 `
  -HunyuanRoot "C:\path\to\Hunyuan3D2_WinPortable"

If Hunyuan is already in a common location, agents can try:

powershell -ExecutionPolicy Bypass -File .\install.ps1

The installer will auto-detect a root that contains python_standalone\python.exe and Hunyuan3D-2\api_server.py; otherwise it prints the official Hunyuan setup URL and asks for -HunyuanRoot or -Gui.

After install, start a new Codex thread and ask:

Use Hunyuan GLB Generator to generate a low-poly GLB from C:\path\to\reference.png.

One-Line Clone And Install

After this repository is published, users can run:

powershell -NoProfile -ExecutionPolicy Bypass -Command "git clone https://github.com/BeyondRandom/hunyuan-glb-generator-codex.git; Set-Location hunyuan-glb-generator-codex; .\install.ps1 -Gui"

What Codex Gets

Once installed, Codex can use these MCP tools:

• hunyuan_status
• hunyuan_diagnose
• hunyuan_start_api
• hunyuan_stop_api
• hunyuan_generate_from_image
• hunyuan_enqueue_image_batch
• hunyuan_batch_status

The bundled skill tells Codex when to use those tools, which settings are best for small GLBs, and how to run an agentic batch loop. Agents should call hunyuan_diagnose first on unfamiliar machines. It reports whether Hunyuan was configured, auto-discovered, or missing, lists valid discovered roots, recommends texture backend/profile settings, and includes setup guidance when Hunyuan is not found.

For textured Hunyuan3D 2.0 batches, backend: auto selects api_low_vram, which launches a temporary API-compatible low-VRAM server using the same texture offload profile as the Hunyuan UI. Users can force backend: api on high-VRAM machines or set profile manually.

Examples

The plugin includes sample reference images and batch manifests:

• plugins/hunyuan-glb-generator/examples/reference_images/
• plugins/hunyuan-glb-generator/examples/batch_manifest.low-poly.json
• plugins/hunyuan-glb-generator/examples/batch_manifest.textured-low-poly.json
• plugins/hunyuan-glb-generator/examples/batch_manifest.example.json

Known-good sample inputs:

Corn crop tile	Water bucket carry item

Run the low-poly example from the plugin folder:

cd .\plugins\hunyuan-glb-generator
python .\scripts\hy3d_asset_controller.py enqueue --manifest .\examples\batch_manifest.low-poly.json

Run the colored/textured low-poly example:

python .\scripts\hy3d_asset_controller.py enqueue --manifest .\examples\batch_manifest.textured-low-poly.json

See Batch Workflows for reference-image guidance and batch prompts.

Documentation

• Install
• Batch Workflows
• Publishing
• Plugin README

Safety

This plugin controls local Hunyuan3D processes and can use substantial GPU/VRAM. It only stops Python processes whose command line points inside the configured Hunyuan root. Machine-specific config is written to:

%LOCALAPPDATA%\Codex\hunyuan-glb-generator\config.json

No local Hunyuan path needs to be committed to GitHub.

License

This plugin is released under the MIT License.

This repository does not include Hunyuan3D, Hunyuan3D model weights, Tencent source code, Tencent model files, or Tencent trademarks. Users must install Hunyuan3D separately and comply with the license terms that apply to their own use. Tencent is not affiliated with, associated with, sponsoring, or endorsing this plugin. See NOTICE.