🧠 Intrigues MatchEngine API Reference

Overview

The MatchEngine is part of the Intrigues core system and provides a lightweight, callback-based matchmaking mechanism between actors.

It helps characters find suitable partners using rule-based compatibility checks and user-defined filters.

🔧 CandidateFilter (Optional)

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

Description

CandidateFilter is a user-defined function that determines who can be evaluated as a match.

It runs before expensive rule-based logic (IsCompatibleAsync) to filter out invalid candidates.

Signature

public Func<Actor, Actor, bool> CandidateFilter;

Purpose

To filter out obviously incompatible actors early — improving performance and allowing logic customization

(e.g., same-gender marriage, family bans, rank restrictions).

Example

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

// Same-gender allowed
IM.Instance.MatchEngine.CandidateFilter = (self, other) =>
    !other.HasSpouse; // No gender check

📝 Note: CandidateFilter is typically set in DemoManager.cs > Start() and affects all matchmaking.

🔍 FindMatch (Callback-Based)

IM.Instance.MatchEngine.FindMatch(actor, "Love Rule", match => {
    if (match != null)
        actor.StartScheme("Love", match);
});

Description

FindMatch scans all eligible candidates for the given actor, using a specified rule (like "Love Rule").

It executes asynchronously in the background and returns the first valid match through a callback.

Signature

public void FindMatch(Actor actor, string rule, Action<Actor> onMatchFound)

Parameters

Name	Type	Description
`actor`	`Actor`	The actor seeking a match
`rule`	`string`	The rule used to determine compatibility
`onMatchFound`	`Action<Actor>`	Called with the matched actor or `null` if none found

Example

IM.Instance.MatchEngine.FindMatch(actor, "Love Rule", match => {
    if (match != null)
        actor.StartScheme("Love", match);
    else
        Debug.Log("No match found.");
});

Notes

The callback always fires, even if no match is found (with null).
Ideal for use in Update(), timers, MarriageTimer(), or any non-async context.
Evaluation is spread over frames to avoid freezing the main thread.

⚠️ Performance Tip

Always define a CandidateFilter — especially in simulations with 100+ actors — to avoid evaluating thousands of unnecessary compatibility rules.

🧪 Debugging Tip

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

You can log how many candidates passed the filter:

✅ Summary

Feature	Purpose
CandidateFilter	Pre-filters actors before heavy compatibility check
FindMatch	Finds the first compatible partner via callback
Fully async	Internally asynchronous without requiring async/await
Lightweight	Designed to scale to hundreds of actors
Customizable	Users define their own filtering logic