Peril_Dice/AUTOMATIC_REZ_POSITIONING.md

# Automatic Rez-Time Position Detection 🎯

## Yes! Displays automatically detect their positions at rez!

The Peril Dice Game now features **fully automatic position detection** - no config files required, no manual scanning needed. Just rez your displays and they automatically configure themselves!

## How It Works

### ✨ **At Rez Time:**
1. Display rez without config notecard
2. Display immediately broadcasts: "I'm a [scoreboard/leaderboard/dice] at position X"
3. Controller receives the request and calculates the relative position
4. Controller responds: "Your offset is Y, your rotation is Z"
5. Display configures itself and announces: "Ready!"

**Total time: ~1-2 seconds after rez** ⚡

### 🔄 **Automatic Retry System:**
- If no controller response in 5 seconds → retry request
- If still no response in 10 seconds → retry again
- Continues until controller found or manually configured

## Three Positioning Methods

### 🚀 **Method 1: Automatic Rez Detection (NEW!)**
**Zero interaction required!**
- Rez displays anywhere near controller 
- They auto-configure instantly
- **No config files needed**
- **No menu interactions needed**

### 🛠️ **Method 2: Manual Position Reset (Enhanced)**
- Position displays manually where you want them
- Owner Menu → 🛠️ Troubleshooting → Reset Follower Positions
- Automatically updates all display positions
- Still works if auto-rez detection fails

### 📝 **Method 3: Traditional Config (Legacy)**
- Create config notecard with position values
- Still supported for advanced users
- Overrides automatic detection

## Technical Implementation

### Follower Display Side
```lsl
// At rez/state_entry:
if (no_config_notecard) {
    // Broadcast auto-config request
    llRegionSay(DATA_CHANNEL, "AUTO_CONFIG_REQUEST|scoreboard|<pos>|<rot>");
    // Set retry timer
    llSetTimerEvent(5.0);
}

// When controller responds:
llRegionSay(DATA_CHANNEL, "AUTO_CONFIG_RESPONSE|scoreboard|<offset>|<rotation>");
// Configure self automatically
MY_OFFSET = received_offset;
MY_ROTATION = received_rotation;
```

### Controller Side  
```lsl
// Listen for auto-config requests
if (msg starts with "AUTO_CONFIG_REQUEST") {
    // Calculate relative position
    vector offset = (display_pos - controller_pos) / controller_rot;
    rotation rel_rot = display_rot / controller_rot;
    
    // Send response back
    llRegionSay(display_channel, "AUTO_CONFIG_RESPONSE|" + type + "|" + offset + "|" + rotation);
}
```

## User Experience

### 🎮 **For Game Owners:**
- **Rez and forget** - displays auto-configure
- See automatic configuration messages in chat
- Manual reset still available if needed
- Works with multiple displays simultaneously

### 🔧 **For Display Setup:**
- Set `DISPLAY_TYPE = "scoreboard"` in follower script
- Rez display near controller (within ~96 meters)
- Watch it auto-configure in 1-2 seconds
- No config notecard required

## Configuration Messages

You'll see messages like:
```
🎆 Auto-configured scoreboard display at rez!
   Position: <128.1, 45.7, 22.0>
   Calculated offset: <0.0, 3.0, 0.5>
   Calculated rotation: <0.0, 0.0, 0.0, 1.0>
```

On display side:
```
🎆 scoreboard auto-configured successfully!
Auto-detected offset: <0.0, 3.0, 0.5>
Auto-detected rotation: <0.0, 0.0, 0.0, 1.0>
🟢 Ready and listening for controller movement...
```

## Compatibility & Fallbacks

### ✅ **Multi-Instance Safe**
- Each game table has unique channels
- No interference between multiple setups
- Works with owner-specific dynamic channels

### 🛡️ **Robust Fallback Chain**
1. **Auto-detection at rez** (preferred)
2. **Manual position reset** (if auto fails)
3. **Config notecard** (traditional method)
4. **Default positions** (as last resort)

### 🔄 **Migration Friendly**
- Existing config-based displays continue working
- New displays use auto-detection
- Mixed setups supported
- Gradual migration possible

## Troubleshooting

### "No controller response - retrying"
- **Cause**: Controller too far away or not running
- **Solution**: Move display closer or ensure controller is active
- **Range**: Typically works within ~50-100 meters

### Display doesn't auto-configure
- Check `DISPLAY_TYPE` is set correctly in follower script  
- Verify controller has Owner Dialog Handler with auto-config support
- Ensure both use same dynamic channel system
- Try manual position reset as backup

### Multiple displays configure incorrectly
- Auto-detection uses current positions at rez time
- Position displays where you want them BEFORE rezzing
- Use manual reset to adjust positions later

## Benefits Summary

### 🎯 **User Benefits**
- **Zero configuration** - just rez and play
- **Instant setup** - no waiting or manual steps  
- **Error-free** - no manual config editing mistakes
- **Intuitive** - works as users expect

### 🔧 **Technical Benefits**
- **Self-documenting** - positions are automatically calculated
- **Consistent** - eliminates configuration drift
- **Scalable** - works with any number of displays
- **Reliable** - multiple fallback methods

### 🚀 **Operational Benefits**
- **Faster deployment** - no setup time
- **Reduced support** - fewer configuration issues
- **Better UX** - seamless experience
- **Future-proof** - extensible architecture

---

## The Complete Automation Journey

**Phase 1** ✅: Manual config files (traditional)
**Phase 2** ✅: Integrated position reset tool (manual scan)  
**Phase 3** ✅: Automatic position updates (no manual config editing)
**Phase 4** ✅: **Automatic rez-time detection (zero interaction)**

**We've achieved full automation!** 🎉

Just rez your displays and they work - no config files, no menus, no manual steps required.