OCR and template matching

OCR and template matching automatically select a weapon class based on your game's HUD. The selected class supplies the settings you configured for that weapon, including its RCS setup where applicable.

These features recognize the weapon HUD. They do not replace your target-detection model.

#Which should I use?

Only one method can be on: enabling OCR, Template Match or AI Weapon turns the other two off.

#Before you start

1. Select the correct game profile and create the weapon classes you want to switch between.
2. Check each class's settings manually. Recognition selects a class; it does not create or tune its settings.
3. Start Moonlight's capture/detection so the live preview shows your game.
4. Use the resolution, HUD scale, and capture setup you normally play with.
5. Make sure the weapon name or icon is visible in the captured image.

ROI means Region of Interest: the small rectangle where Moonlight looks for the weapon name or icon. Set this against the captured image, not the size of the preview window or the aim FOV.

• X / Y: where the rectangle starts, measured from the captured image's top-left corner.
• W / H: the rectangle's width and height.

Keep the ROI tight, but do not cut off text or icons. Avoid unrelated HUD elements and animated backgrounds where possible.

#Set up OCR

#1. Enable OCR

Open Game Profiles → OCR and enable Auto Weapon Detection (OCR). Leave OCR Engine on native and choose the language used by your weapon HUD under OCR Languages.

#2. Add a weapon rule

Under Weapon Text Mappings, select + Add Rule.

1. Enter the weapon name under Keyword to Match, for example AK-47.
2. Choose the corresponding Target Weapon Class.
3. Under OCR Search Region (ROI), adjust X, Y, W, and H around the weapon-name text.
4. Check ROI Crop in the rule's live preview. The complete name should be readable, with as little unrelated text as possible.
5. Leave Case Sensitive Matching off unless capitalization needs to distinguish your rules.
6. Select Save Rule.

Each rule can have its own search region. Add further rules only after your first weapon switches correctly.

#3. Check what OCR actually reads

Use OCR Debug Status, especially Last Text and Last Match. The rule editor also provides an OCR Result display while detection runs.

• Wrong or missing text: adjust the ROI and preprocessing first.
• Correct text but no match: check the keyword, target class, and similarity thresholds.
• Wrong class: check for overly similar keywords or thresholds that are too lenient.

The Test button tests text you type against your mappings. It does not read the screen or prove that your ROI works. Confirm the final setup with live detection.

#4. Tune OCR only if needed

There is a global similarity threshold and a per-rule threshold. Live matching uses the stricter of the two. For example, global 0.90 still requires 90% similarity even if a rule is set to 80%.

Keep your existing detection interval initially. Improve the crop before lowering thresholds or increasing scan frequency. Enable OCR Debug Logging only when troubleshooting, then turn it off again.

#Set up Template Matching: Per-Rule

#1. Enable the feature

Open Game Profiles → Template Match, enable Weapon Template Matching, and select Per-Rule (Manual ROI) under Matching Mode.

#2. Capture a clean template

1. Select the weapon class that should receive the rule.
2. Equip that weapon in the game and wait for its HUD icon to settle.
3. Select Capture from frame.
4. Use Recapture frame if the displayed image is outdated.
5. Drag a rectangle around the distinctive weapon icon. Avoid ammunition counts, selection borders, and other changing elements.
6. Select Save template… and save as PNG.

This creates a rule for the active class and an initial search region around the captured icon. Use Edit to verify both. The capture workflow initially sets a match threshold of 0.70; do not assume that value is strict enough for your game.

Capture from Moonlight's own feed so the reference matches the image Moonlight receives. If you already have suitable images, use + Add and Add Image instead.

#3. Verify the rule

Select the rule and choose Edit.

1. Confirm Target Weapon Class.
2. Check Search Region (ROI) around the icon's actual location.
3. Start with Correlation Coefficient (Recommended) as the matching method.
4. Inspect Live ROI (Raw), Live ROI (Processed), and Match Score.
5. Compare the score with the correct weapon equipped, then with other weapons equipped.
6. Set Match Threshold so the correct icon passes and the wrong icons fail. 0.80 is the editor's suggested starting point, not a universal value.
7. Save with OK.

Calibrate sets a threshold just below the current live score. Use it only while the correct weapon is visible, then test other weapons too. It cannot establish accuracy from one positive example.

#4. Keep preprocessing simple

Use the Original, Processed, and live ROI previews to judge changes.

• Start without extra filters when the captured icon already matches well.
• Try Convert to Grayscale when color variations are unhelpful.
• Use thresholding or contour options only if they make the icon clearer and preserve its distinctive shape.
• Leave Enable Color Filter and Enable Brightness Filter off unless needed. These can reject an otherwise valid match.
• Use Multi-scale only if icon size varies. Checking more scales adds work.
• Add a small number of useful image variants when the same weapon genuinely has different HUD appearances.

If correct and incorrect weapons produce similar scores, improve the template or crop rather than simply lowering the threshold.

#Control switching speed and stability

These template-matching controls work together:

Start with the existing values. If switching is slow, check all three settings before reducing the interval. To watch recognition, use the center preview (or the live preview inside the rule editor).

#No-Match Fallback

Leave Enable Fallback off while setting up your rules.

Once recognition is reliable, enable it only if you want Moonlight to select a specific fallback class after nothing matches for the configured Timeout. Choose the class you actually want in that situation.

Fallback does not recognize an unknown weapon. It selects your chosen class when recognition has been absent long enough. Hidden HUDs, menus, or an overly strict rule can therefore trigger it.

#Set up Template Matching: Slotted

Use Slotted (Hotbar Grid) when your game displays inventory slots with a visible selected-slot indicator.

1. Under Slot Grid Definition, set Slots, Direction, X Position, Y Position, Slot Width, Slot Height, and Spacing so the preview rectangles line up with the hotbar.
2. Adjust Crop Padding to exclude the slot border without cutting away the weapon icon.
3. Under Selected Slot Detection, start with Auto Detect.
4. Change selected slots in-game and check Selected Slot in Slot Detection Status.
5. If selection is wrong, choose the method that matches the HUD: Color Match, Brightness, or Blue Channel, and tune its visible controls.
6. Add your images and class mappings under Slot Templates.
7. Test each slot and weapon combination.

Verify slot selection before tuning icon matching. A correct weapon template cannot fix recognition aimed at the wrong slot.

#Troubleshooting

#Final check

• Equip every mapped weapon and confirm the active class changes correctly.
• Switch quickly between weapons to check the delay.
• Test ADS, reloading, menus, and any state that changes or hides the HUD.
• Confirm that unrelated HUD content does not trigger another class.
• If using fallback, deliberately hide the matching HUD and verify the selected fallback class.
• Restart Moonlight and verify the saved setup again.

For support, provide your capture resolution, relevant rule settings, and the live debug text or match score. A screenshot of the ROI is more useful than a screenshot of the game alone.