===============================================================================
                             NFSMW TAKEDOWN N2O
                                   v1.0.1
===============================================================================

Wreck a cop, get nitrous.

An ASI plugin for Need for Speed: Most Wanted (2005, PC). Every time you take
a cop car out of a pursuit, a slice of nitrous goes straight into your bottle.
How big a slice depends on which unit you wrecked, how hot the pursuit is,
and whether you are in a race.

Roadblocks, rammed cruisers, spike strips, cops shoved into traffic and
pursuit-breaker drops all count - anything the game itself treats as a cop
takedown.

New in 1.0.1: you can also earn nitrous just for HITTING a cop, empty the
bottle at the start of every race, and switch off the game's own passive
refill so takedowns become the only way to fill it. All three are covered
further down.


===============================================================================
                              INSTALLATION
===============================================================================

1. Make sure you have an ASI loader installed (usually a file named
   dinput8.dll in your main Need for Speed Most Wanted folder).

2. Drop 'NFSMWTakedownN2O.asi' and 'NFSMWTakedownN2O.ini' into your game's
   'scripts' folder.

3. Launch the game.

That's it! There are no keys to press to activate it. It plays nicely alongside
Unlimiter, Bartender, ExtraOptions, and the Widescreen Fix.

To uninstall, simply delete the two files from your scripts folder.

UPGRADING FROM 1.0.0: replace both files. The new INI adds two sections, so
keeping your old one means the new features stay off. If you had tuned your
values, copy them across into the new INI rather than keeping the old file.


===============================================================================
                           TUNING & CONFIGURATION
===============================================================================

Everything lives in 'NFSMWTakedownN2O.ini'. Open it with any text editor (like
Notepad). Changes take effect the next time you launch the game.

Charges are on a 0-10 scale where 10.0 is a completely full bottle, so 1.0 is
a tenth of the bar and 0.25 is a fortieth. Decimals as small as 0.001 work.
Negative values drain your nitrous instead. The result is always capped at a
full bottle and never goes below empty.

A ';' at the start of a line comments it out, and a commented-out line means
DISABLED - not 1.0. That is how you switch individual levels or cop types off.
All twenty level rows ship active, so out of the box you are rewarded at every
level.

IMPORTANT: your car must have a nitrous package fitted - Race, Pro, Super,
Ultimate or Junkman. On a stock car the mod deliberately awards nothing,
because a car with no nitrous capacity cannot spend what it is given. The check
reads the car's real nitrous attributes rather than a list of package names, so
custom packages work too. Fit one mid-session and rewards resume right away.

The six sections:

[Nitrous:Vehicles]
   Base nitrous per cop model. All twelve stock units are listed, plus a
   'default' fallback for anything else. Add-on cop cars work too - just add
   a line using the pvehicle name from VltEd.

[Nitrous:HeatMultipliers]
   heat01 - heat10, multiplying the base charge by your current pursuit heat.

[Nitrous:RaceMultipliers]
   race01 - race10, stacking on top of the heat multiplier while a race is
   running. In free roam this is always 1.0.

   Final Gain = Vehicle Charge x Heat Multiplier x Race Multiplier

[Nitrous:Collision]                                          (new in 1.0.1)
   Charge for HITTING a cop without wrecking it, set per level with
   heat01 - heat10 and race01 - race10. Any contact counts, from any
   direction. The row value IS the charge - it is not multiplied by the
   multiplier sections again, since the level is already decided by which
   row gets read. raceXY applies during a race, heatXY in free roam.

   Keep these small. Contact is constant in a pursuit, so this adds up far
   faster than takedowns do. It ships at 0.25 per hit as a conservative
   starting point.

[Nitrous:RaceStart]                                          (new in 1.0.1)
   KeepNitrous = true or false. What happens to your nitrous the moment a
   race begins.

   true  = vanilla. You start the race with whatever was in the bottle.
   false = the bottle is emptied to 0% as the race starts, so every race is
           run on nitrous you earn during it rather than on a full bottle you
           rolled up with.

   This covers every event the game counts as a race - Blacklist races,
   Quick Race, circuits, sprints, drags and tollbooths.

   It only empties the bottle ONCE, as the race starts. It does not stop you
   refilling during the race, so it pairs well with the reward tables: no
   free boost off the line, but cops you take out along the way still pay.
   If you want no refills during the race either, set the matching raceXY
   rows in [Nitrous:Recharge] to false as well.

[Nitrous:Recharge]                                           (new in 1.0.1)
   true / false per level, controlling whether the game's OWN passive
   nitrous recharge is allowed to run - the refill driven by RECHARGE_MIN,
   RECHARGE_MIN_SPEED, RECHARGE_MAX and RECHARGE_MAX_SPEED in VltEd. It
   does not change those values; it just permits or blocks the refill they
   produce.

   Set it to false and takedowns become your only source of nitrous, which
   is where this pairs well with the reward table. Spending nitrous is never
   blocked, only refilling. A missing line means true, so leaving the
   section alone changes nothing.

   During a race BOTH heatXY and raceXY must be true for the refill to run,
   so setting either one to false blocks it. In free roam only heatXY is
   read.

[General]
   Enabled = 0 turns the mod off without removing it.

   EnableLogging = 1 writes NFSMWTakedownN2O.log next to the INI, showing
   exactly which rows were picked and what your nitrous bar did. It is off
   by default; turn it on while tuning or when reporting a problem:

      Cop disabled: copsuvpatrol | level index 1 -> race02 |
        base 1.00 x heat 1.00 x race 1.00 = 1.00 | combo x1, bounty 45000
        nitrous gauge 0.046 -> 0.146
      Cop hit at race02 -> 0.25
        nitrous gauge 0.146 -> 0.171
      Passive recharge BLOCKED at heat05

   Very handy while tuning. Turn it off for normal play - pursuit-breaker
   chains and sustained ramming both produce a lot of lines.


===============================================================================
                                CHANGELOG
===============================================================================

v1.0.1
------
NEW      [Nitrous:Collision] - nitrous for hitting a cop without wrecking it,
         set per level with heat01 - heat10 and race01 - race10. Any contact
         counts, from any direction. Ships at 0.25 per hit.

NEW      Your car must have a nitrous package fitted for any reward to apply.
         A stock car has zero nitrous capacity, so anything granted to it
         filled a gauge the game would never let you spend. Race, Pro, Super,
         Ultimate and Junkman are all recognised, as is any custom package -
         the check reads the car's real nitrous attributes rather than a list
         of names. Fit one mid-session and rewards resume immediately.

FIXED    Rewards could land and then vanish. The gauge was written part-way
         through a frame and the game's own nitrous update could overwrite it
         before the frame ended. It is now re-applied after that update runs.
         This is why takedowns sometimes did nothing unless you happened to be
         using nitrous at that exact moment.

FIXED    [Nitrous:Recharge] could read the wrong row. The current level was
         only refreshed on a rewarded takedown, so a commented-out row left the
         recharge veto using a stale level. It now refreshes on every cop
         event.

CHANGED  EnableLogging now defaults to 0. Turn it on while tuning, or if
         something misbehaves - the log names every row the mod reads.

NEW      [Nitrous:RaceStart] - KeepNitrous = false empties your bottle to 0%
         the moment a race starts, so you cannot roll up to a Blacklist race
         on a full tank and boost your way to a win. Covers Quick Race and
         every other event the game counts as a race. Defaults to true.

NEW      [Nitrous:Recharge] - true/false per level, controlling whether the
         game's own passive nitrous refill is allowed to run. Set it false and
         takedowns become your only source of nitrous. During a race either
         row can veto the refill.

CHANGED  Default charges are now 1.0 across [Nitrous:Vehicles] and both
         multiplier sections, up from 0.5. Three stacked 0.5s worked out to
         1.25% of the bar per takedown, which was too small to notice.

CHANGED  Logging now reports collision payouts, blocked refills and race
         starts alongside takedowns, and prints the raw pursuit level index
         next to the row it resolved to.

v1.0.0
------
Initial release. Nitrous on cop takedowns, scaled by cop model, pursuit heat
level and race level. Every kill method the game counts as a takedown counts
here too, pursuit breakers included.


===============================================================================
                            COMPATIBILITY
===============================================================================

Written against the v1.3 executable (speed.exe, 6,029,312 bytes). The plugin
verifies the game's code at startup and, on an executable it does not
recognise, writes the reason to the log and patches nothing rather than
risking a crash. If nothing seems to happen, set EnableLogging = 1 and read
the log - it will tell you why.


===============================================================================
                              SOURCE & CREDITS
===============================================================================

Created by eatincrispies

For full under-the-hood details, specific math breakdowns, and C++ source code,
visit the repository:
https://git.gay/eatincrispies/mw-takedown-n20