mousehunt-utils v1.11.0

🐭️ MouseHunt - MouseHunt Utils

A helper library for MouseHunt userscripts.

Current Version: 1.10.5

Usage

Add the following to your userscript in the header.

// @require https://cdn.jsdelivr.net/npm/mousehunt-utils@1.10.5/mousehunt-utils.js

Your userscript should have a header like this:

// ==UserScript==
// @name         My Userscript
// @description  This is my userscript.
// @require      https://cdn.jsdelivr.net/npm/mousehunt-utils@1.10.5/mousehunt-utils.js
// @match        https://www.mousehuntgame.com/*
// ==/UserScript==

Once you've added the @require line, you can use the functions in the library with no extra setup!

Available functions

Triggers

• onRequest Do something when a request is made.
• onAjaxRequest Do something when a request is made. Deprecated: Use onRequest instead.
• onEvent Do something when an event is triggered.
• onPageChange Do something when the page changes.
• onDialogShow Do something when a popup or overlay shows.
• onDialogHide Do something when a popup or overlay hides.
• onOverlayChange Do something when a popup or overlay changes. Deprecated: Use onDialogShow and onDialogHide instead.
• onTrapChange Do something when a trap component changes, such as the charm or cheese.
• onTravel Do something when the user travels to a new location.

Data

• doRequest Make a request to a MouseHunt endpoint.

Page and User Data

• getCurrentLocation Get the current location.
• getCurrentPage Get the current page.
• getCurrentTab Get the current tab.
• getCurrentSubtab Get the current subtab.
• isOverlayVisible Check if a popup or overlay is visible.
• getCurrentOverlay Get the current popup or overlay.
• isDarkMode Check if the user is using dark mode.
• isLoggedIn Check if the user is logged in.
• isLegacyHUD Check if the user is using the legacy HUD.
• userHasItem Check if the user has an item.
• getUserItems Get the details of an array of items.
• getUserSetupDetails Get the details of the user's setup.

Popups

• createPopup Create a basic popup.
• createChoicePopup Create a popup with two choices.
• createImagePopup Create a popup with an image, similar to the mouse image popup.
• createLarryPopup Create a popup with the Larry Office background.
• createPaperPopup Create a popup with a paper background.
• createMapPopup Create a popup inside the treasure map popup.
• createWelcomePopup Create a popup that shows once.
• showHornMessage Show a message in the horn popup.

Settings

• addSetting Add a setting to the Game Settings page.
• addSettingsTab Add a tab to the Game Settings page.
• getSetting Get the value of a setting.
• saveSetting Save a setting.
• createFavoriteButton Create a favorite button.

Miscellaneous

• addStyles Add CSS styles to the page.
• addSubmenuItem Add a submenu item to the menu.
• addItemToGameInfoBar Add an item to the Game Info Bar.
• makeButton Create a button.
• makeElement Create an element.
• makeElementDraggable Make an element draggable, automatically saving and restoring the position.
• wait Wait for a number of milliseconds.

Debugging

• clog Log a message to the console.
• debug Log a message to the console if debugging is enabled.
• enableDebugMode Enable debugging.

onRequest

Do something when a request is made, either on every request or on a specific endpoint.

Parameters

Examples

onRequest(() => {
  // Do something when the userInventory endpoint is called.
}, 'managers/ajax/users/userInventory.php');

// Doing something on all requests.
onRequest((req) => { console.log(req) })

onAjaxRequest

Do something when a request is made, either on every request or on a specific endpoint. Deprecated: Use onRequest instead.

Parameters

Examples

onAjaxRequest(() => {
  // Do something when the userInventory endpoint is called.
}, 'managers/ajax/users/userInventory.php');

// Doing something on all requests.
onAjaxRequest((req) => { console.log(req) })

onEvent

Do something when an event is triggered - a wrapper around the HG event registry.

Parameters

Examples

onEvent('travel_complete', () => {
  // Do something when the user travels.
});

onEvent('ajax_response', () => {
  console.log('Fired when an ajax request is made.');
});

onPageChange

Do something when the page changes, either on any page or when leaving or entering a specific page.

Parameters

All parameters are optional, but you probably want to specify at least one of change, show, or hide.

Available pages

Any of these can be used as the <page> parameter.

