RacesOfValheim/GEMINI.md
2026-07-30 19:00:13 +02:00

3.2 KiB

RacesOfValheim — Development Rules

New Race: Skin Visibility Pattern

When creating a new race, always implement skin/visual patches following the Furling pattern:

1. UpdateColors patch (skin color — in-game + multiplayer + main menu)

[HarmonyPatch(typeof(VisEquipment), "UpdateColors")]
public static class <Race>SkinColorPatch
{
    public static void Postfix(VisEquipment __instance)
    {
        if (!__instance.m_isPlayer) return;
        Player player = __instance.GetComponent<Player>();
        if (player == null) return;

        // ZDO first (in-game + remote players), then m_customData fallback
        // (main menu preview and first spawn frame — Player.m_localPlayer is null there)
        // DO NOT check player == Player.m_localPlayer in the fallback.
        string race = "Human";
        ZNetView nview = player.GetComponent<ZNetView>();
        if (nview != null && nview.IsValid())
            race = nview.GetZDO().GetString("RacesOfValheim_Race", "Human");
        else if (player.m_customData != null &&
                 player.m_customData.TryGetValue("Race", out string savedRace))
            race = savedRace;

        if (race != "<RaceName>") return;

        // Apply skin, hair, beard colors here...
    }
}

2. UpdateVisuals patch with GetPlayerRace() helper (model swaps — in-game + multiplayer + main menu)

[HarmonyPatch(typeof(VisEquipment), "UpdateVisuals")]
public static class <Race>_VisEquipment_UpdateVisuals_Patch
{
    public static string GetPlayerRace(VisEquipment visEq)
    {
        Player player = visEq.GetComponent<Player>();
        if (player != null)
        {
            ZNetView nview = player.GetComponent<ZNetView>();
            if (nview != null && nview.IsValid())
                return nview.GetZDO().GetString("RacesOfValheim_Race", "Human");
            // No Player.m_localPlayer check — works for menu preview too
            if (player.m_customData != null &&
                player.m_customData.TryGetValue("Race", out string r))
                return r;
        }
        return "Human";
    }

    public static void Postfix(VisEquipment __instance)
    {
        if (!__instance.m_isPlayer) return;
        string race = GetPlayerRace(__instance);
        if (race != "<RaceName>") return;
        // Apply model changes here...
    }
}

3. FejdStartup patches (main menu character preview)

These must be added to RacesOfValheim.cs — they are shared across all races. The patches already exist (FejdStartup_SetupCharacterPreview_Patch and FejdStartup_SetSelectedProfile_Patch). They call UpdateVisuals + UpdateColors on the preview player via GetPreviewPlayer(). No changes needed when adding new races — they fire for all VisEquipment patches automatically.

Key rules summary

  • Never use player == Player.m_localPlayer as a gate for m_customData fallback.
  • Always use ZDO as primary source, m_customData as fallback — in that order.
  • UpdateColors = skin/hair/beard tint. UpdateVisuals = model-level changes (head swaps, hide items).
  • The FejdStartup patches already handle the menu; just make sure your UpdateColors/UpdateVisuals use the pattern above.