NPC Attachments

NPC attachments define customizable parts that can be attached to character models, including eyes, ears, hair, beards, and faces. These are primarily used for player character customization but can also be applied to humanoid NPCs.

Tip

Attachments are configured in model definitions via DefaultAttachments and RandomAttachmentSets. See the Model Definitions - Attachments section for the full schema and JSON examples.

Asset Locations

• DirectoryAssets/Common/Characters/

  • DirectoryBody_Attachments/

    • DirectoryEyes/

      • Eyes.blockymodel
      • Eyes_Fullbright_Pupil.blockymodel
      • DirectoryEyes_Textures/

        • …
    • DirectoryEars/

      • Ears1.blockymodel
      • Elf_Ear_Small.blockymodel
    • DirectoryEyebrows/

      • …
    • DirectoryMouths/

      • …
    • DirectoryFaces/

      • Player_Face_Detached.blockymodel
    • DirectoryBeards/

      • Full.blockymodel
      • VikingBeard.blockymodel
      • (35+ beard styles)
  • DirectoryHaircuts/

    • GenericShort.blockymodel
    • PonyTail.blockymodel
    • Mohawk.blockymodel
    • (180+ hairstyles)
  • Player.blockymodel
  • DirectoryPlayer_Textures/

    • …

Attachment Types

Eyes

Eye attachments define the eye shapes and textures for characters.

Model	Description
Eyes.blockymodel	Standard eyes
Eyes_Fullbright_Pupil.blockymodel	Eyes with bright pupils

Available Textures:

• Greyscale.png - Standard grayscale (for tinting)
• Greyscale_Large.png - Larger eye variant
• Almond_Greyscale.png - Almond-shaped eyes
• Plain_Greyscale.png - Simple eye design
• Eyes_Square_Pupil.png - Square pupil style
• Outlander_Brown.png - Brown outlander eyes
• Outlander_Red.png - Red outlander eyes

Ears

Ear attachments provide different ear shapes.

Model	Description
Ears1.blockymodel	Standard ears
Elf_Ear_Small.blockymodel	Small elven ears

Beards

Beard attachments for facial hair customization.

Category	Styles
Short	Goatee, SoulPatch, ThinGoatee
Medium	Full, Trimmed, Groomed, Medium
Long	Full_Long, GoateeLong, Large
Styled	Curly, Wavy, Handlebar, TwirlyMoustache
Braided	DoubleBraid, TripleBraid
Themed	PirateBeard, PirateGoatee, VikingBeard, Soldier
Simple	Simple, SimpleLong, ShortTrimmed

Full Beard List:

• ChinCurtain, Curly, Full, Full_Long
• Goatee, GoateeLong, Groomed, Groomed_Large
• Handlebar, Hip, Large, Medium
• Moustache, PirateBeard, PirateGoatee
• ShortTrimmed, Simple, SimpleLong
• Soldier, SoulPatch, Stylish
• ThinGoatee, Trimmed, TripleBraid
• TwirlyMoustache, VikingBeard, Wavy

Most beards use _Greyscale.png textures for color tinting.

Haircuts

Over 180 hairstyle options organized by category:

Category	Examples
Short	GenericShort, SuperShort, Short, Quiff, QuiffLeft
Medium	GenericMedium, BobCut, SimpleBobcut, MessyBobcut
Long	GenericLong, Long, LongCurly, WavyLong, LongBangs
Ponytails	PonyTail, SidePonytail, PuffyPonytail, WavyPonytail, WidePonytail
Braids	Braid, BraidDouble, ThickBraid, WavyBraids, BraidedPonytail
Buns	Bun, FighterBuns, PonyBuns, SideBuns, StraightHairBun, RoseBun, ElfBackBun
Pigtails	Pigtails, LongPigtails, SmallPigtails, LongHairPigtail, SingleSidePigtail
Curly	Curly, CurlyShort, MediumCurly, LongCurly, FrizzyLong
Wavy	WavyShort, WavyLong, MessyWavy, EmoWavy, OmbreWavy
Mohawks	Mohawk, RaiderMohawk
Dreadlocks	Dreadlocks, Dreadlocks02, Dreadlocks03, ShortDreads
Bangs	Bangs, LongBangs, EmoBangs, CuteEmoBangs, BangsShavedBack, Fringe
Slicked	Slickback, SuperSlickback, Sideslick, SuperSideSlick
Cultural	Cornrows, BantuKnot, AfroPuffs, Frizzy_Volume
Themed	Viking, VikingWarrior, Viking_TopKnot, Samurai, Berserker
Emo/Scene	Emo, EmoBangs, EmoWavy, CuteEmoBangs
Fantasy	Cat, Wings, Witch, MaleElf, ElfBackBun

Faces

Detached face attachments for special character types.

Model	Description
Player_Face_Detached.blockymodel	Detached face for customization

Eyebrows & Mouths

Additional facial feature attachments.

Type	Location
Eyebrows	Body_Attachments/Eyebrows/
Mouths	Body_Attachments/Mouths/

Texture Conventions

Greyscale Textures

Most attachments use grayscale textures (*_Greyscale.png) that are tinted at runtime:

Beard_Greyscale.png    → Tinted to match hair color
Haircut_Greyscale.png  → Tinted to match selected color
Eyes_Greyscale.png     → Tinted to match eye color

This allows a single model/texture to support multiple colors.

Color Textures

Some attachments have pre-colored textures:

Outlander_Brown.png    → Fixed brown color
Outlander_Red.png      → Fixed red color

Creating Custom Attachments

Hair Attachment

MyPlugin_Haircut.blockymodel
MyPlugin_Haircut_Greyscale.png

Requirements:

• Model anchored to head bone
• Grayscale texture for color tinting
• Proper UV mapping

Beard Attachment

MyPlugin_Beard.blockymodel
MyPlugin_Beard_Greyscale.png

Requirements:

• Model anchored to jaw/chin area
• Grayscale texture for tinting
• Compatible with face animations

Eye Attachment

MyPlugin_Eyes.blockymodel
MyPlugin_Eyes_Greyscale.png

Requirements:

• Model positioned at eye sockets
• Support for blinking animations
• Grayscale for iris color tinting

Best Practices

1. Use grayscale textures - Enables color customization
2. Follow bone naming - Match existing attachment points
3. Test with animations - Verify attachments move correctly
4. Optimize geometry - Keep polygon count reasonable
5. Match art style - Follow Hytale’s voxel aesthetic
6. Consider clipping - Test with various body types
7. Support tinting - Use grayscale for customizable colors

Related

• NPC Overview - NPC system overview
• Model Definitions - NPC model configuration
• NPC Behaviors - Behavior system
• NPC Groups - Group membership