JoshyGnomes v0.1.30  --  a BepInEx mod for Burglin' Gnomes
============================================================================

WHAT IT DOES
------------
  SETTINGS PANEL
  * Press F1 in game for a JoshyGnomes settings panel. Click the toggles,
    drag the sliders, and click the key row to rebind the freeze key.
    Changes apply straight away and are saved to the .cfg for you.

  ROUND TIMER
  * A clock icon and the REAL time remaining as MM:SS, permanently in the
    TOP-RIGHT corner of the screen. Your task list is left exactly as the
    game made it.
  * The HOST can press F10 to FREEZE the timer. While frozen the countdown
    stops, the round can never end on the time limit, and the text blinks
    BLUE once a second so you can tell it is deliberate.
  * The freeze stays on across rounds until the host turns it back off.
  * The freeze key can be set in the settings panel (F1) or the .cfg file.

  STOCKPILE MESSAGES
  * A message whenever the stockpile gains resources -- for example when Bob
    hauls something home. Reads "Received 2 clonk -- now 8/10", using the
    same names and caps you see in the stockpile.

  TASK MESSAGES
  * A line at the bottom of the screen when part of a task is completed,
    when the number of completed tasks goes up, and when everything is done.

  DEAD PLAYER LIST
  * The list of dead players -- heading and all -- is shown to EVERYONE as
    soon as anyone is dead, instead of only to players who are dead
    themselves.
  * Names are colored by whether CPR can still save them: WHITE if they can
    be revived, RED if they cannot. Note that the game will still LET someone
    perform CPR on a red one -- it just can never work.
  * TIED-UP players are listed too, colored by where they are: MICROWAVE
    yellow, OVEN orange, FRIDGE dark blue, FISH TANK light blue, anywhere
    else gray. If one dies in there, the name fades to the usual white/red.

  BOB
  * Bob -- the statue that hauls stolen goods out of the yards -- shown under
    the round timer, top right. The "Bob" button in the F1 panel picks how:
        3D           -- his real model in its own colors
        FLAT         -- the same model as a flat grey shape with a black border
        STICK FIGURE -- a red/green figure shaped like Bob (belly and all):
                        red when idle, green when busy
        OFF          -- nothing
  * 3D and Flat play the game's own animations at the game's own speed:
    standing when he has nothing to do, walking when he goes to fetch
    something, arms raised when he carries it home.
  * Pick FRONT or SIDE view in the F1 panel ("Bob view").
        FRONT -- he walks toward you going out to an item, and away from
                 you carrying it home
        SIDE  -- he walks right going out, and left carrying it home
  * The item he is heading for is shown ahead of him (on the ground in front
    in Front view, to his right in Side view), and the one he is carrying
    floats over his head. Everyone sees the same item -- the host's mod tells
    the others which one he picked. "Bob's item" in the F1 panel picks how:
    OUTLINE (just its outline), ITEM (the item itself), or OFF.
  * He sits tucked right under the timer; picking something up slides him
    down to make room for it.
  * QUEUE COUNT: "Queue: N" under Bob shows how many stolen items are still
    waiting for him -- not counting the one he is heading for or carrying.
    Everyone sees the host's count. Switch it off with "Bob's queue count"
    in the F1 panel.
  * PICKUP FIX (host only, on by default): Bob now also fetches items the
    game itself misses -- like toilet paper lying on its side. Switch it off
    with "Bob pickup fix (host)" in the F1 panel.
  * RETRIES (host only): if Bob sets off for an item but can't get to it,
    the game normally drops it for good. Now he tries again up to 3 more
    times, 20 seconds apart, then gives up. Only items the game itself gave
    him are retried -- nothing he isn't meant to take.
  * BACK OUTSIDE (host only): if an item goes back indoors while Bob is
    after it, he no longer forgets it. Once it is outside again (and under
    open sky) he is sent for it again. That trip doesn't use up a retry.
  * UNSTICK (host only): when Bob grabs something stuck in a player or a
    wall -- the fork, the plunger -- it now actually comes loose and goes
    home with him, so it gets delivered. (The game has this built in but
    never switches it on.)

  WHO LEFT
  * A message when a player is kicked, drops, or quits. The game itself
    announces nothing at all. Everyone running the mod sees the same thing,
    including whether it was a kick.

NOTE: freezing the timer also freezes passive karma gain, the gnomium spawn
rate, and the time of day -- all three are driven by round progress.


REQUIREMENTS
------------
  * Burglin' Gnomes on Steam
  * BepInEx 5.4.23.5 (BepInExPack 5.4.2305) -- install it from Thunderstore
    Mod Manager, or from https://thunderstore.io/c/burglin-gnomes/


