# Emoji Fix

IMVU Classic uses an old embedded Gecko engine that cannot reliably render
modern Unicode emoji in chat. Missing glyphs appear as hex boxes, often called
tofu boxes.

The emoji patch fixes chat rendering and adds a searchable picker beside
**Send**.

## What It Adds

| Feature | Behavior |
| --- | --- |
| Twemoji rendering | Converts chat emoji into image glyphs |
| Picker | Searchable emoji picker with categories |
| Favorites | Local favorites saved in the embedded browser storage |
| Shortcuts | Text shortcuts like `lol`, `pog`, and `:)` |
| Cache | Emoji images cached in `localStorage` after first load |
| Restore | Timestamped backup and restore flow |

## Install

```powershell
.\install.ps1
```

or:

```powershell
python -m imvu_toolkit emoji install
```

Restore:

```powershell
python -m imvu_toolkit emoji restore
```

## How It Works

The patch changes two IMVU Classic assets:

| Asset | Change |
| --- | --- |
| `library.zip` | Replaces `im/common.py` so chat message bytes decode as UTF-8 first, with Windows-1252 fallback |
| `imvuContent.jar` | Injects emoji JavaScript, patches chat HTML/CSS/JS, and adds picker assets |

Injected JavaScript lives in:

```text
emoji_assets/js/emojiDisplay.js
emoji_assets/js/emojiSuggestions.js
emoji_assets/js/emojiPicker.js
emoji_assets/js/emojiList.js
emoji_assets/js/emojiCache.js
```

The generated emoji catalog is stored in `emojiList.js`.

## User Workflow

1. Close IMVU.
2. Install the emoji patch.
3. Reopen IMVU.
4. Open chat and use the smiley button beside **Send**.
5. Type a supported shortcut and press **Tab** to accept the suggestion.
6. Use the gear button in the picker to switch shortcut behavior.

## Updating the Emoji List

Regenerate the catalog:

```powershell
python -m imvu_toolkit emoji generate-list
```

The command runs the `scripts/generate_emoji_list.py` helper. It may fetch
Unicode `emoji-test.txt` when regenerating the catalog.

## Limitations

- Chat is the supported target. Profile fields and room titles are not patched.
- The first load of each emoji image needs internet access to jsDelivr.
- IMVU client updates can overwrite patched files. Re-run the installer after an
  update if emoji support disappears.
- Favorites are local to the embedded browser storage on that PC.

## Related Docs

- [Installation and Restore](Installation-and-Restore.md)
- [Troubleshooting](Troubleshooting.md)
- [Project Architecture](Project-Architecture.md)
- [Detailed architecture](../architecture.md)