N3BuilderF2P Port Development Plan

Status and authority

This document defines the full port of the DreamBot N3BuilderF2P AIO into the n3Plugins RuneLite suite. The executable parity ledger owns current implementation and acceptance status. The four API comparison reports remain focused references:

• Lifecycle and state
• Entities and interactions
• Inventory and banking
• Navigation

The plan derives the old behavior inventory from the live checkout at D:\NewBackup\my-aio\N3BuilderF2P. The old repository source and its docs/runtime_verification_status.md ledger define implemented DreamBot behavior. Live n3Plugins source defines the target APIs. If either source changes, update the affected disposition before implementation.

Implementation and test results outrank this plan. A static test, accepted dispatch, or successful client launch does not establish gameplay acceptance.

Current implementation

Phase 0, the Phase 1 shell, and the scheduler core of Phase 2 provide the registered, stopped-by-default plugin; exact seven-state scheduler; deterministic weighted selection and old task-duration profiles; fixed 18-module registry; immutable snapshots; Break Handler/input lifecycle; reset handling; and fail-closed mandatory preflight detection.

Woodcutting, Mining, Fishing, Firemaking, Cooking, Smithing, and Prayer now have live-capable workflows. Focused tests cover old tool, supply, location, food, bar, ore, product, and bone policies; travel; later action verification; selective storage and return cycles; stale targets; and competition handling. Mining includes Dwarven relocation and a module-local Port Sarim deposit-box path with an observed inventory-reduction postcondition. Fishing's optional cooking handoff and Al Kharid path remain pending. Firemaking reuses the current lane planner. Cooking reuses Auto Cooker models without its lifecycle owner. Smithing reuses Bank Stander Plus recipes, facilities, and batch planning for its correlated furnace and anvil stages. Prayer verifies every burial through bone reduction or XP. Acquisition-required states block because the GE owner remains unported. The other 11 modules return module_workflow_pending. See the parity ledger for the remaining static and live gates.

Product decision

Build one native RuneLite plugin under com.n3plugins.aiobuilder and register it through runelite-plugin.properties. The plugin will schedule AIO work, own user-facing AIO configuration and status, and compose shared n3 workflows. It will not recreate DreamBot as a compatibility layer.

Use these ownership rules:

• PacketUtilsPlugin retains Walker ticking, interaction pacing, input locking, synthetic input, humanization, and shared runtime ownership.
• The AIO plugin owns task selection, skill progression, module transitions, target goals, and AIO policy.
• Existing feature plugins remain independent RuneLite plugins. The AIO may reuse shared classes they already expose, but it must not control their panels, hotkeys, private controllers, or plugin lifecycle.
• Shared SDK changes require more than one consumer or a missing cross-cutting contract. Keep one-off module behavior inside the AIO package.
• The controller pulses one active workflow once per game tick. No blocking waits, executor-owned gameplay loops, or parallel action schedulers may be added.

Full parity scope

The old runtime verification ledger identifies 18 concrete gameplay modules. Full parity covers their implemented behavior and excludes claims that the old repository marks absent.

Old module	Initial n3 disposition	Required parity work
Melee combat	Audit AIO Fighter for reuse	Preserve melee-style goals, full equipment readiness, food policy, target selection, loot policy, world-hop policy, and task completion.
Ranged combat	Audit AIO Fighter for reuse	Preserve bow and arrow support. Do not add the old repository's absent crossbow or safe-spot claims.
Magic combat	Audit AIO Fighter and magic actions	Preserve combat-spell selection, rune and staff requirements, target selection, and autocast verification.
High Alchemy	Audit Market Alcher and shared alchemy code	Preserve AIO funding, candidate selection, buy limits, cooldowns, equipment, casting, and profit observations.
Woodcutting	Compose Power Skiller query/action owners	Port progression, axe policy, training spots, competition handling, banking, and goals.
Mining	Compose Power Skiller query/action owners	Port progression, pickaxe policy, training spots, competition handling, normal banking, and the Port Sarim deposit-box path.
Fishing	Compose Power Skiller query/action owners	Port progression, tool and bait policy, training spots, optional cook handoff, banking, and goals.
Cooking	Audit Auto Cooker for reuse	Preserve progressive food selection, location choice, range/fire interaction, banking, and completion goals.
Smithing	Audit Bank Stander Plus recipes	Preserve bars, tool requirements, furnace/anvil routing, production selection, banking, and goals.
Crafting	Audit Bank Stander Plus recipes	Preserve leather and gold-jewellery tiers, mould/tool/thread requirements, GE handoff, production widgets, and goals.
Firemaking	Audit Power Skiller and Bank Stander Plus	Preserve tinderbox/log policy, lane selection, lighting confirmation, banking, and goals.
Runecrafting	Implement AIO module over shared actions	Preserve Air to Mind to Water to Earth to Fire to Body progression, tiara/talisman handling, Rune Mysteries gate, banking, and altar routes.
Prayer	Implement AIO module over shared actions	Preserve bone supply, acquisition decision, bury confirmation, and goals.
Monster/drop money maker	Audit Fighter and Auto Looter	Preserve cow/chicken selection, food policy, cowhide and remains handling, loot thresholds, banking, and completion policy.
Wizard's mind-bomb money maker	Implement AIO economy workflow	Preserve purchase, sale, world-hop, stock, bank, and blocked-task policy.
Tutorial Island	Audit Tutorial Island plugin for reuse	Preserve section progression, inventory contracts, username generation, recovery, and fresh-account completion.
Rune Mysteries	Audit Quest Script and Questing Assistant	Preserve Duke dialogue, package delivery, Wizard Tower traversal, Sedridor flow, notes return, completion, and Runecrafting handoff.
Security Stronghold	Audit Quest Script and Fighter support	Preserve food preparation, four-floor traversal, security dialogue answers, combat avoidance, reward confirmation, and terminal completion.