EASIEST INSTALL  (recommended)
------------------------------
  Don't use this zip. Instead grab the updater from

      https://files.snapzfs.com/Burglin_Gnomes_Game_Files/

  Save JoshyGnomes-Update.bat into your  BepInEx\plugins  folder and
  double-click it. It fetches the newest version by itself, and keeps itself
  up to date too -- so you only ever download it once.


MANUAL INSTALL
--------------
  1. Find your plugins folder.
       Thunderstore Mod Manager:
         %AppData%\Thunderstore Mod Manager\DataFolder\BurglinGnomes\
             profiles\<YourProfile>\BepInEx\plugins\
       Manual BepInEx install:
         <Steam>\steamapps\common\Burglin' Gnomes\BepInEx\plugins\
  2. Delete any existing  JoshyGnomes  folder in there.
  3. Copy the  JoshyGnomes  folder from this zip into  plugins\  so you end
     up with  ...\BepInEx\plugins\JoshyGnomes\JoshyGnomes.dll
  4. Launch the game modded (Thunderstore Mod Manager -> "Start modded").


CONFIGURATION
-------------
  After running the game once with the mod, edit

      BepInEx\config\josh.burglingnomes.joshygnomes.cfg

  [Timer]
    Frozen              true/false  -- host's freeze state (persists)
    FreezeKey           default F10 -- any Input System key name
    FreezeModifier      default None -- e.g. LeftCtrl, for a key combo
    ShowTimer           default true -- the top-right MM:SS readout
    TimerScale          default 1.0 -- MULTIPLE of its normal size
    ShowClockIcon       default true -- show the clock icon beside the time

  [Multiplayer]
    RequireModOnAllPlayers  default TRUE -- kick players without the mod
    VersionCheckSeconds     default 10 -- grace period before that kick

  [Tasks]
    Notifications       default true -- task progress / count / all-complete
    ResourceMessages    default true -- "Received 2 clonk -- now 8/10"

  [Hud]
    MessageLines        default 4   -- how many messages on screen at once
    MessageHoldSeconds  default 4   -- before each fades out over a second
    MessageFontSize     default 30  -- scales with the window, not raw pixels
    MessageBottomOffset default 260 -- raise this if messages hit the hotbar
    DeadListForEveryone default true -- show the dead list to living players
    DeadListColorByRevivable  default true -- white/red by CPR eligibility
    DeadListShowTied    default true -- tied-up players on the dead list
    BobStyle            default Model -- Model (3D), Flat, Stick, or Off
    BobIndicatorHeight  default 130 -- scales with the window, not raw pixels
    BobWalkFps          default 8   -- his step rate at full speed
    BobModelView        default Front -- Front or Side
    BobModelBackground  default false -- dark panel behind the model
    BobCarriedItem      default Outline -- items he fetches/carries: Outline, Item, Off
    BobItemOutlineColor default #FFFFFF -- the outline's color
    BobModelLight       default 1.0 -- extra light on him; 0 = level light only
    BobQueueCount       default true -- "Queue: N" under Bob

  [Darts]
    Range               default 66  -- how far a blowgun dart can hit (game: 22)

  [Bob]
    PickupFix           default true -- HOST: Bob also fetches off-centre items
    Retries             default 3   -- HOST: extra tries for items he can't reach; 0 = off
    RetryDelaySeconds   default 20  -- HOST: wait between those tries
    UnstickOnGrab       default true -- HOST: stuck forks/plungers come loose for Bob
    AnnouncePlayersLeaving  default true -- "X left the game" / "X was kicked"

  [Menu]
    OpenKey             default F1 -- opens the settings panel
    Scale               default 1.0 -- size of that panel

  [Bindings]
    RestoreGameDefaultsOnce  default false -- see the note below

  [Settings]
    MapMenuStructure    default true -- log the settings menu layout once

  [Probe]
    LogOnStartup        default true -- log engine/game info at load
    DumpSessionOnF9     default true -- F9 dumps session state to the log


