Skip to main content

Using Custom Textures

Using Custom Textures allows you to replace the model's built-in textures with your own custom image files. This provides the most direct way to modify your character's appearance, as you're editing the actual image files that the model uses.

What Are Custom Textures?​

Custom Textures are PNG image files that replace the model’s original texture files. The image shown here is an atlas page. The atlas page contains a collection of regions.

Atlas page example showing texture regions

The atlas page is the image source that the model directly references at runtime. When you enable the Use Custom Textures option and reload the textures, EmoteLab looks for the atlas pages, and uses them in place of the built-in textures. The changes then become visible in the model preview immediately.

Texture Cache Folder​

The atlas pages are stored in the texture cache folder at:

C:\Users\<username>\Documents\EmoteLab\Texture Cache\[ModelName]\Custom Textures
info

If the system Documents folder has been relocated, the files may instead be found in a different drive or path, such as: E:\Users\Documents\EmoteLab\Texture Cache\[ModelName]\Custom Textures

When you first enable Custom Textures, the system automatically creates the following folder structure:

Custom Textures/
  ├── {atlas1}.png
  ├── {atlas2}.png
  ├── {atlas3}.png
  └── ... (additional atlas files)

How to Use Custom Textures​

Custom texture settings and tools are in the Texture tab at the top of the interface.

How to use custom textures

Step 1: Switch to Custom Textures​

  1. Enable custom textures: Turn on Use Custom Textures toggle.
  2. Wait for setup: If the custom texture folder does not exist, EmoteLab creates it and copies built-in texture atlas pages as templates. If the folder already exists, EmoteLab uses the files in that folder and automatically fills in any missing pages from built-in textures.
  3. Check the result: The model switches to custom textures. On first use, you may not see visual changes yet because EmoteLab copies built-in textures into the custom folder as templates.

Step 2: Editing Custom Textures​

  1. Open the texture folder: Click Open Custom Texture Folder to open it in your file explorer.
  2. Edit PNG files: Open the texture files in your preferred image editor.
  3. Follow these rules:
    • Keep the same image dimensions.
    • Preserve transparency (alpha channel).
  4. Save in place: Keep the same file names and overwrite the existing PNG files.
File Naming & Integrity
  • Exact name matching: All atlas pages must keep the exact same names (case-sensitive) as the originals.
  • Exact dimension matching: All atlas pages must keep the exact same dimensions as the originals.
  • No missing files: Every atlas page must be present.

Step 3: Reloading Textures​

  1. Return to EmoteLab.
  2. Reload textures: Click Reload Textures in the Texture section.
  3. Verify in viewport: Your texture changes should appear immediately.
Reload Textures

You must click Reload Textures after editing files, or your changes will not appear in the viewport.

Switching Back to Original Textures​

To return to using the original built-in textures:

  1. Disable custom textures: Turn off Use Custom Textures.
  2. Model updates: The model immediately switches back to built-in textures.

Step 4: Saving your Character​

Click Save Character to save the character with custom textures. For more details, see Character Management.

Saving the character is required to preserve compatibility across versions. When a character is saved with custom textures, EmoteLab unpacks the atlas pages and stores the edited textures as individual region PNGs. This approach allows EmoteLab to manage compatibility of custom characters between model updates, where regions may be added, removed, or reordered.

note

If you save a character with custom textures before reloading, the saved character may contain texture files that are different from what you expected based on the current viewport preview.

To avoid accidental mismatches, always do this before saving:

  1. Click Reload Textures.
  2. Verify the final look in the viewport.
  3. Then click Save Character.
warning

The custom texture folder is not permanent storage for finalized edits.

Your custom files remain in the folder when switching back to built-in textures, but they can be overwritten when loading a character that has custom textures enabled.

To preserve your edited textures, you must save a character with Use Custom Textures enabled.

How Characters with Custom Textures are Handled​

When saving a character:​

  1. EmoteLab saves the character data (active parts, slider adjustment, coloring information) into a JSON.
  2. The atlas pages are unpacked into region PNGs and saved along side the character data json file.
  • Source: Texture Cache/[ModelName]/Custom Textures/ (full atlas pages).
  • Target: [CharacterFolder]/Regions/ (individual region PNGs).
Atlas page example showing texture regions

When loading a character:​

  1. EmoteLab reads the character data JSON file.
  2. If the character is using custom texture, EmoteLab will look for the Regions folder.
  3. The region PNGs are packed into atlas pages and put in the cache Custom Textures folder.

If the region exist (previous edited version), the app will load the edited region. If the required region does not exist (if new regions are adeed to the model or due to the removal of regions in the region folder). the app will fall back the to the regions in built-in textures.
3. Emotelab will then repack all the regions into atlas pages and put them in the cache Custom Textures folder.

Texture Utility​

Texture Utility provides batch operations for atlas pages. When Use Custom Textures is enabled, atlas pages from the currently loaded model appear in the atlas list.

Texture Utility

You can select atlas pages for batch processing with:

  • Checkboxes for individual pages
  • Select All: select all atlas pages
  • Toggle Selection: invert selection

Fix Selected Outlines​

Applies alpha bleeding to selected atlas pages. After editing textures in some image editors, visible white or black edge artifacts may appear around model parts. This option helps remove those outline artifacts.

Reset Selected Atlas​

Resets selected atlas pages to the default built-in version.

warning

All batch operations modify files permanently and cannot be undone. If needed, create a backup before running batch operations.