Skip to content

tsitu/MH-Tools

Repository files navigation

🐭 MH Tools · GitHub Pages

Suite of JavaScript tools for the browser game MouseHunt.

Feel free to post your questions, comments, or concerns on the forum thread, or right here on GitHub. Alternatively, join the discussion on Discord's #community-tools channel for faster responses.

📖 Table of Contents

Instructions

💭 General Tips

Several tools make use of mottie's tablesorter plugin, which includes useful additional features such as multi-column sorting with Shift or special characters for filtering.

We recommend installing the MHCT extension if you have not already. It records valuable information from active hunts only. Virtually all data for recent updates has been sourced from MHCT's publicly accessible database backups.

Disclaimer: Newer tools like 'Crafting Wizard' and 'Trap Setup Powers' may be incompatible with outdated or feature-constrained browsers such as Internet Explorer, Opera Mini, Samsung Internet, and Blackberry Browser. Older tools may also become incompatible with these browsers at any point.

🔖 Bookmarklets

Bookmarklets are pieces of JavaScript code that are saved as a bookmark in the user's browser, enabling them to interact with webpages on the fly. We provide 9 different bookmarklets: Catch Rate Estimator, Map Solver, Best Setup: Load Items, Best Setup: Fields, Marketplace Analyzer, Crown Solver, Crafting Wizard, Powers: Worksheet and the all-in-one Auto-Loader. They are each available on their corresponding tool's page.

Using the Auto-Loader is recommended because it automatically grabs the latest version of each bookmarklet without having to manually update.

You must be on the official mousehuntgame.com website for these bookmarklets to work. Same-origin policy blocks access to DOM elements and requests to server endpoints while playing in Facebook's <iframe>.

Note: Mobile browsers can vary in their approach to accessing bookmarklets. For example, in Chrome for Android, you must type the first few characters of a bookmarklet's name in the address bar and click it from there for the code to take effect.

Bookmarklet Functionality
CRE Automatically fills in the Catch Rate Estimator with your location, sublocation, cheese, charm, weapon, base, and more
Setup: Load Items Automatically loads your owned weapons, bases, and charms into Best Setup
Setup: Fields Automatically fills in Best Setup with your location, sublocation, cheese, charm, and more
Analyzer Generates a pop-up dialog that allows you to download your entire Marketplace transaction history and send it to the tool
Map Automatically fills in the Map Solver's mouse name textarea with all of the remaining uncaught mice on your Active Map
Crown Generates a pop-up dialog that allows you to select the crown types and corresponding catch cutoff values that you'd like to send over to the Crown Solver

Note: Favorited mice will be prioritized in the resulting list
Crafting Automatically loads your 'Crafting Table' materials into Crafting Wizard
Powers: Worksheet Generates a pop-up dialog that allows you to select a mouse group/subgroup to target with your current trap setup
Loader Generates a pop-up dialog that gives you access to the latest versions of each bookmarklet

§ Browser Installation Tips

On desktop, drag the blue bookmarklet link to your browser's bookmarks bar. On mobile, first tap the corresponding clipboard icon to copy the bookmarklet code to your clipboard, then paste it into the URL field of a new bookmark. The following instructions illustrate the basic concepts for 4 major browsers - these concepts should apply to other browsers as well (including mobile), but specific steps may vary.


Chrome
Google Chrome

  1. Bookmark an arbitrary page and give it a memorable name like 'CRE' or 'Auto-Loader'
  2. Copy the bookmarklet code by right-clicking its link and selecting Copy link address
  3. Right-click on your newly created bookmark and select Edit...
  4. Paste the bookmarklet code into the URL field and hit Save


Firefox
Mozilla Firefox

  1. Right-click on the bookmarklet link, select Bookmark This Link, and name it accordingly


Edge Edge
Microsoft Edge / Internet Explorer

  1. Bookmark an arbitrary page and give it a memorable name like 'CRE' or 'Auto-Loader'
  2. Copy the bookmarklet code by right-clicking its link and selecting Copy link
  3. Go to 'Hub -> Favorites', right-click on your newly created bookmark and click Edit URL
  4. Paste the bookmarklet code into the text field and hit Enter to save
  5. If that doesn't work, there is a third-party application called EdgeManage that claims to add a lot of missing features for managing Favorites - please use at your own discretion
  6. Internet Explorer 11 allows you to drag bookmarklets directly to your favorites bar, or right-click and choose Add to favorites. However, it doesn't seem to support certain JavaScript features that enable the bookmarklets to run properly