• camp
• travel
• inventory
• shop
• mice
• friends
• sendSupplies
• team
• tournament
• news
• scoreboards
• discord

Examples

onPageChange({
  change: () => { console.log('Current page: ' + getCurrentPage()); },
  travel: {
    show: () => { console.log('travel is visible'); },
    hide: () => { console.log('travel is hidden'); }
  },
});

onDialogShow

Do something when a popup / overlay shows, either on any popup or when a specific popup is shown.

Parameters

Available Popups / Overlays

Any of these can be used as the <overlay> parameter, as well as passing in any other overlay name.

• map
• item
• mouse
• image
• convertible
• adventureBook
• marketplace
• gifts
• support
• premiumShop

Examples

onDialogShow(() => {
    console.log('Opened map popup');
  }, 'map');

onDialogHide

Do something when a popup / overlay hides, either on any popup or when a specific popup is hidden.

Parameters

Available Popups / Overlays

Any of these can be used as the <overlay> parameter, as well as passing in any other overlay name.

• map
• item
• mouse
• image
• convertible
• adventureBook
• marketplace
• gifts
• support
• premiumShop

Examples

onDialogHide(() => {
    console.log('Closed map popup');
  }, 'map');

onOverlayChange

Deprecated: Use onDialogShow and onDialogHide instead.

Do something when a popup / overlay changes, either on any popup or when a specific popup is shown or hidden.

Parameters

All parameters are optional, but you probably want to specify at least one of change, show, or hide.

Available Popups / Overlays

Any of these can be used as the <overlay> parameter.

• map
• item
• mouse
• image
• convertible
• adventureBook
• marketplace
• gifts
• support
• premiumShop

Examples

onOverlayChange({
  change: () => { console.log('overlayPopup changed'); },
  show: () => { console.log('overlayPopup is visible'); },
  hide: () => { console.log('overlayPopup is hidden'); },
  map: {
    show: () => { console.log('treasureMapPopup is visible'); },
    hide: () => { console.log('treasureMapPopup is hidden'); },
  },
});

onTrapChange

Do something when a trap component changes, such as the charm or cheese.

Parameters

All parameters are optional, but you probably want to specify at least one of change, show, or hide.

Available Components

• bait
• base
• weapon
• charm
• skin

Examples

onTrapChange({
  change: () => { console.log('trap changed'); },
  show: () => { console.log('trap is visible'); },
  hide: () => { console.log('trap is hidden'); },
  bait: {
    show: () => { console.log('bait is visible'); },
    hide: () => { console.log('bait is hidden'); }
  },
});

onTravel

Do something when the user travels to a new location.

Parameters

Examples

onTravel('table_of_contents', {
  shouldAddReminder: true,
  title: 'Make sure you enable CC!',
  text: 'If you don\'t enable CC, your writing will be slower.',
  button: 'Dismiss',
});

onTravel('rift_valour', {
  shouldAddReminder: true,
  title: 'Valour Rift'
  text: 'You should go to Floating Islands instead.',
  button: 'Travel',
  action: () => { app.pages.TravelPage.travel('floating_islands'); },
});

Data

doRequest

Make a request to a MouseHunt endpoint.

Parameters

Examples

doRequest(
  'managers/ajax/pages/page.php',
  {
    page_class: 'HunterProfile',
    'page_arguments[tab]': 'mice',
    'page_arguments[sub_tab]': 'location',
  }
).then((data) => {
  // Do something with the data.
});

const itemData = await doRequest('managers/ajax/users/userInventory.php', {
  action: 'get_items',
  'item_types[]': 'cheddar_cheese'
});

console.log(itemData); // { cheddar_cheese: { ... } }

Page and User Data

getCurrentLocation

Returns the current location.

getCurrentPage

Returns the current page.

getCurrentTab

Returns the current tab.

getCurrentSubtab

Returns the current subtab, falling back to the current tab if there is no subtab.

isOverlayVisible

Returns whether there is currently a popup / overlay visible.

getCurrentOverlay

Returns the current visible popup / overlay.

isDarkMode

Returns whether the user is using dark mode, either via the extension or MHCT dark mode option.

isLoggedIn

Returns whether the user is logged in.

isLegacyHUD

Returns whether the user is using the legacy HUD.

