# DPI Fixes

DPI tooling is for high-DPI display issues in IMVU Classic, such as offset click
targets, clipped dialogs, scaling mismatch, or tab and 3D scene artifacts.

Emoji support is independent. Use DPI fixes only when you are actively
troubleshooting display scaling.

## First Choice: Windows-Level Scaling

Start with the Windows compatibility scaling helper:

```powershell
python -m imvu_toolkit tools scale-window
```

Persistent/watch mode while testing:

```powershell
python -m imvu_toolkit tools scale-window --watch
```

This helper does not patch IMVU files. It writes per-user DPI compatibility
registry values and resizes/restores the IMVU window.

The default low-resolution compatibility mode maps to:

```text
~ DPIUNAWARE
```

This keeps IMVU's native, Gecko, and scene layers in one coordinate system. The
tradeoff is softer rendering because Windows scales the whole process.

## Decision Path

| Symptom | Start With |
| --- | --- |
| Whole client is offset or mouse clicks miss targets | `tools scale-window --watch` |
| Scaling works but the client looks too soft | Instrument first, then consider internal patches |
| White line between UI and scene | `dpi white-line` |
| Dialogs or cards clip content | `dpi dialog-scaling` |
| Room overlay hitboxes are wrong | `dpi clean-layout`, then `dpi room-hitboxes` |
| Overlay clicks land on the wrong element | `dpi overlay-click` |

## Instrumentation

Capture a compatible baseline:

```powershell
python -m imvu_toolkit tools dpi-probe --children --out .\compatible_probe.jsonl
```

Capture sharp/high-DPI behavior:

```powershell
python -m imvu_toolkit tools dpi-probe --children --watch --interval 1.0 --out .\sharp_probe.jsonl
```

Compare key windows:

```powershell
python -m imvu_toolkit tools compare-probes .\compatible_probe.jsonl .\sharp_probe.jsonl
```

Create a broader Markdown audit:

```powershell
python -m imvu_toolkit tools audit-probe --baseline .\compatible_probe.jsonl --capture --samples 3 --interval 1.0 --out .\output.md
```

## Internal Patch Commands

These patches can modify `library.zip` or `imvuContent.jar`. They create their
own backup suffixes and should be tested one at a time.

| CLI command | Legacy script | Purpose |
| --- | --- | --- |
| `python -m imvu_toolkit dpi clean-layout` | `patch_imvu_clean_dpi_layout.py` | Core layout and Gecko compensation |
| `python -m imvu_toolkit dpi room-hitboxes` | `patch_imvu_room_overlay_hitboxes.py` | In-room overlay hitbox tuning |
| `python -m imvu_toolkit dpi overlay-click` | `patch_imvu_overlay_click_remap.py` | Packaged UI JavaScript click remap |
| `python -m imvu_toolkit dpi dialog-scaling` | `patch_imvu_dialog_scaling.py` | Dialog/card scaling adjustments |
| `python -m imvu_toolkit dpi white-line` | `patch_imvu_white_line.py` | Tab/3D background seam fix |

Pass script-specific options after `--` when needed:

```powershell
python -m imvu_toolkit dpi clean-layout -- --configure-sharp
python -m imvu_toolkit dpi clean-layout -- --restore
```

## Restore

Each patch family restores from its own latest backup suffix:

```powershell
python -m imvu_toolkit dpi clean-layout -- --restore
python -m imvu_toolkit dpi room-hitboxes -- --restore
python -m imvu_toolkit dpi overlay-click -- --restore
python -m imvu_toolkit dpi dialog-scaling -- --restore
python -m imvu_toolkit dpi white-line -- --restore
```

## Known Limits

The DPI patches are advanced and not guaranteed to fix every room UI, overlay,
or notification issue. If Windows-level scaling is functionally correct, keep it
as the baseline before testing sharper internal patches.

## Related Docs

- [Detailed DPI runbook](../dpi-patches.md)
- [Compatibility](../compatibility.md)
- [Troubleshooting](Troubleshooting.md)