Virtual Pad Explanation

ACTION GAME MAKER General
1

virtualpad_agm.zip (9.6 KB)

VirtualJoystick calculates an “axis vector,” “angle,” and “distance” from touch or mouse positions and sends actions to InputMap according to configuration.

Main features are as follows:

  1. Maintains the current input vector

    • Use get_axis() to retrieve the current axis (positive X to the right, negative Y upward)
    • Use get_input_strength() to retrieve the vector length (0.0 to 1.0)
    • Use get_input_angle_deg() to retrieve the angle (degrees; 0° to the right, 90° upward)

  2. Determines actions based on angle and distance bands

    • Configure “which angle range to handle” in VirtualJoystickAngleConfig
    • Within it, configure “distance range and action name” using VirtualJoystickDistanceBand
    • When the input angle and distance fall within a band, the band’s action is sent to InputMap

  3. Automatically appends AGM suffixes

  4. Allows arbitrary notifications via signals
    When sending signals to AGM game objects, connect generic_signal(signal_name: String, value: Variant) to the target object’s receive_signal.

2. Usage with Minimal Configuration

Instructions for using VirtualJoystick as a four-direction, single-stage virtual pad with minimal settings.

2-1. Add VirtualJoystick Node to Scene

  1. Directly add VirtualJoystick to the Scene Tree
    OR
    Add a Node2D and attach the script virtual_joystick.gd to it.

2-2. Press the Auto-Generate Child Nodes Button

When selecting the VirtualJoystick node, the Inspector displays a button labeled “Generate and Assign Default Child Nodes.”
(If the button does not appear or fails to generate nodes properly, save the project and restart.)

  1. Press this button once.

  2. The following nodes are automatically created:

    • area_control_node
      A Control node covering the entire screen or specified area, used as the touch-sensitive region.
      If left empty, the entire screen becomes the touch area for the virtual pad.
      If the virtual pad does not respond, review this setting.

    • base_texture_rect_node
      A TextureRect for the base image.

    • knob_texture_rect_node
      A TextureRect for the knob image.

    If needed, assign a separately prepared TextureRect to overlay_texture_rect_node.

2-3. Register Actions in InputMap

  1. In InputMap
    Register the keys you wish to use with the virtual pad.

2-4. Auto-Generate Angle Actions

  1. Set use_angle_actions in VirtualJoystick to true.
  2. Press the “Auto-Generate 4-Direction Angle Actions” button in the Inspector.
  3. Four VirtualJoystickAngleConfig entries are added to angle_actions:
    • Right
      Angle range: -45° to 45°
    • Up
      Angle range: 45° to 135°
    • Left
      Angle range: 135° to -135° (including 360° wraparound)
    • Down
      Angle range: -135° to -45°

Each angle_config contains only one band, initially configured as “one distance band covering 0–1 regardless of angle.”

2-5. Assign Action Names to Distance Bands

  1. Open the VirtualJoystickAngleConfig for Right.
  2. Select bands[0] (VirtualJoystickDistanceBand) inside it.
  3. Enter the desired InputMap key name in action_name.

2-6. Adjust dead_zone and max_distance

  1. dead_zone

    • When the axis length is below this value, the axis is treated as zero.
    • To prevent responses to slight movements, set this to approximately 0.15–0.2.

  2. max_distance

    • Specifies the maximum distance the knob can move, in pixels.
    • Adjust to match the radius of the base image.

2-7. Run and Verify

  1. In Play Mode, touch or drag within the area_control_node’s range.
  2. The base and knob will move, and the configured distance bands will activate according to the input angle and distance.