CustomItemForge

Tools to inspect and transform .vroidcustomitem files for VRoid Studio. This project is independent from VRoid branding; compatibility is described as for VRoid.

Part of the VRoidTools index.

English · Español

Features (v0.1.1-alpha.0)

• Inspect with three sections: VRoid / VRoidCustomItem / File
• Validate, clone, compare, probe, compatibility
• Unified GUI (Tkinter) — English default, Spanish available
• Family engines (hair / clothing / accessory) with honest stubs until calibration samples arrive
• CLI: cif / custom-item-forge

Download (end users)

1. Get the .zip from the latest release (CustomItemForge-*.zip).
2. Extract it anywhere.
3. Follow RELEASE.txt inside the zip.

Artifact	Use
CustomItemForge_Win.pyw	Windows GUI — double-click, no console
CustomItemForge.sh	macOS / Linux GUI
CustomItemForge.pyz	CLI, or GUI when run with no arguments

Requires Python 3.12+ with Tkinter. The release build bundles Pillow for thumbnails.

Each published GitHub Release builds and attaches this zip automatically. Maintainers: see docs/GITHUB_RELEASES.md / docs/GITHUB_RELEASES_ES.md.

On Windows, open the GUI with CustomItemForge_Win.pyw (not the .pyz — that opens a console).

Quick start (developers)

git clone https://github.com/P3M-ACTF/CustomItemForge.git
cd CustomItemForge
python -m pip install -e ".[dev]"
custom-item-forge inspect path\to\item.vroidcustomitem
custom-item-forge gui
pytest

Double-click scripts/CustomItemForge.pyw during development (runs from source, not the release bundle).

Build the release bundle locally

python scripts/build_release.py
# or: .\scripts\build_release.ps1

See docs/RELEASE.md.

Calibration samples

Hair is calibrated against Studio 2.14.0 fixtures under tests/fixtures/real/hair/ (gitignored binaries; see NOTES.md). Clothing / accessory merge still need samples — docs/CALIBRATION.md.

License

MIT