# 🎯 Accusation Result System

**Version**: 2.0  
**Status**: Implemented

Rich result objects for detailed accusation feedback, partial credit, and better UX.

---

## Overview

Instead of simple `true/false`, the accusation system now returns **detailed result objects** that provide:

- Partial credit scoring
- Component-level feedback (actor vs location)
- Better reveal UI data
- "You were close!" messaging

---

## Result Object Structure

### **AccusationResult**

```lua
{
  correct = boolean,        -- Overall correctness
  actorCorrect = boolean,   -- Did they accuse the right person?
  locationCorrect = boolean,-- Did they get the location right?
  hasLocation = boolean,    -- Does this scenario check location?
  score = number           -- 0-2 points (actor + location)
}
```

### **Example Results**

**Perfect Accusation**:

```lua
{
  correct = true,
  actorCorrect = true,
  locationCorrect = true,
  hasLocation = true,
  score = 2
}
```

**Partial Credit (Right Actor, Wrong Location)**:

```lua
{
  correct = false,
  actorCorrect = true,
  locationCorrect = false,
  hasLocation = true,
  score = 1
}
```

**Wrong Actor**:

```lua
{
  correct = false,
  actorCorrect = false,
  locationCorrect = false,
  hasLocation = true,
  score = 0
}
```

**No Location Required**:

```lua
{
  correct = true,
  actorCorrect = true,
  locationCorrect = false,
  hasLocation = false,
  score = 1
}
```

---

## API Changes

### **AccusationManager.IsAccusationCorrect**

**Before**:

```lua
local isCorrect = AccusationManager:IsAccusationCorrect(gameController, accusation)
if isCorrect then
  -- Winner!
end
```

**After**:

```lua
local result = AccusationManager:IsAccusationCorrect(gameController, accusation)
if result.correct then
  -- Winner!
elseif result.actorCorrect then
  -- Partial credit!
end
```

### **GameController.DetermineWinners**

**Before**:

```lua
local winners = GameController:DetermineWinners()
```

**After**:

```lua
local winners, partialCredit, results = GameController:DetermineWinners()

-- winners: array of player names who got it completely right
-- partialCredit: array of player names who got actor right but location wrong
-- results: detailed array of all accusation results
```

---

## Scoring System

### **Points**

- **Actor Correct**: +1 point
- **Location Correct**: +1 point
- **Maximum**: 2 points

### **Winner Categories**

1. **Full Winners** (`score = 2` or `score = 1` with no location)
   - Got everything right
   - Displayed prominently in reveal

2. **Partial Credit** (`score = 1` with location required)
   - Got actor right, location wrong
   - "You were close!" feedback

3. **Incorrect** (`score = 0`)
   - Wrong actor
   - Standard feedback

---

## Usage Examples

### **Check Single Accusation**

```lua
local accusation = {
  accuser = "PlayerName-Realm",
  targetPlayer = "SuspectName-Realm",
  targetLocation = "courtyard"
}

local result = HS.Core.AccusationManager:IsAccusationCorrect(
  gameController,
  accusation
)

if result.correct then
  print("Perfect! You got it right!")
elseif result.actorCorrect then
  print("Close! Right person, wrong location.")
else
  print("Not quite. Keep investigating!")
end
```

### **Determine All Winners**

```lua
local winners, partialCredit, results = gameController:DetermineWinners()

print(string.format("Winners: %d", #winners))
print(string.format("Partial Credit: %d", #partialCredit))

for _, resultData in ipairs(results) do
  local r = resultData.result
  print(string.format(
    "%s: Actor=%s, Location=%s, Score=%d",
    resultData.accuser,
    tostring(r.actorCorrect),
    tostring(r.locationCorrect),
    r.score
  ))
end
```

### **Reveal UI Feedback**

```lua
for _, resultData in ipairs(gameController.accusationResults) do
  local result = resultData.result
  local accusation = resultData.accusation

  if result.correct then
    ShowMessage(accusation.accuser, "🎉 Perfect! You solved it!")
  elseif result.actorCorrect then
    ShowMessage(accusation.accuser, "🔍 Close! Right person, wrong place.")
  else
    ShowMessage(accusation.accuser, "❌ Not quite. Better luck next time!")
  end
end
```

---

## EventBus Integration

### **HS_WINNERS_DETERMINED Event**

**Payload**:

