use named parameter style

2b0a3558 · Vury Leo · ab526506 · 2b0a3558 · 2b0a3558 · 2b0a3558
Commit 2b0a3558 authored May 31, 2025 by Vury Leo
5 changed files
--- a/script/c12450071.lua
+++ b/script/c12450071.lua
@@ -5,7 +5,7 @@ function s.initial_effect(c)
 	c:EnableReviveLimit()
 	aux.AddLinkProcedure(c,aux.FilterBoolFunction(Card.IsLinkType,TYPE_EFFECT),2)
 	--fusion
-	local e1=FusionSpell.CreateSummonEffect(c,nil,nil,LOCATION_ONFIELD)
+	local e1=FusionSpell.CreateSummonEffect(c,{pre_select_mat_location=LOCATION_ONFIELD})
 	e1:SetDescription(aux.Stringid(id,0))
 	e1:SetType(EFFECT_TYPE_IGNITION)
 	e1:SetRange(LOCATION_MZONE)

--- a/script/c37630732.lua
+++ b/script/c37630732.lua
@@ -2,7 +2,10 @@
 local s,id,o=GetID()
 function s.initial_effect(c)
 	--Activate
-	FusionSpell.RegisterSummonEffect(c,s.fusfilter,nil,nil,nil,nil,nil,nil,nil,nil,nil,s.stage_x_operation)
+	FusionSpell.RegisterSummonEffect(c,{
+		fusfilter=s.fusfilter,
+		stage_x_operation=s.stage_x_operation
+	})
 end
 ---@param c Card

--- a/script/c58199906.lua
+++ b/script/c58199906.lua
@@ -23,6 +23,7 @@ function s.activate(e,tp,eg,ep,ev,re,r,rp)
 	e1:SetProperty(EFFECT_FLAG_PLAYER_TARGET)
 	e1:SetTargetRange(1,0)
 	e1:SetReset(RESET_PHASE+PHASE_END)
+	e1:SetCountLimit(1)
 	e1:SetTarget(s.chain_target)
 	e1:SetOperation(s.chain_operation)
 	e1:SetValue(aux.FilterBoolFunction(Card.IsRace,RACE_MACHINE))
@@ -40,5 +41,4 @@ function s.chain_operation(e,te,tp,tc,mat,sumtype,sumpos)
 	Duel.Remove(mat,POS_FACEUP,REASON_EFFECT+REASON_MATERIAL+REASON_FUSION)
 	Duel.BreakEffect()
 	Duel.SpecialSummonStep(tc,sumtype,tp,tp,false,false,sumpos)
-	e:Reset()
 end
\ No newline at end of file
--- a/script/c87931906.lua
+++ b/script/c87931906.lua
@@ -2,7 +2,12 @@
 local s,id=GetID()
 function s.initial_effect(c)
 	--Activate
-	local e1=FusionSpell.CreateSummonEffect(c,s.fusfilter,nil,s.pre_select_mat_location,nil,nil,s.fcheck,s.gcheck)
+	local e1=FusionSpell.CreateSummonEffect(c,{
+		fusfilter=s.fusfilter,
+		pre_select_mat_location=s.pre_select_mat_location,
+		additional_fcheck=s.fcheck,
+		additional_gcheck=s.gcheck
+	})
 	e1:SetCategory(CATEGORY_SPECIAL_SUMMON+CATEGORY_FUSION_SUMMON+CATEGORY_DECKDES)
 	e1:SetCountLimit(1,id+EFFECT_COUNT_CODE_OATH)
 	c:RegisterEffect(e1)

--- a/script/utility.lua
+++ b/script/utility.lua
@@ -1991,7 +1991,45 @@ end
 FusionSpell = {}
 ---@alias FUSION_SPELL_PRE_SELECT_MAT_LOCATION_FUNCTION fun(tc:Card,tp:integer):integer
