Tanabata — a bridge between Marvelous Designer and Blender

About the name — "Tanabata" is a Japanese word meaning the bridge between the princess of cloth and her prince. This tool connects Marvelous Designer and Blender.

Tanabata moves your character and clothes between Blender and Marvelous Designer (MD) with one click, so you can:

1. Send an animated body from Blender into MD as an avatar.
2. Simulate the cloth on it in MD (your normal MD workflow).
3. Bring the finished garment — with its materials and animation — back into Blender for rendering.

No manual exporting/importing/re-linking textures, and no piles of huge cache files left on your disk: temporary files are reused and cleaned up automatically.

---

What you need

Blender	5.1 (the add-on zip is built for 5.1)
Marvelous Designer	2026 (Personal edition works)
OS	Windows

You do not need to know any coding or use a terminal. Everything is done with buttons and menus.

---

How it works (in one picture)

   Blender  ──(animated body)──►  Marvelous Designer
   (renders)                       (simulates cloth)
            ◄──(garment + anim)──

Blender quietly runs a small "listener". Marvelous Designer sends it the files through a temporary folder. You drive it mostly from MD's menu items, plus two buttons in Blender's Tanabata panel for the final garment animation.

---

Install — Part 1: the Blender add-on

1. Get the file dist/tanabata-0.2.14.zip (Blender 5.1).
2. In Blender: Edit ▸ Preferences ▸ Get Extensions.
3. Click the small ▼ (top-right of that window) ▸ Install from Disk…
4. Choose tanabata-0.2.14.zip.
5. Press N in the 3D viewport — you'll see a "Tanabata" tab in the sidebar on the right.

Install — Part 2: the Marvelous Designer plug-ins

The MD-side scripts live in the md_addon/ folder: 1_get_BL_avater.py, 3_get_BL_animation.py, 2_send_clothes_BL.py, 4_get_export_ABC_name.py.

In Marvelous Designer:

1. Plugins ▸ Plug-in Manager ▸ + ADD
2. Add each of the four .py files above.
3. They now appear under Plugins ▸ Plug-in (by file name):
   • 1_get_BL_avater — frame-1 (static) body → MD
   • 3_get_BL_animation — full animated body → MD
   • 2_send_clothes_BL — garment OBJ + materials + seam metadata → Blender
   • 4_get_export_ABC_name — simulated garment animation → temp (.abc)

---

Before you start: match the frame rate

Set MD's animation FPS to the same value as your Blender scene (e.g. 24).

This is important, not cosmetic: the avatar animation is stored at Blender's frame times. If MD plays at a different FPS it has to interpolate the body between frames, and on fast motion the cloth can intersect or break. Matching the FPS makes MD simulate on the exact body shapes Blender produced.

(Tanabata warns you in the log if it detects a mismatch.)

---

Use it