The old QuestModule, QuestDescriptor, and furnace helper files support these modules; they are not separate gameplay modules.

Excluded from parity

Do not add behavior that the old repository marks unimplemented:

• Crossbow and bolt ranged support.
• Safe-spot ranged or magic combat.
• Power-drop gathering modes.
• Cook's Assistant or Sheep Shearer automation.
• Goal-based scheduling beyond the old time, weight, and target-level rules.
• Death or gravestone recovery that the old ledger marks absent.
• An HTTP metrics sink that the old repository keeps as a placeholder.

The standalone n3MarketAlcher remains a separate DreamBot product. Shared pure-Java alchemy policy may move to n3Plugins when licensing, dependencies, Java 11 compatibility, and consumer ownership permit it. The port must not copy its Swing application or deployment behavior into the AIO plugin.

Old responsibility disposition

Port behavior, not the old class tree.

Old responsibility	Target owner	Disposition
BankOperationsCoordinator cache and widget mechanics	SdkEvents, BankActions, loadouts	Delete DreamBot mechanics. Preserve known/unknown bank state and post-write observation rules.
ModuleBankingCoordinator	AIO preparation state plus BankWorkflowBuilder	Port the preparation decision. Do not create a coordinator until more than one AIO component needs a separate owner.
BankAccessCoordinator	BankActions.openNearestAccessible(), Walker, deposit-box actions	Reuse shared access. Port only missing contextual bank and deposit-box policy.
GE lifecycle and buy execution	GrandExchangeActions and existing GE workflow owners	Reuse result-aware actions. Port exact task-funding, retry, collection, and blocked-task policy.
Funding, coin, liquidation, and buy-limit policy	AIO economy package, shared pure policy where reusable	Port. Keep protected-item and unknown-balance guards.
Equipment loadout and supply evaluation	SDK loadouts, BankRestockPlan, AIO module requirements	Replace mechanics. Preserve slot-aware readiness, required/tolerated items, and forward-progress decisions.
Module chooser, scheduling, and routing	AIO controller	Port as one scheduler. Preserve target goals, weighted selection, task durations, cooldowns, and terminal all-blocked behavior.
NavigationCoordinator transport	Walker and route catalogs	Delete duplicate transport. Preserve only route policy absent from Walker.
Lumbridge stairs and Al Kharid gate policy	Walker actions and route catalogs	Reuse when the shared route owns the full postcondition. Add one shared transport repair if several consumers need missing behavior.
Training-location selection	Individual AIO modules	Port as module data and policy. Do not build a generic location hierarchy.
World hopping	Existing world actions plus AIO policy	Port competition and stock decisions. Reuse shared action and readiness checks.
Custom anti-ban, mouse, and break systems	Packet Utils humanization and Break Handler	Delete old runtime owners. Map user-facing intent only where a current n3 setting has the same contract.
Account and login bootstrap	RuneLite lifecycle plus AIO preflight	Port Tutorial Island and Rune Mysteries decisions. Do not restore removed suite-wide account bootstrap behavior.
Interaction and game-tab wrappers	Api.actions.*	Replace with result-aware actions and observed postconditions.
Combat utility and drop policy	Fighter, Auto Looter, combat actions, AIO policy	Reuse shared mechanics. Port old thresholds, remains policy, and recent-kill continuity if existing owners lack them.
Runecrafting plan	AIO Runecrafting module	Port the F2P progression data and state transitions.
Swing GUI, QuickStart, and paint	RuneLite config, N3PluginPanel, toolbar panel, overlay	Replace platform UI. Preserve settings and status meaning, not layout or CLI flags.
JSONL metrics	Existing n3 telemetry patterns or AIO snapshot	Port session/task/action observations only if current suite telemetry lacks them. Do not add a second global metrics runtime.

