zentap/scripts

ZenTap Build Scripts

This directory contains shell scripts for automating common development tasks for the ZenTap project.

Scripts Overview

🎵 convert_audio.sh

Converts audio files to the proper format and specifications for the ZenTap game.

📱 build_app.sh

Builds APK and AAB files for Android in debug and release modes.

📱 run_emulator.py ⭐ NEW

Comprehensive Python script to launch ZenTap in Android emulators with selectable resolutions.

📱 run_emulator.sh ⭐ NEW

Bash script to launch ZenTap in Android emulators with resolution options.

---

Audio Conversion Script

Prerequisites

• ffmpeg must be installed on your system
  • Ubuntu/Debian: sudo apt install ffmpeg
  • macOS: brew install ffmpeg
  • Windows: Download from ffmpeg.org

Usage

./scripts/convert_audio.sh

How it works

1. Looks for source audio files in assets/audio/source/
2. Converts them according to specifications in assets/audio/README.md:
   • Sound Effects: MP3 format, 44.1 kHz, 128 kbps, mono, 0.1-0.5 seconds
   • Background Music: MP3 format, 44.1 kHz, 192 kbps, stereo, 2-8 minutes
3. Outputs converted files to appropriate directories:
   • Sound effects: assets/audio/source/
   • Menu music: assets/audio/menu/
   • Ingame music: assets/audio/ingame/
   • Compressed versions: assets/audio/compressed/
4. Validates file durations and reports status

Required Files

Sound Effects (source/)

• bubble_pop.mp3 - Primary bubble pop sound effect
• bubble_pop_alt.mp3 - Alternative bubble pop sound effect
• ambient_background.mp3 - Legacy background music

Theme-Based Menu Music (menu/)

• menu_default.mp3 - Default theme menu music
• menu_spring.mp3 - Spring theme menu music
• menu_summer.mp3 - Summer theme menu music
• menu_autumn.mp3 - Autumn theme menu music
• menu_winter.mp3 - Winter theme menu music

Theme-Based Ingame Music (ingame/)

• ingame_default_001.mp3 - Default theme gameplay music
• ingame_spring_001.mp3 - Spring theme gameplay music
• ingame_summer_001.mp3 - Summer theme gameplay music
• ingame_autumn_001.mp3 - Autumn theme gameplay music
• ingame_winter_001.mp3 - Winter theme gameplay music (track 1)
• ingame_winter_002.mp3 - Winter theme gameplay music (track 2)

Supported Source Formats

WAV, MP3, OGG, FLAC, M4A

---

Build Script

Prerequisites

• Flutter SDK must be installed and configured
• Android SDK and build tools must be set up
• Run flutter doctor to ensure all dependencies are satisfied

Usage

Build all variants (default)

./scripts/build_app.sh

Build specific variants

# Debug only
./scripts/build_app.sh --debug

# Release only
./scripts/build_app.sh --release

# APK files only
./scripts/build_app.sh --apk-only

# AAB files only
./scripts/build_app.sh --aab-only

# Clean build before building
./scripts/build_app.sh --clean --all

Get help

./scripts/build_app.sh --help

Build Variants

Variant	Description	Use Case
Debug APK	Development build with debugging symbols	Testing on devices, debugging
Release APK	Optimized build for production	Side-loading, testing stores
Debug AAB	Development Android App Bundle	Play Console internal testing
Release AAB	Production Android App Bundle	Google Play Store release

Output Location

Built files are saved in build/outputs/ with timestamps:

• APK files: build/outputs/apk/
• AAB files: build/outputs/bundle/

File Naming Convention

• ZenTap_debug_YYYYMMDD_HHMMSS.apk
• ZenTap_release_YYYYMMDD_HHMMSS.aab

---

Installation Instructions

Installing APK files

# Install via ADB
adb install build/outputs/apk/ZenTap_release_*.apk

# Or transfer to device and install manually

Uploading AAB files

1. Upload the AAB file to Google Play Console
2. Use for app releases on Google Play Store

---

Troubleshooting

Audio Conversion Issues

• ffmpeg not found: Install ffmpeg using your system's package manager
• Missing source files: Place original audio files in assets/audio/source/
• Duration warnings: Check if your audio files meet the length requirements

Build Issues

• Flutter not found: Ensure Flutter is installed and added to PATH
• Android toolchain issues: Run flutter doctor and follow the suggestions
• Build failures: Run flutter clean and try building again

Common Commands

