Merge pull request #1325 from endlessm/filling-docs

Document the components of the fill-matching game mechanic

Author: wjt

scenes/game_elements/characters/enemies/throwing_enemy/components/throwing_enemy.gd

@@ -1,9 +1,16 @@
 # SPDX-FileCopyrightText: The Threadbare Authors
 # SPDX-License-Identifier: MPL-2.0
 @tool
-## Enemy that throws projectiles to the player.
 class_name ThrowingEnemy
 extends CharacterBody2D
+## Enemy that throws [Projectile]s to the player.
+##
+## @tutorial: https://github.com/endlessm/threadbare/discussions/1323
+##
+## This is a piece of the fill-matching mechanic.
+## [br][br]
+## When throwing, the label/color of the projectile is picked from
+## [member allowed_labels] and [member color_per_label].
 
 enum State { IDLE, WALKING, ATTACKING, DEFEATED }
 

scenes/game_elements/props/filling_barrel/components/filling_barrel.gd

@@ -3,7 +3,17 @@
 @tool
 class_name FillingBarrel
 extends StaticBody2D
-
+## A barrel that starts empty and gets filled until completion
+##
+## @tutorial: https://github.com/endlessm/threadbare/discussions/1323
+##
+## This is a piece of the fill-matching mechanic.
+## [br][br]
+## Call [member fill()] to increment the amount. When
+## [member needed_amount] is reached, the [signal completed]
+## is emited.
+
+## Emited when the barrel amount reaches [member needed_amount].
 signal completed
 
 const DEFAULT_SPRITE_FRAMES: SpriteFrames = preload("uid://dlsq0ke41s1yh")
@@ -61,13 +71,13 @@ func _ready() -> void:
 	animated_sprite_2d.frame = 0
 
 
-## Increment the amount by one and play the fill animation. If completed, also play the completed
+## Increment the amount and play an animation. If completed, also play the completed
 ## animation and remove this barrel from the current scene.
-func fill() -> void:
+func increment(by: int = 1) -> void:
 	if _amount >= needed_amount:
 		return
-	animation_player.play(&"fill")
-	_amount += 1
+	animation_player.play(&"increment")
+	_amount += by
 	animated_sprite_2d.frame = floor(float(_amount) / needed_amount * _total_frames())
 	if _amount >= needed_amount:
 		_disable_collisions.call_deferred()

scenes/game_elements/props/filling_barrel/filling_barrel.tscn

@@ -106,7 +106,7 @@ tracks/3/keys = {
 }
 
 [sub_resource type="Animation" id="Animation_fs5vc"]
-resource_name = "fill"
+resource_name = "increment"
 length = 0.8
 tracks/0/type = "audio"
 tracks/0/imported = false
@@ -152,7 +152,7 @@ tracks/2/keys = {
 _data = {
 &"RESET": SubResource("Animation_tu5xq"),
 &"completed": SubResource("Animation_6inx0"),
-&"fill": SubResource("Animation_fs5vc")
+&"increment": SubResource("Animation_fs5vc")
 }
 
 [node name="FillingBarrel" type="StaticBody2D" groups=["filling_barrels"]]

scenes/game_elements/props/projectile/components/projectile.gd

@@ -1,9 +1,21 @@
 # SPDX-FileCopyrightText: The Threadbare Authors
 # SPDX-License-Identifier: MPL-2.0
-## A RigidBody2D that can be thrown between enemies and player. It has a label too, and it can
-## be used to fill barrels with the matching label.
 class_name Projectile
 extends RigidBody2D
+## A projectile that can fill matching [FillingBarrel]s.
+##
+## @tutorial: https://github.com/endlessm/threadbare/discussions/1323
+##
+## This is a piece of the fill-matching mechanic.
+## [br][br]
+## The projectile has a [member label] and optionally a [member color]
+## to tint it.
+## When the projectile collides with a [FillingBarrel] and both labels match,
+## it calls [member FillingBarrel.increment()] and is removed.
+## [br][br]
+## The projectile will live in the scene until [member duration_timer] times up.
+## When the projectile collides with anything, this timer is resetted, so the
+## projectile life is expanded.
 
 ## The projectile can fill barrels with the matching label.
 @export var label: String = "???"
@@ -61,7 +73,13 @@ var _trail_particles: GPUParticles2D
 @onready var visible_things: Node2D = %VisibleThings
 @onready var animated_sprite_2d: AnimatedSprite2D = %AnimatedSprite2D
 @onready var trail_fx_marker: Marker2D = %TrailFXMarker
+
+## How long the projectile lives in the scene.
+## [br][br]
+## This timer is restarted each time the projectile collides with anything.
+## So the life of the projectile is extended in each collision.
 @onready var duration_timer: Timer = %DurationTimer
+
 @onready var hit_sound: AudioStreamPlayer2D = %HitSound
 
 
@@ -142,7 +160,7 @@ func _on_body_entered(body: Node2D) -> void:
 	if body.owner is FillingBarrel:
 		var filling_barrel: FillingBarrel = body.owner as FillingBarrel
 		if filling_barrel.label == label:
-			filling_barrel.fill()
+			filling_barrel.increment()
 			queue_free()
 
 

scenes/game_logic/fill_game_logic.gd

@@ -2,12 +2,31 @@
 # SPDX-License-Identifier: MPL-2.0
 class_name FillGameLogic
 extends Node
+## Manages the logic of the fill-matching game.
+##
+## @tutorial: https://github.com/endlessm/threadbare/discussions/1323
+##
+## This is a piece of the fill-matching mechanic.
+## [br][br]
+## Grabs the label and optional color of each [FillingBarrel] that exist in the
+## current scene, and assigns them as the allowed label/color of the [Projectile]
+## that each [ThrowingEnemy] is allowed to throw.
+## Each time a [FillingBarrel] is filled, perform the label/color assignment again
+## so [ThrowingEnemy]s only throw projectiles that can increase the amount of
+## the remaining barrels.
+## [br][br]
+## Also keep track of the completed [FillingBarrel]s and emit [signal goal_reached]
+## when [member barrels_to_win] is reached.
 
+## Emited when [member barrels_completed] reaches [member barrels_to_win].
 signal goal_reached
 
+## How many barrels to complete for winning.
 @export var barrels_to_win: int = 1
+
 @export var intro_dialogue: DialogueResource
 
+## Counter for the completed barrels.
 var barrels_completed: int = 0
 
 

scenes/quests/story_quests/el_juguete_perdido/2_combat/combat.tscn

@@ -83,7 +83,6 @@ animations = [{
 
 [sub_resource type="Resource" id="Resource_a51xm"]
 script = ExtResource("9_w3dy0")
-name = ""
 type = 1
 metadata/_custom_type_script = "uid://bgmwplmj3bfls"
 

scenes/quests/story_quests/el_juguete_perdido/objects_components/barrel.tscn

@@ -106,7 +106,7 @@ tracks/3/keys = {
 }
 
 [sub_resource type="Animation" id="Animation_fs5vc"]
-resource_name = "fill"
+resource_name = "increment"
 length = 0.8
 tracks/0/type = "audio"
 tracks/0/imported = false
@@ -152,7 +152,7 @@ tracks/2/keys = {
 _data = {
 &"RESET": SubResource("Animation_tu5xq"),
 &"completed": SubResource("Animation_6inx0"),
-&"fill": SubResource("Animation_fs5vc")
+&"increment": SubResource("Animation_fs5vc")
 }
 
 [node name="FillingBarrel" type="StaticBody2D" groups=["filling_barrels"]]