vrm-weapon-attach

Attach GLB weapon models to VRM avatar hand bones in Three.js.

2|1|Updated Mar 28, 2026
One-click install
npx skills add https://github.com/viverseofficial/viverse-sdk-skills --skill vrm-weapon-attach
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: vrm-weapon-attach
Source: https://github.com/viverseofficial/viverse-sdk-skills/tree/main/skills/vrm-weapon-attach
Command: npx skills add https://github.com/viverseofficial/viverse-sdk-skills --skill vrm-weapon-attach

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires three, @pixiv/three-vrm.

What problem does it solve?

This skill resolves common 3D integration issues such as props floating at the wrist, incorrect weapon orientation, and lack of natural grip poses when attaching GLB models to VRM avatars in Three.js.

Core Features & Use Cases

  • World-Space Holder Pattern: Prevents matrix propagation issues by using a dedicated group for weapon parenting.
  • Normalized Bone Tracking: Ensures weapons follow animated hand movements accurately by utilizing normalized humanoid bones.
  • Visual Enhancement: Provides built-in logic for emissive glow and material adjustments to make props look integrated.
  • Use Case: Perfect for developers building VRM-based games or social experiences who need to attach swords, bows, or other items to avatar hands with realistic finger curling and orientation.

Quick Start

Use the vrm-weapon-attach skill to configure the weapon holder and sync the sword model to the avatar left hand bone.

Frequently Asked Questions about vrm-weapon-attach

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I attach a 3D weapon GLB model to a VRM avatar hand in Three.js?

To attach a weapon to a VRM avatar, you integrate the GLB prop with the normalized hand bones using the @pixiv/three-vrm framework. This ensures precise positioning and orientation correction so the weapon follows animated hand movements accurately.

Why does my VRM weapon prop float at the wrist instead of the hand?

VRM weapon props float at the wrist due to matrix propagation issues when directly parenting objects. Using a dedicated world-space holder group for weapon parenting prevents this, ensuring the prop aligns correctly with the avatar's hand bone hierarchy.

How can I make a VRM avatar grip a sword with natural finger curling?

You can achieve natural finger curling by utilizing normalized humanoid bone tracking from the @pixiv/three-vrm framework. This manages the bone hierarchy to facilitate accurate hand-grip animations that sync with the attached weapon.

Does the world-space holder pattern fix incorrect weapon orientation on VRM avatars?

Yes, the world-space holder pattern fixes incorrect weapon orientation by preventing matrix propagation issues. It uses a dedicated group for weapon parenting and applies orientation correction to ensure props look properly integrated.

Can I add emissive glow to 3D props attached to VRM avatars?

Yes, you can add emissive glow to attached props. The skill provides built-in logic for visual material enhancement, allowing you to apply emissive glow and material adjustments to make the 3D weapons look integrated with the VRM avatar.

Do I need normalized humanoid bones to animate VRM props in Three.js?

Yes, normalized humanoid bones are required for accurate runtime matrix synchronization. Utilizing the normalized bone hierarchy from @pixiv/three-vrm ensures weapons follow animated hand movements correctly during interactive avatar experiences.