---@alias FUSION_FCHECK_FUNCTION fun(tp:integer,mg:Group,fc:Card,all_mg:Group):boolean
+---@alias FUSION_FGCHECK_FUNCTION fun(tp:integer,mg:Group,fc:Card,all_mg:Group):boolean
+---	@class FusionEffectParams
+--- @field fusfilter? fun(c:Card):boolean
+---     Optional filter to restrict which Fusion Monsters can be summoned.
+--- @field matfilter? fun(c:Card):boolean
+---     Optional filter for valid Fusion Materials.
+---     Use only under strong constraints (e.g., D-Fusion effects).
+--- @field pre_select_mat_location? integer|fun():integer
+---     Location(s) to look for materials before knowing which ones will be used.
+---     Defaults to `LOCATION_HAND | LOCATION_MZONE`.
+--- @field mat_operation_code_map? {[integer]:FUSION_OPERATION_CODE}[]
+---     List of operations to perform on materials based on location.
+---     Defaults to:  
+---     ```lua
+---     {
+---         { [LOCATION_GRAVE] = FusionSpell.FUSION_OPERATION_BANISH },
+---         { [0xff] = FusionSpell.FUSION_OPERATION_GRAVE }
+---     }
+---     ```
+--- @field post_select_mat_location? integer|nil
+---     Location(s) to look for materials after they've been selected.
+--- @field additional_fcheck? FUSION_FGCHECK_FUNCTION
+---     Optional final check to validate the selected material group.
+--- @field additional_gcheck? FUSION_FGCHECK_FUNCTION
+---     Optional quick check to validate partial material groups (for performance).
+--- @field fuslocation? integer
+---     The location to summon Fusion Monsters from. Defaults to `LOCATION_EXTRA`.
+--- @field sumtype? integer
+---     The summon type to perform. Defaults to `SUMMON_TYPE_FUSION`.
+--- @field sumpos? integer
+---     The position to summon the monster in. Defaults to `POS_FACEUP`.
+--- @field stage_x_operation? FUSION_SPELL_STAGE_X_CALLBACK_FUNCTION
+---     Optional callback executed at key stages of the summon process.
+---     Example stage: `FusionSpell.STAGE_BEFORE_SUMMON_COMPLETE`.
+--- @field extra_target? fun(e:Effect, tp:integer, eg:Group, ep:integer, ev:integer, re:Effect, r:integer, rp:integer, chk:integer):nil
+---     Optional extra targeting logic (e.g., to show hints or manage chains).
+--- @field pre_select_mat_opponent_location? integer|fun():integer
+---     Opponent-side locations to search for materials before they are selected.
 --- Add LOCATION_EXTRA to EFFECT_EXTRA_FUSION_MATERIAL list, remove once core updated
@@ -2004,56 +2042,80 @@ function FusionSpell.GetFusionMaterial(tp,locations)
    return res
 end
---@param c	Card card that uses the effect
+--- Get possible materials from opponent locations, must be face-up
---@param fusfilter	(fun(c:Card):boolean)? filter for the monster to be Fusion Summoned
+function FusionSpell.GetFusionMaterialFromOpponentLocation(tp,locations)
---@param matfilter	(fun(c:Card):boolean)? filter for the materials, use it only under very strong limitation like D-Fusion.
+	return Duel.GetMatchingGroup(Card.IsFaceup,tp,0,locations,nil)
---@param pre_select_mat_location integer|FUSION_SPELL_PRE_SELECT_MAT_LOCATION_FUNCTION? location where to find the materials before known the materials (default LOCATION_HAND|LOCATION_MZONE)
+end
---@param mat_operation_code_map {[integer]:FUSION_OPERATION_CODE}[]? operation code to do for the materials, it will be check in order (default [{ LOCATION_GRAVE: FUSION_OPERATION_BANISH}, { 0xff: FUSION_OPERATION_GRAVE}])
---@param post_select_mat_location integer? location where to find the materials after known the materials (default nil)
+--- Registers a Fusion Summon effect to a card.
---@param additional_fcheck function? function to check the final material group fits the requirement
+--- @param c Card                         -- The card to register the effect to.
---@param additional_gcheck function? function to check the part of potiential material group fits the requirement to improve performance
+--- @param opts FusionEffectParams
---@param fuslocation integer? location where to summon fusion monsters from (default LOCATION_EXTRA), use it on Clock Lizard
+--- @return Effect                        -- The registered effect object.
---@param sumtype integer? summon type (default SUMMON_TYPE_FUSION)
+function FusionSpell.RegisterSummonEffect(c,opts)
---@param sumpos integer? summon position (default POS_FACEUP)
+    local e1 = FusionSpell.CreateSummonEffect(c,opts)
---@param stage_x_operation function? callback function when special summon is in progress. will be called with different stage name
+    Card.RegisterEffect(c, e1)
-function FusionSpell.RegisterSummonEffect(c,fusfilter,matfilter,pre_select_mat_location,mat_operation_code_map,post_select_mat_location,additional_fcheck,additional_gcheck,fuslocation,sumtype,sumpos,stage_x_operation)
-	local e1=FusionSpell.CreateSummonEffect(c,fusfilter,matfilter,pre_select_mat_location,mat_operation_code_map,post_select_mat_location,additional_fcheck,additional_gcheck,fuslocation,sumtype,sumpos,stage_x_operation)
-	Card.RegisterEffect(c,e1)
    return e1
 end
