Market Alcher DreamBot Comparison And Upgrade Plan

This audit compares the adjacent DreamBot standalone Market Alcher guide/source against the current RuneLite implementation in com.n3plugins.marketalcher. Live source wins over prose on both sides; where the DreamBot README disagrees with its Java source, the source is treated as authoritative.

Sources inspected

• DreamBot guide and source: N3MarketAlcherStandalone/README.md, N3MarketAlcher.java, AlchemyConfig.java, AlchemyCandidateSelector.java, AlchemyRetryPolicy.java, FailedOfferCooldowns.java, WikiMarketClient.java, WikiMarketParser.java, and AlcherWindow.java.
• RuneLite source of truth and docs: N3PLUGINS_SOURCE_OF_TRUTH.md and the Market Alcher guide.
• RuneLite implementation: MarketAlcherPlugin, MarketAlcherController, RuneLiteMarketAlcherRuntime, MarketAlcherConfig, MarketAlcherRuntimeConfig, AlchemyCandidateSelector, MarketSupplyPlanner, StatsTracker, GrandExchangeActions, and the focused Market Alcher tests.

Executive mapping

Area	DreamBot standalone	RuneLite implementation	Status
State machine	LOAD_MARKET, CHECK_LEVEL, EQUIP_FIRE_STAFF, BUY_NATURE_RUNES, BUY_ALCH_TARGETS, ALCH, IDLE	Adds BANK_SUPPLIES, CLOSE_BANK, and STOPPED; CHECK_LEVEL exists but level/spellbook failures resolve to STOPPED	Implemented with RuneLite-specific bank and stop states
Market data	OSRS Wiki mapping and 5m price endpoints	Same endpoints via WikiMarketClient; cached and surfaced through the UI status	Implemented
Target filters	Members toggle, protected/blocked names, min profit, min 5m volume, buy limit, cooldown	Same core filters, with preferred item IDs and row diagnostics	Implemented
Selection modes	PROFIT, XP_THROUGHPUT, BALANCED	Configurable PROFIT, XP_THROUGHPUT, and BALANCED; preferred items still rank first	Implemented
Budget planning	Builds affordable purchase plans, accounting for item price, nature rune price, per-offer budget, and batch caps	Uses AlchemyPurchasePlan + PurchaseBudget; reserves gp, pending target spend, carried nature runes, and per-offer budget before submitting through the shared GE buy pipeline	Implemented
Adaptive batch sizing	Optional min/max batch sizing and retry shrink factor	Configurable adaptive sizing feeds MarketSupplyPlanner.BatchSizing with volume-based caps and slow-fill failure shrinkage	Implemented
Nature rune restock	Configurable restock quantity; buys when inventory natures are depleted	Configurable restock quantity, default 1000, bought when inventory and bank cannot supply natures	Implemented
Staff handling	Equipment, inventory, bank, then GE Staff of fire buy	Same behavior, expanded to 11 fire-supplying equipment IDs	Implemented and improved
Banking	DreamBot assumes inventory supplies after startup except staff bank check	RuneLite can withdraw nature runes and noted alch targets mid-session	Intentional RuneLite improvement
GE submission	DreamBot API calls per loop; active pending orders tracked by name	Shared GrandExchangeActions.createBuyPipeline with submit confirmation and pending purchase baselines	Implemented with stronger shared API ownership
GE reconciliation	Rebuilds/adopts live GE buy offers, uses transferred amount	Adopts orphan offers, reconciles live quantitySold, also detects inventory/bank deltas from submit baselines	Implemented and improved
No-progress timeout	90 seconds in source	Configurable, default 90 seconds	Implemented
Retry/lockout	Retry price policy, cooldowns, session lockout	Retry price policy, short/long cooldowns, session lockout, separate cancel/rebuy ticks	Implemented
Cooldown persistence	Per-account cooldown file	Cooldowns are in-memory; buy limits and stats persist	Missing
Inventory ownership	Ignores unrelated alchables unless opportunistic mode is enabled	Ignores unrelated alchables by default; explicit opportunistic toggle can allow them	Implemented
Config UI	Swing Targets/Config/Stats, presets, mouse/user-agent options	Sidebar quick settings plus detached Targets/Stats/Settings window; RuneLite config provider still exists	Mostly implemented, some options missing
Stats	Per-account stats, aggregate accounts tab, checkpoint every 10 alchs	Per-account lifetime/session/per-item stats and decision log under .runelite	Partial
Mouse/anti-ban	DreamBot custom mouse profiles and passive idle logging	RuneLite uses shared InteractionApi, ActionPacer, and Break Handler integration	Do not port directly
Live verification	README says runtime only build-verified	RuneLite docs keep GE fill, alch widget timing, and bank close behavior as live verification pending	Still pending