userHasItem

Returns whether the user has a specific item.

userHasItem(itemType);

Parameters

Examples

if (! userHasItem('super_brie_cheese')) {
  console.log("Oh no! You're out of SB!");
}

getUserItems

Get the data for an array of items.

Parameters

Examples

const items = await getUserItems(['super_brie_cheese']);
console.log(items); // { super_brie_cheese: { ... } }

getUserSetupDetails

Gets the details of the user's setup, including the current power, luck, etc from each component and aura.

getUserSetupDetails()

Popups

createPopup

Creates a popup with the given title and content. Make sure to add an event listener to the target element to show the popup.

Parameters

Examples

const examplePopupTarget = document.querySelector('.mousehuntHud-gameInfo');
if (examplePopupTarget) {
  examplePopupTarget.addEventListener('click', () => {
    createPopup({
      title: 'Example Popup',
      content: 'This is an example popup.',
    });
  });
}

createChoicePopup

Creates a popup with two choices.

Parameters

Examples

createChoicePopup({
  title: 'Choose your favorite Mouse',
  choices: [
    {
      id: 'treasurer_mouse',
      name: 'Treasurer',
      image: 'https://www.mousehuntgame.com/images/mice/medium/bb55034f6691eb5e3423927e507b5ec9.jpg?cv=2',
      meta: 'Mouse',
      text: 'This is a mouse',
      button: 'Select',
      callback: () => {
        console.log('treasurer selected');
      }
    },
    {
      id: 'high_roller_mouse',
      name: 'High Roller',
      image: 'https://www.mousehuntgame.com/images/mice/medium/3f71c32f9d8da2b2727fc8fd288f7974.jpg?cv=2',
      meta: 'Mouse',
      text: 'This is a mouse',
      button: 'Select',
      callback: () => {
        console.log('high roller selected');
      }
    },
  ],
});

createImagePopup

Creates a popup with the given title and content.

Parameters

Examples

const exampleImagePopupTarget = document.querySelector('.mousehuntHud-userStat-row.points');
if (exampleImagePopupTarget) {
  exampleImagePopupTarget.addEventListener('click', () => {
    createImagePopup({
      title: 'Example Image Popup',
      image: 'https://example.com/example.png',
    });
  });
}

createLarryPopup

Create a popup with the Larry's office style.

Parameters

Examples

const exampleLarryPopupTarget = document.querySelector('.mousehuntHud-userStat-row.gold');
if (exampleLarryPopupTarget) {
  exampleLarryPopupTarget.addEventListener('click', () => {
    createLarryPopup('This is an example Larry popup.');
  });
}

createPaperPopup

Create a popup with the paper style.

Parameters

Examples

const examplePaperPopupTarget = document.querySelector('.mousehuntHud-userStat-row.gold');
if (examplePaperPopupTarget) {
  examplePaperPopupTarget.addEventListener('click', () => {
    createPaperPopup({
      title: 'Example Paper Popup',
      content: {
        title: 'Example Paper Popup',
        text: 'This is an example paper popup.',
        image: 'https://example.com/example.png',
        button: {
          text: 'Example Button',
          href: 'https://example.com',
        },
      },
    });
  });
}

createMapPopup

Creates a popup that shows while in the map popup.

Parameters

Examples

const exampleMapPopupTarget = document.querySelector('.mousehuntHud-userStat-row.gold');
if (exampleMapPopupTarget) {
  exampleMapPopupTarget.addEventListener('click', () => {
    createMapPopup({
      title: 'Example Map Popup',
      content: 'This is an example map popup.',
    });
  });
}

createWelcomePopup

Creates a popup that shows once.

Parameters

Examples

const exampleWelcomePopupTarget = document.querySelector('.mousehuntHud-userStat-row.gold');
if (exampleWelcomePopupTarget) {
  exampleWelcomePopupTarget.addEventListener('click', () => {
    createWelcomePopup({
      id: 'example-welcome-popup',
      title: 'Example Welcome Popup',
      content: 'This is an example welcome popup.',
      columns: [
        {
          title: 'Example Column 1',
          content: 'This is an example column 1.',
        },
        {
          title: 'Example Column 2',
          content: 'This is an example column 2.',
        },
      ],
    });
  });
}

