camera_set/get_view_*() Functions Related to Following a Target Are Unclear

[ParodyKnaveBob]

Description

Monthly IDE (and thus Manual) v2023.11.1.129

I did a lot of digging (and testing) before coming here, and I either failed as a researcher, or the manual lacks information. This relates to #2534 but goes much further, and yet it almost entirely boils down to one question: Does the camera care about its target instance's x and y or its mask_index? (Answer: x and y. I'll file a separate Feature Request re: I expected and would prefer mask_index.)

• Cameras and Viewports
  No mention of camera targeting, which is probably fine. I just figured I'd mention it explicitly.
• camera_set_view_speed
  • The opening paragraph (the only paragraph) would improve if it mentioned the target instance in its first sentence.
  • The xspeed and yspeed arguments would improve if they mentioned the target instance at all.
  • The GML example would improve if it were anything more than function(arbitrary_arguments); explained via, The above code will function on the arbitrary arguments.
  • This whole page has zero real explanation what it actually does in relation to an instance moving around in a room.
  • Ontop that, the word target never appears in the page, obfuscating it from relevance and potentially denying it in searches.
  • Ontop that, the page says, camera_id, xspeed, yspeed, and the IDE says, camera, x_speed, y_speed; consistency would be nice, but I understand if this subpoint is low priority.
• camera_set_view_border
  This page would improve by mentioning that the border relates to the target instance's x and y values (and not its mask_index). It would further improve by advising that if you want the mask_index to act like it has any bearing, you either need to center your sprite origin or math out the border/position manually, depending which direction the target instance moves within the room.
• camera_set_view_target
  • The syntax definition -- camera_set_view_target(camera_id, instance_id/object_id) -- would improve if that confusing / were removed. See how the instance_destroy Syntax and Arguments sections handle this.
  • This page would improve by noting that the target is only followed via x and y, that if you want the mask_index to act like it has any bearing, you either need to center your sprite origin or math out the border/position manually, depending which direction the target instance moves within the room.
• camera_get_view_speed_x camera_get_view_speed_y
  • These pages would improve if the speeds being gotten were clarified as being the set speeds vs. the actual current speeds, which then opens the door to noting a targeted instance.
  • The word target never appears on these pages, obfuscating them from relevance and potentially denying them in searches.
• camera_get_view_border_x camera_get_view_border_y
  • These first sentences would improve if rewritten; just off the top of my head (for x and horizontal): "This function can be used to retrieve the border value of the given camera along the x axis (horizontal border) regarding the camera's target instance to follow."
  • It probably wouldn't hurt their one paragraph to mention the border is the distance from the x or y and not the mask_index.
  • They might improve if their example explanations didn't use xborder and yborder as one-word terms; at the very least, they might use x_border and y_border to match the arguments described on the camera_set_view_border() page.
  • The word target never appears on these pages, obfuscating them from relevance and potentially denying them in searches.
• camera_get_view_target
  This page might improve if it, too, noted that the target is only followed via x and y and that if you want the mask_index to act like it has any bearing, you either need to center your sprite origin or math out the border/position manually, depending which direction the target instance moves within the room.

It's possible the related IDE tooltips might be improved in conjunction with all this, but them being terse is expected and fine imo. The manual is the real meal to the tooltips' appetizers. $;^ ]

Manual Link

No response