Engage Kill Character Model Expression Repair Blender Addon

中文Readme请点击这里

1. Why

When exporting game models as FBX files, facial expressions are not preserved. The actual vertex offsets for expressions are exported as JSON files (_bs_all.json and _bs_btl.json) in the same directory as the model.

This addon adds expressions as shape keys to the model using data from these JSON files.

2. How to Use

1) Addon Installation

• Place the addon folder in Blender's \scripts\addons\ directory,
  OR
• Use Edit > Preferences... > Add-ons > Install... to select the ZIP file and enable the addon.

2) Addon Usage

a. Import Character Model

Typically located in:
assets\veyron\external\assetbundleresources\character\model\chr\base\

b. Apply Expressions to Character

1. In the 3D Viewport, select:
   Object > Apply BlendShapes from JSON
   
2. Select the expression JSON file corresponding to the model
   (Usually in the same directory as the model file):
   
3. Verify shape keys are properly added:
   

c. Important Notes

• c.1 Adjust the Global Scale Factor during import if needed (default recommended).

• c.2 Duplicate shape keys will be overwritten if re-imported.

• c.3 Using JSON files from other models may cause errors due to vertex mismatches.

• c.4 This addon is exclusively for Engage Kill mobile game models. Compatibility with other games is untested.

• c.5 Languages Supported: Simplified Chinese, Traditional Chinese, English, Japanese

d. Other Features

New in v1.3.0:

1. Automatic PMX Expression Categorization Facial expressions are automatically assigned to the corresponding panels (eyes, mouth).

2. PMX Import of Combined Expressions Loads combined expression JSON files from the following directory: assets/veyron/external/assetbundleresources/effect/advchr/<model_name>/ This import process only handles eye and mouth expressions and does not process bone rotation or external effects.

   Blender 4.0+ Support: When running in Blender 4.0 or higher, combined expressions can optionally be converted into vertex (shape‑key) expressions during import.

New in v1.4.0:

1. One-Click Render Preset (PMX) Rebuilds the game's unlit NPR shader Character/MatcapOutline as a Blender node graph, so an imported PMX is rendered the way the game draws it instead of the dark, light-direction-dependent result MMD-style shading always gives. Select the model, choose a preset and press One-Click Render Preset.

   • Presets live in the addon's presets/ folder: engagekill.json is the general preset shared by every character, and presets/characters/<model>.json overrides it entirely for a single model.
   • The texture folder is auto-detected; set it by hand only when the textures are not stored next to the model.
   • Every texture is read as Non-Color and the view transform must be Raw — the game runs a non-linear (gamma) project, so the shader's numbers are the pixels.

2. Hair Highlight Recovery The sheen band on the hair is sampled from _MatcapHighlightTex through TEXCOORD2, a vertex channel that AssetStudio's FBX export drops and that PMX converters frequently fill in incorrectly. The preset uses it from UV1 when that is a coherent uv, and otherwise rebuilds it from the cache shipped inside the addon (cache/hair_channels_<model>.npz), matched by vertex position. Only when neither source is available is the sheen turned off.

3. Multi-language UI All text added by the above goes through the same translation table as the rest of the addon (Simplified Chinese, Traditional Chinese, English, Japanese), including Blender 5.x's zh_HANS / zh_HANT language identifiers.

New in v1.4.1:

1. Outline Width in Pixels The outline is now measured in pixels of the rendered image (Outline Width (px), default 1.2) and is driven by the camera, so the rim keeps a constant screen width whether the model is framed close or far. It is measured against the same reference the FBX pipeline uses, so the addon and the pipeline draw the same rim.

2. Panel Clean-up The One-Click Render Preset button now matches the rest of the panel, and the redundant hint line under it is gone.

New in v1.4.2:

1. Vertex Colour Recovery The game's shader reads vcol in three places - it scales the shade, it blends the _VertexBColor tint, and it gates the matcap sheen - but a PMX vertex holds only a position, a normal, two uvs, up to four extra uvs and the skin weights. There is no colour field anywhere in the format, so a model imported from a PMX comes in white however faithful the conversion was: an eyelid and eyebrow mesh (face_e) ends up about twice as bright as the FBX, a mouth (face_m) about five times, and tinted hair loses its pink. The preset now matches the bundle's own colour back on by vertex position and uv0, from the cache shipped inside the addon (cache/vcol_channels_<model>.npz). A mesh the bundle draws white stays white, exactly as the game draws it.

3. Credits & Disclaimer

• Code primarily generated by DeepSeek and optimized with ChatGPT.

• Special thanks to UnityPy community and QQ user "Ran Wang Yi" for technical guidance.

• Engage Kill is copyrighted by SQUARE ENIX CO., LTD. (株式会社スクウェア・エニックス).

• Game service has terminated. Official website: https://www.jp.square-enix.com/engage-kill/

• dependencies

  blender-addon-update https://github.com/CGCookie/blender-addon-updater/tree/v1.1.1