From 6715b24da57034a822807ce040d1fa257152f248 Mon Sep 17 00:00:00 2001 From: Di Fan <26423504+dayfine@users.noreply.github.com> Date: Sat, 31 Oct 2026 09:21:36 -0700 Subject: [PATCH 01/49] Lab: set up lab/main, the base for lab builds (#92) * Add Command File Runner, a developer program driven by text command files Answering "does this detector fire on that screen?" meant a rebuild and a full program run. Command File Runner runs .txt files dropped into /inbox against the live console, one command per line (press, dpad, stick, wait, shot/shots, detect, wait_for/expect, state, close_game, help, stop), and writes a timed result file with screenshots to /outbox, stopping a file at its first failing line. Options set the command folder and whether to stop once the inbox is empty. Games can register their own commands and detectors. README.md next to the code documents the file format and every command; like the other testing programs it has no page on the documentation site. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E * Command File Runner: unit tests for reading command files Moves the line splitting, button and D-pad names and the inbox order into their own file, unchanged, and tests them without a console. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E * Command File Runner: replace CommandLine with free functions A command line is now just its words: split_command_line() returns them, and required_arg(), optional_number() and optional_duration() read arguments from them, with the same error messages. All definitions move to the .cpp. Adds a unit test for the argument readers and checks the error messages. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E * Command File Runner: read numbers with strtod() instead of std::stod() On the macOS Intel CI build, the std::invalid_argument from std::stod() escapes the catch (std::exception&), so the "argument errors" test failed with "Unknown exception". strtod() reports a bad number without throwing; the error message is unchanged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E * Command File Runner: walk until the screen holds still, and report how long it moved A timed stick hold moves a different number of tiles from one try to the next, so a map measured with holds is not measured. "walk x y" holds the left stick in 200 ms slices and stops when two slices in a row barely change the screen (a wall, a sign, someone in the way). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E * Command File Runner: 'history label' saves the console's recent video With Stream History on, a lab script can keep the video of a program run that just ended (the RNG reset and launch) by running this right after. Ported from beceebc71 on lab/frlg-nav-cfr to the free-function command signature. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E --------- Co-authored-by: Claude Opus 5.5 --- .../ComputerPrograms_UnitTestRunner.cpp | 2 + .../NintendoSwitch/NintendoSwitch_Panels.cpp | 2 + .../NintendoSwitch_CommandFileParsing.cpp | 105 ++++ .../NintendoSwitch_CommandFileParsing.h | 54 ++ .../NintendoSwitch_CommandFileRunner.cpp | 540 ++++++++++++++++++ .../NintendoSwitch_CommandFileRunner.h | 98 ++++ ...NintendoSwitch_CommandFileRunner_Tests.cpp | 172 ++++++ .../NintendoSwitch_CommandFileRunner_Tests.h | 22 + .../Programs/CommandFileRunner/README.md | 126 ++++ SerialPrograms/cmake/SourceFiles.cmake | 6 + 10 files changed, 1127 insertions(+) create mode 100644 SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileParsing.cpp create mode 100644 SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileParsing.h create mode 100644 SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileRunner.cpp create mode 100644 SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileRunner.h create mode 100644 SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileRunner_Tests.cpp create mode 100644 SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileRunner_Tests.h create mode 100644 SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/README.md diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp index 61b81d1059..e1c2c26d55 100644 --- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp +++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp @@ -26,6 +26,7 @@ #include "NintendoSwitch/Inference/NintendoSwitch_CheckOnlineDetector.h" #include "NintendoSwitch/Inference/NintendoSwitch_FailedToConnectDetector.h" #include "NintendoSwitch/Inference/NintendoSwitch_UpdatePopupDetector.h" +#include "NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileRunner_Tests.h" #include "NintendoSwitch/Programs/Typewriter/NintendoSwitch_Typewriter_Tests.h" #include "VideoGames/PokemonHome/PokemonHome_Tests.h" @@ -63,6 +64,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){ NintendoSwitch::add_tests_CheckOnlineDetector(ret); NintendoSwitch::add_tests_FailedToConnectDetector(ret); NintendoSwitch::add_tests_UpdatePopupDetector(ret); + NintendoSwitch::add_tests_CommandFileRunner(ret); NintendoSwitch::Typewriter::add_tests_TypewriterTextMapping(ret); NintendoSwitch::PokemonFRLG::add_tests(ret); NintendoSwitch::PokemonRSE::add_tests(ret); diff --git a/SerialPrograms/Source/NintendoSwitch/NintendoSwitch_Panels.cpp b/SerialPrograms/Source/NintendoSwitch/NintendoSwitch_Panels.cpp index 2979a83f4b..16ff56933b 100644 --- a/SerialPrograms/Source/NintendoSwitch/NintendoSwitch_Panels.cpp +++ b/SerialPrograms/Source/NintendoSwitch/NintendoSwitch_Panels.cpp @@ -21,6 +21,7 @@ #include "Programs/NintendoSwitch_TurboMacro.h" #include "Programs/NintendoSwitch_PushJoySticks.h" #include "Programs/NintendoSwitch_PreventSleep.h" +#include "Programs/CommandFileRunner/NintendoSwitch_CommandFileRunner.h" #include "Programs/NintendoSwitch_FriendCodeAdder.h" #include "Programs/NintendoSwitch_FriendDelete.h" #include "Programs/NintendoSwitch_RecordKeyboardController.h" @@ -78,6 +79,7 @@ std::vector PanelListFactory::make_panels() const{ ret.emplace_back("---- Testing ----"); ret.emplace_back(GameConsole::make_ConsolePanel()); ret.emplace_back(GameConsole::make_ConsoleProgram()); + ret.emplace_back(make_SingleSwitchProgram()); if (STATIC_GLOBALS.DEVELOPER_MODE){ ret.emplace_back("---- Developer Tools ----"); diff --git a/SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileParsing.cpp b/SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileParsing.cpp new file mode 100644 index 0000000000..8039699fe0 --- /dev/null +++ b/SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileParsing.cpp @@ -0,0 +1,105 @@ +/* Command File Parsing + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include +#include +#include "Common/Cpp/Exceptions.h" +#include "NintendoSwitch_CommandFileParsing.h" + +namespace PokemonAutomation{ +namespace NintendoSwitch{ + + +std::vector split_command_line(const std::string& line){ + std::vector words; + std::istringstream in(line); + std::string word; + while (in >> word && word[0] != '#'){ + words.push_back(word); + } + return words; +} + +const std::string& required_arg(const std::vector& words, size_t index){ + if (index >= words.size()){ + throw ParseException(words[0] + ": missing argument " + std::to_string(index)); + } + return words[index]; +} + +double optional_number(const std::vector& words, size_t index, double fallback){ + if (index >= words.size()){ + return fallback; + } + // strtod() rather than std::stod(): on the macOS Intel CI build, the + // std::invalid_argument that std::stod() throws is not caught as a + // std::exception. + const char* begin = words[index].c_str(); + char* end = nullptr; + errno = 0; + const double value = std::strtod(begin, &end); + if (end == begin || errno == ERANGE){ + throw ParseException(words[0] + ": argument " + std::to_string(index) + " is not a number: " + words[index]); + } + return value; +} + +Milliseconds optional_duration(const std::vector& words, size_t index, Milliseconds fallback){ + return Milliseconds((int64_t)optional_number(words, index, (double)fallback.count())); +} + + +Button parse_buttons(const std::string& text){ + static const std::map NAMES{ + {"A", BUTTON_A}, {"B", BUTTON_B}, {"X", BUTTON_X}, {"Y", BUTTON_Y}, + {"L", BUTTON_L}, {"R", BUTTON_R}, {"ZL", BUTTON_ZL}, {"ZR", BUTTON_ZR}, + {"PLUS", BUTTON_PLUS}, {"MINUS", BUTTON_MINUS}, + {"LCLICK", BUTTON_LCLICK}, {"RCLICK", BUTTON_RCLICK}, + {"HOME", BUTTON_HOME}, {"CAPTURE", BUTTON_CAPTURE}, + }; + Button buttons = BUTTON_NONE; + std::istringstream in(text); + std::string name; + while (std::getline(in, name, '+')){ + auto iter = NAMES.find(name); + if (iter == NAMES.end()){ + throw ParseException("Unknown button: " + name); + } + buttons = (Button)(buttons | iter->second); + } + return buttons; +} + +DpadPosition parse_dpad(const std::string& text){ + static const std::map NAMES{ + {"UP", DPAD_UP}, {"DOWN", DPAD_DOWN}, {"LEFT", DPAD_LEFT}, {"RIGHT", DPAD_RIGHT}, + }; + auto iter = NAMES.find(text); + if (iter == NAMES.end()){ + throw ParseException("Unknown D-pad direction: " + text); + } + return iter->second; +} + +std::optional next_command_file(const std::string& inbox){ + std::optional next; + for (const Filesystem::Path& path : Filesystem::list_directory(Filesystem::Path(inbox))){ + if (!Filesystem::is_regular_file(path) || path.extension().string() != ".txt"){ + continue; + } + if (!next || path.string() < next->string()){ + next = path; + } + } + return next; +} + + + +} +} diff --git a/SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileParsing.h b/SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileParsing.h new file mode 100644 index 0000000000..28ca34fd76 --- /dev/null +++ b/SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileParsing.h @@ -0,0 +1,54 @@ +/* Command File Parsing + * + * From: https://github.com/PokemonAutomation/ + * + * Reading command files for the Command File Runner: the words of a line, + * button and D-pad names, and which inbox file runs next. + * + */ + +#ifndef PokemonAutomation_NintendoSwitch_CommandFileParsing_H +#define PokemonAutomation_NintendoSwitch_CommandFileParsing_H + +#include +#include +#include +#include "Common/Cpp/Time.h" +#include "Common/Cpp/Filesystem/Filesystem.h" +#include "NintendoSwitch/Controllers/NintendoSwitch_ControllerButtons.h" + +namespace PokemonAutomation{ +namespace NintendoSwitch{ + + +// The words of one line of a command file. A word starting with '#' starts +// a comment that runs to the end of the line. Word 0 is the command name. +std::vector split_command_line(const std::string& line); + +// Word `index` of a command line. Throws ParseException if it is missing. +const std::string& required_arg(const std::vector& words, size_t index); + +// Word `index` as a number, or `fallback` if it is missing. Throws +// ParseException if it is not a number. +double optional_number(const std::vector& words, size_t index, double fallback); + +// Word `index` as a number of milliseconds, or `fallback` if it is missing. +// Throws ParseException if it is not a number. +Milliseconds optional_duration(const std::vector& words, size_t index, Milliseconds fallback); + + +// A button name, or several joined with '+' (e.g. "L+R"). Throws +// ParseException for an unknown name. +Button parse_buttons(const std::string& text); + +// "UP", "DOWN", "LEFT" or "RIGHT". Throws ParseException otherwise. +DpadPosition parse_dpad(const std::string& text); + +// The ".txt" file in `inbox` whose name sorts first, if any. +std::optional next_command_file(const std::string& inbox); + + + +} +} +#endif diff --git a/SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileRunner.cpp b/SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileRunner.cpp new file mode 100644 index 0000000000..8ad10e6d07 --- /dev/null +++ b/SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileRunner.cpp @@ -0,0 +1,540 @@ +/* Command File Runner + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include +#include +#include "Common/Cpp/Exceptions.h" +#include "Common/Cpp/Concurrency/Mutex.h" +#include "Common/Cpp/Filesystem/Filesystem.h" +#include "Common/Cpp/Filesystem/FileIO.h" +#include "CommonFramework/GlobalAutoPaths.h" +#include "CommonFramework/ImageTools/ImageDiff.h" +#include "CommonFramework/ImageTypes/ImageRGB32.h" +#include "CommonFramework/Exceptions/OperationFailedException.h" +#include "CommonFramework/VideoPipeline/VideoFeed.h" +#include "CommonTools/VisualDetectors/BlackScreenDetector.h" +#include "NintendoSwitch/Commands/NintendoSwitch_Commands_PushButtons.h" +#include "NintendoSwitch/Inference/NintendoSwitch_HomeMenuDetector.h" +#include "NintendoSwitch/Inference/NintendoSwitch_StartGameUserSelectDetector.h" +#include "NintendoSwitch/Programs/NintendoSwitch_GameEntry.h" +#include "NintendoSwitch_CommandFileParsing.h" +#include "NintendoSwitch_CommandFileRunner.h" + +namespace PokemonAutomation{ +namespace NintendoSwitch{ + +using namespace std::chrono_literals; + + +namespace{ + +// Defaults for timings a command line leaves out. +constexpr Milliseconds BUTTON_HOLD = 160ms; // Long enough for every game to see the press. +constexpr Milliseconds BUTTON_RELEASE = 160ms; +constexpr Milliseconds DPAD_HOLD = 100ms; // One menu step without auto-repeat. +constexpr Milliseconds DPAD_RELEASE = 200ms; +constexpr Milliseconds STICK_HOLD = 160ms; +constexpr Milliseconds STICK_RELEASE = 160ms; +constexpr Milliseconds SHOTS_INTERVAL = 500ms; +constexpr Milliseconds WAIT_FOR_TIMEOUT = 5000ms; + +// "walk": the stick is held in slices this long, and the frames between +// slices are compared (RMSD at 192x108). Two slices in a row under the +// threshold count as standing still against something. +constexpr Milliseconds WALK_SLICE = 200ms; +constexpr Milliseconds WALK_LIMIT = 5000ms; +constexpr double WALK_STILL_RMSD = 10; + +// How often "wait_for" and "expect" check a new frame. +constexpr Milliseconds DETECTOR_POLL_INTERVAL = 100ms; + +// How often an empty inbox is checked for a new file. +constexpr Milliseconds INBOX_POLL_INTERVAL = 500ms; + + + +struct Registry{ + Mutex lock; + std::map detectors; + std::map> commands; // name -> usage, command +}; +Registry& registry(){ + static Registry registry; + return registry; +} + +// Detectors every game can use. +void register_builtin_detectors(){ + static const bool registered = []{ + register_command_file_detector("black", [](ConsoleHandle&){ return std::make_unique(); }); + register_command_file_detector("white", [](ConsoleHandle&){ return std::make_unique(); }); + register_command_file_detector("home", [](ConsoleHandle& console){ return std::make_unique(console, COLOR_RED); }); + register_command_file_detector("user_select", [](ConsoleHandle& console){ return std::make_unique(console); }); + return true; + }(); + (void)registered; +} + +std::unique_ptr make_detector(const std::string& name, ConsoleHandle& console){ + Registry& r = registry(); + LockGuard lg(r.lock); + auto iter = r.detectors.find(name); + if (iter == r.detectors.end()){ + throw ParseException("Unknown detector: " + name + " (try \"help\")"); + } + return iter->second(console); +} + +std::optional find_registered_command(const std::string& name){ + Registry& r = registry(); + LockGuard lg(r.lock); + auto iter = r.commands.find(name); + if (iter == r.commands.end()){ + return std::nullopt; + } + return iter->second.second; +} + +} + + + +void register_command_file_command(const std::string& name, const std::string& usage, CommandFileCommand command){ + Registry& r = registry(); + LockGuard lg(r.lock); + r.commands[name] = {usage, std::move(command)}; +} +void register_command_file_detector(const std::string& name, CommandFileDetectorFactory factory){ + Registry& r = registry(); + LockGuard lg(r.lock); + r.detectors[name] = std::move(factory); +} + + + +namespace{ + +// Runs the lines of one command file. +class LineRunner{ +public: + LineRunner(CommandFileSession& session, std::string name) + : m_session(session) + , m_name(std::move(name)) + {} + + // Runs one line. Returns false for "stop". Throws to fail the line. + bool run(const std::vector& words){ + if (words[0] == "stop"){ + return false; + } + auto iter = builtins().find(words[0]); + if (iter != builtins().end()){ + (this->*iter->second.handler)(words); + return true; + } + std::optional command = find_registered_command(words[0]); + if (!command){ + throw ParseException("Unknown command: " + words[0] + " (try \"help\")"); + } + (*command)(m_session, words); + return true; + } + + // Saves the current frame as /_