class flixel.addons.plugin.control.FlxControlHandler

Available on all platforms

  • Makes controlling an FlxSprite with the keyboard a LOT easier and quicker to set-up!
  • Sometimes it's hard to know what values to set, especially if you want gravity, jumping, sliding, etc.
  • This class helps sort that - and adds some cool extra functionality too :)
  • TODO: Hot Keys
  • TODO: Binding of sound effects to keys (seperate from setSounds? as those are event based)
  • TODO: Specify animation frames to play based on velocity
  • TODO: Variable gravity (based on height, the higher the stronger the effect)
  • @link http://www.photonstorm.com
  • @author Richard Davey / Photon Storm

Class Fields

static var KEYMODE_JUST_DOWN:Int

This keyboard fires when the key has just been pressed down, and not again until it is released and re-pressed

static var KEYMODE_PRESSED:Int

This keymode fires for as long as the key is held down

static var KEYMODE_RELEASED:Int

This keyboard fires only when the key has been pressed and then released again

static var MOVEMENT_ACCELERATES:Int

The "Accelerates" Movement Type means the sprite will accelerate until it reaches maximum speed.

static var MOVEMENT_INSTANT:Int

The "Instant" Movement Type means the sprite will move at maximum speed instantly, and will not "accelerate" (or speed-up) before reaching that speed.

static var ROTATION_ACCELERATES:Int

The "Accelerates" Rotaton Type means the sprite will accelerate until it reaches maximum rotation speed.

static var ROTATION_INSTANT:Int

The "Instant" Movement Type means the sprite will rotate at maximum speed instantly, and will not "accelerate" (or speed-up) before reaching that speed.

static var ROTATION_STOPPING_DECELERATES:Int

The "Decelerates" Stopping Type means the sprite will start decelerating when no rotation keys are being pressed. Deceleration continues until rotation speed reaches zero.

static var ROTATION_STOPPING_INSTANT:Int

The "Instant" Stopping Type means the sprite will stop rotating immediately when no rotation keys are being pressed, there will be no deceleration.

static var ROTATION_STOPPING_NEVER:Int

The "Never" Stopping Type means the sprite will never decelerate, any speed built up will be carried on and never reduce.

static var STOPPING_DECELERATES:Int

The "Decelerates" Stopping Type means the sprite will start decelerating when no direction keys are being pressed. Deceleration continues until the speed reaches zero.

static var STOPPING_INSTANT:Int

The "Instant" Stopping Type means the sprite will stop immediately when no direction keys are being pressed, there will be no deceleration.

static var STOPPING_NEVER:Int

The "Never" Stopping Type means the sprite will never decelerate, any speed built up will be carried on and never reduce.

Instance Fields

function new(Sprite:FlxSprite, MovementType:Int, StoppingType:Int, ?UpdateFacing:Bool = false, ?EnableArrowKeys:Bool = true):Void

Sets the FlxSprite to be controlled by this class, and defines the initial movement and stopping types. * After creating an instance of this class you should call setMovementSpeed, and one of the enableXControl functions if you need more than basic cursors. * *

Sprite

The FlxSprite you want this class to control. It can only control one FlxSprite at once. *

MovementType

Set to either MOVEMENTINSTANT or MOVEMENTACCELERATES *

StoppingType

Set to STOPPINGINSTANT, STOPPINGDECELERATES or STOPPING_NEVER *

UpdateFacing

If true it sets the FlxSprite.facing value to the direction pressed (default false) *

EnableArrowKeys

If true it will enable all arrow keys (default) - see setCursorControl for more fine-grained control

function addHotKey(Key:String, Callback:Dynamic, Keymode:Int):Void

Creates a new Hot Key, which can be bound to any function you specify (such as "swap weapon", "quit", etc) * *

Key

The key to use as the hot key (String from flixel.system.input.Keyboard, i.e. "SPACE", "CONTROL", "Q", etc) *

Callback

The function to call when the key is pressed *

Keymode

The keymode that will trigger the callback, either KEYMODEPRESSED, KEYMODEJUSTDOWN or KEYMODERELEASED

function disableRotationLimits():Void

Disables rotation limits set in place by setRotationLimits()

function flipGravity():Void

