Refactors how legs are displayed so they no longer appear above one-another when looking EAST or WEST (#66607)

So, for over 5 years, left legs have been displaying over right legs. Never noticed it? Don't blame you.
Here's a nice picture provided by #20603 (Bodypart sprites render with incorrect layering), that clearly displays the issue that was happening:

It still happened to this day.
Notice how the two directions don't look the same? That's because the left leg is always displaying above the right one.

Obviously, that's no good, and I was like "oh, that's a rendering issue, so there's nothing I can do about it, it's an issue with BYOND".

Until it struck me.

"What if we used a mask that would cut out the parts of the right leg, from the left leg, so that it doesn't actually look as if it's above it?"

Here I am, after about 25 hours of work, 15 of which of very painful debugging due to BYOND's icon documentation sucking ass.

So, how does it work?

Basically, we create a mask of a left leg (that'll be explained later down the line), more specifically, a cutout of JUST the WEST dir of the left leg, with every other dir being just white squares. We then cache that mask in a static list on the right leg, so we don't generate it every single time, as that can be expensive. All that happens in update_body_parts(), where I've made it so legs are handled separately, to avoid having to generate limb icons twice in a row, due to it being expensive. In that, when we generate_limb_icon() a right leg, we apply the proper left leg mask if necessary.

Now, why masking the right leg, if the issue was the left leg?
Because, see, when you actually amputated someone, and gave them a leg again, it would end up being that new leg that would be displayed below the other leg. So I fixed that, by making it so that bodyparts would be sorted correctly, before the end of update_body_parts(). Which means that right legs ended up displaying above left legs, which meant that I had to change everything I had written to work on right legs rather than left legs.

I spent so much time looking up BYOND documentation for MapColors() and filters and all icon and image vars and procs, I decided to make a helper proc called generate_icon_alpha_mask(), because honestly it would've saved me at least half a day of pure code debugging if I had it before working on this refactor.

I tried to put as much documentation down as I could, because this shit messes with your brain if you spend too long looking at it. icon and image are two truly awful classes to work with, and I don't look forward to messing with them more in the future.

Anyway. It's nice, because it requires no other effort from anyone, no matter what the shape of the leg is actually like. It's all handled dynamically, and only one per type of leg, meaning that it's not actually too expensive either, which is very nice. Especially since it's very downstreams-friendly from being done this way.


It fixes #20603 (Bodypart sprites render with incorrect layering), an issue that has been around for over half a decade, as well as probably many more issues that I just didn't bother sifting through.

Plus, it just looks so much better.

code/modules/mob/living/carbon/carbon_update_icons.dm

@@ -248,24 +248,40 @@
 	update_wound_overlays()
 	var/list/needs_update = list()
 	var/limb_count_update = FALSE
+	var/obj/item/bodypart/l_leg/left_leg
+	var/obj/item/bodypart/r_leg/right_leg
+	var/old_left_leg_key
 	for(var/obj/item/bodypart/limb as anything in bodyparts)
 		limb.update_limb(is_creating = update_limb_data) //Update limb actually doesn't do much, get_limb_icon is the cpu eater.
+
+		if(limb.body_zone == BODY_ZONE_R_LEG)
+			right_leg = limb
+			continue // Legs are handled separately
+
 		var/old_key = icon_render_keys?[limb.body_zone] //Checks the mob's icon render key list for the bodypart
 		icon_render_keys[limb.body_zone] = (limb.is_husked) ? limb.generate_husk_key().Join() : limb.generate_icon_key().Join() //Generates a key for the current bodypart
-		if(!(icon_render_keys[limb.body_zone] == old_key)) //If the keys match, that means the limb doesn't need to be redrawn
+
+		if(limb.body_zone == BODY_ZONE_L_LEG)
+			left_leg = limb
+			old_left_leg_key = old_key
+			continue // Legs are handled separately
+
+		if(icon_render_keys[limb.body_zone] != old_key) //If the keys match, that means the limb doesn't need to be redrawn
 			needs_update += limb
 
 
+	// Here we handle legs differently, because legs are a mess due to layering code. So we got to process the left leg first. Thanks BYOND.
+	var/legs_need_redrawn = update_legs(right_leg, left_leg, old_left_leg_key)
+
 	var/list/missing_bodyparts = get_missing_limbs()
 	if(((dna ? dna.species.max_bodypart_count : BODYPARTS_DEFAULT_MAXIMUM) - icon_render_keys.len) != missing_bodyparts.len) //Checks to see if the target gained or lost any limbs.
 		limb_count_update = TRUE
 		for(var/missing_limb in missing_bodyparts)
 			icon_render_keys -= missing_limb //Removes dismembered limbs from the key list
 
-	if(!needs_update.len && !limb_count_update)
+	if(!needs_update.len && !limb_count_update && !legs_need_redrawn)
 		return
 
-	remove_overlay(BODYPARTS_LAYER)
 
 	//GENERATE NEW LIMBS
 	var/list/new_limbs = list()
@@ -277,12 +293,51 @@
 		else
 			new_limbs += limb_icon_cache[icon_render_keys[limb.body_zone]] //Pulls existing sprites from the cache
 
+	remove_overlay(BODYPARTS_LAYER)
+
 	if(new_limbs.len)
 		overlays_standing[BODYPARTS_LAYER] = new_limbs
 
 	apply_overlay(BODYPARTS_LAYER)
 
 
+/**
+ * Here we update the legs separately from the other bodyparts. Thanks BYOND for so little support for dir layering.
+ *
+ * Arguments:
+ * * right_leg - Right leg that we might need to update. Can be null.
+ * * left_leg - Left leg that we might need to update. Can be null.
+ * * old_left_leg_key - The icon_key of the left_leg, passed here to avoid having to re-generate it in this proc.
+ *
+ * Returns a boolean, TRUE if the legs need to be redrawn, FALSE if they do not need to be redrawn.
+ * Necessary so that we can ensure that modifications of legs cause overlay updates.
+ */
+/mob/living/carbon/proc/update_legs(obj/item/bodypart/r_leg/right_leg, obj/item/bodypart/l_leg/left_leg, old_left_leg_key)
+	var/list/left_leg_icons // yes it's actually a list, bet you didn't expect that, now did you?
+	var/legs_need_redrawn = FALSE
+	if(left_leg)
+		// We regenerate the look of the left leg if it isn't already cached, we don't if not.
+		if(icon_render_keys[left_leg.body_zone] != old_left_leg_key)
+			limb_icon_cache[icon_render_keys[left_leg.body_zone]] = left_leg.get_limb_icon()
+			legs_need_redrawn = TRUE
+
+		left_leg_icons = limb_icon_cache[icon_render_keys[left_leg.body_zone]]
+
+	if(right_leg)
+		var/old_right_leg_key = icon_render_keys?[right_leg.body_zone]
+		right_leg.left_leg_mask_key = left_leg?.generate_mask_key().Join() // We generate a new mask key, to see if it changed.
+		// We regenerate the left_leg_mask in case that it doesn't exist yet.
+		if(right_leg.left_leg_mask_key && !right_leg.left_leg_mask_cache[right_leg.left_leg_mask_key] && left_leg_icons)
+			right_leg.left_leg_mask_cache[right_leg.left_leg_mask_key] = generate_left_leg_mask(left_leg_icons[1], right_leg.left_leg_mask_key)
+		// We generate a new icon_render_key, which also takes into account the left_leg_mask_key so we cache the masked versions of the limbs too.
+		icon_render_keys[right_leg.body_zone] = right_leg.is_husked ? right_leg.generate_husk_key().Join("-") : right_leg.generate_icon_key().Join()
+
+		if(icon_render_keys[right_leg.body_zone] != old_right_leg_key)
+			limb_icon_cache[icon_render_keys[right_leg.body_zone]] = right_leg.get_limb_icon()
+			legs_need_redrawn = TRUE
+
+	return legs_need_redrawn
+
 
 /////////////////////////
 // Limb Icon Cache 2.0 //
@@ -313,6 +368,29 @@
 
 	return .
 
+/**
+ * Generates a cache key for masks (mainly only used for right legs now, but perhaps in the future...).
+ *
+ * This is exactly like generate_icon_key(), except that it doesn't add `"-[draw_color]"`
+ * to the returned list under any circumstance. Why? Because it (generate_icon_key()) is
+ * a proc that gets called a ton and I don't want this to affect its performance.
+ *
+ * Returns a list of strings.
+ */
+/obj/item/bodypart/proc/generate_mask_key()
+	RETURN_TYPE(/list)
+	. = list()
+	if(is_dimorphic)
+		. += "[limb_gender]"
+	. += "[limb_id]"
+	. += "[body_zone]"
+	for(var/obj/item/organ/external/external_organ as anything in external_organs)
+		if(!external_organ.can_draw_on_bodypart(owner))
+			continue
+		. += "[external_organ.generate_icon_cache()]"
+
+	return .
+
 ///Generates a cache key specifically for husks
 /obj/item/bodypart/proc/generate_husk_key()
 	RETURN_TYPE(/list)
@@ -346,3 +424,61 @@
 		. += "-HAIR_HIDDEN"
 
 	return .
+
+/obj/item/bodypart/r_leg/generate_icon_key()
+	RETURN_TYPE(/list)
+	. = ..()
+	if(left_leg_mask_key) // We do this so we can cache the versions with and without a mask, for when there's no left leg.
+		. += "-[left_leg_mask_key]"
+
+	return .
+
+/**
+ * This proc serves as a way to ensure that right legs don't overlap above left legs when their dir is WEST on a mob.
+ *
+ * It's using the `left_leg_mask_cache` to avoid generating a new mask when unnecessary, which means that there needs to be one
+ * for the proc to return anything.
+ *
+ * Arguments:
+ * * right_leg_icon_file - The icon file of the right leg overlay we're trying to apply a mask to.
+ * * right_leg_icon_state - The icon_state of the right leg overlay we're trying to apply a mask to.
+ * * image_dir - The direction applied to the icon, only meant for when the leg is dropped, so it remains
+ * facing SOUTH all the time.
+ *
+ * Returns the `/image` of the right leg that was masked, or `null` if the mask didn't exist.
+ */
+/obj/item/bodypart/r_leg/proc/generate_masked_right_leg(right_leg_icon_file, right_leg_icon_state, image_dir)
+	RETURN_TYPE(/image)
+	if(!left_leg_mask_cache[left_leg_mask_key] || !right_leg_icon_file || !right_leg_icon_state)
+		return
+
+	var/icon/right_leg_icon = icon(right_leg_icon_file, right_leg_icon_state)
+	right_leg_icon.Blend(left_leg_mask_cache[left_leg_mask_key], ICON_MULTIPLY)
+	return image(right_leg_icon, right_leg_icon_state, layer = -BODYPARTS_LAYER, dir = image_dir)
+
+
+/**
+ * The proc that handles generating left leg masks at runtime.
+ * It basically creates an icon that are all white on all dirs except WEST, where there's a cutout
+ * of the left leg that needed to be masked.
+ *
+ * It does /not/ cache the mask itself, and as such, the caching must be done manually (which it is, look up in update_body_parts()).
+ *
+ * Arguments:
+ * * image/left_leg_image - `image` of the left leg that we need to create a mask out of.
+ *
+ * Returns the generated left leg mask as an `/icon`, or `null` if no left_leg_image is provided.
+ */
+/proc/generate_left_leg_mask(image/left_leg_image)
+	RETURN_TYPE(/icon)
+	if(!left_leg_image)
+		return
+	var/icon/left_leg_alpha_mask = generate_icon_alpha_mask(left_leg_image.icon, left_leg_image.icon_state)
+	// Right here, we use the crop_mask_icon to single out the WEST sprite of the mask we just created above.
+	var/icon/crop_mask_icon = icon(icon = 'icons/mob/left_leg_mask_base.dmi', icon_state = "mask_base")
+	crop_mask_icon.Blend(left_leg_alpha_mask, ICON_MULTIPLY)
+	// Then, we add (with ICON_OR) that singled-out WEST mask to a template mask that has the NORTH,
+	// SOUTH and EAST dirs as full white squares, to finish our WEST-directional mask.
+	var/icon/new_mask_icon = icon(icon = 'icons/mob/left_leg_mask_base.dmi', icon_state = "mask_rest")
+	new_mask_icon.Blend(crop_mask_icon, ICON_OR)
+	return new_mask_icon