EvidenceManager v1.0
by Gamecock Tomahawk
====================

A RagePluginHook plugin for GTA V that adds physical evidence collection
to traffic stops and investigations. Search a suspect or vehicle, pick out
what you found, and the items appear as 3D props on your player vehicle's
hood. Bag what matters, discard what doesn't, then drive to Mission Row PD
to book everything into the evidence room.

Loose weapons on the ground are automatically collected as evidence when
you pick them up — removed from your weapon wheel and placed on the hood.

Includes custom item lists for StopThePed pat-downs and vehicle searches.

REQUIREMENTS
------------
- RagePluginHook (ragepluginhook.net)
- RAGENativeUI (github.com/alexguirre/RAGENativeUI)
- StopThePed (recommended, for pat-down/vehicle search integration)

INSTALLATION
------------
1. Drag the "plugins" folder from this zip into your GTA V root folder
   and let it merge with the existing one.

That's it. The folder structure inside the zip mirrors your game directory:

   plugins\
     EvidenceManager.dll
     EvidenceManager.ini
     EvidenceManager\
       props_personal.txt       (pat-down item-to-prop mappings)
       props_vehicle.txt        (vehicle search item-to-prop mappings)
     LSPDFR\
       StopThePed\
         PatDownItems.xml       (what items can roll during pat-downs)
         VehicleItems.xml       (what items can roll during vehicle searches)

2. Load via RagePluginHook.

CONTROLS
--------
F2              Open the Evidence Manager menu
F2 (near clerk) Open the Evidence Room booking menu instead

Position adjustment mode (active after selecting Adjust Position):
  Up / Down      Raise or lower the props on the hood
  Left / Right   Shift props toward windshield or toward bumper
  Enter          Confirm new position
  Backspace      Cancel and revert

WORKFLOW
--------
1. Conduct a pat-down or vehicle search through StopThePed (or any
   other mod — this works standalone too).

2. Press F2 to open the Evidence Manager menu.