Already implemented in RuneLite

• Market fetch, cache, parser, UI refresh, and error surfacing for the OSRS Wiki mapping and 5m price endpoints.
• Core automation loop for market load, staff recovery, bank recovery, nature rune buying, alch-target buying, high-alchemy casting, idling, and terminal stopped states.
• Shared action routing through InteractionApi.actions.*, including BankActions, GrandExchangeActions, InventoryActions, MagicActions, DialogActions, SkillsActions, and TabActions.
• GE buy pipeline construction, submit confirmation, ready-collect handling, orphan offer adoption, partial-fill accounting, same-tick collect delay, and separate-tick cancel/retry behavior.
• Retry price increases that preserve a minimum retry profit floor.
• Buy-limit tracking and account-scoped buy-limit persistence.
• Fire staff handling for more than the DreamBot baseline Staff of fire path.
• Staged High Alch flow that handles GE closure, Magic tab visibility, spell selection, manual deselection, and item click on a later tick.
• Account bootstrap and Break Handler gating through the n3 suite runtime.
• Custom RuneLite sidebar/window UI with target diagnostics, settings, stats, preferred item IDs, blacklist, protected items, overlay, and decision log.
• Focused tests around controller states, runtime inventory reads, GE offers, parser behavior, candidate filtering, buy limits, persistence, and descriptor registration.

Intentional RuneLite divergences

• RuneLite can visit the bank mid-session to withdraw nature runes and noted target items. DreamBot deliberately avoids mid-session banking beyond staff recovery; the RuneLite behavior is a useful suite-level upgrade.
• RuneLite uses shared action APIs and pacing instead of DreamBot mouse profile code. Porting DreamBot's custom mouse system would fight the n3 architecture.
• RuneLite persists under .runelite instead of DreamBot's DreamBot/Scripts paths. This matches RuneLite plugin conventions.
• RuneLite limits concurrent buy orders to 1-3 distinct targets. DreamBot's config allows more GE slots; RuneLite now reserves budget across pending slots but keeps the cap conservative until 4+ slot stress and live GE verification exist.
• RuneLite has explicit wrong-spellbook and repeated-buy-failure STOPPED states instead of treating every terminal condition as idle.

Implemented from backlog

• DreamBot-style inventory ownership policy: the controller now alchs plugin-owned, withdrawn, selected, or bought target items by default and ignores unrelated profitable inventory items unless Opportunistic inventory alching is enabled.
• Nature rune restock quantity is configurable and defaults to 1000.
• Independent buy permissions exist for nature runes, fire staff, and alch targets. Disabled paths surface status text and do not submit GE orders.
• Selection mode is configurable and flows through MarketAlcherConfig, MarketAlcherRuntimeConfig, AlchemySelectionConfig, and AlchemyCandidateSelector.
• MarketSupplyPlanner.purchasePlans builds budget-aware alch target plans. The controller reserves a 2000 gp floor, already-pending target spend, carried nature runes, configured max concurrent order budget, and buy limits before submitting the first eligible plan through the existing buyItem()/GrandExchangeActions.createBuyPipeline path.
• Adaptive batch sizing is configurable through MarketAlcherConfig, MarketAlcherRuntimeConfig, and the Settings tab. When enabled, target buy quantities use volume-based min/max caps and shrink after partial-fill timeouts recorded by FailedOfferCooldowns.

