Development Guide

Development Guide

This page is for contributors changing patch code, injected assets, tests, or docs.

Setup

git clone https://github.com/JSukar/IMVU-TOOLKIT.git
cd IMVU-TOOLKIT
python -m pip install -e ".[dev]"

Run checks:

ruff check src tests
pytest

Build dependencies are separate:

python -m pip install -e ".[build]"

Project Conventions

• Prefer the unified CLI in docs and examples.
• Keep root-level legacy scripts working.
• Add patch markers for injected or rewritten content.
• Back up before writing patched IMVU files.
• Support --restore for mutating patch scripts.
• Validate expected signatures before modifying files.
• Keep changes focused and update docs for user-visible behavior.

Adding or Changing Emoji Behavior

Main locations:

src/imvu_toolkit/patches/emoji/
emoji_assets/js/
tests/fixtures/
tests/test_emoji_patch.py
tests/test_jar_integration.py

If the emoji catalog changes, regenerate:

python -m imvu_toolkit emoji generate-list

Adding or Changing DPI Behavior

Main locations:

patches/dpi/
src/imvu_toolkit/patches/dpi/registry.py
scripts/imvu_dpi_runtime_probe.py
scripts/audit_imvu_dpi_probe.py
scripts/compare_imvu_probes.py

If a new DPI script should be exposed through the CLI, add it to DPI_SCRIPTS in src/imvu_toolkit/patches/dpi/registry.py.

Adding or Changing Tool Scripts

Main locations:

scripts/
src/imvu_toolkit/tools/runner.py

If a new utility should be exposed through the CLI, add it to TOOL_SCRIPTS in src/imvu_toolkit/tools/runner.py.

Tests

Use fixture-based tests for deterministic transforms. The test suite should not require a live IMVU install.

Helpful commands:

pytest tests/test_emoji_patch.py
pytest tests/test_jar_integration.py
pytest tests/test_installer_runner.py

Docs

Update the wiki for workflow guidance and update the reference docs for deeper technical explanations:

docs/wiki/
docs/architecture.md
docs/dpi-patches.md
docs/compatibility.md
docs/FAQ.md

Update CHANGELOG.md under [Unreleased] for user-visible changes.