https://github.com/realwhyknot/vrcfury-qol
Quality-of-life Editor tools for VRCFury: flipbook migration, mass reference replacement, component move, auto global parameter sync, and more.
https://github.com/realwhyknot/vrcfury-qol
avatar-tools editor-tools unity unity-editor vrcfury vrchat vrchat-avatars
Last synced: 22 days ago
JSON representation
Quality-of-life Editor tools for VRCFury: flipbook migration, mass reference replacement, component move, auto global parameter sync, and more.
- Host: GitHub
- URL: https://github.com/realwhyknot/vrcfury-qol
- Owner: RealWhyKnot
- License: gpl-3.0
- Created: 2026-05-07T16:13:59.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-20T14:21:09.000Z (26 days ago)
- Last Synced: 2026-05-20T19:26:26.349Z (26 days ago)
- Topics: avatar-tools, editor-tools, unity, unity-editor, vrcfury, vrchat, vrchat-avatars
- Language: C#
- Homepage: https://vpm.whyknot.dev/
- Size: 185 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# VRCFury QoL
[](LICENSE)
[](https://vrcfury.com/)
[](https://unity.com/)
Quality-of-life Editor tools for [VRCFury](https://vrcfury.com/). The goal: features appear *where you're already working* -- right-click a page, click a button on a flipbook row, see a banner on a Toggle, drop in two objects to swap references -- instead of hiding behind a separate window.
The framework is designed so adding a new tool is usually a single small file with one `[InitializeOnLoad]` registration. See the [Adding a Tool](https://github.com/RealWhyKnot/vrcfury-qol/wiki/Adding-a-Tool) wiki page.
## What you get
- **Move all VRCFury components** between GameObjects in one Undo step. Pick "Move whole components" to preserve serialization shape, or "Merge into one component" to consolidate features onto a single carrier object. *(Right-click a GameObject -> WhyKnot -> vrcfury-qol -> Move all VRCFury components to...)*
- **Replace references in selection.** Pick GameObjects, the window lists every distinct Object referenced by their VRCFury components -- one row per unique value, with a count of how many places it's used. Drag a replacement onto a row and click Apply; every occurrence of that object across the scan is swapped in one Undo step. Per-selection *Include children* toggle controls whether each entry recurses into descendants. *(Tools -> WhyKnot -> vrcfury-qol -> Replace References..., or right-click a selection -> WhyKnot -> vrcfury-qol -> Replace references in selection...)*
- **Missing-reference warning.** On editor startup (and again every assembly reload), the tool scans every VRCFury component in the open scene for `Object` references whose target has been deleted, and pops a non-modal window listing each one with a Ping button. Dismiss it once and it stays dismissed until the next reload -- so real problems can't linger silently, but you don't get nagged after you've acknowledged the situation. Can be re-run anytime via *Tools -> WhyKnot -> vrcfury-qol -> Check for missing references...*.
- **Auto-synced Global Parameter on every Toggle.** A green banner on the Toggle inspector confirms `useGlobalParam = true` and `globalParam = MenuPath` are kept in sync. Per-toggle opt-out via the banner button or right-click menu. Stops VRCFury from silently renaming parameters during avatar regen.
- **Preview toggles and flipbooks.** The Toggle banner and each flipbook page row include a `Preview` button that creates a temporary, non-saveable avatar copy in place, applies the selected toggle or page to that copy, and hides the source avatar in Scene view. It does not move or reframe the Scene camera. While the copy is active, the same button turns into a red `Stop Previewing` button that destroys the copy and restores visibility.
- **Migrate child toggles into a Flipbook.** Right-click a Flipbook Builder action; it scans the same GameObject + descendants for non-flipbook VRCFury Toggles and folds each into the flipbook as a new page, deleting the source components. Confirmation dialog shows exactly what will happen.
- **Duplicate a flipbook page** below the current page via the inline `Duplicate` button next to every `Page #N` label, or duplicate to the end from the right-click menu.
- **Duplicate one state action** in place with `Duplicate item`, or use `Copy to page` on a flipbook page action to append just that one BlendShape / Material Swap / action to another page.
- **Hot reload + compile-error log.** Watches `Assets/**/*.cs` and triggers `AssetDatabase.Refresh()` even when Unity is unfocused. Per-assembly compile summary + errors appended to `/Logs/VrcfQolHotReload.log` (rolls over at 512 KB).
Detailed walkthroughs of every tool live in the [Tools Overview](https://github.com/RealWhyKnot/vrcfury-qol/wiki/Tools-Overview) wiki page.
## Installation
### VCC (recommended)
Add the WhyKnot VPM listing to the [VRChat Creator Companion](https://creators.vrchat.com/), then this package shows up under **Manage Project -> Add Package**.
1. Click . The page redirects to a `vcc://` handler URL and VCC opens with the listing pre-filled. Click **I Understand, Add Repository**.
2. If that doesn't work, in VCC go to **Settings -> Packages -> Add Repository**, paste `https://vpm.whyknot.dev/index.json`, click **I Understand, Add Repository**.
3. Open any project, click **Manage Project**, find **VRCFury QoL** in the package list, hit **Add**.
Unity compiles the package into a dedicated `dev.whyknot.vrcfury-qol.Editor` assembly (`Editor/` only -- nothing leaks into runtime builds). Hard-depends on `com.vrcfury.vrcfury` (>= 1.1300.0); VCC will refuse to install without VRCFury present.
### Manual install
For Unity projects not managed by VCC: download `dev.whyknot.vrcfury-qol-X.Y.Z.zip` from [the latest release](https://github.com/RealWhyKnot/vrcfury-qol/releases/latest), unzip into `Packages/dev.whyknot.vrcfury-qol/` (so `Packages/dev.whyknot.vrcfury-qol/package.json` exists), and Unity's Package Manager picks it up on next refresh. VRCFury must already be installed in the project.
Tested against VRCFury **1.1303.x** on Unity **2022.3**.
For per-clone setup steps (hot-reload bootstrap, etc.) see the [Installation](https://github.com/RealWhyKnot/vrcfury-qol/wiki/Installation) wiki page.
## Adding your own tool
A tool is a small `[InitializeOnLoad]` static class that registers itself with `VrcfQol`. The framework provides typed helpers so your tool never has to walk the reflection cache by hand. The full developer guide with examples for every `Register*` method lives at [Adding a Tool](https://github.com/RealWhyKnot/vrcfury-qol/wiki/Adding-a-Tool).
## Documentation
- [Wiki home](https://github.com/RealWhyKnot/vrcfury-qol/wiki) -- long-form docs
- [Tools Overview](https://github.com/RealWhyKnot/vrcfury-qol/wiki/Tools-Overview) -- every shipping tool
- [Architecture](https://github.com/RealWhyKnot/vrcfury-qol/wiki/Architecture) -- how the framework hooks VRCFury via reflection + UI overlay
- [Adding a Tool](https://github.com/RealWhyKnot/vrcfury-qol/wiki/Adding-a-Tool) -- developer guide for new tools
- [Troubleshooting](https://github.com/RealWhyKnot/vrcfury-qol/wiki/Troubleshooting) -- common failure modes
## Not a replacement for review
These tools make real, destructive changes to your scene (deleting source VRCFury components during a migration, replacing object references in bulk, forcing `useGlobalParam` on by default, etc). Always:
1. Commit your project to version control first, or duplicate the avatar.
2. Try any tool on one small group before pointing it at anything large.
## Contributing
Bug reports, feature requests, and pull requests are all welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev loop and PR conventions.
## License
Licensed under the GNU General Public License v3.0 or later. See [LICENSE](LICENSE) for the full text.