MatchEngine

🧠 Intrigues MatchEngine API Reference

Overview

The MatchEngine is part of the Intrigues core system and provides a lightweight, asynchronous matchmaking mechanism between actors. It is designed to help characters find suitable partners based on rule-based logic and customizable conditions.

---

🔧 CandidateFilter (Optional)

IM.Instance.MatchEngine.CandidateFilter = (self, other) => ...;

Description:

CandidateFilter is a user-defined delegate that determines which actors are eligible to be evaluated as potential matches. It is executed before expensive rule-based compatibility checks (IsCompatibleAsync) are triggered.

Signature:

public Func<Actor, Actor, bool> CandidateFilter;

Purpose:

To filter out clearly invalid candidates early, improving performance and allowing customization of match logic (e.g., support for same-gender marriages, polygamy, or role-based restrictions).

Example:

// Allow only opposite-gender, unmarried actors
IM.Instance.MatchEngine.CandidateFilter = (self, other) =>
    other.HasSpouse == false && other.Gender != self.Gender;

// Allow same-gender matches
IM.Instance.MatchEngine.CandidateFilter = (self, other) =>
    other.HasSpouse == false; // no gender check

📝 Note: This filter is typically set once during initialization (e.g., in DemoManager.cs > Start()), and applies globally across all match operations. 🔍 FindMatch(Actor actor, string rule)

Actor matched = await IM.Instance.MatchEngine.FindMatch(actor, "Love Rule");

Description:

Scans all eligible actors to find a suitable match for the given actor, based on a specified rule (e.g., "Love Rule"). Returns the first actor that passes both the CandidateFilter (if any) and the IsCompatibleAsync(...) rule evaluation.

Signature:

public async Task<Actor> FindMatch(Actor actor, string rule)

Parameters:

Name	Type	Description
actor	Actor	The actor who is seeking a match
rule	string	The name of the rule used to check compatibility

Returns:

• Actor – A compatible partner, or null if no match is found

Example:

private async void TryFindSpouse(Actor actor)
{
    var match = await IM.Instance.MatchEngine.FindMatch(actor, "Love Rule");

    if (match != null)
    {
        actor.StartScheme("Love", match);
    }
    else
    {
        Debug.Log("No compatible match found.");
    }
}

How It Works:

1. Filters all actors using CandidateFilter (if set)
2. Shuffles the list to avoid bias
3. Iterates through each candidate and checks rule-based compatibility
4. Returns the first matching actor

⚠️ Performance Tip

In large simulations (100+ actors), skipping CandidateFilter can cause significant slowdowns. Always define a lightweight CandidateFilter to minimize expensive async rule checks.

---

🧪 Debugging Tip

To check how many candidates are being evaluated, you can log:

var count = IM.Actors.Count(p => MatchEngine.CandidateFilter(actor, p));
Debug.Log($"Evaluating {count} candidates for {actor.Name}");

✅ Summary

Feature	Purpose
CandidateFilter	Filters actors before compatibility check
FindMatch	Asynchronously finds the first compatible match
Fully async	Doesn’t freeze the main thread
Customizable	Users define matching conditions
Performant	Filtering avoids unnecessary rule execution

---

For more advanced matching (e.g., scoring, top-N matches, or group dynamics), consider extending MatchEngine or integrating it with custom rule graphs.