Target runtime architecture

Plugin and controller

AioBuilderPlugin will follow normal RuneLite lifecycle:

1. startUp() creates the controller and panel, registers the Break Handler, overlay, navigation button, and hotkey, and leaves automation stopped.
2. The user starts or stops automation through the panel or one configured hotkey.
3. onGameTick checks login state and break state, pulses the controller once, updates the immutable snapshot, and owns or releases the shared input lock.
4. shutDown() stops the active workflow, cancels only the Walker handle owned by this plugin, unregisters UI and break resources, releases the input lock, and clears transient account state.

The plugin must call breakHandler.startPlugin(this) only while AIO work is active. It must call startBreak(this) when a due break begins and release its input lock during the break.

Scheduler

Use one top-level scheduler with these responsibilities:

• Evaluate mandatory preflight before ordinary tasks.
• Filter enabled modules by goals, requirements, cooldowns, and account state.
• Select a task with the old weighted and duration policy.
• Build one preparation workflow for supplies and equipment.
• Pulse one active module workflow.
• Verify task completion, failure, or transition state before selecting again.
• Surface a terminal blocked state when no module can make progress.

The scheduler must not infer completion from DISPATCHED. Each module supplies its own completion predicate and failure reason.

Module contract

Each concrete AIO module must declare:

• Stable module ID and display name.
• Enablement and goal predicate.
• Required inventory, tolerated inventory, protected items, and equipment loadout.
• Whether it needs bank preparation, GE acquisition, or neither.
• Task-duration profile and selection weight.
• Workflow builder and completion predicate.
• Recoverable and terminal failure classification.
• Snapshot fields needed by the panel, overlay, and tests.

Do not expose DreamBot types, blocking delays, or boolean-only interaction results through this contract.

State and persistence

RuneLite configuration stores user choices and goals. Runtime state remains in memory unless the behavior needs restart continuity.

Persist:

• Enabled modules and locations.
• Target levels and task preferences.
• Combat, loot, supply, and economy settings that have a current behavior contract.
• Panel display preferences.

Keep transient:

• Active state-machine state.
• Entity and widget references.
• Walker handles.
• Action pacing and retry counters.
• Observed inventory, equipment, and bank snapshots.

Use a salted account hash only when account-specific deterministic behavior needs it. Do not retain raw account identifiers or create profile files outside RuneLite configuration.

Development phases

Each phase ends with focused tests, documentation updates, and a current diff review. A later phase may start after static acceptance, but no module counts as ported until its live postconditions pass.

Phase 0: Behavior ledger

• Convert every row in the full parity table into an executable acceptance checklist.
• Record old source owners, old verification state, target n3 owners, and missing contracts.
• Capture old settings and defaults that affect behavior.
• Mark DreamBot-only mechanics for deletion.
• Resolve documentation conflicts against live source before coding.

Exit gate: each old module and cross-cutting policy has one disposition and one acceptance owner.

Phase 1: Native plugin shell

• Add AioBuilderPlugin, config, controller, snapshot, panel, overlay, and registration.
• Implement stopped-by-default startup, hotkey control, active-only Break Handler tracking, input-lock ownership, and idempotent shutdown.
• Add login, hop, connection-loss, and plugin-shutdown reset behavior.
• Show current module, workflow state, reason, elapsed task time, and terminal error.

Exit gate: lifecycle tests prove start, stop, break, reset, and cleanup without gameplay actions.

Phase 2: Scheduler and preparation contracts

• Implement module registry, enablement, target goals, weighted selection, task duration, cooldowns, and terminal all-blocked state.
• Represent required, tolerated, protected, and equipped items with SDK loadouts plus AIO policy.
• Add preparation flow for bank, equipment, GE acquisition, and return-to-task.
• Preserve the old taskPrepared invariant: execution starts only after the current loadout passes a fresh observation.

Exit gate: deterministic tests cover empty candidates, all blocked, task completion, task switch, insufficient funds, unknown bank state, loadout failure, and restart reset.

Phase 3: Woodcutting vertical slice

• Port woodcutting progression, axe policy, training spots, competition response, walking, interaction, banking, and target completion.
• Reuse Power Skiller query/action behavior where its contract matches.
• Verify dispatch followed by animation, XP, inventory, or resource-state evidence.

Exit gate: one complete cycle passes offline scenarios and live tests: select, prepare, travel, chop, bank, return, stop, break, and resume.

Phase 4: Gathering and firemaking

