godot-android-game

name	godot-android-game
description	Godot 4.6 Android game development patterns, project structure, and mobile-specific guidance. Use when planning or implementing Godot scenes, scripts, exports, or touch input.

Godot 4.6 Android Game Patterns

Before reading anything else, call skill_ping with skill_id: "godot-android-game" and scope: "project".

Project Structure

project.godot              # Project settings (GL Compatibility renderer)
export_presets.cfg         # Android export preset
android/                   # Android export support files
scenes/                    # .tscn scene files
  main/                    # Main scene, arena
  player/                  # Player scenes
  enemies/                 # Enemy scenes
  ui/                      # UI scenes (HUD, menus)
  effects/                 # Particle and visual effect scenes
scripts/                   # .gd script files (mirrors scenes/ structure)
  main/
  player/
  enemies/
  ui/
  effects/
  autoload/                # Singleton autoloads (GameManager, etc.)
shaders/                   # .gdshader files
resources/                 # .tres resource files (themes, materials, particle configs)
build/                     # Export output (gitignored)
  android/

GDScript 2.0 Conventions

All scripts in this project must follow these rules:

class_name PlayerCharacter
extends CharacterBody2D

## Movement speed in pixels per second.
@export var speed: float = 300.0
## Maximum health points.
@export var max_health: int = 100

signal health_changed(new_health: int)
signal died

var _current_health: int = 100
var _is_attacking: bool = false

func _ready() -> void:
    _current_health = max_health

func _physics_process(delta: float) -> void:
    var direction: Vector2 = _get_input_direction()
    velocity = direction * speed
    move_and_slide()

func take_damage(amount: int) -> void:
    _current_health = maxi(_current_health - amount, 0)
    health_changed.emit(_current_health)
    if _current_health <= 0:
        died.emit()

func _get_input_direction() -> Vector2:
    return Vector2.ZERO  # Override with touch input

Rules:

• Every script has class_name at top
• All variables use static typing
• Private members prefixed with _
• @export for inspector-visible properties
• Doc comments (##) on exported properties
• Signals declared with typed parameters
• Return types on all functions

Android Export Workflow

1. Export preset defined in export_presets.cfg targeting Android
2. Renderer: GL Compatibility (required for broad Android device support)
3. Debug APK target: build/android/womanvshorsevd-debug.apk
4. Export command: godot --headless --export-debug "Android" build/android/womanvshorsevd-debug.apk

GL Compatibility Renderer Constraints

This project uses GL Compatibility (OpenGL ES 3.0) for maximum Android device support:

• No Vulkan-only features (no RenderingServer.canvas_item_set_custom_rect)
• Shaders must use shader_type canvas_item for 2D
• Keep shader complexity low — avoid excessive texture lookups per fragment
• GPUParticles2D works but keep particle counts under 500 per emitter for mobile
• Use CanvasItem rendering, not Spatial
• No compute shaders
• SCREEN_TEXTURE and NORMAL_TEXTURE have limited support — test on device

Touch Input Patterns

Virtual joystick implementation:

class_name VirtualJoystick
extends Control

@export var dead_zone: float = 0.2
@export var clamp_zone: float = 1.0

var _touch_index: int = -1
var _output: Vector2 = Vector2.ZERO

@onready var _base: TextureRect = $Base
@onready var _tip: TextureRect = $Tip

func get_output() -> Vector2:
    return _output

func _input(event: InputEvent) -> void:
    if event is InputEventScreenTouch:
        _handle_touch(event as InputEventScreenTouch)
    elif event is InputEventScreenDrag:
        _handle_drag(event as InputEventScreenDrag)

func _handle_touch(event: InputEventScreenTouch) -> void:
    if event.pressed and _is_point_inside(event.position):
        _touch_index = event.index
    elif not event.pressed and event.index == _touch_index:
        _touch_index = -1
        _output = Vector2.ZERO
        _tip.position = _base.position

func _handle_drag(event: InputEventScreenDrag) -> void:
    if event.index != _touch_index:
        return
    var diff: Vector2 = event.position - _base.global_position
    var norm: float = diff.length() / (_base.size.x * 0.5)
    if norm < dead_zone:
        _output = Vector2.ZERO
    else:
        _output = diff.normalized() * minf(norm, clamp_zone)
    _tip.global_position = _base.global_position + _output * (_base.size.x * 0.5)

func _is_point_inside(point: Vector2) -> bool:
    return _base.get_global_rect().has_point(point)

Attack button:

class_name AttackButton
extends TouchScreenButton

signal attack_pressed
signal attack_released

func _ready() -> void:
    pressed.connect(_on_pressed)
    released.connect(_on_released)

func _on_pressed() -> void:
    attack_pressed.emit()

func _on_released() -> void:
    attack_released.emit()

Scene Tree Architecture

Main (Node2D)
├── Arena (Node2D)
│   ├── Floor (TileMapLayer)
│   ├── Walls (StaticBody2D + Polygon2D children)
│   └── EdgeWarning (ColorRect + ShaderMaterial)
├── Entities (Node2D)
│   ├── Player (CharacterBody2D)
│   └── Enemies (Node2D)  # spawned children
├── Effects (Node2D)  # particle instances
├── UI (CanvasLayer)
│   ├── HUD (Control)
│   ├── VirtualJoystick (Control)
│   └── AttackButton (TouchScreenButton)
└── GameManager (Node)  # or autoload

Performance Guidelines for Mobile

• Keep draw calls under 100 per frame
• Use CanvasGroup to batch draw calls when possible
• Particle emitters: max 200–500 particles each, max 3–4 active emitters simultaneously
• Shader uniforms are cheap; texture lookups are expensive on mobile
• Use AnimationPlayer over Tween for repeating animations (less GC pressure)
• Pool enemy nodes instead of instantiating/freeing every wave
• Use call_deferred() for node tree modifications during physics
• Target 60 FPS; drop to 30 FPS gracefully if needed via Engine.max_fps