flame/doc/other-inputs.md

Other inputs

This includes documentation for input methods besides keyboard and mouse.

For other input documents, see also:

• Gesture Input: for mouse and touch pointer gestures
• Keyboard Input: for keystrokes

Joystick

Flame provides a component capable of creating a virtual joystick for taking input for your game. To use this feature, you need to create a JoystickComponent, configure it the way you want, and add it to your game.

Check this example to get a better understanding:

class MyGame extends FlameGame with HasDraggableComponents {

  MyGame() {
    joystick.addObserver(player);
    add(player);
    add(joystick);
  }

  @override
  Future<void> onLoad() async {
    super.onLoad();
    final image = await images.load('joystick.png');
    final sheet = SpriteSheet.fromColumnsAndRows(
      image: image,
      columns: 6,
      rows: 1,
    );
    final joystick = JoystickComponent(
      knob: SpriteComponent(
        sprite: sheet.getSpriteById(1),
        size: Vector2.all(100),
      ),
      background: SpriteComponent(
        sprite: sheet.getSpriteById(0),
        size: Vector2.all(150),
      ),
      margin: const EdgeInsets.only(left: 40, bottom: 40),
    );

    final player = Player(joystick);
    add(player);
    add(joystick);
  }
}

class JoystickPlayer extends SpriteComponent with HasGameRef {
  /// Pixels/s
  double maxSpeed = 300.0;

  final JoystickComponent joystick;

  JoystickPlayer(this.joystick)
      : super(
          size: Vector2.all(100.0),
        ) {
    anchor = Anchor.center;
  }

  @override
  Future<void> onLoad() async {
    super.onLoad();
    sprite = await gameRef.loadSprite('layers/player.png');
    position = gameRef.size / 2;
  }

  @override
  void update(double dt) {
    super.update(dt);
    if (joystick.direction != JoystickDirection.idle) {
      position.add(joystick.velocity * maxSpeed * dt);
      angle = joystick.delta.screenAngle();
    }
  }
}

So in this example, we create the classes MyGame and Player. MyGame creates a joystick which is passed to the Player when it is created. In the Player class we act upon the current state of the joystick.

The joystick has a few fields that change depending on what state it is in. These are the fields that should be used to know the state of the joystick:

• intensity: The percentage [0.0, 1.0] that the knob is dragged from the epicenter to the edge of the joystick (or knobRadius if that is set).
• delta: The absolute amount (defined as a Vector2) that the knob is dragged from its epicenter.
• velocity: The percentage, presented as a Vector2, and direction that the knob is currently pulled from its base position to a edge of the joystick.

If you want to create buttons to go with your joystick, check out MarginButtonComponent.

A full examples of how to use it can be found here. And it can be seen running here.

HudButtonComponent

A HudButtonComponent is a button that can be defined with margins to the edge of the Viewport instead of with a position. It takes two PositionComponents. button and buttonDown, the first is used for when the button is idle and the second is shown when the button is being pressed. The second one is optional if you don't want to change the look of the button when it is pressed, or if you handle this through the button component.

As the name suggests this button is a hud by default, which means that it will be static on your screen even if the camera for the game moves around. You can also use this component as a non-hud by setting hudButtonComponent.isHud = false;.

If you want to act upon the button being pressed (which would be the common thing to do) you can either pass in a callback function as the onPressed argument, or you extend the component and override onTapDown, onTapUp and/or onTapCancel and implement your logic in there.

Gamepad

Flame has a separate plugin to support external game controllers (gamepads), checkout here for more information.