========================================
  IMMERSIVE CONVERSATIONS
========================================

Talk to any NPC in GTA V. They'll respond based on who they are,
where they are, what's happening around them, and who they think
you are. Works with LSPDFR
or standalone modded GTA V.

Out of the box, NPC dialogue appears as text on screen. If you want
NPCs to speak out loud, you can set up ElevenLabs voice (optional).


WHAT YOU NEED
-------------
1. RagePluginHook (RPH) - you probably already have this
2. Ollama - free AI that runs on your computer (handles NPC dialogue)


STEP 1: INSTALL OLLAMA
-----------------------
1. Go to https://ollama.com and download it
2. Install it like any other program
3. Open a Command Prompt (search "cmd" in Windows Start menu)
4. Type this and press Enter:

       ollama pull llama3

5. Wait for it to finish downloading (this is a one-time thing)


STEP 2: INSTALL THE MOD
------------------------
1. Copy ImmersiveConversations.dll into your GTA V "plugins" folder
2. Copy ImmersiveConversations.ini into your GTA V "plugins" folder

Your plugins folder is usually at:
   Grand Theft Auto V\plugins\

That's it — the mod works with text on screen right away.


OPTIONAL: ADD AI VOICE (ELEVENLABS)
------------------------------------
Want NPCs to actually talk? Set up ElevenLabs. You'll need a free
or paid account at https://elevenlabs.io.

1. Get your API key:
   - Click your profile icon (top right)
   - Click "Profile + API key"
   - Copy the API key

2. Open ImmersiveConversations.ini in Notepad and paste your key:

       ApiKey=your_key_here

3. Now pick some voices. Go to the ElevenLabs Voice Library:
   https://elevenlabs.io/voice-library

   - Browse and preview voices you like
   - Click "Add to VoiceLab" on each one you want to use
   - Go to your VoiceLab (Voices page on the left sidebar)
   - Click a voice, then click "ID" to copy its Voice ID

4. Paste the voice IDs into your INI, separated by commas:

       MaleVoiceIds=abc123,def456,ghi789
       FemaleVoiceIds=jkl012,mno345

   The more voices you add, the more variety you get. Each NPC
   picks a consistent voice based on their appearance, so the
   same person always sounds the same.

   Minimum: 1 male and 1 female voice ID.
   Recommended: 3-5 of each for good variety.

If you skip this step, the mod still works — you just won't hear
voice, only text on screen.


HOW TO USE
----------
- Hold Right Shift + U near an NPC to start a conversation
- Aim at a distant NPC and press U to start from far away
  (Controller: LT + A | Keyboard/Mouse: Right Click + U)
  The confirm key (U / A) can be changed in the INI file.
  Must be unarmed — won't work while holding a weapon.
- Type your response when prompted
- Select "End conversation" to walk away

- Hold Right Shift + I to set the situation context
  (tell the NPC what's going on so they react to it)


CUSTOMIZATION
-------------
Open ImmersiveConversations.ini in Notepad to change:

- PlayerIdentity: How NPCs see you. Default is "a police officer."
  Change it to anything — "a paramedic", "a celebrity", "a hitman",
  "an alien that everyone accepts." NPCs will treat you accordingly.

- Callsign: Your radio name when talking to dispatch.

- Volume: How loud NPC voices are (0.0 to 1.0). Default is 0.8.

- VoicePlayerLines: Set to true if you want YOUR lines spoken
  out loud too, not just NPCs.

- PlayerVoice: Set to "default" to automatically match your
  character's gender (first male or female voice from your list).
  Change it to a specific voice ID if you want a particular voice.

- ActivationKey / ActivationModifier: Change the keyboard combo to start talking.
  ActivationButton / ActivationButtonModifier: Controller equivalent (default: None).

- ContextButton / ContextButtonModifier: Controller equivalent for the context
  key (default: None). Keyboard uses ContextKey / ContextModifier.

- LongRangeKey / LongRangeButton: Change the confirm key for long-range
  conversations (default: U on keyboard, A on controller).

- Temperature: How creative NPC responses are (0.0 = robotic, 1.0 = wild).
  Default 0.5 is a good balance.


VOICE TIPS
----------
- Spelling must be accurate for proper pronunciation.
- Caps change nothing, but grammar changes everything. The better
  the grammar, the better the AI understands how to say something.
- Use quotation marks around words you want emphasized.
- Use commas for natural breaks in speech.


TROUBLESHOOTING
---------------
Q: Nothing happens when I press the key
A: Make sure Ollama is running. Look for the Ollama icon in your
   system tray (bottom right of your screen, near the clock).
   If it's not there, open Command Prompt and type: ollama serve
   Then try again. If that doesn't work, run: ollama pull llama3

Q: I set up ElevenLabs but there's no sound
A: Check your INI — make sure ApiKey, MaleVoiceIds, and FemaleVoiceIds
   are all filled in. Check the RagePluginHook log for error messages.

Q: I get an error about API key
A: Make sure you copied the full API key with no extra spaces.
   Check that your ElevenLabs account is active.

Q: Voices sound weird or different than expected
A: Try different voices from the ElevenLabs library. Preview them
   on the website before adding them.

Q: Responses are slow
A: Dialogue speed depends on your computer (Ollama runs locally).
   Voice speed depends on your internet (ElevenLabs is online).

Q: I'm hitting my ElevenLabs character limit
A: Free accounts have a monthly limit. Upgrade your plan, or just
   leave voice off and use text on screen.

Q: NPCs only speak English
A: The mod is English-only for now.
