Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
5fedcce
BDSP AutoStory: stop for Starter RNG at the Verity Lakefront
dayfine Nov 12, 2026
1e1a9bd
Merge branch 'bdsp/starter-rng-callable' into bdsp/autostory-starter-rng
dayfine Nov 12, 2026
2102439
BDSP AutoStory: run Starter RNG in 00.02
dayfine Nov 12, 2026
db63d7e
Merge remote-tracking branch 'origin/bdsp/autostory-v4' into bdsp/aut…
dayfine Nov 12, 2026
b6ec3bc
Merge branches 'bdsp/autostory-starter-rng-handoff' and 'bdsp/starter…
dayfine Nov 12, 2026
76f0726
BDSP AutoStory: red test: the Starter RNG handoff save checks the Ver…
dayfine Nov 13, 2026
1e40b62
BDSP AutoStory: the Starter RNG handoff save checks the card; one han…
dayfine Nov 13, 2026
5824ff6
BDSP AutoStory: document plan_story_run for Code Health
dayfine Nov 13, 2026
d141c1a
BDSP AutoStory: plan_story_run comment names its parameter
dayfine Nov 13, 2026
393c83d
Merge remote-tracking branch 'origin/bdsp/starter-rng-callable' into …
dayfine Nov 13, 2026
fa59f9c
Merge origin/bdsp/autostory-starter-rng-handoff into bdsp/autostory-s…
dayfine Nov 13, 2026
fe6aa23
BDSP AutoStory: Starter RNG default row, player model option, fatal o…
dayfine Nov 13, 2026
bd1b9da
BDSP AutoStory Starter RNG: lint fixes (private options, split tests …
dayfine Nov 13, 2026
29a2278
BDSP AutoStory Starter RNG: const filters accessor
dayfine Nov 13, 2026
89b2d42
BDSP AutoStory Starter RNG: drop const filters accessor
dayfine Nov 13, 2026
7a46b79
AutoStory: shared RNG handoff contract; BDSP Starter RNG adopts it
dayfine Nov 13, 2026
1836dd3
AutoStory: shared RNG handoff contract
dayfine Nov 13, 2026
00624b4
AutoStory RNG handoff: a program's end can be the user's turn
dayfine Nov 13, 2026
eed3b65
AutoStory RNG handoff: options struct for the mode, test table
dayfine Nov 13, 2026
bb44bba
Merge autostory/rng-handoff into bdsp/autostory-starter-rng
dayfine Nov 13, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
#include "Pokemon_StoryEvents_Tests.h"
#include "Pokemon_StoryInterrupts_Tests.h"
#include "Pokemon_StoryLog_Tests.h"
#include "Pokemon_StoryRngHandoff_Tests.h"
#include "Pokemon_StorySavePolicy_Tests.h"
#include "Pokemon_StorySegments_Tests.h"
#include "Pokemon_StoryStepExecutor_Tests.h"
Expand All @@ -44,6 +45,7 @@ inline void add_tests_AutoStory(UnitTestDatabase& database){
add_tests_StoryRun(database);
add_tests_AutoStoryStats(database);
add_tests_StoryLog(database);
add_tests_StoryRngHandoff(database);
add_tests_StoryRangeOptions(database);
add_tests_StoryEvents(database);
add_tests_StorySegments(database);
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
/* Story RNG Handoff
*
* From: https://github.com/PokemonAutomation/
*
*/

#include "Common/Cpp/Color.h"
#include "Common/Cpp/Exceptions.h"
#include "CommonFramework/Exceptions/OperationFailedException.h"
#include "Pokemon_StoryRngHandoff.h"

namespace PokemonAutomation{
namespace Pokemon{


RngHandoffMode rng_handoff_mode(const RngHandoffOptions& options){
if (options.run){
return RngHandoffMode::RUN;
}
return options.stop ? RngHandoffMode::STOP : RngHandoffMode::OFF;
}

bool RngHandoffResult::succeeded() const{
return failure.empty();
}

std::optional<std::string> run_rng_handoff_or_user_turn(
Logger& logger, const std::string& program, const RngHandoffCall& call
){
const RngHandoffResult result = call();
if (!result.succeeded()){
throw_and_log<OperationFailedException>(logger, ErrorReportMode::SEND_ERROR_REPORT, result.failure);
}
if (!result.user_turn.empty()){
logger.log(program + " stopped for the user: " + result.user_turn, COLOR_BLUE);

Check warning on line 35 in SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRngHandoff.cpp

View workflow job for this annotation

GitHub Actions / code-health

Code health (advisory)

style: build strings with std::format, not + on a literal / std::to_string / std::string (fork AGENTS.md "Strings")
return result.user_turn;
}
logger.log(program + " succeeded: " + result.summary, COLOR_BLUE);

Check warning on line 38 in SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRngHandoff.cpp

View workflow job for this annotation

GitHub Actions / code-health

Code health (advisory)

style: build strings with std::format, not + on a literal / std::to_string / std::string (fork AGENTS.md "Strings")
return std::nullopt;
}

Outcome run_rng_handoff(Logger& logger, const std::string& program, const RngHandoffCall& call){
const std::optional<std::string> user_turn = run_rng_handoff_or_user_turn(logger, program, call);
if (user_turn){
// A story action has no stop to give the user's turn to.
throw_and_log<OperationFailedException>(logger, ErrorReportMode::SEND_ERROR_REPORT, *user_turn);
}
return outcome_ok();
}


} // namespace Pokemon
} // namespace PokemonAutomation
86 changes: 86 additions & 0 deletions SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRngHandoff.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
/* Story RNG Handoff

Check warning on line 1 in SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRngHandoff.h

View workflow job for this annotation

GitHub Actions / code-health

Code health (advisory)

<header>: header_symbols=7 (advisory above 6, limit 8)
*
* From: https://github.com/PokemonAutomation/
*
* The part of an AutoStory run that hands the game to an RNG program (BDSP
* Starter RNG, FRLG Starter RNG and Gift RNG) and takes it back. A game
* supplies the program's call; the contract around it is shared:
*
* - A handoff row has a mode: OFF (the story plays it by hand), STOP (the run
* ends after the row's handoff save, for the user to run the RNG program)
* or RUN (the story calls the RNG program itself and continues).
* - The call ends in an RngHandoffResult: no failure means the game stands
* where the story goes on; a failure is the reason it does not. A game
* whose program can also end where the user takes over (FRLG: the target
* hit but not shiny, the attempts spent) gives that end a user_turn, which
* is a stop and not an error. What the story runs after a continuation
* (FRLG: the rows after a shiny) is the game's, built from the call.
* - A failed RUN stops the program. It never retries the row: the program's
* own reset loop is the retry, and a reload of the save would lose a
* shiny it caught.
*
*/

#ifndef PokemonAutomation_Pokemon_StoryRngHandoff_H
#define PokemonAutomation_Pokemon_StoryRngHandoff_H

#include <functional>
#include <optional>
#include <string>
#include "Common/Cpp/Logging/AbstractLogger.h"
#include "Pokemon_StoryOutcome.h"

namespace PokemonAutomation{
namespace Pokemon{


// What a handoff row does with its RNG program.
enum class RngHandoffMode{
OFF,
STOP,
RUN,
};

// A handoff's two options.
struct RngHandoffOptions{
bool stop = false;
bool run = false;
};

// The mode for a handoff's two options: RUN takes precedence over STOP.
RngHandoffMode rng_handoff_mode(const RngHandoffOptions& options);


// How an RNG program's call ended, as the story needs it.
struct RngHandoffResult{
// Empty: the game stands where the story goes on. Otherwise why it does not.
std::string failure;
// What a success did, for the log: the resets used, the target hit.
std::string summary;
// Not empty (and no failure): the program ended where the user takes
// over, with this for them. The run stops without an error report.
std::string user_turn;

bool succeeded() const;
};

// The call a handoff row runs in place of its steps.
using RngHandoffCall = std::function<RngHandoffResult()>;

// Runs `call` for the RNG program `program` ("Starter RNG"). A success is
// logged with its summary and returned as an ok Outcome. A failure throws
// OperationFailedException with an error report, so that no row retry
// reruns the program's reset loop.
Outcome run_rng_handoff(Logger& logger, const std::string& program, const RngHandoffCall& call);

// As run_rng_handoff(), for a program whose call may end in the user's turn:
// returns that message, which is logged, and the run stops there. Returns
// nothing when the game stands where the story goes on.
std::optional<std::string> run_rng_handoff_or_user_turn(
Logger& logger, const std::string& program, const RngHandoffCall& call
);


} // namespace Pokemon
} // namespace PokemonAutomation
#endif
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
/* Story RNG Handoff Tests
*
* From: https://github.com/PokemonAutomation/
*
*/

#include <format>
#include <optional>
#include <string>
#include <string_view>
#include "Common/Cpp/TestRunners/UnitTest.h"
#include "CommonFramework/Exceptions/OperationFailedException.h"
#include "Pokemon_StoryRngHandoff.h"
#include "Pokemon_StoryRngHandoff_Tests.h"

namespace PokemonAutomation{
namespace Pokemon{

namespace{

struct RngHandoffInput{
std::string_view name;
UnitTestResult (*body)(Logger& logger);
};

struct RngHandoffExpectation{
std::string_view description;
};

struct RngHandoffTestCase{
RngHandoffInput input;
RngHandoffExpectation expectation;
};

class Test_RngHandoff : public UnitTest{
public:
explicit Test_RngHandoff(RngHandoffTestCase scenario)
: UnitTest("Pokemon::StoryRngHandoff - " + std::string(scenario.input.name))

Check warning on line 38 in SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRngHandoff_Tests.cpp

View workflow job for this annotation

GitHub Actions / code-health

Code health (advisory)

style: build strings with std::format, not + on a literal / std::to_string / std::string (fork AGENTS.md "Strings")
, m_scenario(scenario)
{}

virtual UnitTestResult run(Logger& logger, CancellableScope&) const override{
return m_scenario.input.body(logger);
}

private:
RngHandoffTestCase m_scenario;
};

// rng_handoff_mode()'s two options.
UnitTestResult test_mode(Logger&){
struct Case{
RngHandoffOptions options;
RngHandoffMode expected;
};
const Case cases[] = {
{.options = {.stop = false, .run = false}, .expected = RngHandoffMode::OFF},
{.options = {.stop = true, .run = false}, .expected = RngHandoffMode::STOP},
{.options = {.stop = false, .run = true}, .expected = RngHandoffMode::RUN},
{.options = {.stop = true, .run = true}, .expected = RngHandoffMode::RUN},
};
for (const Case& item : cases){
if (rng_handoff_mode(item.options) != item.expected){
return std::format("stop={}, run={}: wrong mode", item.options.stop, item.options.run);
}
}
return true;
}

// A success is an ok Outcome and calls the program once.
UnitTestResult test_success(Logger& logger){
int calls = 0;
const Outcome outcome = run_rng_handoff(logger, "Test RNG", [&]{
calls++;
return RngHandoffResult{.summary = "2 resets"};
});
if (!outcome.succeeded()){
return "Expected an ok outcome";
}
if (calls != 1){
return std::format("Expected 1 call, got {}", calls);
}
return true;
}

// A failure throws, once: nothing reruns the program.
UnitTestResult test_failure(Logger& logger){
int calls = 0;
try{
run_rng_handoff(logger, "Test RNG", [&]{
calls++;
return RngHandoffResult{.failure = "out of resets"};
});
}catch (OperationFailedException&){
if (calls != 1){
return std::format("Expected 1 call, got {}", calls);
}
return true;
}
return "Expected OperationFailedException";
}

// The user's turn is returned, not thrown, once; a success has none; a
// failure throws even with one.
UnitTestResult test_user_turn(Logger& logger){

Check warning on line 105 in SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRngHandoff_Tests.cpp

View workflow job for this annotation

GitHub Actions / code-health

Code health (advisory)

PokemonAutomation::Pokemon::test_user_turn( Logger & logger): function_lines=27 (advisory above 25, limit 50)
int calls = 0;
const std::optional<std::string> turn = run_rng_handoff_or_user_turn(logger, "Test RNG", [&]{
calls++;
return RngHandoffResult{.user_turn = "save by hand"};
});
if (!turn || *turn != "save by hand"){
return "Expected the user's turn";
}
if (calls != 1){
return std::format("Expected 1 call, got {}", calls);
}
const std::optional<std::string> none = run_rng_handoff_or_user_turn(logger, "Test RNG", []{
return RngHandoffResult{.summary = "shiny"};
});
if (none){
return "A success has no user's turn";
}
try{
run_rng_handoff_or_user_turn(logger, "Test RNG", []{
return RngHandoffResult{.failure = "out of resets", .user_turn = "ignored"};
});
}catch (OperationFailedException&){
return true;
}
return "A failure must throw even with a user's turn";
}

const RngHandoffTestCase RNG_HANDOFF_CASES[] = {
{
.input = {.name = "RUN takes precedence over STOP", .body = test_mode},
.expectation = {.description = "RUN wins when both options are on"},
},
{
.input = {.name = "a success is ok", .body = test_success},
.expectation = {.description = "an ok outcome after one call"},
},
{
.input = {.name = "a failure throws without a retry", .body = test_failure},
.expectation = {.description = "OperationFailedException after one call"},
},
{
.input = {.name = "a user's turn is returned, not an error", .body = test_user_turn},
.expectation = {.description = "the message comes back; a failure still throws"},
},
};

} // namespace


void add_tests_StoryRngHandoff(UnitTestDatabase& database){
for (const RngHandoffTestCase& scenario : RNG_HANDOFF_CASES){
database.add<Test_RngHandoff>(scenario);
}
}


} // namespace Pokemon
} // namespace PokemonAutomation
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
/* Story RNG Handoff Tests
*
* From: https://github.com/PokemonAutomation/
*
*/

#ifndef PokemonAutomation_Pokemon_StoryRngHandoff_Tests_H
#define PokemonAutomation_Pokemon_StoryRngHandoff_Tests_H

#include "Common/Cpp/TestRunners/UnitTestDatabase.h"

namespace PokemonAutomation{
namespace Pokemon{


// Registers unit tests for the shared RNG handoff contract.
void add_tests_StoryRngHandoff(UnitTestDatabase& database);



} // namespace Pokemon
} // namespace PokemonAutomation
#endif
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,16 @@



// 00.02 with Run Starter RNG in AutoStory: runs Starter RNG from the
// Verity Lakefront (17, 14) start save through the Starly battle and
// Rowan's scene, ending on the VerityLakefront overworld at (17, 14..15).
Pokemon::Outcome starter_rng(StoryExecutor& executor, Pokemon::RunState&, const Pokemon::StoryStep&){

Check warning on line 124 in SerialPrograms/Source/PokemonBDSP/Programs/AutoStory/Actions/PokemonBDSP_AutoStory_Events_Lake.cpp

View workflow job for this annotation

GitHub Actions / code-health

Code health (advisory)

style: starter_rng: output parameter 'StoryExecutor& executor' comes before an input; put inputs (by value, const&) first and non-const references last (Google "Function Parameter Ordering")
if (!executor.env().run_starter_rng){
return Pokemon::outcome_failed("starter_rng_not_configured", "Starter RNG is not configured on StoryEnv.");
}
return executor.env().run_starter_rng();
}

// 00.04: Dawn's catching tutorial on Route 202: her lines and her demo
// battle, B for 70 s.
void catch_tutorial(VideoStream& stream, ProControllerContext& context){
Expand All @@ -134,6 +144,7 @@
events.emplace("azure_flute_if_there", console_event(azure_flute_if_there));
events.emplace("starter_briefcase", console_event(starter_briefcase));
events.emplace("choose_starter", choose_starter);
events.emplace("starter_rng", starter_rng);


events.emplace("catch_tutorial", console_event(catch_tutorial));
Expand Down
Loading
Loading