Switches the gravity applied to the sprite. If gravity was +400 Y (pulling them down) this will swap it to -400 Y (pulling them up) * To reset call flipGravity again

function removeBounds():Void

Clears any previously set sprite bounds

function removeHotKey(Key:String):Bool

Removes a previously defined hot key * *

Key

The key to use as the hot key (String from flixel.system.input.Keyboard, i.e. "SPACE", "CONTROL", "Q", etc) *

returns

True if the key was found and removed, false if the key couldn't be found

function resetSpeeds(?ResetX:Bool = true, ?ResetY:Bool = true):Void

TODO * *

ResetX*
ResetY

function setAdvancedMovementSpeed(LeftSpeed:Int, RightSpeed:Int, UpSpeed:Int, DownSpeed:Int, SpeedMaxX:Int, SpeedMaxY:Int, ?DecelerationX:Int = 0, ?DecelerationY:Int = 0):Void

Set the speed at which the sprite will move when a direction key is pressed. * All values are given in pixels per second. So an xSpeed of 100 would move the sprite 100 pixels in 1 second (1000ms) * Due to the nature of the internal Flash timer this amount is not 100% accurate and will vary above/below the desired distance by a few pixels. * * If you don't need different speed values for every direction on its own then use setMovementSpeed * *

LeftSpeed

The speed in pixels per second in which the sprite will move/accelerate to the left *

RightSpeed

The speed in pixels per second in which the sprite will move/accelerate to the right *

UpSpeed

The speed in pixels per second in which the sprite will move/accelerate up *

DownSpeed

The speed in pixels per second in which the sprite will move/accelerate down *

SpeedMaxX

The maximum speed in pixels per second in which the sprite can move horizontally *

SpeedMaxY

The maximum speed in pixels per second in which the sprite can move vertically *

DecelerationX

Deceleration speed in pixels per second to apply to the sprites horizontal movement (default 0) *

DecelerationY

Deceleration speed in pixels per second to apply to the sprites vertical movement (default 0)

function setBounds(X:Int, Y:Int, Width:Int, Height:Int):Void

Limits the sprite to only be allowed within this rectangle. If its x/y coordinates go outside it will be repositioned back inside. * Coordinates should be given in GAME WORLD pixel values (not screen value, although often they are the two same things) * *

X

The x coordinate of the top left corner of the area (in game world pixels) *

Y

The y coordinate of the top left corner of the area (in game world pixels) *

Width

The width of the area (in pixels) *

Height

The height of the area (in pixels)

function setCursorControl(?AllowUp:Bool = true, ?AllowDown:Bool = true, ?AllowLeft:Bool = true, ?AllowRight:Bool = true):Void

Enables Cursor/Arrow Key controls. Can be set on a per-key basis. Useful if you only want to allow a few keys. * For example in a Space Invaders game you'd only enable LEFT and RIGHT. * *

AllowUp

Enable the UP key *

AllowDown

Enable the DOWN key *

AllowLeft

Enable the LEFT key *

AllowRight

Enable the RIGHT key

function setCustomKeys(CustomUpKey:String, CustomDownKey:String, CustomLeftKey:String, CustomRightKey:String):Void

Sets Custom Key controls. Useful if none of the pre-defined sets work. All String values should be taken from flixel.system.input.Keyboard * Pass a blank (empty) String to disable that key from being checked. * *

CustomUpKey

The String to use for the Up key. *

CustomDownKey

The String to use for the Down key. *

CustomLeftKey

The String to use for the Left key. *

CustomRightKey

The String to use for the Right key.

function setDeceleration(SpeedX:Int, SpeedY:Int):Void

Deceleration is a speed (in pixels per second) that is applied to the sprite if stopping type is "DECELERATES" and if no acceleration is taking place. * The velocity of the sprite will be reduced until it reaches zero, and can be configured separately per axis. * *

SpeedX

The speed in pixels per second at which the sprite will have its horizontal speed decreased *

SpeedY

The speed in pixels per second at which the sprite will have its vertical speed decreased

function setDvorakSimplifiedControl(?AllowUp:Bool = true, ?AllowDown:Bool = true, ?AllowLeft:Bool = true, ?AllowRight:Bool = true):Void

