Xbox Avatar for CastleForge v1

Your Xbox Original Avatar as your character in Castle Miner Z, as a
CastleForge mod.

One DLL in !Mods. No patched executable — nothing is written to
CastleMinerZ.exe, so a game update cannot break the install and there is
nothing to back up or restore.

What you get

• Your avatar replaces the stock character, for you and for everyone in the
  session running this mod.
• Your own hands and glove in first person, posed by the game's own held-item
  animation — the fist around a pickaxe, the finger on a trigger.
• Held items sit in the avatar's real grip, worked out from its finger bones,
  so short, tall, slim and heavy builds all hold a pickaxe properly.
• Players without the mod are unaffected and see the stock character.

Installing

1. Install CastleForge.
2. Drop XboxAvatar.dll into the game's !Mods folder.
3. Start the game. The mod unpacks its importer and capture bridge into
   !Mods/XboxAvatar/.
4. Type /avatar import in chat, leave the avatar you want on screen, and
   confirm the capture. It loads the moment the importer closes — no restart.

To remove: delete XboxAvatar.dll and the !Mods/XboxAvatar folder.

Commands

Command	What it does
/avatar	What the mod is currently using.
/avatar import	Capture your Xbox Original Avatar and load it.
/avatar reload	Re-read avatar.ocavatar without restarting, and offer it to everyone in the session.
/avatar grip <0-1>	How far the first-person hand closes. 1 is the game's pose, 0 the open hand.

Capture runs as a separate process on purpose: the bridge is x64 because the
Xbox Original Avatars app is, while Castle Miner Z is x86. The mod starts it for
you and picks up the result, which is the part that used to mean quitting to the
desktop.

Multiplayer

Avatars are exchanged only with players who also have the mod, over a
capability-gated channel that vanilla clients never see. Transfers are served
round-robin, so a full lobby joining at once does not leave the last player
waiting through everyone else's avatar.

Notes for the curious

This began as an add-on that rewrote five call sites in CastleMinerZ.exe with
dnlib and kept a byte-exact backup. On CastleForge four of those became Harmony
patches and the fifth is ModBase.Tick, which the loader already calls.

The one wrinkle: mods load after the engine has built its network message table,
and message IDs are positional. The mod registers itself and rebuilds that
table at load. Its packet sorts after every stock type, so stock IDs do not
move — there is a test that asserts exactly that — and a peer advertising a
different ID is left on the stock character rather than sent packets its game
would misread.

Five tests run on every build: the avatar format and protocol, stock packet IDs,
the third-person grip, the first-person hand geometry, and how the mod is
packaged and wired.

Requirements

Windows, Castle Miner Z on Steam, CastleForge, and the Xbox Original Avatars app
if you want to capture an avatar. No game files are included or modified.

XboxAvatar.dll
SHA-256 AA0C30AC2B9B9B0D1DB68825D707A4C92F30E1AD04F0867F4A5940A3BE960F5E

GPL-3.0-or-later. The avatar runtime is MIT from
openclassic-xbox-avatar and
castleminerz-xbox-avatar,
included here under GPL as MIT permits. Thanks to RussDev7 for CastleForge and
for the embedding pattern this mod follows.