ScriptingEngine extended to allow non-Card objects to integrate with it

Author: db0

CHANGELOG.md

@@ -16,6 +16,12 @@ New **mandatory** CardConfig property added: `EXPLANATIONS` (Dictionary). It sto
 
 New CFConst poperty added: `VIEWPORT_FOCUS_ZOOM_TYPE`. Set to either "resize" or "scale" (default = "resize"). If set to scale, will magnify the card during viewport focus using godot scaling. If set to resize, will resize the card's viewport dupe's dimentions. This prevent blurry text, but needs more setup in the card's front script.
 
+Game has been adjusted to allow the ScriptingEngine to work non-Card classes. To enable this the following changes have been made which might affect your game if you've extended the Card or ScriptingEngine classes
+
+* Card `card_name` property has been renamed to `canonical_name`
+* Card `retrieve_card_scripts` function has been renamed to `retrieve_scripts`
+* ScriptingEngine and ScriptObject `owner_card` variable has been renamed to `owner` and is not expected that it be a Card class
+
 ### Bugs
 
 * Fixed crash when window x-axis resized to minimum
@@ -28,6 +34,7 @@ New CFConst poperty added: `VIEWPORT_FOCUS_ZOOM_TYPE`. Set to either "resize" or
 * Deckbuilder will now display the total or filtered count of cards shown
 * Added new class: GameStats, which can be used to submit stats to your own instance of [CGF-Stats](https://github.com/db0/CGF-Stats)
 * Can now show extra info below card focus viewport, such as keyword explanations or illustrator info
+* Can now extend deckbuilder DBListCardObject and 
 
 #### ScriptingEngine
 

INSTALL.md

@@ -24,6 +24,7 @@ While everything in there can be modified, some files need to exist in one form
 * You **need** CustomScripts.gd, even if it custom_script() function does not match anything.
 * You **need** CFConst, but you should customize its constants to fit your needs. It is in custom so that you do not lose your changes during an upgrade.
 * You **need** at least 1 Card Back, 1 Card Front and 1 CardManipulationButton scene, to link to your card templates.
+* You **need** at least 1 Info Panel Scene. You can re-use CGFInfoPanel.tcsn
 
 All other files, especially those starting with "CGF" can be deleted, or you can keep them around for reference.
 

README.md

@@ -124,7 +124,7 @@ Please see the [Install Guide](INSTALL.md)
 
 One of the most powerful features of this framework, is the possibility to easily script each individual card's abilities from start to finish, so that a player only needs to double-click on a card and your code will handle the proper execution. This allows games to very easily create complete rules enforcement of all card abilities, from the simplest to the most tricky ones.
 
-Please see the [ScriptDefinitions](https://github.com/db0/godot-card-gaming/wiki/ScriptDefinitions) documentation for more details
+Please see the [ScriptingEngine](SCRIPTING_ENGINE] and [ScriptDefinitions](https://github.com/db0/godot-card-gaming/wiki/ScriptDefinitions) documentation for more details.
 
 The game comes with some sample scripted cards which can be found under `res://src/custom/cards/sets`.
 

SCRIPTING_ENGINE.md

@@ -0,0 +1,18 @@
+# Godot Card Game Scripting Engine
+
+The ScriptingEngine (ScEng) of the Card Game Framework is a way to allow complex interactions and manipulations of the board to be encoded in objects in the game through a simple json dictionary.
+
+Please check the [basic information in the wiki](https://github.com/db0/godot-card-gaming/wiki/ScriptDefinitions) first.
+
+## Connecting new objects to the ScriptingEngine
+
+The ScriptingEngine has been created in such a way so as to allow even non-card objects to make use of its capabilities. 
+
+To achieve that, you need to prepare you object in the following way:
+
+1. Add the object to the "scriptables" group. Objects in this group are checked whenever looking for effects that modify automatic intereactions with the board
+1. Add a "canonical_name" variable to your object's script and set it so that it has a human-readable value which refers to that object. This is used in dialogues to the player and for filtering effects
+1. Add an `execute_scripts()` method to the object. This will be called automatically due to signals and should be called with manual intereactions. It should behave similar to the `execute_scripts()` 
+in the Card object, checking filters, checking confirmations and finally invoking the ScriptingEngine with a list of tasks. The best approach would be to copy `execute_scripts()` and modify it.
+1. Add a `get_state_exec()` method to the object. This should return a string of one of the various states the object can be in, which are used to filter the correct scripts for execution.
+1. Add a `retrieve_scripts()` method to the object. This should retrieve all of the object's scripts, from wherever they are stored.

src/core/AlterantEngine.gd

@@ -29,12 +29,12 @@ func _ready() -> void:
 # Sets the owner of this Scripting Engine
 func _init(
 		trigger_card: Card,
-		alterant_card: Card,
+		alterant_object,
 		scripts_queue: Array,
 		task_details: Dictionary) -> void:
 	calculate_next_alteration(
 			trigger_card,
-			alterant_card,
+			alterant_object,
 			scripts_queue.duplicate(),
 			task_details)
 
@@ -44,7 +44,7 @@ func _init(
 # against the relevant filters and per_ requests.
 func calculate_next_alteration(
 		trigger_card: Card,
-		alterant_card: Card,
+		alterant_object,
 		scripts_queue: Array,
 		task_details: Dictionary) -> void:
 	if scripts_queue.empty():
@@ -54,7 +54,7 @@ func calculate_next_alteration(
 		var script := ScriptAlter.new(
 				scripts_queue.pop_front(),
 				trigger_card,
-				alterant_card,
+				alterant_object,
 				task_details)
 		if not script.is_primed:
 			yield(script,"primed")
@@ -64,7 +64,7 @@ func calculate_next_alteration(
 		# with one less item in our scripts_queue.
 		calculate_next_alteration(
 				trigger_card,
-				alterant_card,
+				alterant_object,
 				scripts_queue,
 				task_details)
 
@@ -79,7 +79,7 @@ func calculate_alteration(script: ScriptAlter) -> void:
 	elif SP.VALUE_PER in str(alteration_requested):
 		var per_msg = perMessage.new(
 				script.get_property(SP.KEY_ALTERATION),
-				script.owner_card,
+				script.owner,
 				script.get_property(script.get_property(SP.KEY_ALTERATION)),
 				script.trigger_card)
 		alteration = per_msg.found_things

src/core/CFControl.gd

@@ -176,7 +176,7 @@ func instance_card(card_name: String) -> Card:
 			+ card_definitions[card_name][CardConfig.SCENE_PROPERTY] + ".tscn")
 	var card = template.instance()
 	# We set the card_name variable so that it's able to be used later
-	card.card_name = card_name
+	card.canonical_name = card_name
 	return(card)
 
 
@@ -308,5 +308,10 @@ class SignalPropagator:
 		# It also fails to execute if I use any other flag than GROUP_CALL_UNIQUE
 		for card in cfc.get_tree().get_nodes_in_group("cards"):
 			card.execute_scripts(trigger_card,trigger,details)
+		# If we need other objects than cards to trigger scripts via signals
+		# add them to the 'scriptables' group ang ensure they have
+		# an "execute_scripts" function
+		for card in cfc.get_tree().get_nodes_in_group("scriptables"):
+			card.execute_scripts(trigger_card,trigger,details)
 #		cfc.get_tree().call_group_flags(SceneTree.GROUP_CALL_UNIQUE  ,"cards",
 #				"execute_scripts",trigger_card,trigger,details)

src/core/CFScriptUtils.gd

@@ -15,15 +15,15 @@ extends Reference
 # 	of each alterant, and each value is the modification done by that
 #	specific alterant.
 static func get_altered_value(
-		_owner_card,
+		_owner,
 		task_name: String,
 		task_properties: Dictionary,
 		value: int) -> Dictionary:
 	# The key for the alterant cache is the hash of the
 	# values passed to this function.
 	# This is the only way to compare dicts.
 	var alterant_cache_key = {
-		"_owner_card": _owner_card,
+		"_owner_card": _owner,
 		"task_name": task_name,
 		"task_properties": task_properties,
 		"value": value
@@ -36,17 +36,20 @@ static func get_altered_value(
 	else:
 		var value_alteration := 0
 		var alterants_details := {}
-		for card in cfc.get_tree().get_nodes_in_group("cards"):
-			var card_scripts = card.retrieve_card_scripts(SP.KEY_ALTERANTS)
+		var scriptables_array : Array =\
+				cfc.get_tree().get_nodes_in_group("cards")\
+				+ cfc.get_tree().get_nodes_in_group("scriptables")
+		for obj in scriptables_array:
+			var scripts = obj.retrieve_scripts(SP.KEY_ALTERANTS)
 			# We select which scripts to run from the card, based on it state
-			var state_scripts = card_scripts.get(card.get_state_exec(), [])
+			var state_scripts = scripts.get(obj.get_state_exec(), [])
 			# To avoid unnecessary operations
 			# we evoke the AlterantEngine only if we have something to execute
 			var task_details = _generate_trigger_details(task_name, task_properties)
 			if len(state_scripts):
 				var alteng = cfc.alterant_engine.new(
-						_owner_card,
-						card,
+						_owner,
+						obj,
 						state_scripts,
 						task_details)
 				if not alteng.all_alterations_completed:
@@ -57,7 +60,7 @@ static func get_altered_value(
 					# Each key in the alterants_details dictionary is the
 					# card object of the alterant. The value is the alteration
 					# this alterant has added to the total.
-					alterants_details[card] = alteng.alteration
+					alterants_details[obj] = alteng.alteration
 		# As a general rule, we don't want a positive number to turn
 		# negative (and the other way around) due to an alteration
 		# For example: if a card says, "decrease all costs by 3",

src/core/CardTemplate.gd

@@ -123,7 +123,7 @@ export var mandatory_grid_name : String
 # If not set, will be set to the value of the Name label in the front.
 # if that is also not set, will be set.
 # to the human-readable value of the "name" node property.
-export var card_name : String setget set_card_name, get_card_name
+var canonical_name : String setget set_card_name, get_card_name
 # Contains the scene which has the Card Back design to use for this card type
 # It needs to be scene which uses a CardBack class script.
 export(PackedScene) var card_back_design : PackedScene
@@ -190,7 +190,7 @@ var _placement_slot : BoardPlacementSlot = null
 #
 # Each key is a ScriptingEngine reference, and each value is a dictionary
 # With the following keys:
-# * requesting_card: The card object which has requested this temp modifier
+# * requesting_object: The object which has requested this temp modifier
 # * modifer: A dictionary with all the modifications requested by this card
 #	Each key is a (numerical) property name,
 #	and value is the temp modifier requested for this property.
@@ -236,7 +236,7 @@ onready var highlight = $Control/Highlight
 func _ready() -> void:
 	set_card_size(card_size)
 	_init_card_layout()
-	# The below call ensures out card_name variable is set.
+	# The below call ensures out canonical_name variable is set.
 	# Normally the setup() function should be used to set it,
 	# but setting the name here as well ensures that a card can be also put on
 	# The board without calling setup() and then use its hardcoded labels
@@ -267,9 +267,9 @@ func _init_card_layout() -> void:
 
 
 # Ensures that the canonical card name is set in all fields which use it.
-#  var card_name, "Name" label and self.name should use the same string.
+#  var canonical_name, "Name" label and self.name should use the same string.
 func _init_card_name() -> void:
-	if not card_name:
+	if not canonical_name:
 		# If the variable has not been set on start
 		# But the Name label has been set, we set our name to that instead
 		if card_front.card_labels["Name"].text != "":
@@ -286,7 +286,7 @@ func _init_card_name() -> void:
 	else:
 		# If the variable has been set, we ensure label and node name
 		# are matching
-		set_card_name(card_name)
+		set_card_name(canonical_name)
 
 
 # Called every frame. 'delta' is the elapsed time since the previous frame.
@@ -469,12 +469,12 @@ func _on_Card_mouse_exited() -> void:
 # This function handles filling up the card's labels according to its
 # card definition dictionary entry.
 func setup() -> void:
-	# card_name needs to be setup before we call this function
-	set_card_name(card_name)
+	# canonical_name needs to be setup before we call this function
+	set_card_name(canonical_name)
 	# The properties of the card should be already stored in cfc
 	var read_properties: Dictionary
 	if state != CardState.VIEWPORT_FOCUS:
-		read_properties = cfc.card_definitions.get(card_name, {})
+		read_properties = cfc.card_definitions.get(canonical_name, {})
 	else:
 		read_properties = properties.duplicate()
 	for property in read_properties.keys():
@@ -644,7 +644,7 @@ func get_property_and_alterants(property: String,
 			# Each value in the modifier_details dictionary is another dictionary
 			# Where the key is the card object which has added this modifier
 			# And the value is the modifier this specific card added to the total
-			temp_modifiers.modifier_details[modifiers_dict.requesting_card] =\
+			temp_modifiers.modifier_details[modifiers_dict.requesting_object] =\
 					modifiers_dict.modifier.get(property,0)
 		property_value += temp_modifiers.value_modification
 		# We use this flag to avoid an alteranty which alters get_property
@@ -830,34 +830,34 @@ func get_is_viewed() -> bool:
 	return is_viewed
 
 
-# Setter for card_name
+# Setter for canonical_name
 # Also changes the card label and the node name
 func set_card_name(value : String) -> void:
 	# if the card_front.card_labels variable is not set it means ready() has not
 	# run yet, so we just store the card name for later.
 	if not card_front:
-		card_name = value
+		canonical_name = value
 	else:
 		# We set all areas of the card to match the canonical name.
 		var name_label = card_front.card_labels["Name"]
 		card_front.set_label_text(name_label,value)
 		name = value
-		card_name = value
+		canonical_name = value
 		properties["Name"] = value
 
 
-# Getter for card_name
+# Getter for canonical_name
 func get_card_name() -> String:
-	return card_name
+	return canonical_name
 
 
-# Overwrites the built-in set name, so that it also sets card_name
+# Overwrites the built-in set name, so that it also sets canonical_name
 #
-# It's preferrable to set card_name instead.
+# It's preferrable to set canonical_name instead.
 func set_name(value : String) -> void:
 	.set_name(value)
 	card_front.card_labels["Name"].text = value
-	card_name = value
+	canonical_name = value
 
 # Setter for card_rotation.
 #
@@ -1235,7 +1235,7 @@ func execute_scripts(
 	if cfc.game_paused:
 		return
 	common_pre_execution_scripts(trigger)
-	var card_scripts = retrieve_card_scripts(trigger)
+	var card_scripts = retrieve_scripts(trigger)
 	# I use this spot to add a breakpoint when testing script behaviour
 	# especially on filters
 	if _debugger_hook:
@@ -1259,7 +1259,7 @@ func execute_scripts(
 	# Then you'd include an "is_optional_board" key at the same level as "board"
 	var confirm_return = CFUtils.confirm(
 		card_scripts,
-		card_name,
+		canonical_name,
 		trigger,
 		state_exec)
 	if confirm_return is GDScriptFunctionState: # Still working.
@@ -1273,7 +1273,7 @@ func execute_scripts(
 	# it means it's a multiple choice between two scripts
 	if typeof(state_scripts) == TYPE_DICTIONARY:
 		var choices_menu = _CARD_CHOICES_SCENE.instance()
-		choices_menu.prep(self.card_name,state_scripts)
+		choices_menu.prep(canonical_name,state_scripts)
 		# We have to wait until the player has finished selecting an option
 		yield(choices_menu,"id_pressed")
 		# If the player just closed the pop-up without choosing
@@ -1330,7 +1330,7 @@ func execute_scripts(
 #
 # Returns a dictionary of card scripts for this specific card
 # based on the current trigger.
-func retrieve_card_scripts(trigger: String) -> Dictionary:
+func retrieve_scripts(trigger: String) -> Dictionary:
 	var found_scripts: Dictionary
 	# If scripts have been defined directly in this Card object
 	# They take precedence over CardScriptDefinitions.gd
@@ -1343,7 +1343,7 @@ func retrieve_card_scripts(trigger: String) -> Dictionary:
 		# This retrieves all the script from the card, stored in cfc
 		# The seeks in them the specific trigger we're using in this
 		# execution
-		found_scripts = cfc.set_scripts.get(card_name,{}).get(trigger,{}).duplicate()
+		found_scripts = cfc.set_scripts.get(canonical_name,{}).get(trigger,{}).duplicate()
 	return(found_scripts)
 
 
@@ -1683,7 +1683,7 @@ func common_post_execution_scripts(trigger: String) -> void:
 # scripts on the card during an attempt to drag it from hand.
 func _has_targeting_cost_hand_script() -> bool:
 	var ret := false
-	var hand_scripts = retrieve_card_scripts("manual").get("hand",[])
+	var hand_scripts = retrieve_scripts("manual").get("hand",[])
 	# We don't check multiple choice cards
 	if hand_drag_starts_targeting and typeof(hand_scripts) == TYPE_ARRAY:
 		for task in hand_scripts: