===============================================
  EXILE HUNTER'S BESTIARY - ModernUO EDITION
  Final stable version
  Author: Imagine
  Refactored: Expa
===============================================

INSTALL

  1. Copy the ExileHunterBestiary folder to:

       Projects/UOContent/Custom/ExileHunterBestiary/

  2. Make sure the generated death-event file exists:

       HunterCreatureDeathEvent.cs

  3. Build the project:

       dotnet build

  4. Start the server.

  IMPORTANT:

    The final version does not require any changes to BaseCreature.cs.

    Do not add:
      - EventSink.CreatureDeath
      - a custom Kill() override
      - a custom OnDeath() override
      - a BaseCreature damage patch

    Do not keep this legacy file:

      BaseCreature.ExileHunterBestiary.cs

    Do not keep old patch files such as:

      PATCH_BaseCreature.txt


ACTIVE DEATH HANDLER

  Creature deaths are handled by the generated ModernUO event:

      BaseCreature.CreatureDeathEvent

  The handler is located in:

      HunterCreatureDeathEvent.cs

  This is not an EventSink event. Do not use:

      EventSink.CreatureDeath


COMBAT TRACKING

  HunterCombatTracker receives player combat activity through:

      EventSink.AggressiveAction

  The tracker stores:

    - the last player attacker;
    - the player's pet owner when applicable;
    - the creature serial;
    - the creature location;
    - the creature map;
    - the time of the last hit.

  The stored location is used because ModernUO can remove the creature
  before the generated death event is handled.


CORPSE DROPS

  The treatise is placed into the creature's corpse.

  If the corpse is not available immediately, the system retries for a
  short period.

  The system does not intentionally place the treatise on the ground.

  If no corpse can be found after the retry period, the drop is canceled.


CONFIGURATION

  Add these values inside the "settings" object in modernuo.json:

    "exileBestiary.enabled": "True",
    "exileBestiary.debug": "False",
    "exileBestiary.damage.mode": "Mark",
    "exileBestiary.damage.perCreatureBonus": "0.10",
    "exileBestiary.damage.categoryMilestoneBonus": "0.20",
    "exileBestiary.damage.totalCap": "0.25",
    "exileBestiary.damage.markDuration": "00:00:10",
    "exileBestiary.damage.markTickSeconds": "00:00:02",
    "exileBestiary.damage.markTickPercent": "0.01",
    "exileBestiary.drop.chance": "-1.0",
    "exileBestiary.drop.pityThreshold": "40"

  Drop chance values:

    -1.0  Use the creature's registered chance
     1.0  100% chance
     0.5  50% chance
     0.02 2% chance
     0.0  No random drops

  Example for guaranteed drops:

    "exileBestiary.drop.chance": "1.0"

  The configuration must be inside:

    {
      "settings": {
        ...
      }
    }


DAMAGE MODE

  The recommended mode is:

    "exileBestiary.damage.mode": "Mark"

  Mark mode is patch-free and does not require BaseCreature.cs changes.

  The mark system uses:

    - EventSink.AggressiveAction
    - a timer
    - public ModernUO APIs

  It applies periodic bonus damage while the hunter remains near
  the marked creature.


COMMANDS

  [Bestiary

    Opens the Hunter's Bestiary.

  [Bestiario

    Alias for [Bestiary.

  [BestiaryTest

    Game Master command that runs the treatise pipeline against the nearest
    registered creature.

    The command uses the configured chance and is intended for testing.

  [BestiaryDiag

    Game Master diagnostic command that displays combat-tracker counters.


STARTUP CHECK

  The server should report a bestiary initialization message similar to:

    Initialized with N creatures across 8 categories.

  When Mark mode is enabled, it should also report:

    Hunter's Mark enabled ...


TROUBLESHOOTING

  No treatise appears:

    1. Confirm the creature exists in BestiaryData.cs.
    2. Confirm the creature type was registered at startup.
    3. Confirm exileBestiary.enabled is True.
    4. Confirm the player actually damaged the creature.
    5. Confirm EventSink.AggressiveAction is receiving events.
    6. Confirm the generated event file exists.
    7. Confirm no old BaseCreature patch file remains.
    8. Set exileBestiary.drop.chance to 1.0.
    9. Temporarily set exileBestiary.debug to True.

  No combat events are tracked:

    Run:

      [BestiaryDiag

    The AggressiveAction counter should increase after attacking a creature.

  Log says "killer not resolved":

    The system did not receive LastKiller and did not find a valid player
    in HunterCombatTracker.

  Log says "killer is not a player":

    The kill was credited to an NPC, an uncontrolled creature, or another
    non-player source.

  Log says "creature not registered":

    The creature type is not present in BestiaryData.cs or could not be
    resolved by AssemblyHandler.FindTypeByName.

  Treatise is already learned:

    A player receives only one treatise for a creature that has already
    been mastered. Additional drops are blocked for that player.

  Treatise is not visible:

    Open the creature corpse and check its contents. The treatise is not
    automatically placed into the player's backpack.


SAVE DATA

  Profiles are stored at:

    Data/ExileHunterProfiles.xml

  Saved data includes:

    - learned creature IDs;
    - pity counters;
    - player serials.

  Invalid creature IDs are ignored during loading.


FILES TO KEEP

  BestiaryCategory.cs
  BestiaryData.cs
  BestiaryRegistry.cs
  DamageMode.cs
  HunterBestiaryEngine.cs
  HunterCombatTracker.cs
  HunterCreatureDeathEvent.cs
  HunterCreatureEntry.cs
  HunterProfile.cs
  HunterProfileStore.cs
  HunterBestiaryGump.cs
  HunterDamageHook.cs
  HunterDeathHook.cs
  HunterMarkHook.cs
  HunterBestiary.cs
  HunterTreatise.cs


LEGACY FILES TO REMOVE

  BaseCreature.ExileHunterBestiary.cs
  PATCH_BaseCreature.txt

  Also remove any legacy bestiary file that overrides:

    BaseCreature.Kill()
    BaseCreature.OnBeforeDeath()
    BaseCreature.OnDeath()


PRODUCTION SETTINGS

  After confirming the system works, use:

    "exileBestiary.debug": "False"

  Keep debug enabled only while diagnosing the drop pipeline.