3. Select "Add Evidence" — a text box appears on screen. Type a
   description of what you found (for example: "knife", "brown
   powder", "switchblade", "pistol"). The plugin fuzzy-matches
   your text against its item database.
     - If one match is found, the item is added directly.
     - If multiple matches are found, a picker menu appears.
     - If nothing matches, you'll see a "no match" notification.

4. The item spawns as a 3D prop on your player vehicle's hood,
   arranged in a grid. Add as many items as you need.

5. Check off the items you want to keep, then select:
     - "Bag Evidence" to store them in your inventory, or
     - "Discard Evidence" to remove them from the hood.

6. Drive to Mission Row PD and approach the evidence room clerk
   (marked with a blue "Evidence Room" blip on your map when nearby).

7. Press F2 near the clerk. The Evidence Room menu opens, showing
   everything in your inventory as checkboxes. Check the items you
   want to book, then select "Confirm" — the checked items appear
   on the evidence counter and are removed from your inventory.

AUTOMATIC WEAPON PICKUP
------------------------
The plugin scans the area around you for loose weapons on the ground
every 5 seconds. "Loose" means not held by or attached to anyone —
only weapons lying on the ground are tracked. Your own holstered or
equipped weapons are never touched.

When you walk over a tracked loose weapon and pick it up, the plugin
removes it from your weapon wheel and places it on your player
vehicle's hood as evidence. You'll see a notification when a weapon
is auto-collected. From there you can bag or discard it through the
menu like any other evidence.

MENU STRUCTURE
--------------
Evidence Manager (F2)
  Add Evidence       Type a description to search for and place a
                     matching prop on your player vehicle's hood
  Adjust Position    Enter real-time mode to nudge all hood props
                     up/down or toward/away from the windshield
  [item checkboxes]  Check items currently on the hood, then choose
                     Bag or Discard below
  Bag Evidence       Move all checked items into your inventory
  Discard Evidence   Remove all checked items from the hood without
                     saving them
  View Inventory     See everything you've bagged so far

Evidence Room (F2 near clerk)
  [item checkboxes]  Check inventory items to book into evidence
  Confirm            Book all checked items — props appear on the
                     evidence counter, items leave your inventory

EVIDENCE CATEGORIES
-------------------
Items are color-coded by severity in all menus:

  Red      Always illegal — heavy drugs, explosives, stolen goods,
           illegal firearms
  Yellow   Potentially illegal — small drug amounts, concealed
           weapons, forged documents, suspicious paraphernalia
  Green    Suspicious but legal — tools, legal cash, legal weapons,
           personal items

FEATURES
--------
- Automatic weapon collection: loose weapons picked up off the ground
  are removed from your wheel and placed on the hood as evidence.
  Weapons held by or attached to peds are ignored.
- Fuzzy text search: type a partial description and the plugin finds
  the closest match from over 400 items across both databases.
- 3D prop placement: evidence appears physically on your player
  vehicle's hood with per-item rotation and height adjustments so
  each prop sits correctly (guns on their sides, knives flat, etc.).
- Adjustable positioning: nudge all props if they clip through or
  float above a particular vehicle's hood model.
- Persistent inventory: bagged evidence is saved to disk and survives
  plugin reloads.
- Evidence room booking: physically place props on the Mission Row PD
  evidence counter to close out a case.
- Hood warning: a yellow on-screen warning appears if you get into a
  vehicle that still has evidence on its hood.
- Evidence room blip: a blue map marker appears near the clerk when
  you're within range.

CONFIGURATION
-------------
Open plugins\EvidenceManager.ini in Notepad to change:

[EvidenceRoom]
  X, Y, Z         Clerk position coordinates (default: Mission Row PD)
  ClerkModel       Ped model for the evidence clerk
                   (default: s_m_y_cop_01)
  ClerkHeading     Direction the clerk faces (default: 95.922)
  InteractRadius   How close you need to be to the clerk for the
                   Evidence Room menu to appear (default: 2.0)

CUSTOMIZING ITEMS
-----------------
Two pairs of files control what items exist:

StopThePed XMLs (what can roll during searches):
  plugins\LSPDFR\StopThePed\PatDownItems.xml
  plugins\LSPDFR\StopThePed\VehicleItems.xml

  Each item has a chance attribute: "rare", "normal", or "often".
  Items are grouped under <RedItems>, <YellowItems>, <GreenItems>.

EvidenceManager prop mappings (description-to-3D-model links):
  plugins\EvidenceManager\props_personal.txt
  plugins\EvidenceManager\props_vehicle.txt

  Format:  prop_model_name | description
  Grouped under # RED, # YELLOW, # GREEN section headers.

To add a new item, add it to both the relevant XML (so StopThePed
can roll it) and the relevant txt file (so EvidenceManager can
spawn its 3D prop). The description text must match between the two.

TROUBLESHOOTING
---------------
Q: I pressed F2 and nothing happened
A: Make sure EvidenceManager.dll is loaded in RagePluginHook. Check
   the RPH console or log for "EvidenceManager loaded."

Q: I added evidence but nothing appeared on the hood
A: Make sure you have a player vehicle. The plugin places evidence
   on your last driven vehicle's hood.

Q: Props are floating above / clipping through the hood
A: Select "Adjust Position" from the menu and use Up/Down arrow
   keys to raise or lower them until they sit correctly.

Q: I can't find the evidence room
A: The clerk is inside Mission Row PD. When you're within about
   25 meters, a blue "Evidence Room" blip appears on your map.

Q: An item from StopThePed doesn't show up in EvidenceManager
A: The description in the StopThePed XML must have a matching line
   in the EvidenceManager prop txt file. Check that both files
   have the same description text for that item.

Q: A weapon I picked up wasn't auto-collected
A: The plugin scans for loose weapons every 5 seconds. If you pick
   one up between scans (before it's been tracked), it won't be
   caught. Walk near a weapon and wait a moment before picking it up.