In Blender, open the Tanabata sidebar tab and click Start Listener once. Leave it on. Then, in the Body field of that same panel, pick your animated character mesh. (Tanabata uses this field — not whatever happens to be selected — so it can't grab the wrong object later.)

By default Tanabata uses %TEMP%\tanabata and cleans/reuses files to save disk. If you want to keep the exchange files for a downstream step such as Houdini Vellum, set Bridge storage in the Blender panel before running the MD plug-ins. With a storage folder set, Tanabata writes avatar_one.abc / avatar_all.abc, garment.obj, garment.abc, and hair_roots.abc there and does not delete them. Leaving the field blank keeps the original temporary-file behavior.

The natural order is 1 → make the garment, 2 → bring it back, 3 → animate:

A. Make the garment (Body frame 1 → MD)

1. MD (empty scene): Plugins ▸ Plug-in ▸ 1_get_BL_avater. This brings in just frame 1 of your character — a fast, light, static avatar.
2. If an Import Alembic dialog appears, the defaults are correct (Avatar, metres, axis Y-up) — click OK.
3. Design / fit your garment on this static avatar as usual.

B. Garment → Blender — shape + materials

1. Blender: make sure Start Listener is on.
2. MD: Plugins ▸ Plug-in ▸ 2_send_clothes_BL. (If your MD build can't export silently, an Export OBJ dialog appears — choose garment only, Thin, "Save texture file paths", then OK.)

Export the garment as THIN (single layer), not Thick. The OBJ and the later simulation Alembic must share the same topology so the materials can be carried back onto the animated garment. A Thick garment doubles the OBJ's faces, the topology no longer matches the Alembic, and the materials can't be applied (the garment comes back untextured). Keep the garment thin for both exports.

→ The garment appears in Blender at frame 1 with its materials already applied (textures are baked into the .blend, so nothing breaks later). At the same time, Tanabata converts the garment seam data into a solver-neutral Blender Text datablock named Ageha_ClothSeams_<object>. The imported garment stores the datablock name and summary as ageha_cloth_* custom properties, so downstream cloth solvers can read the Blender file without knowing whether the garment came from Marvelous Designer or another tool. Tanabata also converts MD sewing pairs into Blender mesh loose edges and adds a disabled Tanabata Sewing Data Cloth modifier with sewing springs enabled. The modifier is a data marker only; Tanabata does not ask Blender's cloth solver to simulate the garment.

Now is the moment to save your MD project. It contains the garment but no animation, so the file is small — and you can re-open it later to dress a different animation. From here on it's the render pipeline.

C. Add the animation (Body all frames → MD → Blender)

1. MD: Plugins ▸ Plug-in ▸ 3_get_BL_animation to bring in the full animated body, then simulate the cloth over the whole clip.
2. MD: Plugins ▸ Plug-in ▸ 4_get_export_ABC_name. This writes the garment animation to a temporary file and is done immediately — MD does not wait for Blender. (If your MD build can't export Alembic silently, it copies the exact save path to the clipboard with pyperclip, then tells you to do File ▸ Export ▸ Alembic once to that path.) You can now close the MD project without saving — the heavy animation stays out of it.
3. Blender: in the Tanabata panel press Import Simulated ABC. The garment animation is loaded onto the garment from step B (materials and the per-face material split are re-applied automatically). The garment now moves on its own — ready to render.
4. Blender: when you're happy, press Remove ABC to delete the temporary Alembic and free the disk.

If the garment looks one frame off the avatar (Blender counts frames from 1, MD from 0): change Frame Offset in the Tanabata panel by ±1 and press Import Simulated ABC again, until it lines up.

---

Disk space

Saving disk space is a core goal. Every transfer reuses a fixed temporary file under %TEMP%\tanabata\… (overwritten each time, so nothing piles up). The avatar and OBJ temporaries are deleted right after use; the garment animation Alembic is removed when you press Remove ABC. So a 50 GB animated cache doesn't sit on your SSD. Your saved MD project stays small too — you save it before the animation goes in (step B), so the animation never bloats it. Marvelous Designer's own export folder is left untouched.

For pipeline work, Bridge storage changes only the file policy: the same fixed filenames are written to your chosen folder, and Tanabata preserves them. That leaves two useful Alembics for Houdini/Vellum-style workflows: the Blender avatar ABC as a collider, and MD's garment ABC as the simulated cloth cache. In this mode Remove ABC intentionally skips deletion.

---

Good to know / limitations

• On MD builds that expose the export options to Python, the OBJ and Alembic exports run with no dialog at all. On builds that don't, Tanabata falls back: the OBJ export opens the normal Export OBJ dialog (click OK), and the Alembic export asks you to do File ▸ Export ▸ Alembic once to the shown path.
• Bringing the garment animation into Blender is a separate button you press in Blender (Import Simulated ABC), not something MD waits for. That's deliberate: MD finishes the moment it has written the file, so it never sits blocked.
• 2_send_clothes_BL.py also writes transfer metadata in the bridge folder, then the Blender listener converts it into internal, solver-neutral ageha.cloth_seams.v1 data on the garment. Ageha does not need to read Tanabata files or know anything about Marvelous Designer. The MD API surface stays intentionally small: only the verified safe calls and ExportPatternJSON(path) are used, because some native getter/list APIs can crash MD instead of raising Python exceptions. The Blender listener also writes sewing pairs as loose mesh edges and records a disabled Cloth modifier named Tanabata Sewing Data; this is metadata for downstream solvers, not a Blender simulation step.
• Export Hair ABC writes the configured Hair Curves object to the bridge folder as hair_roots.abc. Before export it moves each whole strand at least 0.5 mm outside the Body mesh, then restores the original hair in Blender. This keeps the strand shape intact for ZOZO Contact Solver / Vellum-style downstream use.
• Materials come in via the OBJ (base colour + normal map). MD's Alembic does not carry materials reliably, which is exactly why step B exists. On import, Tanabata copies the OBJ's material slots onto the animated garment, pins the textures to the Alembic's own UV, and rebuilds the per-face material split with a Geometry Nodes modifier — so a multi-material garment (e.g. satin body + velvet sleeves) comes back correct, not single-coloured.
• Tested on Blender 5.1.2 and Marvelous Designer 2026 Personal, Windows 11.

---

For developers

• The Blender add-on is a single file (__init__.py) packaged as a Blender extension; build a new zip with blender --command extension build --source-dir . --output-dir dist.
• Wire protocol: one JSON object per line over TCP 127.0.0.1:7422, {"id","method","params"} → {"id","result"|"error"}, one request per connection. Methods: ping, export_body_abc (avatar → MD), import_garment_obj (garment OBJ → Blender). The garment animation Alembic does not use the socket — MD writes it to %TEMP%\tanabata\garment.abc and Blender's Import garment ABC button reads it, so the two apps stay decoupled.
• Long avatar exports use a sentinel file (<file>.done.json, written last) so the client waits for completion instead of holding the socket open.

Cloth seam data for solvers

Tanabata treats MD as one possible garment authoring tool, not as a dependency for cloth solvers. During 2_send_clothes_BL.py, the Blender listener converts the source seam metadata into a Blender-native, solver-neutral payload:

• Object custom properties:
  • ageha_cloth_ready
  • ageha_cloth_seams_text
  • ageha_cloth_schema
  • ageha_cloth_unit
  • ageha_cloth_piece_count
  • ageha_cloth_seam_group_count
  • ageha_cloth_seam_pair_count
• Text datablock:
  • Ageha_ClothSeams_<object>
  • JSON schema name: ageha.cloth_seams.v1

The Text datablock contains pieces, seams, and summary. Each seam pair stores two generic segment references (a and b) with piece_name, shape_kind, start, end, direction, and length. A solver such as Ageha should read this Blender data only; it should not require Marvelous Designer, Tanabata temp files, or MD-specific JSON.

Tanabata also stores Blender Cloth sewing data on the mesh:

• Loose mesh edges are added for MD sewing pairs. They are not part of any face.
• A disabled Cloth modifier named Tanabata Sewing Data is added with use_sewing_springs=True.
• Object custom properties:
  • tanabata_sewing_ready
  • tanabata_sewing_edge_count
  • tanabata_sewing_edges_text
  • tanabata_sewing_modifier
  • tanabata_sewing_status
• Text datablock:
  • Tanabata_SewingEdges_<object>
  • JSON schema name: tanabata.blender_cloth_sewing.v1

Downstream solvers can classify mesh edges by face use: normal structural cloth edges have at least one face, while sewing constraints are loose edges with zero faces.

License

MIT.