MWI Market Mate · Feature Documentation
Before We Begin
⚠️ Compliance Notice
This plugin does not include any auto-buy functionality, as automation would violate game rule 4.2.
✅ This plugin: Navigates to a specific item's market page on the client side. This is identical to a player manually Shift-clicking an item in their inventory.
❌ Rule-breaking plugins: Provide one-click batch purchasing of multiple items, sending bulk requests to the server — that's automation.
Therefore, all purchases must be performed manually by the player.
The plugin only helps you find items and calculate quantities — the rest is up to you.
If you don't trust the one-click market navigation feature, the plugin also provides in-market highlighting of items in your shopping list.
The plugin has been submitted to admin for review. All features are fully compliant.
I. Overview
This plugin is a crafting material shortage calculator and manual purchasing assistant. Open any crafting panel and it automatically analyzes the required materials, calculates exactly what you're missing and how much, and lets you add shortages to a shopping list for quick market navigation — purchasing itself always remains a manual action.
Shortage Calculation
- Reads the game data layer (
initClientData) directly instead of parsing on-screen text — recipes and inventory accurate to the unit
- Artisan Tea, Guzzling Pouch and other buffs automatically factored in; optional "Material Buffer" that adds a cushion only on large batches to absorb Artisan Tea's random variance
- Covers crafting panels, alchemy panels (Coinify / Decompose / Transmute), house building panels, and detail popups opened from anywhere (market, inventory, etc.)
- Inline badges on material rows: shortage "Need X", surplus "+X", locked by other plans "🔒N" — all at a glance
Shopping List
- Dual-form UI: desktop side rail / mobile drawer, fully style-isolated from the game and other plugins
- Live market prices, per-item subtotal and estimated total; star protection, reserve quantities, search, direct quantity editing
- Precise WebSocket inventory tracking — purchases auto-deduct from the list, auto-collapse when everything is fulfilled
Market & Purchasing (all manually triggered)
- Market dialog auto-fills the shortage quantity; purchase navigation bar with fulfilled banner; in-market item highlighting
- Configurable "Next-item Shortcut": after fulfilling an item, one key press jumps to the next pending item's market page
Crafting Plans & Upgrade Chains
- Crafting plans lock material inventory, eliminating shortage miscalculation when recipes share materials; create one on demand by ticking "Create plan" when adding to the list (off by default, so it stays out of the way when you only want to buy materials)
- Plan progress uses an "output-item snapshot" that stays accurate after closing the page or crafting offline; the list shows a progress bar and a locked-material breakdown, and you release the lock by clicking "Done" when finished
- Upgrade chain tree view, step checkboxes, "Add Full Chain Materials" creating independent per-step plans (also governed by the "Create plan" checkbox)
- Quest tracking: shows progress of active production quests
Interoperability & Diagnostics
- Public API
window.MWIMM: lets other userscripts read & write the cart, subscribe to changes, and trigger market navigation (docs in the script's header comment)
- Tested side-by-side with MWI_Toolkit and Sunny's MWI Enhancement
- Diagnostic commands:
MWIMM.__log() (one-shot diagnostic log export), __probe(), __key(), __selftest()
- Bilingual UI (Chinese / English), automatically follows the game language setting
📖 Full User Guide: https://mate.colacola.cloud/guide?lang=en
💬 Feedback & Community: https://mate.colacola.cloud/community?lang=en
II. Acknowledgments
Ideas & Suggestions
- Mooooooooo
- AlphB
- wangchyan
- mutallip
- Foreversunny & friends
- Joey
- baozi
- Star
Bug Reports
(In no particular order)
III. Changelog
v2.2.0
Reworks how crafting plans are created and how their progress is tracked — making plans more deliberate and accurate offline.
Fixed / Improved
- Crafting plans are now created on demand: a "Create plan" checkbox (default off) is added when adding to the shopping list; a plan is created and materials locked only if you tick it. This fixes the old behavior where adding to the cart silently created a plan and locked inventory — causing later shortage calculations for other items to not add up, sometimes even while crafting the same item. Whether to create a plan is now entirely your choice.
- Plan progress now uses an "output-item snapshot": on creation, the current output-item inventory is recorded as a baseline; progress = current − baseline, capped at "planned actions × output-per-action." Because it only reads an inventory delta, progress still displays correctly after you close the page or craft offline (the old event-counting approach lost its count when the page was closed).
- Richer plan list: each plan now shows a progress bar and a "Locked" breakdown — see at a glance which materials it locks and how much of each.
- Manual completion: a "Done" button now releases the plan's material lock and removes it from the list; plans no longer auto-complete or auto-disappear — fewer misjudgments, more control.
A one-time page refresh is recommended after upgrading.
Compatibility note: plans created before v2.2.0 still load and keep their locks after upgrading, but need to be recreated (tick "Create plan" then add to the list) before a progress bar appears.
v2.1.1
Reworks the material safety-margin (buffer) algorithm and its controls, plus some shopping-list usability touches.
Fixed
- "Material Buffer" (formerly "Z-score safety margin") didn't match how Artisan Tea actually works: the old probability model overestimated random variance and even bought extra when a material requirement divided evenly under Artisan (fixed per-action consumption, zero variance). It now follows the official wiki mechanic — the decimal part of the reduced per-action requirement is the probability of consuming that material — so variance estimates match the game and there's no over-buying when variance is zero.
Improved
- New "Buffer threshold" (action count): at or below the threshold (default 10), quantities are rounded up to the exact requirement with no buffer; only above it does the selected level add a margin. Small batches (a few pieces of gear) are unaffected; only large batches (a full day of grinding) get a cushion, to avoid coming up a few short due to random variance.
- Buffer levels simplified to: Standard (95%) / Ample (99%) / Full (99.9%) / Off (Off = exact requirement, no buffer).
- Shopping-list hint: a dismissable hint at the top of the list — "tap an item or its row to open it in the market."
- Larger item icons in the shopping list for better clarity.
A one-time page refresh is recommended after upgrading.
v2.1.0
Building on the v2.0.0 architecture upgrade: fixes two classes of panel-detection issues and substantially improves stability when running alongside third-party plugins.
Fixed
- Missing badges and "Add to cart" button on alchemy / enhancement panels: an old panel-whitelist check excluded alchemy (Coinify / Decompose / Transmute) and enhancement panels, causing badges and the add-to-cart button to disappear together on them. Panel detection is now unified, covering crafting / alchemy / enhancement panels consistently.
- Badges freezing or disappearing after a market round-trip: after navigating to a market page and back — especially when running alongside plugins that inject buttons into the panel (e.g. Sunny's MWI Enhancement) — crafting badges could freeze at stale values or vanish entirely until you switched recipes or browser tabs. The root cause was a continuous stream of DOM mutations indefinitely deferring the refresh (debounce starvation): the refresh was queued but never got to run. A refresh-ceiling mechanism now guarantees timely redraws no matter how frequent the mutations are.
Improved
- Recipe identification now reads the exact recipe identity from the game data layer (React Fiber) instead of inferring it from on-screen text or panel class names — more robust detection and better coexistence with third-party plugins.
- Watchdog enhancements: auto-refresh when the market dialog opens / closes, so inventory changes from in-market purchases are reflected promptly; force a redraw when a panel is reused but the recipe has changed, eliminating stale-recipe leftovers.
- Diagnostics:
MWIMM.__log() now includes a debounce-coalesce counter to help pinpoint DOM-mutation storms caused by mutual injection with other plugins.
A one-time page refresh is recommended after upgrading.
v2.0.0
A combined release of architecture upgrade + major stability overhaul + new features, refined through 17 suites / 197 checks.
Added
- Brand-new UI: Shadow DOM dual-form shell (desktop side rail / mobile drawer), fully style-isolated — no more interference with the game or other plugins; settings apply instantly and auto-save
- Diagnostic commands:
MWIMM.__log() exports a one-shot diagnostic log (version / settings / data layer status / full event timeline); plus __probe() for shortage-calculation checkup, __key() for shortcut checkup, __selftest() for parser self-test
Improved Calculation Accuracy & Stability
Other Improvements
- Old settings migrate automatically; a one-time page refresh is recommended after upgrading
How to Report Issues
Run MWIMM.__log() in the F12 console and paste the full output with your report. Certain private/niche plugins may conflict with panel detection (symptom: badges not appearing) — please include the log in that case too.
v1.7.0
Added
- Public API (
window.MWIMM): read & write the cart, subscribe to changes, and trigger market navigation from other userscripts. Write: addToCart / setCartItemQuantity / removeFromCart / clearCart; read: getCartItems / getCartItem / hasCartItem / getCartCount; helpers: resolveItemName / openMarketplace / normalizeItemId; events: ready and cart:change. Full bilingual docs in the script's header comment
- "Next-item Shortcut": when an item is fulfilled and the list has a next pending item, a configurable key press jumps to its market page. Bind via capture mode in settings; single keys and modifier combinations both supported
- Banner shortcut badge: the fulfilled banner shows the current shortcut; if unset, click to jump straight to the corresponding settings row
Improved & Safety Net
- Cart write path split so API batch writes trigger only one persistence + one broadcast
- Strict shortcut scoping: armed only after a fulfilled event, consumed on press, always released when an input field is focused — chat typing is never affected
v1.4.0 – v1.6.1 (Consolidated)
- Compliance: removed auto-advance and the legacy fallback navigation; replaced with an inline fulfilled banner and a "Next item ▶" button — every market page navigation is triggered by a manual player click (v1.4.1 / v1.4.2)
- Calculation: Z-score safety margin model (90%–99.9%, four levels); blue "+X" surplus badge when materials suffice; gold coins excluded from Artisan Tea reduction; same-recipe multi-quest plans accumulate correctly; full-chain adds deduct existing cart quantities (v1.4.2 – v1.4.7)
- Upgrade chains: tree view of the full chain with per-step shortages, step checkboxes, "Add Full Chain Materials" creating independent per-step plans with inventory locking, in-chain stock excluding the chain's own locks (v1.4.2 – v1.4.7)
- Quest tracking panel: active production quest progress with real-time WS updates and "fill shortage / create plan" quick buttons (v1.4.2)
- Market prices: per-item price and subtotal in the list, estimated total bar, instant loading via price cache (v1.5.0 / v1.6.0)
- Bilingual: English UI (120+ strings), bilingual item name resolution, language always follows the game setting (v1.4.0 / v1.5.0)
- UI: major dark theme overhaul (near-black panels + amber gold accent), sliding toggles, settings reorganized into 4 groups, panel position/size auto-restore after F12 / window resize (v1.6.0)
- Lock visibility: 🔒N suffix on material badges and an amber lock summary tag, hover for per-plan breakdown (v1.6.1)
- Stability: script moved to
document-start fixing inventory loss for some users, 6-second cooldown for enhancement panel rebuilds, observer narrowed to the game container, listener de-duplication, Guzzling Pouch / Artisan Tea detection fixes, full-pipeline error capture (v1.4.0 – v1.6.0)
v1.3.6 and Earlier (Consolidated)
- Core features launched: shortage auto-calculation, shopping list, market navigation & highlighting
- Game data layer integration (
initClientData); production recipes no longer depend on DOM parsing, with smart DOM fallback for dynamic-input scenarios
- Artisan Tea & Guzzling Pouch auto-calculation, data source tag for visual buff confirmation
- Precise WebSocket inventory tracking with auto-deduction after purchases; market dialog pre-fill, purchase navigation bar, market data cache
- Crafting plans & inventory locking, plans panel, real-time WS progress tracking with automatic lock release
- Star protection, reserve quantities, auto-collapse on fulfillment, tiered clearing (non-starred / all)
- House building panel shortage calculation; "Current Action" tab manual planned-actions input
- Panel dragging, resizing, item search, editable quantities