MULTIPLAYER  --  EVERYONE NEEDS THE SAME VERSION (as of v0.1.15)
----------------------------------------------------------------
  The host now kicks anyone who joins without JoshyGnomes, or with a
  different version of it, and tells the lobby who it was. Grab the updater
  from files.snapzfs.com and everyone stays in step automatically.

  This is enforced BY THE HOST. So:
    * If the host is out of date, everyone else gets kicked -- including
      people who did update. Whoever hosts should update first.
    * A host WITHOUT the mod kicks nobody; the check simply never runs.

  To go back to the old "optional extra" behaviour, set

      [Multiplayer]
      RequireModOnAllPlayers = false

  With that off nothing about the mod can affect a player who doesn't have
  it: no custom network prefabs, no RPCs, no network variables. The freeze
  still reaches them (the game's own clock stops), they just don't see the
  MM:SS readout, messages, Bob or the dead-list colors.

TROUBLESHOOTING
---------------
  Nothing appears at all
     Check  BepInEx\LogOutput.log  for a line reading
     "JoshyGnomes v0.1.30 loaded." If it is missing, BepInEx itself is not
     loading -- verify you launched modded.

  Messages overlap the inventory hotbar
     Raise  Hud/MessageBottomOffset. It is in 1920x1080 units and scales
     with the window.

  Your key bindings look wrong
     Earlier versions added a "Freeze Timer" row to the game's own bindings
     screen. That is GONE as of v0.1.8. If your bindings still look off, set

         [Menu]
    OpenKey             default F1 -- opens the settings panel
    Scale               default 1.0 -- size of that panel

  [Bindings]
         RestoreGameDefaultsOnce = true

     then launch and open the bindings screen once. It resets the game's key
     bindings to their defaults and switches itself back off. Only key
     bindings are touched -- graphics, audio and voice are left alone.


  v0.1.30 -- tied-up players now show on the dead list, colored by where
  they are: MICROWAVE yellow, OVEN orange, FRIDGE dark blue, FISH TANK light
  blue, anywhere else gray. If they die in there the name fades to white
  (CPR can save them) or red (it can't). Toggle: "Tied players on list" in
  F1. The fish tank never kills, so its names never go red.

  v0.1.29 -- blowgun darts now reach 66 instead of 22 (still dead straight,
  no drop). It is the SHOOTER's setting that counts: "Dart range" in F1.
  Bob also goes back for an item that went indoors and came back out --
  before, he ignored it for the rest of the round (a can on the lawn).

  v0.1.28 -- "Queue: N" under Bob: how many stolen items are still waiting
  for him after the one he is on. Toggle: "Bob's queue count" in F1.

  v0.1.27 -- Bob can now really take a fork that is stuck in you: it comes
  out and he carries it home, instead of walking back empty-handed. Note: if a
  resource is already full (e.g. metal 25/25) a delivery still gives nothing --
  that is the game's storage cap.

  v0.1.26 -- smoother pickup: the item stays in front of Bob while he stands
  by it, then rises into his hands as he turns round (it used to vanish while
  he stood there). Bob now retries items he couldn't reach, up to 3 more
  times, before giving up (host only; [Bob] Retries in the config).

  v0.1.25 -- the item ahead of Bob now only shows while he is actually
  walking to it (it used to appear at the start of a round while he stood at
  the hut). The host's log now says why Bob skips an item: what is over it,
  that he couldn't reach it, or that it is still waiting in his queue.

  v0.1.24 -- the item Bob is running to fetch now actually shows (0.1.23
  looked for it in the wrong place). Bob now also picks up toilet paper lying
  on its side: the game only checks straight down through the roll's end, so
  it missed it -- the host's mod now checks through the middle as well.

  v0.1.23 -- Bob stays tucked in the top-right corner at any size. The item
  he is running to fetch is now shown ahead of him, the same for everyone. New
  FLAT look (grey with a black border), and the stick figure is now shaped
  like Bob. The F1 panel's "Bob" button now cycles Off / 3D / Flat / Stick
  figure, replacing the two old Bob on/off switches -- if you had turned Bob
  off before, turn him off again there.

  v0.1.22 -- the little Bob's legs now move at the same rate as the real
  Bob's in the level. It copies his real animation inputs every frame instead
  of an estimate.

  v0.1.21 -- Bob's view is now Front OR Side (picked in the F1 panel), no
  more side-by-side. He faces the way he's going: toward you / right heading
  out to an item, away from you / left carrying it home. The item he carries
  can be shown as an outline, as the item itself in its real colors, or not
  at all ("Bob's item" in the F1 panel).

  v0.1.20 -- Bob is now his real 3D model instead of a crosswalk figure,
  walking and carrying with the game's own animations, with an outline of the
  item he's carrying above his head. Front and side views are both shown for
  now while we pick one. The crosswalk figure stays as a fallback.

  v0.1.19 -- Bob's figure and the round clock now disappear while you are
  between levels. The game keeps reporting "in round" for the whole vortex
  ride home, so Bob really was still walking around the abandoned level, and
  the clock really was still counting down a round that had already ended.
  Both now hide for the trip in each direction. Bob also no longer reads a
  teleport as a sprint, and no longer flashes green for a moment at the start
  of the next round. Removed a leftover settings-menu probe that was scanning
  every object in the game twice a second, forever, hunting for widget types
  this game does not have.
  v0.1.17 -- stockpile messages now name what the resources came out of, and
  give the plain word alongside the gnome one:
      Received 3 plasto (plastic) from Bear Toy   --   now 8/10
  These are now sent by the host, so the HOST needs the mod for anyone to see
  them (previously a client could work them out alone, but it had no way to
  know what the resources came from).

  v0.1.16 -- spelling only: "color" rather than "colour" throughout.

  v0.1.15 -- everyone in the lobby now needs the same version of the mod. The
  host kicks anyone joining without it or on a different version, and says who
  it was. Set Multiplayer/RequireModOnAllPlayers=false for the old behaviour.
  Also: when the stockpile is full, deliveries that no longer fit are reported
  as discarded -- the game destroys that loot silently, so it is worth knowing.

  v0.1.14 -- two stockpile-message fixes. Logging in no longer dumps a screenful
  of "Received ..." lines: the game reloads your saved stockpile a moment after
  load, and that was being reported as a fresh delivery. Messages now only
  appear during a round. Resource names also no longer read "no translation".

  v0.1.13 -- the stockpile messages from 0.1.12 never actually appeared. They
  were watching the house's resource store, but Bob's deliveries go into a
  different inventory entirely, so nothing ever fired. Now watching the right
  one. The "/10" is your stack cap, which is what house upgrades raise.

  v0.1.12 -- added stockpile messages: when resources come in you get a line
  saying how much you gained, your new total, and your cap. Also, a body that
  fell out of the world now shows RED on the dead list -- falling off the edge
  kills you intact, so nothing was damaged and it used to claim you were
  revivable while your body sat somewhere nobody could reach.

  v0.1.11 -- the dead-list colors now show on your OWN screen while you are
  dead. They were correct for everyone else all along, but a dead player's list
  was never colored at all -- and the game's default color is white, which
  looks exactly like a deliberate "can be revived".

  v0.1.10 -- fixed the dead-list colors. They used the check that decides
  whether CPR can be STARTED, not whether it can work -- so a decapitated gnome
  showed white, let someone perform CPR, and could never actually be revived.
  Now uses the condition the revive itself tests. Also removed a 0.2s stutter at
  the start of each round.

  v0.1.9 -- added a JoshyGnomes settings panel, opened with F1. It is drawn
  entirely by the mod, so it cannot disturb the game's own menus the way the
  bindings row did. The freeze key now lives there.

  v0.1.8 -- the "Freeze Timer" row is no longer added to the game's bindings
  screen. It disturbed that screen more than once and only duplicated what
  Timer/FreezeKey already does. The freeze key itself is unchanged. Added
  Bindings/RestoreGameDefaultsOnce to put the game's bindings back to defaults
  if they were affected. A JoshyGnomes settings page is being worked on, and
  the freeze key will move there.

  v0.1.7 -- Bob's figure moved from the bottom-right up under the round timer,
  clear of the text the game puts along the bottom during play. Dead-list names
  are now white or red depending on whether CPR can still save them. The Freeze
  Timer row shows a proper key graphic when the game has one for that key.

  v0.1.6 -- the Freeze Timer row now goes in the LEFT column (it was landing
  on the right because both columns hold nine rows and the pick was arbitrary),
  and its key name no longer auto-sizes into oversized text. Also logs the
  layout of the settings menu once, as groundwork for a JoshyGnomes tab.

  v0.1.5 -- the dead-player list now shows its "DEAD" heading to living
  players too, not just a bare column of names. The frozen clock now blinks
  white/BLUE instead of white/red. The bindings-menu row is OFF by default:
  it could disturb the game's own bindings screen, and it only duplicated a
  setting the .cfg already has.

  v0.1.4 -- Bob's icon now follows his real animation state instead of only
  "is he holding something". Walking out to FETCH an item now registers -- it
  did not before, so the icon stayed red until the exact moment he picked
  something up. He raises his arms while carrying, matching what he does in
  game, and his legs move at his actual speed.

  v0.1.3 -- Bob became a crosswalk figure with a walking animation, and taller.

  v0.1.2 -- the round timer moved to the top-right corner on its own HUD layer,
  in the game's font, and no longer touches the task list (v0.1.1 wrote into it
  and the text wrapped to two lines). Messages moved clear of the inventory bar
  and use the game's font too. The "Freeze Timer" bindings row is now the LAST
  row of its section with the layout rebuilt, so it is actually visible.
  Not yet tested in a real multiplayer lobby.