Remaining implementation backlog

Priority	Upgrade	Why it matters	Suggested tests
P1	Add manual target lock semantics for targetItemName/auto-select off	DreamBot exposes this but its source appears to auto-select when no target name is set; RuneLite can implement the intended behavior cleanly	Config update tests and target selection tests
P2	Persist FailedOfferCooldowns per account	Avoids forgetting no-fill cooldowns after restart	Persistence tests mirroring BuyLimitTrackerPersistenceTest
P2	Add account aggregate stats view	Brings over DreamBot's account aggregation while preserving current per-account stats	StatsTracker serialization and UI model tests
P2	Expand GrandExchangeActionsTest for buy/sell pipeline progression	Market Alcher depends heavily on the shared GE pipeline; current coverage is thinner than the controller coverage	Tests for invalid request, no free slot, submit recognition, cancel slot, and retry status
P2	Decide whether to raise RuneLite concurrent order cap above 3	Only safe after purchase-plan budget reservation exists	Planner/controller stress tests with 4+ pending targets
P2	Add a live verification checklist artifact	Tests cannot prove GE revision behavior or widget timing	Manual checklist for GE fill, partial fill, cancel, collect, alch cast, and bank close

Incorrect or stale claims found

DreamBot guide/source mismatches

• The README preset values do not match source. The guide says Balanced uses higher profit/lower volume than the source, while source presets use Balanced 50/50 and Profit 150/20.
• The README says Magic level below 55 can be an IDLE terminal error. Source returns the level-check path instead.
• The README implies fill progress is read every loop. Source reads transferred GE amounts in the reconciliation path, so confirm call frequency before using that README wording as a runtime guarantee.
• The README's three-tier price wording reads as if it applies to all items. Source only falls back to DreamBot LivePrices for nature runes and staff; alch targets still require Wiki high-buy prices.
• autoSelectTarget=false exists in DreamBot config/UI, but source appears to auto-select whenever targetItemName is empty. Treat that as a bug in the standalone behavior, not a parity target.

RuneLite docs/source mismatches corrected by this audit pass

• docs/market-alcher.md and the SOT said the standard RuneLite config cog was removed. Live source has a @Provides MarketAlcherConfig provider, so the docs now describe the custom UI as primary while acknowledging the provider.
• docs/market-alcher.md said pending GE offers time out after 10 minutes. Live config defaults to 90,000 ms with a 10,000-600,000 ms range.
• docs/market-alcher.md said GE target buy quantity is capped by free inventory slots. Live source caps by batch size, live buy-limit remaining, and affordable inventory coins; bank withdrawal planning is where free-slot caps apply.
• docs/grand-exchange.md also had stale wording that said GrandExchangeActions did not construct buy/sell offers. This audit pass updated that page to describe createBuyPipeline and createSellPipeline.

Do not port directly

• DreamBot custom mouse profile recording/application should stay out of this plugin unless the suite gains a shared, tested input profile abstraction.
• DreamBot user-agent config is not useful as a user-facing RuneLite setting; the RuneLite market client should keep a stable n3Plugins user-agent.
• DreamBot's no-mid-session-bank limitation should not be copied. RuneLite bank recovery is already safer for long sessions.
• DreamBot LivePrices fallback does not exist in RuneLite. If a fallback is needed, prefer an explicit RuneLite-side policy or skip no-price candidates.

Suggested implementation sequence

1. Wire manual target lock through MarketAlcherConfig, MarketAlcherRuntimeConfig, and the Settings tab.
2. Persist cooldowns and add account aggregate stats after the purchase planner is stable.
3. Run .\gradlew.bat test --tests com.n3plugins.marketalcher.* --console plain and then perform live RuneLite verification for GE fill, partial fill, cancel/retry, collect, High Alch widget timing, and bank close behavior.