GeoSusGame/SETUP_GUIDE.md

# GYROSCOPE TILT GAME - COMPLETE SETUP GUIDE

> **Unity 6 (6000.x) Specific Guide**
> This guide uses Unity 6's new **Build Profiles** system (replaces old Build Settings).
> If you're on Unity 2022 or older, some menu names will be different.

## 📋 TABLE OF CONTENTS
1. [Overview](#overview)
2. [Unity Scene Setup](#unity-scene-setup)
3. [Build Profiles](#build-profiles-unity-6)
4. [Testing on Device](#testing-on-device)
5. [How to Play](#how-to-play)
6. [Customization](#customization)
7. [Troubleshooting](#troubleshooting)

---

## 📖 OVERVIEW

### What This Game Does:
- Detects when you tilt your phone around the Z-axis (portrait to landscape)
- Counts successful tilts (crossing -45° or +45°)
- Tracks time spent holding tilt position
- Hybrid scoring: Complete 10 tilts AND hold for 15 seconds total

### Scripts Included:
1. **GyroTiltController.cs** - Handles all gyroscope input, calibration, and tilt detection
2. **TiltGameManagerAutoStart.cs** - Game logic with auto-start (no UI needed)

### What You'll See:
- Debug text overlay showing angles, score, and objectives
- Optional 3D cube that rotates with your phone
- Game auto-starts after 2 seconds
- Game auto-restarts after completion

---

## 🎮 UNITY SCENE SETUP

### STEP 1: Create GameManager

1. **Create Empty GameObject:**
   - Right-click in **Hierarchy** → **Create Empty**
   - Name it: `GameManager`
   - Position: `(0, 0, 0)`

2. **Add GyroTiltController Script:**
   - Select `GameManager` in Hierarchy
   - In Inspector, click **Add Component**
   - Type: `GyroTiltController`
   - Press Enter

3. **Configure GyroTiltController:**
   ```
   ✓ Enable Gyro On Start: CHECKED
   Smoothing: 0.5
   Left Tilt Threshold: -45
   Right Tilt Threshold: 45
   Deadzone Angle: 10
   Visual Target: (leave empty for now - we'll add in Step 2)
   Visual Rotation Multiplier: 1
   ```

4. **Add TiltGameManagerAutoStart Script:**
   - With `GameManager` still selected
   - Click **Add Component**
   - Type: `TiltGameManagerAutoStart`
   - Press Enter

5. **Configure TiltGameManagerAutoStart:**
   ```
   Gyro Controller: [Drag "GameManager" from Hierarchy here]
   Game Duration: 30
   Target Tilt Count: 10
   Target Hold Time: 15
   Points Per Tilt: 10
   Points Per Second Hold: 5
   Completion Bonus: 100
   Auto Start Delay: 2
   ```

   **IMPORTANT:** You MUST drag the `GameManager` GameObject into the "Gyro Controller" field!

---

### STEP 2: Create Visual Indicator (Optional but Recommended)

This creates a 3D object that rotates when you tilt your phone.

1. **Create 3D Cube:**
   - Right-click Hierarchy → **3D Object** → **Cube**
   - Name it: `TiltIndicator`

2. **Position It:**
   - Select `TiltIndicator`
   - In Inspector, set Transform:
     ```
     Position: X=0, Y=0, Z=5 (in front of camera)
     Rotation: X=0, Y=0, Z=0
     Scale: X=0.5, Y=2, Z=0.1 (makes it arrow-like)
     ```

3. **Optional - Add Color:**
   - In Project window: Right-click → **Create** → **Material**
   - Name: `TiltMaterial`
   - Select it, set Albedo color to bright cyan or any color you like
   - Drag `TiltMaterial` onto `TiltIndicator` in Scene view

4. **Connect to GyroTiltController:**
   - Select `GameManager` in Hierarchy
   - Find the **GyroTiltController** component in Inspector
   - Drag `TiltIndicator` from Hierarchy into the **Visual Target** field
   - Now the cube will rotate with your phone!

---

### STEP 3: Verify Camera Exists

- You should already have **Main Camera** in your scene
- If not: GameObject → Camera
- Default position is fine: `(0, 1, -10)`

---

### STEP 4: Save Your Scene

1. **File** → **Save As**
2. Name: `TiltGame`
3. Save location: `Assets/Scenes/TiltGame.unity`

---

### ✅ FINAL HIERARCHY CHECK

Your Hierarchy should look like this:

```
Scene: TiltGame
├── Main Camera
├── Directional Light (default)
├── GameManager
│   ├── GyroTiltController (script component)
│   └── TiltGameManagerAutoStart (script component)
└── TiltIndicator (Cube)
```

That's it! Only 3-4 GameObjects needed.

---

## 📱 BUILD PROFILES (Unity 6)

Unity 6 uses **Build Profiles** instead of the old Build Settings window.

### STEP 1: Open Build Profiles Window

1. **File** → **Build Profiles**
2. The Build Profiles window opens (replaces old Build Settings)

---

### STEP 2: Create Android Build Profile

1. In Build Profiles window, click **Create Build Profile** (or the **+** button)
2. Select **Android** from the list
3. The Android build profile is created and activated automatically

**For iOS (if targeting iPhone):**
1. Click **+** button in Build Profiles window
2. Select **iOS**
3. You'll need a Mac and Xcode for the actual build

---

### STEP 3: Add Scene to Build Profile

1. In Build Profiles window, make sure your **Android** profile is selected (highlighted)
2. Look for the **Scenes in Build** section
3. Click **Add Open Scenes** button (or drag scene from Project window)
4. You should see `Scenes/TiltGame` in the list with a checkmark

---

### STEP 4: Configure Player Settings

1. In Build Profiles window, with Android profile selected, find the **Player Settings** section
2. Or go to: **Edit** → **Project Settings** → **Player** → **Android tab** (Android icon)
3. Configure these settings:

```
Company Name: YourName
Product Name: TiltGame
Version: 1.0

Resolution and Presentation:
  Default Orientation: Portrait
  (or Auto Rotation if you want flexibility)
  Allowed Orientations for Auto Rotation:
    ✓ Portrait
    ✓ Landscape Left
    ✓ Landscape Right

Other Settings (scroll down):
  Minimum API Level: Android 7.0 'Nougat' (API Level 24) or higher
  Target API Level: Automatic (highest installed)

  Scripting Backend: IL2CPP (recommended) or Mono
  ARM64: ✓ (required for Google Play)
```

---

### STEP 5: Build to Device

**Option A: Build And Run (Recommended)**

1. **Enable USB Debugging on your Android phone:**
   - Settings → About Phone → Tap "Build Number" 7 times
   - Settings → Developer Options → Enable "USB Debugging"

2. **Connect phone via USB cable**

3. **In Unity:**
   - Make sure Android build profile is **active** (selected in Build Profiles window)
   - Click **Build and Run** button in Build Profiles window
   - Choose save location for APK (e.g., `Builds/TiltGame.apk`)
   - Click Save
   - Wait for build (2-10 minutes first time)
   - App automatically installs and launches on phone!

**Option B: Build APK Only**

1. In Build Profiles window, click **Build** button
2. Choose save location (e.g., `Builds/TiltGame.apk`)
3. Click Save and wait for build to complete
4. Transfer APK to phone (Google Drive, email, USB, etc.)
5. Install manually on phone

**Option C: Quick Build (Unity 6 Feature)**

1. Use keyboard shortcut: **Ctrl+B** (Windows) or **Cmd+B** (Mac)
2. Builds to the last used location automatically
3. Super fast for testing iterations!

---

### Unity 6 Build Profiles - What's New?

Unity 6's Build Profiles are better than old Build Settings:

✅ **Multiple profiles:** Create Android, iOS, and PC builds without switching platforms constantly
✅ **Faster switching:** No more waiting 5 minutes to switch platforms
✅ **Per-profile settings:** Different scenes/settings for each platform
✅ **Keyboard shortcuts:** Ctrl+B for quick builds

**Example workflow:**
1. Create Android profile (for phone testing)
2. Create Standalone profile (for PC testing)
3. Switch between them instantly - no re-importing!

---

## 🎮 HOW TO PLAY

### When You Launch the App:

#### **First 2 Seconds:**
```
Debug text shows:
  "Game starting soon..."
  "Hold device and press CALIBRATE if needed"

Raw Z: 12.3°          ← Your current tilt angle (raw sensor data)
Smoothed Z: 11.8°     ← Filtered angle (smoother, less jittery)
State: Neutral        ← Current tilt state
```

**What to do:** Hold your phone in a comfortable position (portrait, landscape, whatever you prefer)

---

#### **Game Starts (After 2 Seconds):**
```
GAME ACTIVE
Time: 30.0s           ← Countdown timer
Score: 0              ← Your current score
Tilts: 0/10          ← Tilt count / target
Hold: 0.0s/15s       ← Hold time / target
```

**Objective:** Complete BOTH goals before time runs out:
- ✅ Cross tilt threshold 10 times (left or right)
- ✅ Hold tilted position for 15 seconds total (cumulative)

---

#### **How to Score Points:**

1. **Tilt Scoring (+10 points each):**
   - Tilt phone LEFT past -45° → triggers "TILT LEFT"
   - Tilt phone RIGHT past +45° → triggers "TILT RIGHT"
   - Each crossing = 1 tilt counted
   - Console shows: `>>> TILT #1! +10 points`

2. **Hold Time Scoring (+5 points per second):**
   - Stay tilted past threshold (left OR right)
   - Timer accumulates while holding
   - Points added continuously: `+5, +10, +15...`

3. **Completion Bonus (+100 points):**
   - Complete BOTH objectives before 30 seconds
   - Automatically awards 100 bonus points
   - Shows: `★★★ ALL OBJECTIVES COMPLETED! ★★★`

---

#### **Visual Feedback:**

- **Tilt Angle Number:** Updates in real-time as you tilt
- **State Indicator:** Shows "Neutral", "TiltLeft", or "TiltRight"
- **Cube Rotation:** The TiltIndicator cube rotates matching your phone tilt
- **Score Counter:** Updates continuously
- **Green Text:** Objectives turn green when completed

---

#### **Game Over:**
```
GAME OVER
Final Score: 245
Restarting in 5s...
```

Game automatically restarts after 5 seconds!

---

### Controls Summary:

| Action | What Happens |
|--------|--------------|
| Tilt left (past -45°) | +1 tilt, +10 points, state = TiltLeft |
| Tilt right (past +45°) | +1 tilt, +10 points, state = TiltRight |
| Hold tilt position | Hold time increases, +5 pts/second |
| Return to neutral | State = Neutral, hold time stops |
| Complete objectives | Game ends, +100 bonus |
| Time reaches 0s | Game ends, no bonus |

---

## ⚙️ CUSTOMIZATION

### Make Game Easier/Harder:

Open Unity, select `GameManager`, modify these values:

**Easier:**
```
TiltGameManagerAutoStart:
  Game Duration: 45 (more time)
  Target Tilt Count: 5 (fewer tilts needed)
  Target Hold Time: 10 (less hold time needed)

GyroTiltController:
  Left Tilt Threshold: -30 (easier to trigger)
  Right Tilt Threshold: 30
```

**Harder:**
```
TiltGameManagerAutoStart:
  Game Duration: 20 (less time)
  Target Tilt Count: 15 (more tilts needed)
  Target Hold Time: 20 (more hold time needed)

GyroTiltController:
  Left Tilt Threshold: -60 (harder to trigger)
  Right Tilt Threshold: 60
```

---

### Adjust Smoothing:

**Jittery/Jumpy rotation?**
```
GyroTiltController:
  Smoothing: 0.7-0.9 (more smoothing, less jitter)
```

**Laggy/Slow response?**
```
GyroTiltController:
  Smoothing: 0.1-0.3 (less smoothing, faster response)
```

---

### Change Scoring:

```
TiltGameManagerAutoStart:
  Points Per Tilt: 20 (instead of 10)
  Points Per Second Hold: 10 (instead of 5)
  Completion Bonus: 500 (instead of 100)
```

---

### Adjust Auto-Start Delay:

```
TiltGameManagerAutoStart:
  Auto Start Delay: 5 (wait 5 seconds instead of 2)
```

Set to `0` to start immediately!

---

### Change Game Duration:

```
TiltGameManagerAutoStart:
  Game Duration: 60 (1 minute game)
```

---

## 🔧 TROUBLESHOOTING

### Problem: "Gyroscope not supported"

**Cause:** Device doesn't have gyroscope sensor (rare on modern phones)

**Fix:**
- Test on a different phone
- Verify gyro exists: Install "Sensor Kinetics" app from Play Store
- Most phones from 2015+ have gyroscope

---

### Problem: Tilt detection feels backwards

**Cause:** Different phone orientation than expected

**Fix Option 1 - Recalibrate:**
- Hold phone in your preferred "neutral" position
- (Future version will have calibrate button)

**Fix Option 2 - Swap thresholds in code:**
```
Left Tilt Threshold: 45
Right Tilt Threshold: -45
```

---

### Problem: Cube doesn't rotate

**Cause:** Visual Target not assigned

**Fix:**
1. Select `GameManager`
2. Find `GyroTiltController` component
3. Drag `TiltIndicator` into "Visual Target" field
4. If field is grayed out, make sure TiltIndicator exists in Hierarchy

---

### Problem: No tilts detected when I tilt phone

**Cause 1:** Threshold too high
```
Solution: Lower thresholds to -30 / +30
```

**Cause 2:** Wrong axis
```
Solution: Check you're tilting around Z-axis (portrait ↔ landscape)
Not tilting forward/backward (that's X-axis)
```

**Cause 3:** Inside deadzone
```
Solution: Lower deadzone from 10 to 5
```

---

### Problem: Game doesn't start

**Cause:** Gyro Controller reference missing

**Fix:**
1. Select `GameManager`
2. Find `TiltGameManagerAutoStart` component
3. Make sure "Gyro Controller" field has `GameManager` assigned
4. If it says "None", drag `GameManager` from Hierarchy into that field

---

### Problem: Compilation errors in Unity

**Cause:** TiltUI.cs or TiltGameManager.cs are active (they need TextMeshPro)

**Fix:**
These files should be disabled (renamed to `.DISABLED` extension).
Only these scripts should exist:
- ✅ GyroTiltController.cs
- ✅ TiltGameManagerAutoStart.cs

If you see TiltUI.cs, rename it to TiltUI.cs.DISABLED

---

### Problem: Gyro drifts over time

**Cause:** Gyroscope sensors have slight drift

**Fix:**
- Calibration helps reset the drift
- In current version, game auto-calibrates on start
- Future: Add manual calibrate button

---

### Problem: Can't install APK on phone

**Cause:** "Install from unknown sources" disabled

**Fix:**
1. Settings → Security
2. Enable "Unknown Sources" or "Install Unknown Apps"
3. Allow installation from your file manager app

---

### Problem: Screen auto-rotates during gameplay

**Cause:** Orientation set to Auto Rotation

**Fix:**
- Unity: Player Settings → Default Orientation → Portrait
- Or: Lock orientation in phone settings during gameplay

---

### Problem: Build fails / Unity crashes

**Solutions:**
1. Close Unity, delete `Library` folder, reopen project
2. Update Android SDK/NDK (Unity Hub → Installs → Add Modules)
3. Lower graphics quality: Edit → Project Settings → Quality → Set to "Low"
4. Check disk space (need ~5GB free)
5. **Unity 6 specific:** Make sure Build Profile is active (highlighted in Build Profiles window)
6. **Unity 6 specific:** Check that scene is in the Build Profile's "Scenes in Build" list

---

## 📊 UNDERSTANDING THE DEBUG TEXT

### Upper Section (Always Visible):
```
Raw Z: -23.4°          ← Direct sensor reading (updates ~100 times/sec)
Smoothed Z: -21.8°     ← Filtered value (what game uses for detection)
State: TiltLeft        ← Current tilt state (Neutral/TiltLeft/TiltRight)
```

**What the angles mean:**
- `0°` = Neutral position (as calibrated)
- Negative (-45°) = Tilted LEFT (counterclockwise)
- Positive (+45°) = Tilted RIGHT (clockwise)
- Range: -180° to +180°

---

### Lower Section (During Gameplay):
```
GAME ACTIVE            ← Game state indicator
Time: 18.3s            ← Countdown (turns red below 10s)
Score: 145             ← Current score (yellow)
Tilts: 7/10           ← Progress (turns green when complete)
Hold: 9.2s/15s        ← Progress (turns green when complete)
```

---

## 🎯 TIPS FOR BEST EXPERIENCE

1. **Calibrate at start:**
   - Hold phone comfortably when game starts
   - This becomes your "0 degrees" reference

2. **Smooth tilting:**
   - Tilt smoothly, not jerky
   - Cross the threshold clearly (go past -45° or +45°)

3. **Alternate left/right:**
   - Tilt left, back to center, tilt right, repeat
   - Gets tilts quickly while building hold time

4. **Hold at threshold:**
   - After tilting past threshold, hold position
   - Accumulates hold time while waiting to tilt back

5. **Watch the cube:**
   - Visual indicator helps you see current tilt
   - When cube is heavily tilted, you're in scoring zone

---

## 📝 GAME STRATEGY

### Beginner Strategy: "Slow and Steady"
- Tilt left → hold 2 seconds → center
- Tilt right → hold 2 seconds → center
- Repeat 10 times
- Time: ~25-30 seconds (good if you're methodical)

### Advanced Strategy: "Fast Tilts"
- Rapid tilts left-right-left-right (get to 10 tilts fast)
- Then hold at either threshold for remaining hold time
- Time: ~15-20 seconds (requires practice)

### Perfect Strategy: "Hybrid"
- Tilt left → hold 1.5s
- Tilt right → hold 1.5s
- Repeat 10 times (10 tilts × 1.5s × 2 = 30s hold time!)
- Completes both objectives simultaneously

---

## 📂 FILE STRUCTURE

```
Assets/
├── Scenes/
│   └── TiltGame.unity          (Your game scene)
├── Scripts/
│   ├── GyroTiltController.cs   (Gyro input handler)
│   └── TiltGameManagerAutoStart.cs (Game logic)
└── Materials/ (optional)
    └── TiltMaterial.mat        (Color for cube)

Builds/
└── TiltGame.apk                (Android build output)
```

---

## 🚀 QUICK START CHECKLIST

Before building, verify:

- [ ] Scene saved as `TiltGame.unity`
- [ ] `GameManager` exists in Hierarchy
- [ ] `GameManager` has 2 scripts: GyroTiltController + TiltGameManagerAutoStart
- [ ] `TiltGameManagerAutoStart` → Gyro Controller field = `GameManager`
- [ ] `TiltIndicator` (cube) exists
- [ ] `TiltIndicator` assigned to GyroTiltController → Visual Target
- [ ] Scene added to Build Profile
- [ ] Android Build Profile created and active
- [ ] Player Settings configured (Orientation, API Level)
- [ ] Phone connected via USB (for Build And Run)
- [ ] USB Debugging enabled on phone

---

## 🎓 NEXT STEPS / ENHANCEMENTS

Want to improve the game? Here are ideas:

### Easy Additions:
- Add UI buttons (requires setting up TextMeshPro)
- Add sound effects on tilt
- Change cube to arrow 3D model
- Add particle effects on successful tilt

### Medium Additions:
- Add difficulty levels (Easy/Medium/Hard)
- Add high score tracking (PlayerPrefs)
- Add different game modes
- Add vibration feedback on tilt

### Advanced Additions:
- Online leaderboards
- Multiple levels with increasing difficulty
- Power-ups (2x points, slow time, etc.)
- Tutorial sequence for first-time players
- Settings menu (adjust thresholds, smoothing)

---

## 📞 NEED HELP?

If you encounter issues not covered in Troubleshooting:

1. Check Unity Console for error messages
2. Verify all steps were followed exactly
3. Try on a different Android device
4. Rebuild after cleaning (delete Library folder)

---

**Created for Unity 6 (6000.2.8f1)**
**Works on Android 7.0+ and iOS 11+**
**Last Updated: 2025-11-15**

---

## 🎉 YOU'RE READY!

Follow the steps above and you'll have a fully working gyroscope tilt game.

**Estimated Setup Time:** 10-15 minutes
**Estimated Build Time:** 5-10 minutes (first build)

Have fun tilting! 📱🎮