Safari
Apple Safari

  1. Bookmark an arbitrary page and give it a memorable name
  2. Right-click on the bookmarklet link and select Copy Link
  3. Right-click on the newly created bookmark, select Edit Address, paste into the text box, and click Done

Calculates catch rate estimates along with points, gold, minimum luck and more.

Bookmarklet: Run the CRE bookmarklet from basically any page on the MH website.

Descriptor Per Sum or Average (bottom row)
Attraction Rate Mouse Sum for this setup
Catch Rate Mouse Average for this setup
Catches (AR * CR per 100 hunts) Mouse Sum per 100 hunts
Gold Catch Average per hunt
Points Catch Average per hunt
Tourney Points Catch Average per hunt
Min Luck Mouse Highest for this particular setup
Rank Catch Per hunt

§ New Formula

In September of 2020, a new catch rate formula was implemented into MH Tools. For years, the classic 3-eff formula served as our closest approximation of MouseHunt's true catch rate mechanics. This formula was regularly challenged, thanks to community reports of misses using setups exceeding predicted "minimum luck" values (ML) that purported to guarantee a mouse's catch. One especially significant challenge came recently, when HitGrab stated in a Feedback Friday episode that weapon type effectiveness is capped at 140%, instead of the assumed 200%.

In light of these discrepancies, Discord user mmalks ran a regression analysis on open-source data from MHCT and posted his results, which appeared to correct many of the "off-by-1" MLs that the classic formula generated.

After observing the increased accuracy of mmalks' new catch rate and ML formulas over an extended period of time, we have decided to incorporate them into the tools. Further research is being conducted to improve on them, and catch rate estimates are liable to change as we inch closer to a fully complete model of MH's catch logic. With that said, please continue to report misses at or above displayed minimum luck values.

Classic catch rate formula: CR = \frac{E * T + \ (3 - min(2, E)) * (min(2, E) * L)^{2}}{E * T + \ M}

New catch rate formula: CR = \frac{E * T + \ 2 * (floor(min(1.4, E) * L))^{2}}{E * T + \ M}

Classic minimum luck formula: ML = \ceil(\frac{\sqrt{\frac{M}{3 - min(2, E)}}}{min(2, E)})

New minimum luck formula:

  • E = Weapon Type Effectiveness %
  • T = Trap Power
  • L = Trap Luck
  • M = Mouse Power

For minimum luck, there's an extra wrinkle due to floating point arithmetic errors in MouseHunt. To match MouseHunt in detail, all of the above formulas must be computed using 64-bit floating point arithmetic. Then, check if the minimum luck is actually enough to guarantee 100% catch rate (i.e. if 2 * floor(min(1.4, E) * L)^2 >= M); if not, increment the minluck by 1. This is described further by beeejk's post.

§ Sample Size Score

An indicator of the quality and accuracy of a specific setup's data based on its sample size and the number of mice in its attraction pool. Setups are separated by locations, sublocations, cheeses and occasionally charms (if they have attraction-altering effects i.e. Warpath Warrior Charm in Waves 1-3 of Fiery Warpath). If you have a charm selected that doesn't affect a setup's mouse population pool, its corresponding "No Charm" data is displayed, since they are equivalent.

Previously, the tool displayed a flat sample size number with a rating assigned to it, which looked like Sample Size: 300 (bad) or Sample Size: 100000 (excellent). This format was misleading because it didn't encode important contextual information. The current scoring scheme takes into account factors such as number of mice in a particular setup, 95% confidence levels, and relative margins of error. It combines and normalizes these factors into a single number, capped at 100.

Note: Certain setups may have low scores or even no sample size data attached to them. This could be because: (1) the data was extracted from HornTracker before we decided to start keeping track of sample sizes, (2) there aren't enough recorded hunts for that setup in MHCT, (3) our population fetching scripts need to be re-run.

§ Special Catch Rate Effects

