🎨Character Head Builder

Upload custom hair and hat sprites for your server's character renderer

Overview

The Character Head Builder allows server administrators to upload their custom Ragnarok GRF files for character head rendering in Discord embeds. This includes hairstyles, headgear/accessories, and palettes.

Required Preparation

Before uploading, you must create a GRF file containing your custom sprites using GRF Editor or similar tools.

Download GRF Tools: https://irowiki.org/wiki/Tools

Your GRF should contain only the custom sprites and configurations you want to use—you don't need to include the entire client.

GRF Structure Requirements

Your GRF should contain files organized like this:

Content Type
GRF Path

Hair Sprites

data/sprite/Àΰ£Á·/¸Ó¸®Åë/³²/*.spr / ¿©/*.spr

Hat Sprites

data/sprite/¾Ç¼¼»ç¸®/³²/*.spr / ¿©/*.spr

Hat Config

data/luafiles514/lua files/datainfo/accessoryid.lub

Hat Names

data/luafiles514/lua files/datainfo/accname.lub

Hair Palettes

data/palette/¸Ó¸®/*.pal

Upload Process

  1. Login to the dashboard at https://ragnasync.com/login using your discord_server_guid found in your channels.conf file

Warning: Never share your discord_server_guid with anyone. This is your secure private key for accessing the dashboard.

  1. Navigate to Builder > Char Heads

  2. Select or drag your GRF file onto the upload area (max 500MB)

  3. The system automatically extracts and processes:

    • Sprite files (.spr/.act) for hair and accessories

    • Palette files (.pal) for color variations

    • Lua configuration files for hat ID mappings

  4. Once uploaded, changes take effect immediately—no restart required

Automatic Configuration

When you upload a GRF file, the system automatically:

  1. Parses accessoryid.lub to extract hat ID mappings

  2. Parses accname.lub to extract sprite file names

  3. Generates a hat library for rendering

No manual configuration is required.

Character Head Rendering

Character heads are rendered at 40x40 pixels and display:

  • Hair style and color

  • Head top accessory

  • Head mid accessory

  • Head bottom accessory

  • GM indicator (yellow background + label) for group_id > 5

Preview

Fallback Behavior

If no custom GRF is uploaded, the system uses RagnaSync default folder with standard Ragnarok sprites.

Discord Avatar Caching

Character heads are used as webhook avatars for in-game chat messages on Discord. Be aware that Discord caches avatar images aggressively:

  • Avatar images are cached by Discord's CDN for extended periods

  • After uploading new sprites, previously sent messages will retain their old avatars

  • Only new messages will display the updated character heads

  • Discord may take some time to refresh cached avatars even for new messages

There is no way to force Discord to clear its avatar cache for existing messages.

Troubleshooting

Issue
Solution

Upload fails

Ensure file is a valid .grf format and under 500MB

Hats not showing

Verify accessoryid.lub and accname.lub are in standard paths

Wrong accessories

Check that sprite names in accname.lub match actual file names

Preview not updating

Clear browser cache or wait a moment for processing

Old avatars on messages

Discord caches avatars—only new messages will show updated sprites

PreviousDiscord AuthenticationNextTicket System NPC

Last updated