• Add Mining, Fishing, and Firemaking.
• Add Port Sarim deposit-box behavior as a shared repair only if another consumer needs it; otherwise keep it in Mining.
• Preserve bait, feather, tinderbox, tool, competition, lane, and location policies.

Exit gate: each module completes a live gather or burn cycle and its distinct bank/deposit path.

Phase 5: Processing skills

• Add Cooking, Smithing, Crafting, Prayer, and Runecrafting.
• Reuse Bank Stander Plus recipes and production actions where their input, facility, widget, and output contracts match.
• Keep multi-stage production on one correlated workflow and observe input/output changes before advancing.
• Add Rune Mysteries gating to Runecrafting without starting the quest from ordinary module selection when preflight already owns it.

Exit gate: each module passes supply exhaustion, missing tool, wrong interface, path failure, output confirmation, and target-completion tests.

Phase 6: Combat and loot

• Add melee, ranged, and magic modules.
• Reuse Fighter loadouts, target selection, combat actions, threat checks, and death-state handling where compatible.
• Port style goals, food thresholds, full-gear readiness, loot value, bones/ashes policy, recent-kill continuity, and competition hopping.
• Fail closed for unsupported crossbows and safe spots.

Exit gate: live tests observe equipment readiness, attack dispatch, combat entry, kill or disengage, loot postconditions, eating, banking, and task completion.

Phase 7: Economy modules

• Add High Alchemy, monster/drop money making, and Wizard's mind-bomb trading.
• Port exact-budget funding, protected-item liquidation, buy limits, retry prices, cooldowns, offer ownership, collection verification, and blocked-task recovery.
• Reuse Market Alcher pure policy and GE action owners after contract comparison.

Exit gate: tests cover partial fills, no coins, unknown bank, buy-limit exhaustion, stale offers, collection, retry cooldown, wrong item, and restart continuity. Live tests must observe GE and inventory postconditions.

Phase 8: Account preflight and quests

• Add mandatory Tutorial Island and Rune Mysteries routing for accounts that need them.
• Add Security Stronghold as its configured task or bootstrap path.
• Reuse existing Tutorial Island and quest infrastructure without driving other plugin UI.
• Preserve quest inventory contracts, dialogue ownership, plane/region checks, and terminal quest-state verification.

Exit gate: scripted scenario coverage passes for each section and recovery path. Fresh-account live acceptance remains a separate required gate.

Phase 9: Parity hardening and release

• Run every module's offline acceptance suite and shared lifecycle contracts.
• Run documentation, Javadoc, packaging, and registration audits.
• Perform live acceptance per module with recorded preconditions and observed postconditions.
• Compare implemented settings and behavior against the Phase 0 ledger.
• Remove compatibility code used only during development.

Exit gate: every in-scope ledger row is complete or carries an explicit, approved deferral. No dispatch-only result counts as live parity.

Validation contract

Static and offline

Use focused JUnit 4 tests and existing fixture/scenario infrastructure. Cover:

• Scheduler selection, blocking, completion, and reset.
• One-action-per-tick behavior and same-tick deduplication.
• Break preemption and input-lock release.
• Known and unknown inventory, equipment, and bank state.
• Required, tolerated, protected, and equipped item reconciliation.
• Interaction status mapping and bounded retries.
• Walker handle ownership and terminal outcomes.
• Logout, hop, connection loss, shutdown, and restart.
• Module-specific progression, acquisition, and completion policy.

Run the shared automation lifecycle, API documentation, focused module, packaging, and documentation tasks selected by .agents/skills/n3-validation/SKILL.md.

Live acceptance

Record these evidence levels separately:

1. The plugin loads and starts.
2. The action owner returns DISPATCHED or another accepted result.
3. RuneLite emits the expected event or state observation.
4. The requested domain postcondition occurs.
5. The complete module cycle reaches its terminal goal.

Use the Agentic Test Loop with a TEST profile when available. Otherwise record manual RuneLite evidence. State Live client verification: pending for every unobserved module or edge case.

Definition of done

The full port is complete when:

• All 18 concrete old gameplay modules have an implemented, reused, or approved-deferred disposition.
• Every implemented module passes focused tests and its live module-cycle acceptance.
• The AIO plugin survives stop, break, logout, hop, disconnect, shutdown, and restart without retaining stale work or input locks.
• Inventory, equipment, bank, GE, Walker, dialogue, production, and combat flows advance from observed postconditions.
• Existing n3 plugins keep their current behavior and no second global runtime owner exists.
• Config, panel, overlay, generated docs, registration, packaging, and maintained contracts remain aligned.
• The final report separates static, package, launch, dispatch, postcondition, and full gameplay evidence.