Merge branch 'dev' into bmf-kern

CHANGELOG.md

@@ -1,3 +1,23 @@
+5.7.0 (TBD)
+
+#### New features:
+- `FlxBitmapFont`: Added `setCharFrame` ([#3037](https://github.com/HaxeFlixel/flixel/pull/3037))
+- `FlxTimer`: Added static `wait` and `loops` methods ([#3040](https://github.com/HaxeFlixel/flixel/pull/3040))
+- `FlxBasic`: Added `container` field and `FlxContainer` and `FlxSpriteContainer` where a basic can only be in one container ([#3050](https://github.com/HaxeFlixel/flixel/pull/3050)) ([#3055](https://github.com/HaxeFlixel/flixel/pull/3055)) ([#3068](https://github.com/HaxeFlixel/flixel/pull/3068)) 
+- `FlxPath`: Added `centerMode` to center on `TOP_LEFT`, `CENTER`, `ORIGIN` and more ([#3052](https://github.com/HaxeFlixel/flixel/pull/3052))
+- `FlxG.plugins`: Added `drawOnTop` field ([#3057](https://github.com/HaxeFlixel/flixel/pull/3057))
+- `FlxCamera`: Added `stopFade`, `stopFlash`, and `stopShake` ([#3063](https://github.com/HaxeFlixel/flixel/pull/3063))
+- `FlxRect`: Added `containsXY` ([#3069](https://github.com/HaxeFlixel/flixel/pull/3069))
+
+
+#### Changes and improvements:
+- `FlxBitmapText`: Honor `scale` when changing `width` and `height` ([#3037](https://github.com/HaxeFlixel/flixel/pull/3037))
+- `FlxSound`: Deprecated `sound.group` setter, avoiding recursion errors ([#3041](https://github.com/HaxeFlixel/flixel/pull/3041))
+- `FlxAssets`: Allow the immediate use of async images, once loaded ([#3022](https://github.com/HaxeFlixel/flixel/pull/3022))
+- `FlxText`: Removed references to `FlxUnicodeUtil` ([#3049](https://github.com/HaxeFlixel/flixel/pull/3049))
+- `FlxObject`: Deprecated `health` and `hurt` ([#3065](https://github.com/HaxeFlixel/flixel/pull/3065))
+	- Added compiler flag `FLX_NO_HEALTH` to create your own replacement, if needed ([#3067](https://github.com/HaxeFlixel/flixel/pull/3067))
+
 5.6.2 (February 10, 2024)
 #### Changes and improvements:
 - `FlxBitmapFont`: Prevent crashes from missing xml fields in `fromAngelCode` ([#3029](https://github.com/HaxeFlixel/flixel/pull/3029))

flixel/FlxBasic.hx

@@ -1,6 +1,7 @@
 package flixel;
 
-import flixel.util.FlxDestroyUtil.IFlxDestroyable;
+import flixel.group.FlxContainer;
+import flixel.util.FlxDestroyUtil;
 import flixel.util.FlxStringUtil;
 
 /**
@@ -69,6 +70,12 @@ class FlxBasic implements IFlxDestroyable
 
 	@:noCompletion
 	var _cameras:Array<FlxCamera>;
+
+	/**
+	 * The parent containing this basic, typically if you check this recursively you should reach the state
+	 * @since 5.7.0
+	 */
+	public var container(get, null):Null<FlxContainer>;
 
 	public function new() {}
 
@@ -84,6 +91,10 @@ class FlxBasic implements IFlxDestroyable
 	 */
 	public function destroy():Void
 	{
+		if (container != null)
+			container.remove(this);
+
+		container = null;
 		exists = false;
 		_cameras = null;
 	}
@@ -181,18 +192,53 @@ class FlxBasic implements IFlxDestroyable
 			_cameras[0] = Value;
 		return Value;
 	}
-
+
+	/**
+	 * The cameras that will draw this. Use `this.cameras` to set specific cameras for this object,
+	 * otherwise the container's cameras are used, or the container's container and so on. If there
+	 * is no container, say, if this is inside `FlxGroups` rather than a `FlxContainer` then the
+	 * default draw cameras are returned.
+	 * @since 5.7.0
+	 */
+	public function getCameras()
+	{
+		return if (_cameras != null)
+				_cameras;
+			else if (_cameras == null && container != null)
+				container.getCameras();
+			else
+				@:privateAccess FlxCamera._defaultCameras;
+	}
+
+	/**
+	 * Helper while moving away from `get_cameras`. Should only be used in the draw phase
+	 */
 	@:noCompletion
-	function get_cameras():Array<FlxCamera>
+	function getCamerasLegacy()
 	{
+		@:privateAccess
 		return (_cameras == null) ? FlxCamera._defaultCameras : _cameras;
 	}
+
+	@:noCompletion
+	function get_cameras():Array<FlxCamera>
+	{
+		return getCamerasLegacy();
+	}
 
 	@:noCompletion
 	function set_cameras(Value:Array<FlxCamera>):Array<FlxCamera>
 	{
 		return _cameras = Value;
 	}
+
+	// Only needed for FlxSpriteContainer.SpriteContainer
+	// TODO: remove this when FlxSpriteContainer is removed
+	@:noCompletion
+	function get_container()
+	{
+		return this.container;
+	}
 }
 
 /**

flixel/FlxCamera.hx

@@ -634,6 +634,10 @@ class FlxCamera extends FlxBasic
 		{
 			itemToReturn = new FlxDrawItem();
 		}
+
+		// TODO: catch this error when the dev actually messes up, not in the draw phase
+		if (graphic.isDestroyed)
+			throw 'Attempted to queue an invalid FlxDrawItem, did you destroy a cached sprite?';
 
 		itemToReturn.graphics = graphic;
 		itemToReturn.antialiasing = smooth;
@@ -1601,15 +1605,41 @@ class FlxCamera extends FlxBasic
 	}
 
 	/**
-	 * Just turns off all the camera effects instantly.
+	 * Stops the fade effect on `this` camera.
 	 */
-	public function stopFX():Void
+	public function stopFade():Void
 	{
-		_fxFlashAlpha = 0.0;
 		_fxFadeAlpha = 0.0;
 		_fxFadeDuration = 0.0;
+	}
+
+	/**
+	 * Stops the flash effect on `this` camera.
+	 */
+	public function stopFlash():Void
+	{
+		_fxFlashAlpha = 0.0;
+		updateFlashSpritePosition();
+	}
+
+	/**
+	 * Stops the shake effect on `this` camera.
+	 */
+	public function stopShake():Void
+	{
 		_fxShakeDuration = 0.0;
+	}
+
+	/**
+	 * Stops all effects on `this` camera.
+	 */
+	public function stopFX():Void
+	{
+		_fxFadeAlpha = 0.0;
+		_fxFadeDuration = 0.0;
+		_fxFlashAlpha = 0.0;
 		updateFlashSpritePosition();
+		_fxShakeDuration = 0.0;
 	}
 
 	/**

flixel/FlxG.hx

@@ -106,7 +106,7 @@ class FlxG
 	 * The HaxeFlixel version, in semantic versioning syntax. Use `Std.string()`
 	 * on it to get a `String` formatted like this: `"HaxeFlixel MAJOR.MINOR.PATCH-COMMIT_SHA"`.
 	 */
-	public static var VERSION(default, null):FlxVersion = new FlxVersion(5, 6, 2);
+	public static var VERSION(default, null):FlxVersion = new FlxVersion(5, 7, 0);
 
 	/**
 	 * Internal tracker for game object.

flixel/FlxGame.hx

@@ -863,9 +863,16 @@ class FlxGame extends Sprite
 
 		FlxG.cameras.lock();
 
-		FlxG.plugins.draw();
-
-		_state.draw();
+		if (FlxG.plugins.drawOnTop)
+		{
+			_state.draw();
+			FlxG.plugins.draw();
+		}
+		else
+		{
+			FlxG.plugins.draw();
+			_state.draw();
+		}
 
 		if (FlxG.renderTile)
 		{

flixel/FlxObject.hx

@@ -699,10 +699,13 @@ class FlxObject extends FlxBasic
 	 */
 	public var maxAngular:Float = 10000;
 
+	#if FLX_HEALTH
 	/**
 	 * Handy for storing health percentage or armor points or whatever.
 	 */
+	@:deprecated("object.health is being removed in version 6.0.0")
 	public var health:Float = 1;
+	#end
 
 	/**
 	 * Bit field of flags (use with UP, DOWN, LEFT, RIGHT, etc) indicating surface contacts. Use bitwise operators to check the values
@@ -1199,18 +1202,21 @@ class FlxObject extends FlxBasic
 		return touching.hasAny(direction) && !wasTouching.hasAny(direction);
 	}
 
+	#if FLX_HEALTH
 	/**
 	 * Reduces the `health` variable of this object by the amount specified in `Damage`.
 	 * Calls `kill()` if health drops to or below zero.
 	 *
 	 * @param   Damage   How much health to take away (use a negative number to give a health bonus).
 	 */
+	@:deprecated("object.health is being removed in version 6.0.0")
 	public function hurt(damage:Float):Void
 	{
 		health = health - damage;
 		if (health <= 0)
 			kill();
 	}
+	#end
 
 	/**
 	 * Centers this `FlxObject` on the screen, either by the x axis, y axis, or both.
@@ -1259,8 +1265,8 @@ class FlxObject extends FlxBasic
 	{
 		if (ignoreDrawDebug)
 			return;
-
-		for (camera in cameras)
+		
+		for (camera in getCamerasLegacy())
 		{
 			drawDebugOnCamera(camera);
 
@@ -1303,8 +1309,8 @@ class FlxObject extends FlxBasic
 		}
 
 		// fill static graphics object with square shape
-		gfx.lineStyle(1, color, 0.5);
-		gfx.drawRect(rect.x, rect.y, rect.width, rect.height);
+		gfx.lineStyle(1, color, 0.75);
+		gfx.drawRect(rect.x + 0.5, rect.y + 0.5, rect.width - 1.0, rect.height - 1.0);
 	}
 
 	inline function beginDrawDebug(camera:FlxCamera):Graphics

flixel/FlxSprite.hx

@@ -796,7 +796,7 @@ class FlxSprite extends FlxObject
 		if (dirty) // rarely
 			calcFrame(useFramePixels);
 
-		for (camera in cameras)
+		for (camera in getCamerasLegacy())
 		{
 			if (!camera.visible || !camera.exists || !isOnScreen(camera))
 				continue;

flixel/FlxState.hx

@@ -1,21 +1,21 @@
 package flixel;
 
-import flixel.group.FlxGroup;
+import flixel.group.FlxContainer;
 import flixel.util.FlxColor;
 import flixel.util.FlxDestroyUtil;
 import flixel.util.FlxSignal;
 import flixel.util.typeLimit.NextState;
 
 /**
  * This is the basic game "state" object - e.g. in a simple game you might have a menu state and a play state.
- * It is for all intents and purpose a fancy `FlxGroup`. And really, it's not even that fancy.
+ * It is for all intents and purpose a fancy `FlxContainer`. And really, it's not even that fancy.
  */
 @:keepSub // workaround for HaxeFoundation/haxe#3749
 #if FLX_NO_UNIT_TEST
 @:autoBuild(flixel.system.macros.FlxMacroUtil.deprecateOverride("switchTo", "switchTo is deprecated, use startOutro"))
 #end
 // show deprecation warning when `switchTo` is overriden in dereived classes
-class FlxState extends FlxGroup
+class FlxState extends FlxContainer
 {
 	/**
 	 * Determines whether or not this state is updated even when it is not the active state.

flixel/FlxStrip.hx

@@ -50,6 +50,7 @@ class FlxStrip extends FlxSprite
 		if (alpha == 0 || graphic == null || vertices == null)
 			return;
 
+		final cameras = getCamerasLegacy();
 		for (camera in cameras)
 		{
 			if (!camera.visible || !camera.exists)

flixel/FlxSubState.hx

@@ -63,7 +63,7 @@ class FlxSubState extends FlxState
 		// Draw background
 		if (FlxG.renderBlit)
 		{
-			for (camera in cameras)
+			for (camera in getCamerasLegacy())
 			{
 				camera.fill(bgColor);
 			}

flixel/animation/FlxAnimationController.hx

@@ -43,14 +43,15 @@ class FlxAnimationController implements IFlxDestroyable
 	/**
 	 * The total number of frames in this image.
 	 * WARNING: assumes each row in the sprite sheet is full!
+	 * @since 5.3.0
 	 */
 	public var numFrames(get, never):Int;
 
 	/**
 	 * The total number of frames in this image.
 	 * WARNING: assumes each row in the sprite sheet is full!
 	 */
-	@:deprecated("frames is deprecated, use numFrames")
+	@:deprecated("frames is deprecated, use numFrames") // 5.3.0
 	public var frames(get, never):Int;
 
 	/**

flixel/effects/FlxFlicker.hx

@@ -166,23 +166,21 @@ class FlxFlicker implements IFlxDestroyable
 	/**
 	 * Just a helper function for flicker() to update object's visibility.
 	 */
-	function flickerProgress(Timer:FlxTimer):Void
+	function flickerProgress(timer:FlxTimer):Void
 	{
 		object.visible = !object.visible;
-
+		
 		if (progressCallback != null)
-		{
 			progressCallback(this);
-		}
-
-		if (Timer.loops > 0 && Timer.loopsLeft == 0)
+
+		if (timer.loops > 0 && timer.loopsLeft == 0)
 		{
 			object.visible = endVisibility;
 			if (completionCallback != null)
-			{
 				completionCallback(this);
-			}
-			release();
+
+			if (this.timer == timer)
+				release();
 		}
 	}
 

flixel/graphics/FlxGraphic.hx

@@ -498,8 +498,11 @@ class FlxGraphic implements IFlxDestroyable
 	{
 		if (collection.type != null)
 		{
-			var collections:Array<Dynamic> = getFramesCollections(collection.type);
-			collections.push(collection);
+			final collections = getFramesCollections(collection.type);
+			if (collections.contains(collection))
+				FlxG.log.warn('Attempting to add already added collection');
+			else
+				collections.push(collection);
 		}
 	}