---@param c	Card card that uses the effect
+--- Creates and returns a Fusion Summon effect, attached to the specified card.
---@param fusfilter	(fun(c:Card):boolean)? filter for the monster to be Fusion Summoned
+--- Accepts a table of named parameters to configure the effect behavior.
---@param matfilter	(fun(c:Card):boolean)? filter for the materials, use it only under very strong limitation like D-Fusion.
+---
---@param pre_select_mat_location integer|FUSION_SPELL_PRE_SELECT_MAT_LOCATION_FUNCTION? location where to find the materials before known the materials (default LOCATION_HAND|LOCATION_ONFIELD)
+--- @param opts? FusionEffectParams Named options table.
---@param mat_operation_code_map {[integer]:FUSION_OPERATION_CODE}[]? operation code to do for the materials, it will be check in order (default [{ LOCATION_GRAVE: FUSION_OPERATION_BANISH}, { 0xff: FUSION_OPERATION_GRAVE}])
+--- @return Effect The created and configured `Effect` object.
---@param post_select_mat_location integer? location where to find the materials after known the materials (default nil)
+function FusionSpell.CreateSummonEffect(c,opts)
---@param additional_fcheck function? function to check the final material group fits the requirement
+	opts=opts or {}
---@param additional_gcheck function? function to check the part of potiential material group fits the requirement to improve performance
+    local fusfilter=opts.fusfilter
---@param fuslocation integer? location where to summon fusion monsters from (default LOCATION_EXTRA), use it on Clock Lizard
+    local matfilter=opts.matfilter or aux.TRUE
---@param sumtype integer? summon type (default SUMMON_TYPE_FUSION)
+    local pre_select_mat_location=opts.pre_select_mat_location or (LOCATION_HAND | LOCATION_MZONE)
---@param sumpos integer? summon position (default POS_FACEUP)
+    local mat_operation_code_map=opts.mat_operation_code_map or {}
---@param stage_x_operation function? callback function when special summon is in progress. will be called with different stage name
+    local post_select_mat_location=opts.post_select_mat_location
---@param extra_target function? extra target function to add opration info etc
+    local additional_fcheck=opts.additional_fcheck
-function FusionSpell.CreateSummonEffect(c,fusfilter,matfilter,pre_select_mat_location,mat_operation_code_map,post_select_mat_location,additional_fcheck,additional_gcheck,fuslocation,sumtype,sumpos,stage_x_operation,extra_target)
+    local additional_gcheck=opts.additional_gcheck
-    matfilter=matfilter or aux.TRUE
+    local fuslocation=opts.fuslocation or LOCATION_EXTRA
-	pre_select_mat_location=pre_select_mat_location or LOCATION_HAND|LOCATION_ONFIELD
+    local sumtype=opts.sumtype or SUMMON_TYPE_FUSION
-	mat_operation_code_map=mat_operation_code_map or {}
+    local sumpos=opts.sumpos or POS_FACEUP
-	-- add last fallback, banish grave, grave others
+    local stage_x_operation=opts.stage_x_operation or aux.TRUE
-	table.insert(mat_operation_code_map,{[LOCATION_GRAVE]=FusionSpell.FUSION_OPERATION_BANISH})
+    local extra_target=opts.extra_target
-	table.insert(mat_operation_code_map,{[0xff]=FusionSpell.FUSION_OPERATION_GRAVE})
+    local pre_select_mat_opponent_location=opts.pre_select_mat_opponent_location
-    fuslocation=fuslocation or LOCATION_EXTRA
-	sumtype=sumtype or SUMMON_TYPE_FUSION
-    sumpos=sumpos or POS_FACEUP
-	stage_x_operation=stage_x_operation or aux.TRUE
-    local e1=Effect.CreateEffect(c)
+    -- Ensure material operation fallbacks are present
+    table.insert(mat_operation_code_map,{ [LOCATION_GRAVE] = FusionSpell.FUSION_OPERATION_BANISH })
+    table.insert(mat_operation_code_map,{ [0xff] = FusionSpell.FUSION_OPERATION_GRAVE })
+    -- Build and return the effect
+    local e1 = Effect.CreateEffect(c)
    e1:SetCategory(CATEGORY_SPECIAL_SUMMON+CATEGORY_FUSION_SUMMON)
    e1:SetType(EFFECT_TYPE_ACTIVATE)
    e1:SetCode(EVENT_FREE_CHAIN)
