Init

2026-02-21 10:23:17 +01:00
parent 5606c2474e
commit 9f71b6a84a
60 changed files with 10652 additions and 0 deletions
--- a/SETUP_GUIDE.md
+++ b/SETUP_GUIDE.md
@@ -0,0 +1,719 @@
+# 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! 📱🎮