|
|
| Line 1: |
Line 1: |
| = 🧠 Intrigues MatchEngine API Reference =
| | , |
| | |
| == Overview ==
| |
| The <code>MatchEngine</code> 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.
| |
| ----
| |
| | |
| == 🔧 <code>CandidateFilter</code> (Optional) ==
| |
| <syntaxhighlight lang="c#">
| |
| IM.Instance.MatchEngine.CandidateFilter = (self, other) => ...;
| |
| </syntaxhighlight>
| |
| | |
| === Description ===
| |
| <code>CandidateFilter</code> 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 (<code>IsCompatibleAsync</code>) are triggered.
| |
| | |
| === Signature ===
| |
| <syntaxhighlight lang="c#">
| |
| public Func<Actor, Actor, bool> CandidateFilter;
| |
| </syntaxhighlight>
| |
| | |
| === 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 ===
| |
| <syntaxhighlight lang="c#">
| |
| // 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
| |
| </syntaxhighlight>📝 '''Note:''' This filter is typically set once during initialization (e.g., in <code>DemoManager.cs > Start()</code>), and applies globally across all match operations.
| |
| | |
| | |
| 🔍 <code>FindMatch(Actor actor, string rule)</code><syntaxhighlight lang="c#">
| |
| Actor matched = await IM.Instance.MatchEngine.FindMatch(actor, "Love Rule");
| |
| </syntaxhighlight>
| |
| | |
| === Description ===
| |
| Scans all eligible actors to find a suitable match for the given <code>actor</code>, based on a specified rule (e.g., <code>"Love Rule"</code>). Returns the first actor that passes both the <code>CandidateFilter</code> (if any) and the <code>IsCompatibleAsync(...)</code> rule evaluation.
| |
| | |
| === Signature ===
| |
| <syntaxhighlight lang="c#">
| |
| public async Task<Actor> FindMatch(Actor actor, string rule)
| |
| </syntaxhighlight>
| |
| | |
| === Parameters ===
| |
| {| class="wikitable"
| |
| !Name
| |
| !Type
| |
| !Description
| |
| |-
| |
| |<code>actor</code>
| |
| |<code>Actor</code>
| |
| |The actor who is seeking a match
| |
| |-
| |
| |<code>rule</code>
| |
| |<code>string</code>
| |
| |The name of the rule used to check compatibility
| |
| |}
| |
| | |
| === Returns ===
| |
| | |
| * <code>Actor</code> – A compatible partner, or <code>null</code> if no match is found
| |
| | |
| === Example ===
| |
| <syntaxhighlight lang="c#">
| |
| 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.");
| |
| }
| |
| }
| |
| </syntaxhighlight>
| |
| | |
| === How It Works ===
| |
| | |
| # Filters all actors using <code>CandidateFilter</code> (if set)
| |
| # Shuffles the list to avoid bias
| |
| # Iterates through each candidate and checks rule-based compatibility
| |
| # Returns the first matching actor
| |
| | |
| == ⚠️ Performance Tip ==
| |
| In large simulations (100+ actors), skipping <code>CandidateFilter</code> can cause significant slowdowns. Always define a lightweight <code>CandidateFilter</code> to minimize expensive async rule checks.
| |
| ----
| |
| | |
| == 🧪 Debugging Tip ==
| |
| To check how many candidates are being evaluated, you can log:<syntaxhighlight lang="c#">
| |
| var count = IM.Actors.Count(p => MatchEngine.CandidateFilter(actor, p));
| |
| Debug.Log($"Evaluating {count} candidates for {actor.Name}");
| |
| </syntaxhighlight>
| |
| | |
| == ✅ Summary ==
| |
| {| class="wikitable"
| |
| !Feature
| |
| !Purpose
| |
| |-
| |
| |<code>CandidateFilter</code>
| |
| |Filters actors before compatibility check
| |
| |-
| |
| |<code>FindMatch</code>
| |
| |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
| |
| |}
| |
| ----<blockquote>For more advanced matching (e.g., scoring, top-N matches, or group dynamics), consider extending <code>MatchEngine</code> or integrating it with custom rule graphs.</blockquote>
| |
