MatchEngine - Revision history

Tayfunwiki at 02:23, 17 May 2025

2025-05-17T02:23:37Z

← Older revision		Revision as of 22:23, 16 May 2025
Line 1:		Line 1:
	,		= 🧠 Intrigues MatchEngine API Reference =

			== Overview ==
			The <code>MatchEngine</code> 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) ==
			<syntaxhighlight lang="c#">
			IM.Instance.MatchEngine.CandidateFilter = (self, other) => ...;
			</syntaxhighlight>

			=== Description ===
			<code>CandidateFilter</code> is a user-defined function that determines who can be evaluated as a match.

			It runs '''before''' expensive rule-based logic (<code>IsCompatibleAsync</code>) to filter out invalid candidates.
			----

			=== Signature ===
			<syntaxhighlight lang="c#">
			public Func<Actor, Actor, bool> CandidateFilter;
			</syntaxhighlight>
			----

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

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

			=== Example ===
			<syntaxhighlight lang="c#">
			// 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
			</syntaxhighlight><blockquote>📝 '''Note:''' CandidateFilter is typically set in <code>DemoManager.cs > Start()</code> and affects all matchmaking.</blockquote>
			----

			== 🔍 FindMatch (Callback-Based) ==
			<syntaxhighlight lang="c#">
			IM.Instance.MatchEngine.FindMatch(actor, "Love Rule", match => {
			if (match != null)
			actor.StartScheme("Love", match);
			});
			</syntaxhighlight>

			=== Description ===
			<code>FindMatch</code> scans all eligible candidates for the given actor, using a specified rule (like <code>"Love Rule"</code>).

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

			=== Signature ===
			<syntaxhighlight lang="c#">
			public void FindMatch(Actor actor, string rule, Action<Actor> onMatchFound)
			</syntaxhighlight>
			----

			=== Parameters ===
			{\| class="wikitable"
			!Name
			!Type
			!Description
			\|-
			\|<code>actor</code>
			\|<code>Actor</code>
			\|The actor seeking a match
			\|-
			\|<code>rule</code>
			\|<code>string</code>
			\|The rule used to determine compatibility
			\|-
			\|<code>onMatchFound</code>
			\|<code>Action<Actor></code>
			\|Called with the matched actor or <code>null</code> if none found
			\|}
			----

			=== Example ===
			<syntaxhighlight lang="c#">
			IM.Instance.MatchEngine.FindMatch(actor, "Love Rule", match => {
			if (match != null)
			actor.StartScheme("Love", match);
			else
			Debug.Log("No match found.");
			});
			</syntaxhighlight>
			----

			=== Notes ===

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

			----

			== ⚠️ Performance Tip ==
			Always define a <code>CandidateFilter</code> — especially in simulations with 100+ actors — to avoid evaluating thousands of unnecessary compatibility rules.
			----

			== 🧪 Debugging Tip ==
			<syntaxhighlight lang="c#">
			var count = IM.Actors.Count(p => MatchEngine.CandidateFilter(actor, p));
			Debug.Log($"Evaluating {count} candidates for {actor.Name}");
			</syntaxhighlight>You can log how many candidates passed the filter:
			----

			== ✅ Summary ==
			{\| class="wikitable"
			!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
			\|}
			----

Tayfunwiki: Replaced content with ","

2025-05-17T02:19:27Z

Replaced content with ","

← Older revision		Revision as of 22:19, 16 May 2025
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>~~

Tayfunwiki at 01:45, 15 May 2025

2025-05-15T01:45:43Z

← Older revision		Revision as of 21:45, 14 May 2025
Line 10:		Line 10:
	</syntaxhighlight>		</syntaxhighlight>

	=== Description: ===		=== 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.		<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: ===		=== Signature ===
	<syntaxhighlight lang="c#">		<syntaxhighlight lang="c#">
	public Func<Actor, Actor, bool> CandidateFilter;		public Func<Actor, Actor, bool> CandidateFilter;
	</syntaxhighlight>		</syntaxhighlight>

	=== Purpose: ===		=== 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).		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: ===		=== Example ===
	<syntaxhighlight lang="c#">		<syntaxhighlight lang="c#">
	// Allow only opposite-gender, unmarried actors		// Allow only opposite-gender, unmarried actors
	IM.Instance.MatchEngine.CandidateFilter = (self, other) =>		IM.Instance.MatchEngine.CandidateFilter = (self, other) =>
	other.HasSpouse == false && other.Gender != self.Gender;		other.HasSpouse == false && other.Gender != self.Gender;

	// Allow same-gender matches		// Allow same-gender matches
	IM.Instance.MatchEngine.CandidateFilter = (self, other) =>		IM.Instance.MatchEngine.CandidateFilter = (self, other) =>
	other.HasSpouse == false; // no gender check		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.		</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#">		🔍 <code>FindMatch(Actor actor, string rule)</code><syntaxhighlight lang="c#">
Line 36:		Line 37:
	</syntaxhighlight>		</syntaxhighlight>

	=== Description: ===		=== 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.		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: ===		=== Signature ===
	<syntaxhighlight lang="c#">		<syntaxhighlight lang="c#">
	public async Task<Actor> FindMatch(Actor actor, string rule)		public async Task<Actor> FindMatch(Actor actor, string rule)
	</syntaxhighlight>		</syntaxhighlight>

	=== Parameters: ===		=== Parameters ===
	{\| class="wikitable"		{\| class="wikitable"
	!Name		!Name
Line 59:		Line 60:
	\|}		\|}

	=== Returns: ===		=== Returns ===

	* <code>Actor</code> – A compatible partner, or <code>null</code> if no match is found		* <code>Actor</code> – A compatible partner, or <code>null</code> if no match is found

	=== Example: ===		=== Example ===
	<syntaxhighlight lang="c#">		<syntaxhighlight lang="c#">
	private async void TryFindSpouse(Actor actor)		private async void TryFindSpouse(Actor actor)
Line 80:		Line 81:
	</syntaxhighlight>		</syntaxhighlight>

	=== How It Works: ===		=== How It Works ===

	# Filters all actors using <code>CandidateFilter</code> (if set)		# Filters all actors using <code>CandidateFilter</code> (if set)

Tayfunwiki: Created page with "= 🧠 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) => ...;
2025-05-15T01:44:26Z

Created page with "= 🧠 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) => ...; </syntax..."

New page
= 🧠 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>