HS2 PMX Importer

Blender 5.0 importer and portability toolkit for Honey Select 2 PMX exports. The project is designed around a Koikatsu-style workflow: bring the exported model into Blender, preserve the useful HS2 data, prepare materials for atlasing, and produce a package that can continue through a Sheepy/Source/GMod pipeline.

Showcase

The comparison below uses the same Riamu character in HS2 and Blender. The left side is the in-game reference; the right side is the imported Blender result.

This is a progress comparison, not a claim of pixel-identical rendering. The geometry, outfit structure, hair layout, eyes, accessories, UV channels, face overlay source data, and export metadata are being carried across. Blender and Source still need their own lighting and shader treatment to reproduce the exact HS2 presentation.

How It Works

1. The HS2 exporter writes a PMX model plus sidecar material and visual metadata.
2. The Blender importer loads the PMX through MMD Tools and renames the UV channels for portability.
3. Material setup reads the HS2 sidecars, chooses baked or raw textures, preserves alpha sources, and places the unchanged Blender shader graph inside an editable per-material HS2 Shader node group.
4. Face overlays such as eyebrows are reconstructed from exported HS2 texture data, with transparent support textures for Blender and MatCombiner. Eyebrow decals use a curved projected mesh so the forehead cannot occlude their center.
5. Optional cleanup removes penis geometry, merges linked face morphs, and cuts collider bones while preserving their mesh weights.
6. Outfit pieces can be separated into individual meshes and exposed as bodygroups or grouped alternatives.
7. The sidebar can write a Source material plan, run a GMod preflight, and export a marked Sheepy PMX package.

Blender Workflow

1. Import model.pmx from the HS2 export folder.
2. Choose the target skeleton, separation mode, shader mode, and preserved physics bones in the HS2 PMX sidebar.
3. Use Apply HS2 Preview Look for a consistent Blender preview.
4. Use Prep Materials for MatCombiner before atlasing.
5. Use Write Source Material Plan and Run GMod Preflight before packaging.
6. Export the Sheepy PMX package for the downstream porter.

The MMD target option keeps the standard MMD skeleton names and maps HS2 finger bones to MMD-compatible finger names. Hair, breast, gluteal, vaginal, and skirt physics bones are opt-in. Collider bones can be removed with weight merging through the import setting or Cut Collider Bones.

The Bone cleanup section can analyze the active armature against every bound mesh. It distinguishes bones with direct vertex weights from parents that are still needed by weighted descendants, then Remove Disconnected Children deletes only branches with no weights, constraints, animation references, or protected MMD/physics role. Reduce Vaginal Bones transfers the cf_J_Vagina_* weights into a compact six-bone chain by default. A real vagina shape key is not synthesized when the PMX has no source morph, because an identical generated key would be a no-op; the bone reducer is the deformation-preserving option for these exports.

Current Fidelity

The importer is already useful for structure and downstream portability, but visual parity is still an active area of development. The largest remaining differences are:

• HS2 Hanmen skin compositing, softness, subsurface response, and color management.
• Face overlays, makeup strength, eyebrow placement, and eye-layer response.
• Hair anisotropic highlights and the exact HS2 hair alpha treatment.
• Clothing alpha behavior and material response under different Blender lighting.
• Reproducing the HS2 camera, ambient light, reflections, and post-processing in Blender and Source.

The exported baked textures are intentionally retained for portability, while raw texture slots and visual metadata remain available for improved shader reconstruction. Baked AIT body color is not re-layered with its raw nipple map, preventing an offset duplicate nipple pass; the raw nipple slot remains tagged for a future portable body bake. This lets the Blender preview improve without discarding the data needed for GMod materials.

The material strategy is informed by the open-source hs2_blender_export reference implementation: it preserves HS2 skin detail, gloss, bump, eye layers, hair, and clothing inputs, and treats bump strength and alpha blending as separate concerns. Our PMX route keeps the same information in sidecars and generates portable alpha assets when an HS2 overlay stores its mask in RGB instead of the image alpha channel.

Shape Keys

Empty PMX morph copies are removed automatically on import, so inactive namida.* tear keys and duplicated face keys on clothing do not reach GMod. Run print_shape_keys.py with Blender 5.0 to write HS2_ShapeKeyList.txt and a non-overwriting HS2_ShapeKeyWhitelist.template.json beside the opened blend. Select exact names from the report, put them in the template's keep list, optionally add portable names under rename, then choose that JSON in the sidebar and enable Apply shape key whitelist. The same whitelist can be applied while importing or to an existing blend.

Exporter Patches

The exporter_patches directory contains the source patches used to preserve additional UV channels, retain useful HS2 material data, capture face visual metadata, and support downstream Source conversion. The Blender importer can work with an existing compatible export; re-exporting is only needed when a newer exporter-side capture is required.

License and Assets

This repository contains project code and patch documentation. Character cards, game data, exported models, and textures remain user-provided assets and are not included in the repository.