-    e1:SetTarget(FusionSpell.GetSummonTarget(fusfilter,matfilter,pre_select_mat_location,mat_operation_code_map,post_select_mat_location,additional_fcheck,additional_gcheck,fuslocation,sumtype,sumpos))
+    e1:SetTarget(FusionSpell.GetSummonTarget(
-    e1:SetOperation(FusionSpell.GetSummonOperation(fusfilter,matfilter,pre_select_mat_location,mat_operation_code_map,post_select_mat_location,additional_fcheck,additional_gcheck,fuslocation,sumtype,sumpos,stage_x_operation))
+        fusfilter,
+        matfilter,
+        pre_select_mat_location,
+        mat_operation_code_map,
+        post_select_mat_location,
+        additional_fcheck,
+        additional_gcheck,
+        fuslocation,
+        sumtype,
+        sumpos,
+        extra_target,
+        pre_select_mat_opponent_location
+    ))
+    e1:SetOperation(FusionSpell.GetSummonOperation(
+        fusfilter,
+        matfilter,
+        pre_select_mat_location,
+        mat_operation_code_map,
+        post_select_mat_location,
+        additional_fcheck,
+        additional_gcheck,
+        fuslocation,
+        sumtype,
+        sumpos,
+        stage_x_operation,
+        pre_select_mat_opponent_location
+    ))
    return e1
 end
@@ -2068,10 +2130,23 @@ end
 ---@param sumtype integer? summon type
 ---@param sumpos integer? summon position
 ---@param extra_target function? extra target function to add opration info etc
-function FusionSpell.GetSummonTarget(fusfilter,matfilter,pre_select_mat_location,mat_operation_code_map,post_select_mat_location,additional_fcheck,additional_gcheck,fuslocation,sumtype,sumpos,extra_target)
+---@param pre_select_mat_opponent_location integer|FUSION_SPELL_PRE_SELECT_MAT_LOCATION_FUNCTION? location where to find the materials before known the materials on opponent location
+function FusionSpell.GetSummonTarget(
+		fusfilter,
+		matfilter,
+		pre_select_mat_location,
+		mat_operation_code_map,
+		post_select_mat_location,
+		additional_fcheck,
+		additional_gcheck,
+		fuslocation,
+		sumtype,
+		sumpos,
+		extra_target,
+		pre_select_mat_opponent_location)
    return function(e,tp,eg,ep,ev,re,r,rp,chk)
        if chk==0 then
-            local sg=Duel.IsExistingMatchingCard(FusionSpell.SummonTargetFilter,tp,fuslocation,0,1,nil,fusfilter,matfilter,e,tp,pre_select_mat_location,mat_operation_code_map,post_select_mat_location,additional_fcheck,sumtype,sumpos)
+            local sg=Duel.IsExistingMatchingCard(FusionSpell.SummonTargetFilter,tp,fuslocation,0,1,nil,fusfilter,matfilter,e,tp,pre_select_mat_location,mat_operation_code_map,post_select_mat_location,additional_fcheck,sumtype,sumpos,pre_select_mat_opponent_location)
 			if sg==true then
 				return true
 			end
