============================================================
 TRAILWATCHERS
 A Minecraft Bedrock Edition addon
============================================================

Hostile mobs learn where you habitually travel, and ambush you there.


----------------------------------------------------------------
 WHAT IT DOES
----------------------------------------------------------------

Every second, the addon records where each grounded player walks into a
per-player "route heatmap" (a coarse 4x4-block grid, keyed by dimension and
cell X/Z). Ground near your own spawn point is discounted to 25% weight, so
the system learns your travel routes rather than the base you stand in.

Heat decays by 10% per in-game day, so your habits fade if you change them.

At dusk, hooded "Scout" mobs spawn 25-40 blocks off your three hottest
routes. A Scout that survives 40 seconds of watching (with actual line of
sight to you or to one of your hot cells) "reports" - an ember puff and a
distant horn. That report queues a Warband ambush: 3-6 vanilla hostiles,
chosen by biome, placed at a chokepoint on your route, in light level 7 or
lower, with a 15-second ember warning when you get close.

The Warband despawns at dawn. One ambush per player, one in-game day cooldown.


----------------------------------------------------------------
 THE SCOUT HAS THREE MOODS
----------------------------------------------------------------

A Scout is not just a camera. What it does depends on what you have done
to it:

  WATCHING (default)
    It keeps its distance and never attacks. It flees if you get within
    8 blocks, because it is a spy, not a soldier. While it can see you (or
    one of your hot cells) it is quietly learning your route.

  CORNERED (you hit it)
    The moment you land a hit, the ruse is over. It stops running, turns
    on you, and fights for 3 damage a hit. It is still watching you while
    it fights - it is right next to you, after all - so a cornered Scout
    is the most dangerous kind.

  REPORTED (it gave you away)
    After it has sounded the horn, it has nothing left to hide. It pursues
    you from up to 32 blocks and hits for 4 damage.

So: a Scout you never touch is a Scout you must break line of sight with. A
Scout you touch once is a Scout you must kill quickly.

Each mood has its own animation:

  WATCHING  the hood sweeps slowly as it scans the ground, and it holds the
            spyglass up to its eye, tracking you.
  FIGHTING  the body drops into a low, forward stance, the hood flares and
            the spyglass arm lashes out on every hit.

The behaviour pack tells the resource pack which mood a Scout is in by
setting its variant (0 watching, 1 cornered, 2 reported); the client reads
that back with query.variant and swaps the animation.


----------------------------------------------------------------
 HOW TO FIGHT BACK
----------------------------------------------------------------

1. Kill Scouts before they report.
    A Scout has only 12 HP and flees when you get within 8 blocks, so it is
    fragile but hard to corner. If it dies first, the observation is lost.

2. Change your routes.
    Heat decays ~10% per in-game day. Taking a new path genuinely redirects
    the ambushes over time.

3. Light up your roads.
    Ambushes only form in light level 7 or lower. Torches work.

4. Build Ward Posts.
    Blocks Scout observation and ambush spawns within 24 blocks. Pulses a
    particle ring so you can see coverage, and hums softly when you are
    standing next to it.

5. Use Decoy Trails.
    Plants a fake hot cell 12 blocks ahead of you, which lives for one
    in-game day, plus a snare that slows nearby Warband members. Point it
    down the road you want them to take, then step aside.

6. Use the Tracker's Spyglass.
    Outlines every Scout within 48 blocks for 5 seconds. 30 second cooldown.


----------------------------------------------------------------
 ITEMS AND BLOCK
----------------------------------------------------------------

Ward Post (block)
  Craft: 1 Cloak Fragment + 5 Stone + 1 Torch (shaped, see below)
    F
    SBS
    SSS
  Suppresses the addon within 24 blocks. Emits light level 7.

Decoy Trail (consumable, stacks to 16)
  Craft (shapeless): 1 Cloak Fragment + 2 String + 1 Slimeball -> 2
  Plants a false hot cell 12 blocks ahead for 1 in-game day and snares
  nearby ambushers.

Tracker's Spyglass (durable, 250 uses)
  Craft (shapeless): 1 Vanilla Spyglass + 1 Cloak Fragment +
                     1 Amethyst Shard + 1 Glowstone Dust
  Reveals every Scout within 48 blocks for 5 seconds, 30 second cooldown.
  Loses one durability per use, so it survives 250 uses.

Scout's Cloak Fragment (crafting material)
  Dropped by Scouts (1-2, boosted by Looting). Used in all three recipes
  above, so killing Scouts is what arms you.

Everything crafts at a normal crafting table and appears in a "Trailwatchers"
creative group.


----------------------------------------------------------------
 SAFETY AND FAIRNESS
