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
2. Unity Scene Setup
3. Build Profiles
4. Testing on Device
5. How to Play
6. Customization
7. 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! 📱🎮