babalae/better-genshin-impact · warning · NormalEndException

请先装备小道具「王树瑞佑」！如果已经装备仍旧出现此提示，请重新仔细阅读文档中的《快速上手》！

Error message

请先装备小道具「王树瑞佑」！如果已经装备仍旧出现此提示，请重新仔细阅读文档中的《快速上手》！

What it means

Thrown as NormalEndException by PressZ on the first gadget-use attempt when the 'TheBoonOfTheElderTree' recognition template is not found on screen. The template matches the gadget icon shown when pressing Z, confirming the correct gadget is equipped. Its absence means the gadget is either not equipped or not the correct one, so auto-wood cannot proceed.

Source

Thrown at BetterGenshinImpact/GameTask/AutoWood/AutoWoodTask.cs:445

        }

        // 手动 GC
        GC.Collect();
    }

    private void PressZ(WoodTaskParam taskParam)
    {
        // IMPORTANT: MUST try focus before press Z
        SystemControl.FocusWindow(TaskContext.Instance().GameHandle);

        if (_first)
        {
            using var contentRegion = CaptureToRectArea();
            using var ra = contentRegion.Find(GetRecognitionObject("TheBoonOfTheElderTree", contentRegion));
            if (ra.IsEmpty())
            {
#if !TEST_WITHOUT_Z_ITEM
                throw new NormalEndException("请先装备小道具「王树瑞佑」！如果已经装备仍旧出现此提示，请重新仔细阅读文档中的《快速上手》！");
#else
                System.Threading.Thread.Sleep(2000);
                Simulation.SendInput.SimulateAction(GIActions.QuickUseGadget);
                Debug.WriteLine("[AutoWood] Z");
                _first = false;
#endif
            }
            else
            {
                Simulation.SendInput.SimulateAction(GIActions.QuickUseGadget);
                Debug.WriteLine("[AutoWood] Z");
                _first = false;
            }
        }
        else
        {
            NewRetry.Do(() =>
            {

View on GitHub (pinned to a7cb36712d)

Solutions

1. Equip the 'Boon of the Elder Tree' gadget in the quick-use slot in-game.
2. If already equipped, check that the correct gadget is active (not a different one).
3. Update the TheBoonOfTheElderTree recognition asset if the icon changed in a game update.
4. Verify the capture resolution matches the expected 1920x1080 base or the asset scaling logic.
5. Refer to the documentation's quick-start guide as the error message suggests.

try
{
    woodTask.PressZ(taskParam);
}
catch (NormalEndException ex) when (ex.Message.Contains("王树瑞佑"))
{
    // Inform the user to equip the correct gadget
    Logger.LogWarning(ex.Message);
}

When it happens

Trigger: Called from PressZ(taskParam) when _first is true. contentRegion.Find(GetRecognitionObject("TheBoonOfTheElderTree", contentRegion)) returns an empty region (ra.IsEmpty() true). Only thrown when TEST_WITHOUT_Z_ITEM is not defined.

Common situations: Gadget 'Boon of the Elder Tree' (王树瑞佑) is not equipped in the quick-use (Z) slot; a different gadget is equipped; the gadget icon template doesn't match due to game version/UI change; the game screen resolution doesn't match the template scale.

Related errors

• 当前不在地图界面
• 首次伐木就未识别到木材数据，已经自动关闭【OCR识别并累计木材数】的功能，请重新启动【自动伐木】功能！
• 当前未处于大地图界面，不能使用GetBigMapScale方法
• 请先在启动页，启动截图器再使用本功能
• 不在主界面，无法识别小地图坐标

AI-assisted analysis of babalae/better-genshin-impact@a7cb36712d (2026-08-13). Data as JSON: /api/errors/75b0ca8efaa9385a. Report an issue: GitHub.