# ZenTap Build Scripts

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

## Scripts Overview

### 🎵 [`convert_audio.sh`](convert_audio.sh)
Converts audio files to the proper format and specifications for the ZenTap game.

### 📱 [`build_app.sh`](build_app.sh)
Builds APK and AAB files for Android in debug and release modes.

### 📱 [`run_emulator.py`](run_emulator.py) ⭐ **NEW**
Comprehensive Python script to launch ZenTap in Android emulators with selectable resolutions.

### 📱 [`run_emulator.sh`](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](https://ffmpeg.org/download.html)

### Usage
```bash
./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`](../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)
```bash
./scripts/build_app.sh
```

#### Build specific variants
```bash
# 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
```bash
./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
```bash
# 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](https://play.google.com/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
```bash
# 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`](../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
```bash
# 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
```bash
# 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)