The following special effects are included in catch rate calculations for both CRE and Best Setup

  • Final Catch Rate Modifiers

    Name Modifier
    Anniversary Weapon variants Up to 10% increased catch rate, i.e. CR + (0.1 * (1 - CR))
    Bounty Hunter 100% catch rate with Sheriff's Badge Charm equipped
    Fort Rox · Up to 50% increased catch rate when upgrades are level 2 or 3
    · 100% catch rate on Nightmancer and Nightfire when upgrades are level 3
    · TODO: Mage Tower effect is not yet implemented
    Ultimate Anchor Charm 100% catch rate while on a dive in Sunken City
    Ultimate Charm 100% catch rate everywhere
    Zugzwang's Ultimate Move Up to 50% increased catch rate in Seasonal Garden & Zugzwang's Tower when amplifier > 0%
    Zurreal the Eternal 0% catch rate without Zurreal's Folly equipped
  • Special Bonuses & Effects

    Name Effect
    Champion Charm +2/3/4 Luck when equipped with Bronze/Silver/Golden Tournament Base
    Dragonbane Charm variants +300/600/900/1200% Power Bonus on Dragon-type mice
    EMP400 Charm +25000 Power with Fusion Fondue armed
    Golem Guardian variants · +6 Luck when equipped with Glowing Golem Guardian Base
    · Charge levels are set in CRE and carry over to Best Setup
    Physical Brace Base +25% Power Bonus when equipped with a Physical weapon
    Polluted Charm variants +4/6/10/15 Luck when equipped with Polluted Base or Refined Pollutinum Base
    Soiled & Living Grove Base · +100 Power, +3% Power Bonus, +5% Attraction Bonus, +4 Luck when equipped with Growth Charm
    · +300 Power, +8% Power Bonus, +20% Attraction Bonus, +9 Luck when equipped with Wild Growth Charm
    Snowball Charm variants +20% Power Bonus when equipped with Festive weapons
    Spellbook Charm +500 Power and +8% Power Bonus when equipped with Spellbook Base
    Spooky Charm variants +20% Power Bonus when equipped with Halloween weapons
  • Location Specific Effects

    Location Effect
    Claw Shot City Claw Shot Base gives +1000 Power when equipped with a S.L.A.C. variant, and +2500 Power when equipped with both a S.L.A.C. variant and a Cactus Charm variant
    Fiery Warpath · Flamebane Charm gives +150 Power
    · Warden Slayer Trap gives +2500 Power and +2500% Power Bonus when equipped in Wave 4 or Portal
    · Super Warpath Charms give +50 Power on corresponding groups
    · TODO: Warpath Thrasher effect is not yet implemented
    Fort Rox Nightlight Charm gives +1/3/5/7/9/12/15% Power Bonus depending on the stage of night
    Gnawnian Express Station Supply Grabber, Bandit Deflector, and Engine Doubler give +1500 Power in Supply Depot, Raider River, and Daredevil Canyon respectively
    Iceberg & Slushy Shoreline · Steam Laser Mk. I gives +1750 Power and +3 Luck
    · Steam Laser Mk. II gives +1250 Power and +2 Luck
    · Steam Laser Mk. III gives +1500 Power and +2 Luck
    · Deep Freeze Base and Ultimate Iceberg Base give +665 Power and +9 Luck in Icewing's Lair, Hidden Depths, and The Deep Lair
    Jungle of Dread · Dreaded Totem Trap gives +8500 Power
    · Dreaded Charm gives +300% Power Bonus
    Sand Crypts Salt level applies a logarithmic function to decrease mouse power for King Grub & King Scarab
    Seasonal Garden · Seasonal Base gives +18% Power Bonus
    · Soul Harvester and Terrifying Spider Trap give +10 Luck during Fall
    · Chesla's Revenge has a 12.5% chance to proc an additional charge
    · TODO: Sandcastle Shard's effect is not implemented due to current/max amp requirement
    Sunken City Depth Charge Base gives +1000 Power while on a dive
    Town of Digby · +30% Power Bonus if Limelight cheese and Mining Charm are equipped
    · TODO: Only against Digby Dirt Dwellers plus increased BBB/I-BB chance?
    Toxic Spill · Washboard Base gives +5% Power Bonus and +5 Luck
    · Soap Charm gives +5000 Power and +10 Luck
    · Super Soap Charm gives +8000 Power and +12 Luck
    Tribal Isles · Tiki Base gives +6 Luck
    · Tribe-specific power charms (Derr/Nerg/Elub) give +600 Power and +5% Power Bonus in their respective locations
    Whisker Woods Rift Taunting Charm only applies Rift Set bonuses on minibosses and MBW
    Zugzwang's Tower · Obvious Ambush and Blackstone Pass give +1800 Power on corresponding side, -2400 Power on opposite side
    · Pawn Pinchers give +10920 Power on corresponding Pawn, -60 Power and -5 Luck on opposite Pawn
    · Rook Crumble Charm gives +300% Power Bonus on Rook mice

Calculates ideal specific locations to hunt for a given list of mice. Based on Chad's and Olaf's solvers.

Bookmarklet: Run the Map bookmarklet from the "Active Map - Mice" section of the UI.

Copy and paste mice from maps, or type names leaving a line break between each. Press Enter to autocomplete and Tab to cycle through autocomplete suggestions. Additionally, autocomplete can be toggled on/off (requires a page refresh to take effect).

