[Developer-Butters]

User Testing

Since this is here and people might test it while it's a WIP, there is a preliminary wiki page at https://github.com/Developer-Butters/pokemonautomation.github.io/blob/BDSP/AutoStory/docs/Programs/PokemonBDSP/AutoStory.md. It describes the current necessary set up post tutorial IT IS ALSO A DRAFT! I will edit it more for a final copy the important part is IV/EV training and move list (though the move list is also still being revised). The "No Outside Help Mode" is not finished. you should get an error if you try to run that option.

Purpose

This WIP PR serves as the main overview of the BDSP Autostory Project. It is primarily modeled after the SV autostory, although several things necessarily differ dure to the game mechanics. This has been a collaborative endeavor with Boombaastical, ArceusMI, GumGumDragoon, and myself(Developer-Butters), so there are different coding styles that need to be normalized and cleaned up as we work to finish this project. There are also several areas where we have used AI to rewatch video play throughs of the project and allowed it to make adjustments. As a WIP, nothing is final and it is not officially ready for review.

This draft presents the overall design for early feedback. It does not represent a finished or fully validated program. It also relies on a branch of the Packages Repo which will have its own set of PRs as we create smaller ones for full merge. I have included our current roadmap below.

I have used AI to summarize discussions the team has had below and outline the current status of the project, outstanding issues, and future design ideas and features.

ArceusMI brought up that this may be overkill for the PR, but I have a habit of liking to overexplain than underexplain. I will try to be more concise in the future smaller PRs and update this one with any new macro information or design changes.

Current work in Progress

• Complete Segment 03 and validate existing Segments 04–09. (assigned Developer Butters)
• Consolidate overlapping helpers and remove obsolete code and documentation. (assigned ArceusMI and GumGumDragoon)

Architecture compared with SV AutoStory

BDSP largely follows SV AutoStory’s program structure:

• Single-switch program with tutorial and main-story selection.
• Normal segment mode and advanced checkpoint mode.
• Common segment/checkpoint interfaces and ordered registries.
• Options and statistics passed through route execution.
• Checkpoint-oriented saving, retries, and game resets.

Our goal is to make program-level behavior nearly identical wherever practical, including configuration, startup checks, checkpoint contracts, notifications, error reporting, statistics, and developer controls. However, BDSP’s menus and graphics have made some things difficult to recreate from SV AutoStory.

Game mechanics require some differences. BDSP navigation uses landmark matching, wall alignment, doorway detection, and interruptible movement rather than SV’s minimap, camera, and map-marker systems. We’ve also been unable so far to reliably verify that the game is saved before moving on. In practice, we have observed the save sequence working, but we haven’t been able to make the program reliably verify that the save completed.

Current program-level gaps include recoverable-error reporting, checkpoint context in retry logs, startup validation, diagnostic gating, and incomplete recovery paths. These are tracked separately from justified game limitations.

Current implementation

Segments 00–09 are registered.

• Segments 00–01: Tutorial and first-badge routes exist and have received substantial reliability work; broader validation remains.
• Segment 02: Route and detector work exists through the approach to Eterna; checkpoint handoffs and recovery need continued validation.
• Segment 03: Active implementation and validation, including Eterna, Galactic HQ, bike acquisition, and Cycling Road.
• Segments 04–09: Existing route implementations to test and audit for missing functionality and unsupported states.

Reference images and other assets live in the separate Packages repository. Required source and resource revisions must be coordinated.

Testing

Testing so far has included Windows with an ESP32-S3 controller using both Switch 1 and Switch 2 consoles, as well as macOS.

Validation is ongoing; full-story reliability, all-language compatibility, and recovery coverage remain work in progress.

We will need additional testign with the other supported controllers as we approach a final product.

Offline-test cleanup (2026-10-24)

BDSP code now uses the project JSON and UTF-8 filesystem utilities in place of Qt file/resource lookup and direct filesystem calls. The main unit-test runner registers the BDSP Bag/menu suites and resolves fixtures through UNIT_TEST_RESOURCE_PATH().

Coordinated revisions:

• Arduino-Source cleanup 65094d4cd.
• CommandLineTests fixtures fb26d17 on BDSP-Autostory.
• Packages fixture removal ad4647b on BDSP-Autostory.