```lua
{
  winners = {"Player1-Realm", "Player2-Realm"},
  partialCredit = {"Player3-Realm"},
  results = {
    {
      accuser = "Player1-Realm",
      accusation = { ... },
      result = { correct = true, actorCorrect = true, ... }
    },
    -- ... more results
  },
  actors = {"thief"}  -- Solution actor IDs
}
```

**Usage**:

```lua
GS.EventBus:On("HS_WINNERS_DETERMINED", function(data)
  for _, winner in ipairs(data.winners) do
    print(winner .. " won!")
  end

  for _, partial in ipairs(data.partialCredit) do
    print(partial .. " was close!")
  end
end)
```

---

## Benefits

### **1. Better UX**

**Before**:

- "Wrong" or "Right"
- No nuance

**After**:

- "Perfect! You got it!"
- "Close! Right person, wrong location."
- "Not quite. Keep investigating!"

### **2. Partial Credit**

Players who correctly identify the culprit but miss the location still get recognition:

- Encourages participation
- Rewards good detective work
- More satisfying gameplay

### **3. Rich Reveal UI**

The reveal screen can show:

- Who got it perfect
- Who was close
- Detailed breakdown per player
- Score leaderboard

### **4. Better Debugging**

Developers can see exactly what went wrong:

```lua
result = {
  correct = false,
  actorCorrect = true,   -- They got this right
  locationCorrect = false, -- But missed this
  score = 1
}
```

### **5. Future Extensibility**

Easy to add more criteria:

- `methodCorrect` - Did they guess the method?
- `motiveCorrect` - Did they understand the motive?
- `timeCorrect` - Did they get the timing right?

---

## Backward Compatibility

### **Simple Boolean Check**

Old code still works:

```lua
local result = AccusationManager:IsAccusationCorrect(gameController, accusation)
if result.correct then
  -- This still works!
end
```

### **Migration Path**

1. **Phase 1**: Use `result.correct` as drop-in replacement for old boolean
2. **Phase 2**: Add partial credit UI
3. **Phase 3**: Add detailed feedback messages
4. **Phase 4**: Add score leaderboard

---

## Testing

### **Test Cases**

**Perfect Accusation**:

```lua
accusation = {
  targetPlayer = "ThiefPlayer-Realm",  -- Has role.id = "thief"
  targetLocation = "courtyard"
}
solution = {
  actors = {"thief"},
  location = "courtyard"
}
-- Expected: correct=true, actorCorrect=true, locationCorrect=true, score=2
```

**Partial Credit**:

```lua
accusation = {
  targetPlayer = "ThiefPlayer-Realm",  -- Has role.id = "thief"
  targetLocation = "cellar"            -- Wrong!
}
solution = {
  actors = {"thief"},
  location = "courtyard"
}
-- Expected: correct=false, actorCorrect=true, locationCorrect=false, score=1
```

**Wrong Actor**:

```lua
accusation = {
  targetPlayer = "InnocentPlayer-Realm",  -- Has role.id = "innocent"
  targetLocation = "courtyard"
}
solution = {
  actors = {"thief"},
  location = "courtyard"
}
-- Expected: correct=false, actorCorrect=false, locationCorrect=true, score=1
```

**No Location**:

```lua
accusation = {
  targetPlayer = "ThiefPlayer-Realm",
  targetLocation = nil
}
solution = {
  actors = {"thief"},
  location = nil  -- No location required
}
-- Expected: correct=true, actorCorrect=true, hasLocation=false, score=1
```

---

## Future Enhancements

### **Weighted Scoring**

```lua
result = {
  score = 0,
  maxScore = 3,
  breakdown = {
    actor = { correct = true, weight = 2, points = 2 },
    location = { correct = false, weight = 1, points = 0 }
  }
}
```

### **Confidence Levels**

```lua
accusation = {
  targetPlayer = "ThiefPlayer-Realm",
  confidence = "certain"  -- "certain", "likely", "guess"
}

result = {
  correct = true,
  confidence = "certain",
  bonusPoints = 1  -- Bonus for high confidence
}
```

### **Multi-Criteria**

```lua
result = {
  correct = true,
  actorCorrect = true,
  locationCorrect = true,
  methodCorrect = false,
  motiveCorrect = true,
  score = 3,
  maxScore = 4
}
```

---

## Summary

The accusation result system transforms binary win/lose into **rich, nuanced feedback**:

✅ **Partial credit** for close guesses  
✅ **Detailed feedback** for better UX  
✅ **Score system** for leaderboards  
✅ **Extensible** for future features  
✅ **Backward compatible** with existing code

**Players get better feedback. Developers get better data. Everyone wins!** 🎯