showHornMessage

Show a message in the horn popup.

Parameters

Examples

showHornMessage({
  title: 'Example Message',
  text: 'This is an example message.',
  button: 'Example Button',
  action: () => {
    console.log('Example action');
  },
});

Settings

addSetting

Adds a boolean setting to the Game Settings page under 'Userscript Settings'.

Parameters

Examples

addSetting('Enable Turbo Mode', 'turbo-mode-enabled', true, 'Enables turbo mode.');

addSetting(
  'My Setting',
  'my-fancy-setting-key',
  false,
  'This is my fancy setting that even has a special section.',
  {
    id: 'my-fancy-section',
    name: 'My Fancy Section',
  }
);

addSetting(
  'My Other Setting',
  'my-other-fancy-setting-key',
  false,
  'This is my other fancy setting that goes in the same section.',
  {
    id: 'my-fancy-section',
    name: 'My Fancy Section',
  }
);

addSettingsTab

Adds a tab to the Game Settings page to show a custom settings page.

Parameters

Examples

addSettingsTab('my-tab', 'My Tab');

const settingSection = {
  id: 'my-section',
  name: 'My fancy section',
};

const tab = addSettingsTab('my-tab', 'My Fancy Tab');

addSetting(
  'This is my fancy setting',
  'my-fancy-setting-key',
  false,
  'This is my fancy setting that goes in the fancy section.',
  settingSection,
  tab
);

getSetting

Gets the value of a setting.

Examples

const mySetting = getSetting('setting_key');
if (mySetting) {
  // Do something.
} else {
  // Do something else.
}

saveSetting

Saves a setting.

Parameters

Examples

saveSetting('setting_key', true);

createFavoriteButton

Creates a favorite button that can be toggled on and off.

Parameters

Examples

const infobar = document.querySelector('.mousehuntHud-gameInfo');

createFavoriteButton({
  id: 'testing_favorite',
  target: infobar,
  size: 'small',
  defaultState: false,
});

Miscellaneous

addStyles

Add CSS styles to the page.

Parameters

Examples

addStyles(`
  .my-class {
    color: red;
  }

  .huntersHornView {
    display: none;
  }
`);

addSubmenuItem

Add a submenu item to the menu.

Parameters

Examples

addSubmenuItem({
  menu: 'kingdom',
  label: 'mouse.rip',
  icon: 'https://www.mousehuntgame.com/images/ui/hud/menu/prize_shoppe.png',
  href: 'https://mouse.rip',
  external: true,
});

addItemToGameInfoBar

Adds a link to the top 'Hunters Online' bar.

Parameters

Examples

addItemToGameInfoBar({
  label: 'mouse.rip',
  icon: 'https://www.mousehuntgame.com/images/ui/hud/menu/prize_shoppe.png',
  href: 'https://mouse.rip',
  external: true,
});

addItemToGameInfoBar({
  label: 'Spring Egg Hunt Helper',
  icon: 'https://www.mousehuntgame.com/images/items/convertibles/transparent_thumb/887162c61d0e01985ffc12e41c03d952.png?cv=2',
  class: 'mh-egg-helper-top-menu',
  callback: bookPopup
});

makeElement

Create an element with a given class and text, optionally appending it to another element.

Parameters

Examples

const myElement = makeElement('div', 'my-class', 'My Text');

makeElement('a', 'some-class', 'This is a link', document.body);

makeButton

Creates a button to match the button style.

Parameters

Examples

const myButton = makeButton('My Button', 'https://example.com');

makeElementDraggable

Make an element draggable, with the ability to automatical saving and restoring the position.

Parameters

Examples

makeElementDraggable(
  '#mh-catch-stats',
  '.mh-catch-stats-header',
  25,
  25,
  'mh-catch-stats-position'
  true
);

wait

Wait for a number of seconds before resolving a promise.

Parameters

Examples

wait(1000).then(() => {
  console.log('1 second has passed');
});

Debugging

clog

Log a message to the console.

Parameters

Examples

clog('Hello World');

clog('hello', 'world');

debug

Log a message to the console if debugging is enabled.

Parameters

Examples

const myVar = getSomeVar();
debug(myVar);

enableDebugMode

Adds an option in the preferences to enable debugging, must be called before using debug.