Enables Dvoark Simplified Controls. Can be set on a per-key basis. Useful if you only want to allow a few keys. * For example in a Space Invaders game you'd only enable LEFT and RIGHT. * *

AllowUp

Enable the up (COMMA) key *

AllowDown

Enable the down (A) key *

AllowLeft

Enable the left (O) key *

AllowRight

Enable the right (E) key

function setESDFControl(?AllowUp:Bool = true, ?AllowDown:Bool = true, ?AllowLeft:Bool = true, ?AllowRight:Bool = true):Void

Enables ESDF (home row) controls. Can be set on a per-key basis. Useful if you only want to allow a few keys. * For example in a Space Invaders game you'd only enable LEFT and RIGHT. * *

AllowUp

Enable the up (E) key *

AllowDown

Enable the down (D) key *

AllowLeft

Enable the left (S) key *

AllowRight

Enable the right (F) key

function setFireButton(Key:String, Keymode:Int, RepeatDelay:Int, Callback:Void ->Void, ?AltKey:String = ''):Void

Enable a fire button * *

Key

The key to use as the fire button (String from flixel.system.input.Keyboard, i.e. "SPACE", "CONTROL") *

Keymode

The FlxControlHandler KEYMODE value (KEYMODEPRESSED, KEYMODEJUSTDOWN, KEYMODERELEASED) *

RepeatDelay

Time delay in ms between which the fire action can repeat (0 means instant, 250 would allow it to fire approx. 4 times per second) *

Callback

A user defined function to call when it fires *

AltKey

Specify an alternative fire key that works AS WELL AS the primary fire key (TODO)

function setGravity(ForceX:Int, ForceY:Int):Void

Gravity can be applied to the sprite, pulling it in any direction. * Gravity is given in pixels per second and is applied as acceleration. The speed the sprite reaches under gravity will never exceed the Maximum Movement Speeds set. * If you don't want gravity for a specific direction pass a value of zero. * *

ForceX

A positive value applies gravity dragging the sprite to the right. A negative value drags the sprite to the left. Zero disables horizontal gravity. *

ForceY

A positive value applies gravity dragging the sprite down. A negative value drags the sprite up. Zero disables vertical gravity.

function setHJKLControl(?AllowUp:Bool = true, ?AllowDown:Bool = true, ?AllowLeft:Bool = true, ?AllowRight:Bool = true):Void

Enables HJKL (Rogue / Net-Hack) controls. Can be set on a per-key basis. Useful if you only want to allow a few keys. * For example in a Space Invaders game you'd only enable LEFT and RIGHT. * *

AllowUp

Enable the up (K) key *

AllowDown

Enable the down (J) key *

AllowLeft

Enable the left (H) key *

AllowRight

Enable the right (L) key

function setIJKLControl(?AllowUp:Bool = true, ?AllowDown:Bool = true, ?AllowLeft:Bool = true, ?AllowRight:Bool = true):Void

Enables IJKL (right-sided or secondary player) controls. Can be set on a per-key basis. Useful if you only want to allow a few keys. * For example in a Space Invaders game you'd only enable LEFT and RIGHT. * *

AllowUp

Enable the up (I) key *

AllowDown

Enable the down (K) key *

AllowLeft

Enable the left (J) key *

AllowRight

Enable the right (L) key

function setJumpButton(Key:String, Keymode:Int, Height:Int, Surface:Int, ?RepeatDelay:Int = 250, ?JumpFromFall:Int = 0, ?Callback:Void ->Void = null, ?AltKey:String = ''):Void

Enable a jump button * *

Key

The key to use as the jump button (String from flixel.system.input.Keyboard, i.e. "SPACE", "CONTROL") *

Keymode

The FlxControlHandler KEYMODE value (KEYMODEPRESSED, KEYMODEJUSTDOWN, KEYMODERELEASED) *

Height

The height in pixels/sec that the Sprite will attempt to jump (gravity and acceleration can influence this actual height obtained) *

Surface

A bitwise combination of all valid surfaces the Sprite can jump off (from FlxObject, such as FlxObject.FLOOR) *

RepeatDelay

Time delay in ms between which the jumping can repeat (250 would be 4 times per second) *

JumpFromFall

