Contextual tutorials for swapping hands and dropping items (#72292)

# Requires https://github.com/tgstation/tgstation/pull/72320 ## About The Pull Request https://user-images.githubusercontent.com/35135081/209700892-e54be6cf-d18c-4d12-acd1-e5eb46e9d82d.mp4 https://user-images.githubusercontent.com/35135081/209700911-751b8a0e-d770-49fa-a6eb-ce50aa0fa670.mp4 --- Adds a system for tutorials that: - Are contextually given - Are not given again after completion - Can optionally not trigger for anyone who first played before a certain date Uses this system for a tutorial for switching hands/dropping items. This tutorial is triggered when you try to click on an item with another item, and `afterattack` return FALSE. In order for this to work as smoothly as possible, I'm going to open a separate PR that cleans up the `afterattack` on everything to either return TRUE/FALSE. ## Why It's Good For The Game SS13 is an extremely confusing game, being able to do tutorials in a non-intrusive way (like a separate tutorial mode) is nice. The system in place is going to be perfectly usable for introducing mechanics to both fresh players and experienced players alike (such as for future content). ## Changelog 🆑 qol: New players will now get a contextual tutorial for how to switch hands and drop items. /🆑 Co-authored-by: Fikou <23585223+Fikou@users.noreply.github.com>
2026-01-25 08:34:23 +00:00 · 2023-01-08 16:29:18 -08:00
parent 8c2c03998f
commit 9740f104d0
31 changed files with 763 additions and 18 deletions
--- a/code/modules/tutorials/tutorials/drop.dm
+++ b/code/modules/tutorials/tutorials/drop.dm
@@ -0,0 +1,109 @@
+#define TIME_TO_START_MOVING_DROP_ICON (0.5 SECONDS)
+
+#define STAGE_DROP_ITEM "STAGE_DROP_ITEM"
+#define STAGE_PICK_SOMETHING_UP "STAGE_PICK_SOMETHING_UP"
+
+/// Tutorial for showing how to drop items.
+/// Fired when clicking on an item with another item with a filled inactive hand.
+/datum/tutorial/drop
+	grandfather_date = "2023-01-07"
+
+	var/stage = STAGE_DROP_ITEM
+	var/atom/movable/screen/drop_preview
+	var/obj/last_held_item
+
+/datum/tutorial/drop/Destroy(force, ...)
+	last_held_item = null
+	user.client?.screen -= drop_preview
+	QDEL_NULL(drop_preview)
+	return ..()
+
+/datum/tutorial/drop/perform(list/params)
+	create_drop_preview(params[SCREEN_LOC])
+	addtimer(CALLBACK(src, PROC_REF(show_instructions)), TIME_TO_START_MOVING_DROP_ICON)
+
+	RegisterSignal(user, COMSIG_MOB_DROPPING_ITEM, PROC_REF(on_dropped_item))
+	RegisterSignal(user, COMSIG_MOB_SWAP_HANDS, PROC_REF(on_swap_hands))
+	RegisterSignal(user, COMSIG_LIVING_PICKED_UP_ITEM, PROC_REF(on_pick_up_item))
+
+	update_held_item()
+
+/datum/tutorial/drop/perform_completion_effects_with_delay()
+	UnregisterSignal(user, list(COMSIG_MOB_DROPPING_ITEM, COMSIG_MOB_SWAP_HANDS, COMSIG_LIVING_PICKED_UP_ITEM))
+	if (!isnull(last_held_item))
+		UnregisterSignal(last_held_item, COMSIG_MOVABLE_MOVED)
+
+	return 0
+
+/datum/tutorial/drop/proc/create_drop_preview(initial_screen_loc)
+	drop_preview = animate_ui_element(
+		"act_drop",
+		initial_screen_loc,
+		ui_drop_throw,
+		TIME_TO_START_MOVING_DROP_ICON,
+	)
+
+/datum/tutorial/drop/proc/show_instructions()
+	if (QDELETED(src))
+		return
+
+	switch (stage)
+		if (STAGE_DROP_ITEM)
+			show_instruction(keybinding_message(
+				/datum/keybinding/mob/drop_item,
+				"Press '%KEY%' to drop your current item",
+				"Click '<b>DROP</b>' to drop your current item",
+			))
+		if (STAGE_PICK_SOMETHING_UP)
+			show_instruction("Pick something up!")
+
+/datum/tutorial/drop/proc/on_swap_hands()
+	SIGNAL_HANDLER
+
+	if (isnull(user.get_active_held_item()))
+		if (stage != STAGE_PICK_SOMETHING_UP)
+			stage = STAGE_PICK_SOMETHING_UP
+			show_instructions()
+	else if (stage == STAGE_PICK_SOMETHING_UP)
+		stage = STAGE_DROP_ITEM
+		show_instructions()
+
+	update_held_item()
+
+/datum/tutorial/drop/proc/on_dropped_item()
+	SIGNAL_HANDLER
+
+	stage = STAGE_PICK_SOMETHING_UP
+	show_instructions()
+
+/datum/tutorial/drop/proc/on_pick_up_item()
+	SIGNAL_HANDLER
+
+	if (stage != STAGE_PICK_SOMETHING_UP)
+		dismiss()
+		return
+
+	complete()
+
+// Exists so that if we, say, place the item on a table, we don't count that as completion
+/datum/tutorial/drop/proc/update_held_item()
+	if (!isnull(last_held_item))
+		UnregisterSignal(last_held_item, COMSIG_MOVABLE_MOVED)
+
+	last_held_item = user.get_active_held_item()
+	if (isnull(last_held_item))
+		return
+
+	RegisterSignal(last_held_item, COMSIG_MOVABLE_MOVED, PROC_REF(on_held_item_moved))
+
+/datum/tutorial/drop/proc/on_held_item_moved()
+	SIGNAL_HANDLER
+
+	if (stage == STAGE_PICK_SOMETHING_UP)
+		return
+
+	dismiss()
+
+#undef STAGE_DROP_ITEM
+#undef STAGE_PICK_SOMETHING_UP
+#undef TIME_TO_START_MOVING_DROP_ICON
--- a/code/modules/tutorials/tutorials/switch_hands.dm
+++ b/code/modules/tutorials/tutorials/switch_hands.dm
@@ -0,0 +1,86 @@
+#define TIME_TO_START_MOVING_HAND_ICON (0.5 SECONDS)
+
+#define STAGE_SHOULD_SWAP_HAND "STAGE_SHOULD_SWAP_HAND"
+#define STAGE_PICK_UP_ITEM "STAGE_PICK_UP_ITEM"
+
+/// Tutorial for showing how to switch hands.
+/// Fired when clicking on an item with another item with an empty inactive hand.
+/datum/tutorial/switch_hands
+	grandfather_date = "2023-01-07"
+
+	var/stage = STAGE_SHOULD_SWAP_HAND
+	var/atom/movable/screen/hand_preview
+
+	// So that they don't just drop the item
+	var/hand_to_watch
+
+/datum/tutorial/switch_hands/New(mob/user)
+	. = ..()
+
+	hand_to_watch = (user.active_hand_index % user.held_items.len) + 1
+
+/datum/tutorial/switch_hands/Destroy(force, ...)
+	user.client?.screen -= hand_preview
+	QDEL_NULL(hand_preview)
+
+	return ..()
+
+/datum/tutorial/switch_hands/perform(list/params)
+	create_hand_preview(params[SCREEN_LOC])
+	addtimer(CALLBACK(src, PROC_REF(show_instructions)), TIME_TO_START_MOVING_HAND_ICON)
+
+	RegisterSignal(user, COMSIG_MOB_SWAP_HANDS, PROC_REF(on_swap_hands))
+	RegisterSignal(user, COMSIG_LIVING_PICKED_UP_ITEM, PROC_REF(on_pick_up_item))
+
+/datum/tutorial/switch_hands/perform_completion_effects_with_delay()
+	UnregisterSignal(user, list(COMSIG_MOB_SWAP_HANDS, COMSIG_LIVING_PICKED_UP_ITEM))
+	return 0
+
+/datum/tutorial/switch_hands/proc/create_hand_preview(initial_screen_loc)
+	hand_preview = animate_ui_element(
+		"hand_[hand_to_watch % 2 == 0 ? "r" : "l"]",
+		initial_screen_loc,
+		ui_hand_position(hand_to_watch),
+		TIME_TO_START_MOVING_HAND_ICON,
+	)
+
+/datum/tutorial/switch_hands/proc/show_instructions()
+	if (QDELETED(src))
+		return
+
+	switch (stage)
+		if (STAGE_SHOULD_SWAP_HAND)
+			var/hand_name = hand_to_watch % 2 == 0 ? "right" : "left"
+			show_instruction(keybinding_message(
+				/datum/keybinding/mob/swap_hands,
+				"Press '%KEY%' to use your [hand_name] hand",
+				"Click '<b>SWAP</b>' to use your [hand_name] hand",
+			))
+		if (STAGE_PICK_UP_ITEM)
+			show_instruction("Pick something up!")
+
+/datum/tutorial/switch_hands/proc/on_swap_hands()
+	SIGNAL_HANDLER
+
+	if (isnull(user.get_active_held_item()))
+		stage = STAGE_PICK_UP_ITEM
+		show_instructions()
+	else if (isnull(user.get_inactive_held_item()))
+		stage = STAGE_SHOULD_SWAP_HAND
+		show_instructions()
+	else
+		// You somehow got an item in both hands during the tutorial without switching hands.
+		// Good job I guess?
+		complete()
+
+/datum/tutorial/switch_hands/proc/on_pick_up_item()
+	SIGNAL_HANDLER
+
+	if (user.active_hand_index != hand_to_watch)
+		return
+
+	complete()
+
+#undef STAGE_PICK_UP_ITEM
+#undef STAGE_SHOULD_SWAP_HAND
+#undef TIME_TO_START_MOVING_HAND_ICON