One Prompt to 3D Holo Card: Codex Skill Automates Blender + Three.js Pipeline

The article introduces Holo Card Studio (GitHub: EverettFish/holo-card-studio), a Codex Skill that lets users generate fully interactive 3D holographic cards from a single natural-language prompt or a reference image. Instead of a flat PNG, the skill produces a rotatable, flip-able card with parallax depth, laser-foil shimmer, and star-glow effects, delivered as a card.blend editable Blender project plus a Three.js web viewer that runs on desktop and mobile.

🚀 Quick Start

1. Environment Requirements

Python 3 + Pillow : required by generate_typography.py (precise text layer) and validate_assets.py (four-layer asset validation).

Node.js + npm : web viewer depends on [email protected] and a local static server ( server.mjs).

Blender (auto-managed) : run_pipeline.py automatically detects the latest 4.5.x official portable build from https://download.blender.org/release/Blender4.5/, verifies its SHA-256 checksum, and extracts it to <project>/tools/ — no manual install needed and no conflict with system Blender.

2. Installation

Clone the repository into Codex's skills directory:

cd ~/.codex/skills/
git clone https://github.com/EverettFish/holo-card-studio

Codex reads SKILL.md frontmatter ( name: holo-card-studio + description) and auto-invokes the skill for relevant tasks.

3. Usage Examples

After installation, simply tell Codex in plain language:

使用 $holo-card-studio 给我做一张水墨风的锦鲤闪卡，文字用书法体，编号 No.001

Or upload a reference image:

「照这张图做一张闪卡，保留人物和构图，背景换成星空」

Codex echoes the inferred card spec, then executes the full pipeline: image generation → typography layer → config writing → pipeline run → local server launch → browser verification (drag, flip, slider, mobile layout) → delivery. Outputs include a local web URL, card.blend, assets/ four-layer PNGs, card-config.json, and a hero render. The author tested with model deepseek-v4-flash and showed resulting card images and delivered code screenshots.

⬇️ Blender Auto-Install — SHA-256 Verified Portable Build

ensure_blender.py

solves “no Blender installed” with a secure, isolated workflow:

Priority search: CLI override → system PATH blender → <project>/tools/ portable → macOS /Applications.

If missing, fetch platform-specific official package: Windows x64/arm64 zip, Linux linux-x64.tar.xz, macOS dmg.

Download matching .sha256 file and verify integrity.

Safe extraction: reject symlinks, reject zip path traversal; on macOS mount dmg, copy .app, unmount.

Create portable/config beside the portable build so Blender preferences stay project-local.

This design eliminates pre-install friction, guarantees supply-chain integrity via official checksums, and avoids version conflicts. Once downloaded, tools/ is reusable.

⚙️ Configuration — Single Source of Truth in card-config.json

All card metadata and parameters live in <project>/card-config.json, consumed by both Blender and web ends:

Copy fields : title, subtitle, technique, tagline, edition, collection, description.

Asset paths : assets.model ( card.glb) + four PNG layers.

Parallax parameters : parameters.subjectScale (default 1.25), subjectDepth (0.4), backgroundDepth (−0.25), foil (0.65).

Layout safe area : safeArea.scale (1.12), safeArea.offset ([−0.06, −0.085]).

Edit the JSON and re-run run_pipeline.py; both Blender scene and web viewer update simultaneously because they share the same config.

📦 Pure-Text Skill Packaging — Code Only, No User Data

The skill can be packaged into a shareable ZIP. Core principle: the skill repo contains only code and text (lightweight, auditable, diffable). Each user's generated artwork, .blend, and GLB remain in their own output project — not bundled in the skill.

📊 End-to-End Invocation Flow

User prompt / reference image
        │
        ▼
Codex reads SKILL.md + references/ (art spec · config schema · acceptance checklist)
        │  Echo spec → confirm
        ▼
Generate four layers (single 1024×1536 canvas): subject / background / lineart + text layer
        │
        ▼
validate_assets.py health-check (dimensions match · true alpha · lineart white-on-black)
        │
        ▼
run_pipeline.py
        ├─ ensure_blender.py ── official portable SHA-256 → <project>/tools/
        ├─ build_card.py ────── headless Blender builds editable scene → card.blend + hero.png
        ├─ export_web.py ────── strip animation → tag character material → export card.glb
        └─ assemble web/ ────── web-template + four layers + config rewrite + npm install
        │
        ▼
node server.mjs → browser opens
        │  GLSL reconstructs four-layer composite + foil + star + glow using same UV formula
        │  uView = camera × cardRoot.inverseMatrix → foil phase follows view
        ▼
verification.md checklist live-test (drag / flip / slider / mobile layout / screenshot diff)
        │
        ▼
Deliver: web URL + card.blend + four layers + card-config.json + hero render

🏗️ Layered Architecture

The skill follows a clean “instruction → script → asset → artifact” layering:

SKILL.md / agents/openai.yaml — Codex operations manual: declares skill name, trigger description, default prompt, implicit invocation allowance.

references/ — Art specification, config schema, delivery acceptance checklist.

scripts/ensure_blender.py — Auto-discover or install official portable Blender with SHA-256 verification, project-local.

scripts/build_card.py — Procedurally construct editable Blender scene: shared node groups, materials, card geometry, camera, lights, bloom, render settings.

scripts/export_web.py — Export character-material-tagged GLB geometry from card.blend.

scripts/generate_typography.py — Produce pixel-perfect transparent text layers.

scripts/validate_assets.py — Validate dimensions, true alpha, lineart contrast.

scripts/run_pipeline.py — Orchestrates validation → Blender → build → export → web assembly.

scripts/package_skill.py — Whitelist-based text-only audit packaging.

assets/web-template/ — Responsive Three.js viewer + zero-dependency static server.

📚 References

Project repo: https://github.com/EverettFish/holo-card-studio
Official docs: none; SKILL.md + references/ serve as complete manual
Related post: Xiaohongshu @乌托邦的香蕉 (original implementation tutorial)