@@ -2086,7 +2161,7 @@ function FusionSpell.GetSummonTarget(fusfilter,matfilter,pre_select_mat_location
        end
        Duel.SetOperationInfo(0,CATEGORY_SPECIAL_SUMMON,nil,1,tp,fuslocation)
 		if extra_target~=nil then
-			extra_target()
+			extra_target(e,tp,eg,ep,ev,re,r,rp,chk)
 		end
    end
 end
@@ -2102,10 +2177,22 @@ end
 ---@param sumtype integer summon type
 ---@param sumpos integer summon position
 ---@param stage_x_operation function callback function when special summon is in progress. will be called with different stage name
-function FusionSpell.GetSummonOperation(fusfilter,matfilter,pre_select_mat_location,mat_operation_code_map,post_select_mat_location,additional_fcheck,additional_gcheck,fuslocation,sumtype,sumpos,stage_x_operation)
+---@param pre_select_mat_opponent_location integer|FUSION_SPELL_PRE_SELECT_MAT_LOCATION_FUNCTION? location where to find the materials before known the materials on opponent location
+function FusionSpell.GetSummonOperation(
+		fusfilter,
+		matfilter,
+		pre_select_mat_location,
+		mat_operation_code_map,
+		post_select_mat_location,
+		additional_fcheck,
+		additional_gcheck,
+		fuslocation,
+		sumtype,
+		sumpos,
+		stage_x_operation,
+		pre_select_mat_opponent_location)
    return function(e,tp,eg,ep,ev,re,r,rp)
+        local sg=Duel.GetMatchingGroup(FusionSpell.SummonTargetFilter,tp,fuslocation,0,nil,fusfilter,matfilter,e,tp,pre_select_mat_location,mat_operation_code_map,post_select_mat_location,additional_fcheck,sumtype,sumpos,pre_select_mat_opponent_location)
-        local sg=Duel.GetMatchingGroup(FusionSpell.SummonTargetFilter,tp,fuslocation,0,nil,fusfilter,matfilter,e,tp,pre_select_mat_location,mat_operation_code_map,post_select_mat_location,additional_fcheck,sumtype,sumpos)
 		--- check for chain material targets
 		local ce_sgs={}
 		local can_chain_material=false
@@ -2150,7 +2237,15 @@ function FusionSpell.GetSummonOperation(fusfilter,matfilter,pre_select_mat_locat
 				end
 				if fusion_effect==e then
 					--- use fusion spell effect
-					local mg=FusionSpell.GetMaterialsGroupForTargetCard(tc,tp,e,matfilter,pre_select_mat_location,mat_operation_code_map,post_select_mat_location)
+					local mg=FusionSpell.GetMaterialsGroupForTargetCard(
+							tc,
+							tp,
+							e,
+							matfilter,
+							pre_select_mat_location,
+							mat_operation_code_map,
+							post_select_mat_location,
+							pre_select_mat_opponent_location)
 					if additional_fcheck~=nil then
 						aux.FCheckAdditional=FusionSpell.GetFusionSpellFCheckAdditionalFunction(additional_fcheck,tp,c)
 					end
@@ -2231,6 +2326,11 @@ function FusionSpell.GetSummonOperation(fusfilter,matfilter,pre_select_mat_locat
 				else
 					--- fusion with chain material
 					fusion_effect:GetOperation()(e,e,tp,tc,materials,sumtype,sumpos)
+					--- use the chain material effect, reset if exhaused
+					fusion_effect:UseCountLimit(tp)
+					if fusion_effect:CheckCountLimit(tp)==false then
+						fusion_effect:Reset()
+					end
 				end
            end
@@ -2262,9 +2362,29 @@ end
 ---@param matfilter	fun(c:Card):boolean filter for the materials, use it only under very strong limitation like D-Fusion.
 ---@param pre_select_mat_location integer|function location where to find the materials before known the materials
-function FusionSpell.GetMaterialsGroupForTargetCard(tc,tp,e,matfilter,pre_select_mat_location,mat_operation_code_map,post_select_mat_location)
+---@param pre_select_mat_opponent_location integer|FUSION_SPELL_PRE_SELECT_MAT_LOCATION_FUNCTION? location where to find the materials before known the materials on opponent location
+function FusionSpell.GetMaterialsGroupForTargetCard(
+		tc,
+		tp,
+		e,
+		matfilter,
+		pre_select_mat_location,
+		mat_operation_code_map,
+		post_select_mat_location,
+		pre_select_mat_opponent_location)
 	local all_locations=FusionSpell.GetAllLocationsForTargetCard(tc,tp,pre_select_mat_location,post_select_mat_location)
 	local mg=FusionSpell.GetFusionMaterial(tp,all_locations)
+	if pre_select_mat_opponent_location~=nil then
+	 	if type(pre_select_mat_opponent_location)=="function" then
+			pre_select_mat_opponent_location=pre_select_mat_opponent_location(tc,tp)
+		end
+		local opponent_mg=FusionSpell.GetFusionMaterialFromOpponentLocation(tp,pre_select_mat_opponent_location)
+		if #opponent_mg>0 then
+			mg:Merge(opponent_mg)
+		end
+	end
 	-- filter by the strong material filter, target card can not be fusion material of itself
 	mg=mg:Filter(matfilter,tc)
 	--- filter out card can not be affected by effect
@@ -2312,12 +2432,13 @@ end
 ---@param fusfilter fun(c:Card,tp:integer):boolean
 ---@param matfilter fun(c:Card,tp:integer):boolean
 ---@param pre_select_mat_location integer|function location where to find the materials before known the materials (default LOCATION_HAND|LOCATION_MZONE)
-function FusionSpell.SummonTargetFilter(c,fusfilter,matfilter,e,tp,pre_select_mat_location,mat_operation_code_map,post_select_mat_location,additional_fcheck,sumtype,sumpos)
+---@param pre_select_mat_opponent_location integer|FUSION_SPELL_PRE_SELECT_MAT_LOCATION_FUNCTION? location where to find the materials before known the materials on opponent location
+function FusionSpell.SummonTargetFilter(c,fusfilter,matfilter,e,tp,pre_select_mat_location,mat_operation_code_map,post_select_mat_location,additional_fcheck,sumtype,sumpos,pre_select_mat_opponent_location)
 	local res=c:IsType(TYPE_FUSION) and (not fusfilter or fusfilter(c,tp)) and c:IsCanBeSpecialSummoned(e,sumtype,tp,false,false,sumpos)
 	if res==false then
 		return false
 	end
-	local mg=FusionSpell.GetMaterialsGroupForTargetCard(c,tp,e,matfilter,pre_select_mat_location,mat_operation_code_map,post_select_mat_location)
+	local mg=FusionSpell.GetMaterialsGroupForTargetCard(c,tp,e,matfilter,pre_select_mat_location,mat_operation_code_map,post_select_mat_location,pre_select_mat_opponent_location)
 	if additional_fcheck~=nil then
 		aux.FCheckAdditional=FusionSpell.GetFusionSpellFCheckAdditionalFunction(additional_fcheck,tp,c)
 	end
@@ -2577,7 +2698,7 @@ function FusionSpell.MultiMaterialEffectPrompt(effects,tp,e)
 end
 --- filter out materials that does not necessary come from fusion spell and pass to the gcheck of fusion spell
--- @param fusion_spell_additional_fcheck_function FUSION_FCHECK_FUNCTION
+--- @param fusion_spell_additional_fcheck_function FUSION_FGCHECK_FUNCTION
 function FusionSpell.GetFusionSpellFCheckAdditionalFunction(fusion_spell_additional_fcheck_function,tp,tc)
 	return (function(f_tp,mg,fc)
 		local extra_mg=mg:Filter(FusionSpell.GetExtraMaterialEffect,nil,tp,tc)
@@ -2586,7 +2707,7 @@ function FusionSpell.GetFusionSpellFCheckAdditionalFunction(fusion_spell_additio
 end
 --- all material must come from chain material, only pass all and pass to the gcheck of fusion spell
--- @param fusion_spell_additional_fcheck_function FUSION_FCHECK_FUNCTION
+--- @param fusion_spell_additional_fcheck_function FUSION_FGCHECK_FUNCTION
 function FusionSpell.GetFusionSpellFCheckAdditionalFunctionForChainMaterial(fusion_spell_additional_fcheck_function,tp,c)
 	return (function(f_tp,mg,fc)
 		return fusion_spell_additional_fcheck_function(f_tp,Group.CreateGroup(),fc,mg)