07 Troubleshooting and Internals

Troubleshooting & Internals

This page has two halves: a practical FAQ/troubleshooting section for pack authors and server owners, and a shorter "how it actually works" section for anyone curious (or debugging something the FAQ doesn't cover). You don't need the second half to use the mod — it exists so that if something ever does misbehave, you know where to look instead of guessing.

FAQ / Troubleshooting

I added a skin's JSON but it doesn't show up anywhere in-game

1. Did you actually reload it? Datapack changes need /reload or a world restart to take effect — MCPSkins re-reads every data/*/skins/*.json file at that point and rebuilds its registry from scratch.
2. Check the server log right after loading for a line like Loaded N TACZ weapon skin configs. — if N is lower than you expect, or you see a Failed to parse TACZ skin config: <file> error above it, your JSON has a syntax or type error (missing required field, wrong type, etc.) in that specific file, and it's being skipped entirely rather than partially loaded.
3. Double check base_gun is spelled exactly like the gun pack registers it — including its namespace (tacz:m4a1, not m4a1). A typo here doesn't error, it just quietly creates skins for a weapon that doesn't exist.
4. Remember two datapacks (or two files) can't both configure the same base_gun — see the warning on the datapack page. Whichever loads last wins outright; the other's skins for that weapon disappear.

The skin is selectable/ownable, but the weapon still looks stock

This is almost always a resource pack path problem, not a datapack problem. Walk through the texture path rules again carefully — the most common mistakes are: forgetting to turn : into / in the base_gun folder name, putting the file under the wrong namespace (it defaults to mcpskins, not the gun pack's own namespace, unless your skin id explicitly says otherwise), or a mismatched skin id between the JSON and the file name.

Also worth knowing: whether a texture file exists is cached in memory per session for performance, since this check would otherwise run on nearly every render frame. That cache clears itself automatically on any client-side resource reload (F3+T, toggling a resource pack, or a full relaunch) — so if you're actively iterating on art, a resource reload is enough, you don't need to restart the whole game.

The 3D weapon changed, but the inventory icon didn't

Expected, if you haven't added a _icon.png — see the icon section. It's a genuinely separate, optional file.

I added a geo-model file and the shape didn't change

Work through this in order:

1. Is full geo-model replacement even active on your TACZ build at all? Check the log once at startup (or the first time any geo-model skin is attempted) for a warning starting with Full geo-model skin replacement disabled. If you see it, this feature couldn't find what it needs in your specific TACZ build — texture/icon skins are unaffected, but no geometry swap will ever work until that's resolved (see "Why does this depend on reflection at all?" below).
2. Is the base model location actually right? Don't guess it — pull it straight from the gun pack's own weapon config, as described on the resource pack page. A wrong namespace/folder here is the #1 cause of "nothing happens."
3. Does the file physically exist, but TACZ still doesn't "see" it? These are two different checks internally — the mod first confirms the file exists in a resource pack, then separately asks TACZ's own model registry whether it recognizes that same location. If the first passes but the second fails, you'll see a warning like TACZ's internal model registry doesn't recognize it — likely a folder/naming mismatch. This means the file exists but isn't in a place/format TACZ's own asset loader is scanning — re-check the base model's exact location (step 1 above) rather than the mod's fallback logic.
4. Skeleton mismatch. If you see the skin's geo-model skeleton likely doesn't match the base weapon's animations, your replacement model is missing a bone the base weapon's animations expect. This is the one geo-model requirement that's non-negotiable — see the resource pack page.

Fuse isn't working / the button/toggle isn't showing

Check Configuration — fusion.enabled and refit_toggle_button.enabled both do exactly what they say, and both default to on, so if either's off it was turned off on purpose somewhere.

Can I skin a weapon from a gun pack that isn't the "main" one?

Yes. Both base_gun and the resource file paths explicitly support any namespace:path GunId, not just weapons under one particular namespace — this is by design, precisely so third-party/community gun packs work the same as any other weapon.

How it works, for the curious (and for contributors)

Feel free to stop reading here if you're just running a server — nothing below changes how you use the mod. This section exists mainly so that if you ever see one of the warnings above, you understand why it exists instead of just what to do about it.

The core trick: a second, independent "what skin is this" value

TACZ identifies a weapon purely by its GunId. MCPSkins adds a second, completely separate piece of data to the item stack recording which skin (if any) is applied, and never touches GunId itself. This value is persistent (survives a relog/server restart) and server-authoritative (a client can't fake owning or wearing a skin it hasn't been granted — every equip round-trips through server validation, as described on the In-Game UI page).

Actually rendering the skin happens by intercepting the exact moment TACZ asks "what does this weapon look like" and, if a skin is set, substituting a patched copy of the answer — with the substitute texture/icon/geometry — before TACZ ever draws it. This is why re-skinning never disturbs attachments, ammo, or anything else TACZ itself is tracking on the item.

Why reflection, and why it's fork-specific

TACZ-1.21.1 doesn't expose an official API for "swap this weapon's rendered model." Rather than duplicating a large, private, version-specific chunk of TACZ's own asset-loading and model-parsing pipeline (fragile in its own right, and guaranteed to drift out of sync with TACZ's actual behavior over time), MCPSkins locates the small number of internal fields/constructors it needs via Java reflection, once per session, and — for the full geometry-replacement path specifically — hands the actual parsing back to TACZ's own code rather than re-implementing it. The result renders exactly as TACZ itself would render a "real" weapon with that model, because it is TACZ's own model-loading code doing the work.

The tradeoff is exactly what you'd expect: this is tied to the internal shape of this specific TACZ-1.21.1 fork build, not a stable public contract. If a future build of the fork renames or restructures the handful of internal fields this depends on, the affected feature — and only that feature — stops working, with a warning logged once rather than a crash. Each layer is independently optional and fails soft:

If this internal detail changes upstream...	...this (and only this) stops working	Everything else keeps working
The weapon-display constructor/config shape	Full geo-model replacement	Texture and icon re-skinning
The private texture field name	Falls back to a slower public getter (a known minor race-condition risk during resource reloads, logged once)	Everything else
The 2D icon field (name unverified, several candidates tried)	Icon overrides	3D texture re-skinning
sun.misc.Unsafe being blocked by the JVM/environment	All texture/icon patching	Nothing — this would be unusual for a normal Minecraft install

None of these failure modes crash the game or the server; each one degrades to "that particular visual layer stays stock" and logs a one-time warning explaining exactly what to check (all quoted verbatim in the FAQ above). If you're maintaining a fork or updating past a TACZ version bump and skins stop rendering correctly, start by reading whatever warning appeared once at startup — it names the exact class/field it went looking for.