"Fused" cheeses (e.g. Gouda/Brie/Swiss) will often show up in results. This indicates that attraction proportions from the underlined cheese has been extrapolated due to low sample sizes.

Type of Attraction Rate Description
Raw Shown for individual mice
Total Sum for a specific location, sublocation, cheese, and charm
Weighted Same as Total AR, but with baseline cheese attraction rates factored in

§ Cheese Filters

Cheese filters allow you to easily hide certain cheeses from the Best Locations table depending on your hunting situation. For example, frugal hunters may want to tick the Magic Essence checkbox to hide costly SB+ derived cheeses.

Filter Category Cheeses
Magic Essence SB+, Moon, Maki, Maki String, Magical String, Magical Rancid Radioactive Blue
Common Brie, Brie String, Cheddar, Gouda, Marble, Marble String, Swiss, Swiss String
Marketplace Crescent, Magical String, Maki, Maki String, Moon, Rancid Radioactive Blue, SB+
Shoppe All four Camemberts, Fishy Fromage, Grilled, Sunrise (separate niche from common?)
Crafted Resonator, Vanilla Stilton, Vengeful Vanilla Stilton, White Cheddar... (many more TBD)
Event (not included) Cupcake Colby, Dumpling, Extra Sweet Cupcake Colby, Marshmallow Monterey, Nian Gao'da, Rewind Raclette, Rockforth, Runny, etc.

Calculates the best trap setup to use for a particular location, sublocation, cheese and/or charm.

Bookmarklet(s): Run the Setup: Load Items bookmarklet on the Camp page and your items will be automatically loaded, ticked, and cached on the Best Setup page. Run the Setup: Fields bookmarklet on basically any page on the MH website and your hunting setup will be automatically loaded into the tool.

To check whether all of your items have properly loaded, you may want to open up the JavaScript console in your browser, both on your MH Camp page and on the Best Setup page. You will then want to compare Number of bases/weapons/charms: # detected values from the former with Bases/Weapons/Charms: # owned / # total from the latter.

'Number of rows to display' is set at 50 by default, with options for 100, 500, 1000, or All rows. When running calculations with close to the maximum number of weapons and bases selected, keep the number of rows low if possible to avoid excessive CPU/RAM usage.


Displays all of your marketplace transactions along with some useful aggregations.

Bookmarklet: Run the Analyzer bookmarklet, and click 'Send to Tool' once you have gathered enough transactions using 'Fetch'.

Type Description
Transaction Gold spent or received in a single trade
Amount Total spent or received for an item or action (includes tariffs)
Price Amount ÷ Quantity (includes tariffs)
Unit Price Gold spent on a single unit in a transaction (excludes tariffs)
Tariffs 10% of 'Buy' actions (Amount - (Math.floor(Amount ÷ 1.1)))

Calculates the best locations to achieve crowns of given mouse breeds based on number of catches.

Bookmarklet: Run the Crown bookmarklet to automatically populate the a list of mice that are closest to a crown

This spin-off of the Map Solver inspired by vsong factors in the difference between 10/100/500/1000/2500/5000 and the number of catches you currently have for a breed. All else being equal, a mouse that's closer to any given crown is weighted more heavily than one that's further away (e.g. a mouse with 99 catches vs. a mouse with 3).

Type of Crown Progress Description
Raw Shown for individual mice, factors in attraction rate and catches remaining until crown
Total Sum for a specific location, sublocation, cheese, and charm
Weighted Same as Total CP, but with baseline cheese attraction rates factored in

Calculates craftable quantities and missing materials for recipes based on your inventory data.

Bookmarklet: Run the Crafting bookmarklet from Inventory -> Crafting -> Crafting Table. The Recipes and Inventory tables should be automatically populated, with the former being sortable and filterable. Crafting materials are saved in localStorage.


Shows the weapons, bases, and charms that match a specified power range and type. Synergizes with the 'Best Setup: Load Items' bookmarklet to use only items you own.

To understand why this tool exists, we need to take a quick crash course on MouseHunt's game mechanics.

The best formula we have for calculating catch rate and minimum luck was derived in 2011. As you can see, it takes into account several variables: power type effectiveness, trap power, trap luck, and mouse power. Total trap power and luck are easy to calculate, since item and effect stats are present in-game. However, neither mouse powers nor exact type effectiveness values are as easily obtained.