A time in ms that allows the Sprite to still jump even if it's just fallen off a platform, if still within ths time limit *

Callback

A user defined function to call when the Sprite jumps *

AltKey

Specify an alternative jump key that works AS WELL AS the primary jump key (TODO)

function setMaximumRotationSpeed(Speed:Float, ?LimitVelocity:Bool = true):Void

Sets the maximum speed (in pixels per second) that the FlxSprite can rotate. * When the FlxSprite is accelerating (movement type MOVEMENT_ACCELERATES) its speed won't increase above this value. * However Flixel allows the velocity of an FlxSprite to be set to anything. So if you'd like to check the value and restrain it, then enable "limitVelocity". * *

Speed

The maximum speed in pixels per second in which the sprite can rotate *

LimitVelocity

If true the angular velocity of the FlxSprite will be checked and kept within the limit. If false it can be set to anything.

function setMaximumSpeed(SpeedX:Int, SpeedY:Int, ?LimitVelocity:Bool = true):Void

Sets the maximum speed (in pixels per second) that the FlxSprite can move. You can set the horizontal and vertical speeds independantly. * When the FlxSprite is accelerating (movement type MOVEMENT_ACCELERATES) its speed won't increase above this value. * However Flixel allows the velocity of an FlxSprite to be set to anything. So if you'd like to check the value and restrain it, then enable "limitVelocity". * *

SpeedX

The maximum speed in pixels per second in which the sprite can move horizontally *

SpeedY

The maximum speed in pixels per second in which the sprite can move vertically *

LimitVelocity

If true the velocity of the FlxSprite will be checked and kept within the limit. If false it can be set to anything.

function setMovementSpeed(SpeedX:Int, SpeedY:Int, SpeedMaxX:Int, SpeedMaxY:Int, ?DecelerationX:Int = 0, ?DecelerationY:Int = 0):Void

Set the speed at which the sprite will move when a direction key is pressed. * All values are given in pixels per second. So an xSpeed of 100 would move the sprite 100 pixels in 1 second (1000ms) * Due to the nature of the internal Flash timer this amount is not 100% accurate and will vary above/below the desired distance by a few pixels. * * If you need different speed values for left/right or up/down then use setAdvancedMovementSpeed * *

SpeedX

The speed in pixels per second in which the sprite will move/accelerate horizontally *

SpeedY

The speed in pixels per second in which the sprite will move/accelerate vertically *

SpeedMaxX

The maximum speed in pixels per second in which the sprite can move horizontally *

SpeedMaxY

The maximum speed in pixels per second in which the sprite can move vertically *

DecelerationX

A deceleration speed in pixels per second to apply to the sprites horizontal movement (default 0) *

DecelerationY

A deceleration speed in pixels per second to apply to the sprites vertical movement (default 0)

function setNumpadControl(?AllowUp:Bool = true, ?AllowDown:Bool = true, ?AllowLeft:Bool = true, ?AllowRight:Bool = true):Void

Enables Numpad (left-handed) Controls. Can be set on a per-key basis. Useful if you only want to allow a few keys. * For example in a Space Invaders game you'd only enable LEFT and RIGHT. * *

AllowUp

Enable the up (NUMPADEIGHT) key *

AllowDown

Enable the down (NUMPADTWO) key *

AllowLeft

Enable the left (NUMPADFOUR) key *

AllowRight

Enable the right (NUMPADSIX) key

function setRotationDeceleration(Speed:Float):Void

Deceleration is a speed (in pixels per second) that is applied to the sprite if stopping type is "DECELERATES" and if no rotation is taking place. * The velocity of the sprite will be reduced until it reaches zero. * *

Speed

The speed in pixels per second at which the sprite will have its angular rotation speed decreased

function setRotationKeys(?LeftRight:Bool = true, ?UpDown:Bool = false, ?CustomAntiClockwise:String = '', ?CustomClockwise:String = ''):Void

Set which keys will rotate the sprite. The speed of rotation is set in setRotationSpeed. * *

LeftRight

Use the LEFT and RIGHT arrow keys for anti-clockwise and clockwise rotation respectively. *

UpDown

Use the UP and DOWN arrow keys for anti-clockwise and clockwise rotation respectively. *

CustomAntiClockwise