# Check Flutter installation
flutter doctor

# Clean Flutter project
flutter clean && flutter pub get

# Run app in debug mode
flutter run

# Check connected devices
flutter devices

---

Color Scheme Reference

Both scripts follow the fSociety.hu color scheme defined in ../SCHEME_COLORS.md:

• Black (#000000) - Primary background
• White (#FFFFFF) - Primary text
• Red (#FF0000) - Error messages
• Gray (#808080) - Secondary elements
• Navy Blue (#000080) - Information messages

---

Emulator Scripts ⭐ NEW

Prerequisites for Emulator Scripts

1. Flutter SDK - Ensure Flutter is installed and in your PATH
2. Android SDK - Install Android SDK with:
   • Android SDK Platform Tools
   • Android Emulator
   • At least one system image (API 34+ recommended)
3. Environment Variables - Set one of:
   • ANDROID_SDK_ROOT
   • ANDROID_HOME
4. Python 3 (for run_emulator.py) - Python 3.6 or later

run_emulator.py (Recommended)

A comprehensive Python script with full features and error handling.

Features:

• Interactive resolution selection menu
• Command-line arguments support
• Automatic AVD creation
• App building and installation
• Emulator lifecycle management
• Cross-platform compatibility

Usage Examples

# Interactive mode (recommended for first-time use)
./scripts/run_emulator.py

# Command line mode with preset resolution
./scripts/run_emulator.py --resolution 3 --build-mode release

# Custom resolution
./scripts/run_emulator.py --width 1080 --height 1920

# List available AVDs
./scripts/run_emulator.py --list-avds

# Full command line example
./scripts/run_emulator.py --resolution 2 --cold-boot --build-mode debug

run_emulator.sh

A bash script for Unix-like systems (Linux, macOS).

Features:

• Interactive menu system
• Command-line arguments
• Colored output
• Basic AVD management

Usage Examples

# Interactive mode
./scripts/run_emulator.sh

# Command line mode
./scripts/run_emulator.sh --width 411 --height 731 --build-mode release

# List AVDs
./scripts/run_emulator.sh --list-avds

# Cold boot with custom resolution
./scripts/run_emulator.sh --width 800 --height 1280 --cold-boot

Available Resolutions

Option	Name	Resolution	Description
1	Phone Small	360×640	Small phone screen
2	Phone Medium	411×731	Standard phone screen
3	Phone Large	414×896	Large phone screen
4	Tablet 7"	600×960	7-inch tablet
5	Tablet 10"	800×1280	10-inch tablet
6	Foldable	673×841	Foldable device
7	Desktop	1920×1080	Desktop resolution
8	Custom	User-defined	Specify your own resolution

Command Line Arguments

Common Arguments (both scripts)

Argument	Description	Example
--width, -w	Screen width in pixels	--width 1080
--height	Screen height in pixels	--height 1920
--avd, -a	Use specific AVD name	--avd My_Custom_AVD
--cold-boot, -c	Wipe data and cold boot	--cold-boot
--build-mode, -b	Build mode (debug/release)	--build-mode release
--list-avds, -l	List available AVDs	--list-avds

Python Script Only

• --resolution, -r - Use preset resolution (1-8)

Bash Script Only

• --no-launch - Don't auto-launch app

Emulator Troubleshooting

Common Issues

1. "Emulator not found"

   • Install Android SDK
   • Set ANDROID_SDK_ROOT or ANDROID_HOME environment variable
   • Ensure emulator is installed in SDK

2. "No AVDs available"

   • Run: flutter emulators --create
   • Or use Android Studio to create an AVD
   • Scripts will attempt to create AVDs automatically

3. "Build failed"

   • Ensure you're in the project root directory
   • Run flutter doctor to check Flutter setup
   • Try flutter clean and rebuild

4. "Emulator won't start"

   • Check if virtualization is enabled in BIOS
   • Try different system image (x86_64 vs arm64)
   • Increase available RAM in AVD settings

Performance Tips

1. Use x86_64 system images for better performance on Intel/AMD systems
2. Enable hardware acceleration (GPU host mode is used by default)
3. Allocate sufficient RAM (scripts use 2GB by default)
4. Use SSD storage for faster emulator boot times

---

Contributing

When modifying these scripts:

1. Test thoroughly on different platforms
2. Update this README if adding new features
3. Follow the existing code style and error handling patterns
4. Ensure cross-platform compatibility (Linux, macOS, Windows with WSL)