CustomSosigModelFramework

Custom Sosig Model Framework

A modular custom sosig model framework for H3VR

VIDEO DEMONSTRATION

The framework replaces the rendered appearance of H3VR Sosigs with humanoid models supplied by independent addon packages. H3VR remains responsible for the Sosig's AI, health, armor, weapons, aiming, damage, and game-mode behavior. The framework drives the custom model's animation and visual hitboxes from that native Sosig.

WARNING: Custom Model Template have not been tested and was made fully by AI. I do not guarantee you can easily make your own models.

The framework and its companion packages are authored by NotGodlike.

Features

• Modular model addons: install or remove models without rebuilding the framework.
• Wrist Menu integration under Custom Sosigs:
• Sosig restores the original H3VR appearance.
• Random chooses from the installed model addons for each Sosig.
• Each addon registers its own named model option.
• Runtime animation mapping for locomotion, crouching, weapon handling, hit reactions, transitions, and death/fall states.
• Visual hand IK to keep animated hands near the Sosig's actual weapon grip without changing H3VR's weapon aiming or accuracy.
• Armor-aware custom hitboxes and an optional translucent blue Armor Hitbox visualization. Body hitboxes are not drawn.
• Custom blood impact and death effects for supported model addons.
• Existing and newly spawned Sosigs use the selected model. The selection is saved in the BepInEx configuration.

Installation

This source repository does not include a compiled release or the model/animation payloads for Metrocop and MW4 Milsim. Obtain compatible framework and addon packages separately; then install them as separate folders under H3VR/BepInEx/plugins/ and start H3VR. Select Custom Sosigs from the Wrist Menu. The framework alone falls back to the original Sosig appearance until at least one compatible model addon is installed.

Packages are intentionally separate:

BepInEx/plugins/

├── NotGodlike-CustomSosigModelFramework/

│ └── CustomSosigModelFramework.dll

├── NotGodlike-Metrocop/ # optional model addon

│ ├── customsosig-model.json

│ └── assets/

└── NotGodlike-MW4Milsim/ # optional model addon

├── customsosig-model.json

└── assets/

Only install one copy of CustomSosigModelFramework.dll. Do not install an older standalone Sosig replacer alongside the framework.

This source repository contains the framework and model-authoring templates. Game models, textures, and animation files are not bundled here unless their redistribution rights are explicitly documented. Model addons may be distributed separately by their respective authors.

Configuration

The BepInEx configuration file is:

BepInEx/config/NotGodlike.h3vr.customsosigmodelframework.cfg

The selected model and Armor Hitbox display preference are saved automatically. If a selected addon is not installed, the framework falls back to the original Sosig appearance. The Armor Hitbox toggle is a visualization only; it does not change damage, armor, or collision behavior.

Creating a model addon

No framework code changes are needed for a normal addon. Start with either:

• Templates/ModelAddon for the addon manifest and runtime asset layout.
• Templates/UnityModelAddon for the Unity authoring project scaffold and armor-hitbox editing helper.

Read the full format and preparation guide in Docs/ModelAddons.md. The preparation script is Tools/prepare-model-addon.ps1.

In brief, an addon supplies a valid model manifest, converted skinned mesh, materials/textures, a compatible humanoid skeleton, and animation clips mapped to the framework's animation roles. An FBX or GLB placed directly into the game folder is not sufficient. Animation quality depends on compatible bone mapping, consistent bind pose/orientation, and correct import settings.

Armor hitboxes in Unity

The Unity template includes an editor helper for adjusting the addon armor-hitbox volumes. Use the visual model bounds and armor coverage as reference, then