The String value of your own key to use for anti-clockwise rotation (as taken from flixel.system.input.Keyboard) *

CustomClockwise

The String value of your own key to use for clockwise rotation (as taken from flixel.system.input.Keyboard)

function setRotationLimits(MinimumAngle:Int, MaximumAngle:Int):Void

Set minimum and maximum angle limits that the Sprite won't be able to rotate beyond. * Values must be between -180 and +180. 0 is pointing right, 90 down, 180 left, -90 up. * *

MinimumAngle

Minimum angle below which the sprite cannot rotate (must be -180 or above) *

MaximumAngle

Maximum angle above which the sprite cannot rotate (must be 180 or below)

function setRotationSpeed(AntiClockwiseSpeed:Float, ClockwiseSpeed:Float, SpeedMax:Float, Deceleration:Float):Void

Set the speed at which the sprite will rotate when a direction key is pressed. * Use this in combination with setMovementSpeed to create a Thrust like movement system. * All values are given in pixels per second. So an xSpeed of 100 would rotate the sprite 100 pixels in 1 second (1000ms) * Due to the nature of the internal Flash timer this amount is not 100% accurate and will vary above/below the desired distance by a few pixels.

function setRotationType(RotationType:Int, StoppingType:Int):Void

RotationType*
StoppingType

function setSounds(?Jump:FlxSound = null, ?Fire:FlxSound = null, ?Walk:FlxSound = null, ?Thrust:FlxSound = null):Void

Set sound effects for the movement events jumping, firing, walking and thrust. * *

Jump

The FlxSound to play when the user jumps *

Fire

The FlxSound to play when the user fires *

Walk

The FlxSound to play when the user walks *

Thrust

The FlxSound to play when the user thrusts

function setStandardSpeed(Speed:Int, ?Acceleration:Bool = true):Void

If you know you need the same value for the acceleration, maximum speeds and (optionally) deceleration then this is a quick way to set them. * *

Speed

The speed in pixels per second in which the sprite will move/accelerate/decelerate *

Acceleration

If true it will set the speed value as the deceleration value (default) false will leave deceleration disabled

function setThrust(ThrustKey:String, ThrustSpeed:Float, ?ReverseKey:String = null, ?ReverseSpeed:Float = 0):Void

If you want to enable a Thrust like motion for your sprite use this to set the speed and keys. * This is usually used in conjunction with Rotation and it will over-ride anything already defined in setMovementSpeed. * *

ThrustKey

Specify the key String (as taken from flixel.system.input.Keyboard) to use for the Thrust action *

ThrustSpeed

The speed in pixels per second which the sprite will move. Acceleration or Instant movement is determined by the Movement Type. *

ReverseKey

If you want to be able to reverse, set the key string as taken from flixel.system.input.Keyboard (defaults to null). *

ReverseSpeed

The speed in pixels per second which the sprite will reverse. Acceleration or Instant movement is determined by the Movement Type.

function setWASDControl(?AllowUp:Bool = true, ?AllowDown:Bool = true, ?AllowLeft:Bool = true, ?AllowRight:Bool = true):Void

Enables WASD controls. Can be set on a per-key basis. Useful if you only want to allow a few keys. * For example in a Space Invaders game you'd only enable LEFT and RIGHT. * *

allowUp

Enable the up (W) key *

allowDown

Enable the down (S) key *

allowLeft

Enable the left (A) key *

allowRight

Enable the right (D) key

function setZQSDControl(?AllowUp:Bool = true, ?AllowDown:Bool = true, ?AllowLeft:Bool = true, ?AllowRight:Bool = true):Void

Enables ZQSD (Azerty keyboard) controls. Can be set on a per-key basis. Useful if you only want to allow a few keys. * For example in a Space Invaders game you'd only enable LEFT and RIGHT. * *

AllowUp

Enable the up (Z) key *

AllowDown

Enable the down (Q) key *

AllowLeft

Enable the left (S) key *

AllowRight

Enable the right (D) key

function slowDown(FactorX:Float, FactorY:Float):Void

TODO * *

FactorX*
FactorY

function speedUp(FactorX:Float, FactorY:Float):Void

TODO * *

FactorX*
FactorY

function update():Void

Called by the FlxControl plugin