Given the unknowns, you may wonder how folks have determined these hidden mouse power numbers with such precision in the past. Kristian G wrote an essential guide on this process a few years back - please read it. The TL;DR gist is that we equip different weapons, bases, and charms to attain a specific total trap power. Then, we look at the description page of the mouse we're targeting and note its 'Difficulty' rating. Depending on what that label says and what boundary is targeted (i.e. Challenging/Difficult, Easy/Moderate), we can deduce upper/lower bounds for the mouse's power. Kristian's post goes into much more detail and provides several examples.

With that explained, you may be wondering whether there are tools out there that make this process less tedious. No matter what, we'll have to manually tweak trap setups in-game and refresh mouse pages to glean information from their 'Difficulty' ratings. But, it would be helpful if we could specify a range of desired total trap powers, and have a tool spit out corresponding trap setups. From what I can gather, HornTracker's Trap Combinations was the best tool for this purpose, along with tehhowch's GetPower sheet on MH Reference. Unfortunately, both tools haven't been updated in some time. Thus, they don't include the latest items and effects.

This is where 'Trap Setup Powers' comes in. With this new tool, you can: [1] hone in on one power type at a time, or include all 10 at once (be aware that a large number of power types ticked with a narrow power range will slow down processing by a significant amount), [2] specify a variety of power-altering parameters, and [3] choose whether to use only owned items or all items. In order to take advantage of showing only items you own, run the 'Best Setup: Load Items' bookmarklet before returning to the Powers tool.

§ Worksheet

This supplementary tool provides a mostly automated way to derive many mouse power values at once. Using the 'Powers: Worksheet' bookmarklet on mousehuntgame.com, select a mouse group/subgroup to target with your current trap setup and Rift Set tier. Then, hit 'Go' and a new tab will open with 3 tables: [1] Mouse Powers - displays sortable columns for mouse group/subgroup/name, and all 10 power type effectiveness values along with their respective min/max boundaries (calculated using your total trap power and mouse difficulty ratings), [2] Mouse Details - displays mouse group/subgroup/name as well as gold/points and links to specific Adversaries pages, and [3] Trap History - displays a reverse chronological history of the power types and precise/displayed powers captured from the bookmarklet.

There are several options to refine the 'Mouse Powers' table view. You can tick the checkboxes for the power types you'd like to be shown, select the mouse group/subgroup/name you'd like to filter down to, and then click 'Reload Table' to apply your preferences. 'Save Preferences' stores your settings in localStorage for future sessions. 'Reset Data' clears all worksheet data. It may be prudent to reset data if performance starts to take a noticeable hit, or if some unexpected data corruption occurs.

The recommended way to use this tool is to focus on a couple groups of mice and narrow down each mouse's min/max power ranges using a variety of setups generated by the main Powers tool. Once you're satisfied, copy/paste the entire 'Mouse Powers' table into Google Sheets (it should copy over very cleanly!) for further manual refinement, allowing you to reset the worksheet data.


Provides a convenient way to spin up multiple independent instances of the CRE tool. Each instance is located in its own <iframe> and setups are easily copy-pasted between tabs. Great for quickly comparing setups that are mostly identical.

Keyboard Shortcut Description
Alt + C Copy setup in current tab
Alt + V Paste setup to current tab
Navigate between tabs (when one is highlighted)

Developers

👷 Build and Run

  1. Download Node.js for your operating system

  2. Run npm install to download project dependencies

  3. Build required wisdom/population JSON and minified JS files locally using npm run build

  4. Serve the tools for local testing using npm run serve, which spins up an instance of http-server on port 8000

📋 Populations

To update population data, download a copy of the most recent MHCT database dump from Keybase (refresh the page if it says 'Not found'). Then, import the data into your SQL client of choice (takes around an hour on MySQL Workbench 8.0 with MySQL Server 5.7.24 on Windows 10). Alternatively, consider downloading and running the Docker images. Finally, use commands such as npm run pop:queso (full list in package.json) to write updated populations to CSV files in data/pop-csv, or use npm run pop to fetch them all simultaneously.

If you would like to merge new data into the master branch, feel free to open a pull request - Travis CI will build it automatically and run the build/process-sample-size.js script, which generates sample size score deltas (example). We use this to verify that data is trending towards improvement.

🐁 Mouse Stats

To update mouse related stats (wisdom, gold, points, effectivesnesses), use command npm run mouse-stats to pull the data from Brad's mouse.rip API which is powered by spreadsheets maintained by community members in the Discord.

💈 Coding Style

We use ESLint (config-airbnb-base) configured with Prettier (prettier/recommended) to enforce consistent coding conventions.

This is still a work in progress, along with converting the codebase to align with modern ES2015+ best practices.

Miscellaneous

⬇️ Useful Links

💟 Thanks to...

License

FOSSA Status