The BDSP screenshot suites require the CommandLineTests revision above. Runtime reference images remain in Packages. Packages and CommandLineTests do not yet have companion PRs.

Validation: Windows Debug build passed; 478 Bag checks and 26 menu checks passed; 15 additional resource/error/layout checks passed, including non-ASCII paths and isolated development/installed resource discovery. All 3,159 source files in the CI tab-check scope were tab-free.

Full local command-line suite: 29,465 passed, 928 failed, zero skipped. The failure count matches the pre-cleanup run; logs include missing PaddleOCR model, image resources, and MP3 fixtures. Live route validation remains ongoing.

Preliminary roadmap

The original five phases remain our planning framework. Some work overlaps, and the roadmap will be refined as we validate the remaining routes.

1. Setup: Research and document the route, develop the user experience, identify information sources, and account for moving NPCs and key fights. Review existing routes for missing information rather than assume they need to be rebuilt.
2. Streamlining: Use joystick movement where appropriate, develop and reuse helpers, improve NPC and location detection, and refine trainer-based battle handling. Determine money and item requirements at relevant cities and maintain buy lists. Optimize movement against a validated route baseline.
3. Cleanup: Consolidate reusable helpers, remove obsolete files and documentation, and normalize coding style and formatting. Keep route-specific sequences in their segment files and review checkpoint descriptions together with their actual boundaries.
4. Beta testing and release preparation: Broaden testing across supported controllers, consoles, platforms, and languages. Validate checkpoint recovery and coordinate source and Packages changes before final merge and release.
5. Future implementation: Identify desired upgrades, determine the changes they require, and plan them with clear dependencies and acceptance criteria. Candidates include further movement optimization, capture-hardware robustness testing, and improved developer testing and diagnostics.

Remaining work

• Align program behavior with SV wherever practical and document justified deviations.
• Support and validate every language supported by BDSP.
• Make retained diagnostics developer-mode only, or remove them before final merge.
• Complete checkpoint save/retry contracts and unsupported recovery paths.
• Validate starter species, level, party position, and required moves before main-story movement.
• Handle fainted-starter and unexpected battle states.
• Verify checkpoint starting positions, endpoints, state, and reset recovery.
• Audit and publish required Packages resources.
• Complete clean-checkout, CI, and live regression validation before final merge.
• Create the "unassisted" mode route modifiers (this is future implementation)

Requested feedback

We would appreciate feedback on the SV-derived architecture, checkpoint and recovery contracts, BDSP helper/detector boundaries, resource distribution, and the order in which to extract focused PRs.

[Developer-Butters]

A note about some of the standalone test programs: these are not intended for use beyond the project and will be removed at a later date.

[Developer-Butters]

in light of the contributions.md and agents.md that have been added recently to the upstream/main project, I'm also conducting an audit of our code to identify anything that goes against these documents. Anything that goes against those documents will be updated as I identify them.

[Dalton-V]

I'd strongly recommend adding tests and test images for all new and edited inference classes.

[Dalton-V]

This file can probably get removed? I saw the comment about remove obsolete code, maybe this was already on that list.

[Developer-Butters]

there's a lot that needs to be cleaned up, but yeah I'll make sure this one gets the axe.

[Mysticial]

As discussed on Discord, it's going to be a long process to get this fully in. But the obvious starting point would be all the new detectors.

I would do a separate PR for each detector - complete with tests and their corresponding images in the CommandLineTests repo.

[Dalton-V]

Hey, it's me again with another nitpick. 😄

Today we updated our contributing.md and agents.md with some code formatting and patterns that we try to follow.

So here is another thing to cleanup once this is ready to leave draft. If statements should be block format and not inline.

So this if statement should look like:

if (!is_white(left_white)){
    return false;
}

For more information and examples see the updated docs:
https://github.com/PokemonAutomation/Arduino-Source/blob/main/CONTRIBUTING.md#coding-conventions-and-program-patterns
https://github.com/PokemonAutomation/Arduino-Source/blob/main/CONTRIBUTING.md#coding-conventions-and-program-patterns

[Developer-Butters]

cool. I'll make sure this gets implemented before it gets finalized.