flixel.FlxSprite:scale and flixel.FlxSprite:setGraphicsSize() vague descriptions

[oscarcederberg]

scale

Change the size of your sprite's graphic. NOTE: The hitbox is not automatically adjusted, use updateHitbox() for that (or setGraphicSize()). WARNING: With FlxG.renderBlit, scaling sprites decreases rendering performance by a factor of about x10!

setGraphicsSize()

Helper function to set the graphic's dimensions by using scale, allowing you to keep the current aspect ratio should one of the Integers be <= 0. It might make sense to call updateHitbox() afterwards!

From the description of scale it sounds like setGraphicsSize() will automatically update the hitbox, which it maybe doesn't ("It might make sense to call updateHitbox() afterwards!") according to the description of setGraphicsSize().

It is most likely that the issue lies in setGraphicsSize()'s description, and it should be clarified. Why does it might make sense to call updateHitbox() afterwards? Does it update hitbox or not? If it doesn't, then scale should also be fixed as it implies that setGraphicsSize() does update the hitbox.

[Geokureli]

The docs could be improved to explain this, but to answer your question:

it's important to remember that the hitbox and the graphic are entirely 2 separate things. While, in many cases, when a dev changes one, they are likely to make a similar change to the other, there are plenty of times that that is not the case, in fact, more-so than not the graphical bounds are slightly different from one another.

It's important to be able to change graphical properties separate from collision properties and vice versa, and it's helpful to have methods that change both, proportionally. In fact we could use many more helpers in this area, when you think about offset and origin as well.

So when you want to increase the hitbox size, you use width and height, because they are simply fields read when detecting object overlaps. When you want to increase the graphic size, you use scale. because this is a property read when rendering the graphic. if changing one automatically changed the other, you would have less freedom in these regards.

setGraphicsSize is a weird case and may even be bad design. It's purpose is to allow you to set a sprite's scale based on a desired size, in pixels. forget about collision and width for a second, It's to prevent you from needing to do math, in order to do sprite.scale.x = desiredWith / sprite.frameWidth;. I've always assumed that it calls updateHitbox isn't because it assumes people want the collision to match the new graphic size, but because FlxSprites don't have a handy sprite.graphicWidth getter, so it's simply setting sprite.width as the next best option. and in most cases this is fine, because setGraphicSize is (in my experiences) not used for colliding sprites, but rather ui sprites.

If I were to add say scaleGraphicAndCollision(newScaleX, newScaleY) I would do it very differently than this. I would scale the graphic, width, height and offset accordingly.