----------------------------------------------------------------

The addon will never target or track a player who is:

  - in Creative or Spectator mode
  - in the world's first 3 in-game days
  - below Y=0
  - in the Nether or the End

Ambushes are capped at one active and one pending per player, with a one
in-game day cooldown after the previous one resolves. Warbands never
include creepers, so an ambush cannot blow up your base.

Performance limits: the heatmap is sampled once per second per player but
only written to disk every 5 seconds (and immediately when you log out);
spawn logic only runs at dusk; hard caps of 4 Scouts and 1 Warband per
player, plus a global cap of 24 loose Scouts. Every entity is
validity-checked before being touched.

All data is tracked per player, so the addon is multiplayer safe.


----------------------------------------------------------------
 THE ACTION BAR
----------------------------------------------------------------

When something is watching you, the action bar tells you:

  "2 Scouts are watching your trail."   a Scout has line of sight on you
  "A Scout is cornered and fighting!"   you hit one and it turned on you
  "Something is gathering on your route." a report is queued, warband pending
  "A warband is on your road."           the warband is live and hunting
  "They have you. Run."                  the 15-second warning has expired

Urgent messages always win over the passive readout, so you will not miss
a horn for the sake of a status line.


----------------------------------------------------------------
 COMMANDS
----------------------------------------------------------------

/scriptevent trail:toggle        turn ambushes on/off
/scriptevent trail:debug         toggle diagnostic logging in chat
/scriptevent trail:status        show current state
/scriptevent trail:heat          list your 10 hottest cells (says why if none)
/scriptevent trail:heatadd       add heat to the cell you are standing in
/scriptevent trail:night         jump to dusk and run the dusk pass now
/scriptevent trail:spawnscout    jump to dusk and spawn Scouts on your routes
/scriptevent trail:clearambush   remove all current ambushers
/scriptevent trail:give          give yourself one of everything

You do NOT need to summon a Scout to test it. trail:spawnscout does the real
thing: it moves the clock to dusk and runs the actual spawn logic against your
real routes, so what you see is genuine behaviour rather than a prop.

If you do use /summon trail:scout anyway, that works too - the addon adopts
any Scout it finds in the world (by its type_family) and starts tracking it,
so it will observe and report exactly like a spawned one.

Give commands:

  /give @s trail:cloak_fragment 8
  /give @s trail:decoy_trail 4
  /give @s trail:trackers_spyglass 1
  /give @s trail:ward_post 8


----------------------------------------------------------------
 TUNING
----------------------------------------------------------------

Every gameplay constant lives in one file:

  Trailwatchers_BP/scripts/config.js

Heat rates, decay, Scout observation time, Warband size, light thresholds,
cooldowns and radii are all there. Edit and re-zip to rebalance.


----------------------------------------------------------------
 TECHNICAL
----------------------------------------------------------------

Built for Minecraft Bedrock 1.26.50+ using stable @minecraft/server 2.10.0.
No experimental toggles are required.

  Trailwatchers_BP  behavior + script module
  Trailwatchers_RP  resources (model, textures, particles, sounds)

The two packs are linked by manifest dependencies; install them together.


----------------------------------------------------------------
 TROUBLESHOOTING
----------------------------------------------------------------

Nothing happens at all
  Confirm BOTH packs are enabled on the world. The behavior pack alone will
  not render the Scout, and the resource pack alone will not run any logic.

No Scouts ever appear
  They need a route first. Walk a few hundred blocks in Survival - heat
  accrues at 1 point per second per cell, and dusk spawning needs at least
  one established hot cell. Check /scriptevent trail:heat first, or use
  /scriptevent trail:heatadd to seed the cell you are standing in.

  Then run /scriptevent trail:spawnscout. That jumps the clock to dusk and
  runs the real spawn logic immediately, so you can confirm Scouts appear
  without waiting for a natural dusk.

  Note that Scouts only spawn AT DUSK (time 11500-13200). If you skip to
  night with a command or sleep in a bed, you may miss the window entirely.
  They also despawn in daylight, by design.

  A Scout spawned on top of you will flee rather than watch - it keeps its
  distance when a player is within 8 blocks. That is intended. Hit it and
  it will turn and fight.

Scouts appear but never ambush
  A Scout needs 40 seconds of actual line of sight. If you keep it at more
  than 48 blocks, or break its sightline, it never reports. Check with
  /scriptevent trail:status, and /scriptevent trail:debug for logging.

Nothing spawns anywhere near my base
  That is intended - cells within 20 blocks of your spawn count at only 25%
  weight, so the addon targets travel routes, not your home.

You want it off for a while
  /scriptevent trail:toggle
