Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions .github/workflows/lab-instance-tools.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,4 @@ jobs:
with:
python-version: '3.12'
- run: python3 -m unittest discover -s devtools/lab -p 'test_lab_instance.py' -v
- run: python3 -m unittest discover -s devtools/lab -p 'test_cfr_steps_to_story.py' -v
23 changes: 18 additions & 5 deletions SerialPrograms/Source/CommonFramework/Windows/Lab.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ takes effect at the next launch.
| `Lab/done/<name>.txt` | app moves | The request, moved here when it starts. |
| `Lab/outbox/<name>.out` | app writes | The request's journal (below). It appears only once the request has finished; `<name>.tmp` shows the progress so far. |
| `Lab/outbox/<name>_<label>.png`, `.mp4` | app writes | Files that `shot`, `shots` and `history` save. |
| `Lab/outbox/<name>.steps.jsonl` | app appends | One JSON line per console command, as it ends: the command and its arguments, start and end time, duration, `ok` or `error`, what the games' detectors and readings saw `before` and `after` it, and the path of `<name>_step_L<line>.jpg`, the frame it ended on. See `NintendoSwitch_CommandFileRecorder.h`; `devtools/lab/cfr_steps_to_story.py` turns it into story table rows. |
| `Lab/state` | app writes | The channel's state, rewritten after every request and whenever the program state changes. |

Write a request somewhere else and then move it into `inbox`, so the app
Expand Down Expand Up @@ -121,6 +122,7 @@ program runs (`STOPPED`); the commands that only read the screen (`shot`,
| Command | What it does |
|---|---|
| `close_game` | Goes to the Home menu from anywhere and closes the game. |
| `type TEXT` | On the system keyboard a game opened (e.g. for the player's name): deletes the field's text, types TEXT (one word), presses + and fails unless the keyboard closes. |

#### Detectors

Expand All @@ -132,10 +134,21 @@ These work on any game:
| `user_select` | The "Who is using the software?" screen. |
| `black` | A black screen. |
| `white` | A white screen. |

Games add their own commands and detectors with
`register_command_file_command()` and `register_command_file_detector()` (see
`NintendoSwitch_CommandFileRunner.h`); `help` lists them.
| `keyboard` | The Switch's system keyboard. |

Games add their own commands, detectors and readings with
`register_command_file_command()`, `register_command_file_detector()` and
`register_command_file_reading()` (see `NintendoSwitch_CommandFileRunner.h`),
from their panel list's constructor; `help` lists them. A reading is a value
rather than yes or no, such as a heading; `detect NAME` prints it. A game's
detectors and readings are recorded before and after every command in the
steps file.

Pokemon Legends: Z-A adds its story actions (`PokemonLZA_AutoStoryCommands.h`):
`lza_talk [A|B]`, `lza_talk_to`, `lza_pick N`, `lza_move ANGLE|ahead MS`,
`lza_face ANGLE [TOL]`, `lza_fly PLACE [LANG]`, `lza_battle`, `lza_heal`,
`lza_shop ITEM...` and `lza_save`; the detectors `lza_dialog`, `lza_overworld`
and `lza_arrow`; and the reading `lza_facing`.

## Owner

Expand Down Expand Up @@ -275,5 +288,5 @@ two-line `state`) is gone. `start` and `stop` are lines in a request, and
`add_tests_LabChannel()` covers the request format, the journal lines, the
state text, the owner lock, the keep-awake schedule and the controller wait before `start` (`LabChannel - ...`
unit tests); `add_tests_CommandFileRunner()` covers the console commands'
arguments. Run them with the app's `--command-line-test-mode`. Selecting,
arguments and `add_tests_CommandFileRecorder()` the steps file's lines. Run them with the app's `--command-line-test-mode`. Selecting,
setting, starting and the presses need a live app and console.
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,13 @@ TapsArguments parse_taps(const std::vector<std::string>& words){
return taps;
}

std::string parse_type_text(const std::vector<std::string>& words){
if (words.size() != 2){
throw ParseException(std::format("{}: expected one word to type, got {}", words[0], words.size() - 1));
}
return words[1];
}



}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,10 @@ struct TapsArguments{
};
TapsArguments parse_taps(const std::vector<std::string>& words);

// The text of "type TEXT": one word, as a name is. Throws ParseException
// for none or more than one.
std::string parse_type_text(const std::vector<std::string>& words);



}
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
/* Command File Recorder
*
* From: https://github.com/PokemonAutomation/
*
*/

#include <chrono>
#include <format>
#include "Common/Cpp/Filesystem/FileIO.h"
#include "Common/Cpp/Filesystem/FilePath.h"
#include "Common/Cpp/Json/JsonArray.h"
#include "NintendoSwitch_CommandFileRecorder.h"

namespace PokemonAutomation{
namespace NintendoSwitch{


namespace{

// UTC, to the millisecond: "2026-11-08T21:04:12.517Z".
std::string utc_time(WallClock time){
return std::format("{:%FT%TZ}", std::chrono::floor<std::chrono::milliseconds>(time));
}

} // namespace


std::string command_file_step_json(const CommandFileStep& step){

Check warning on line 28 in SerialPrograms/Source/NintendoSwitch/Programs/CommandFileRunner/NintendoSwitch_CommandFileRecorder.cpp

View workflow job for this annotation

GitHub Actions / code-health

Code health (advisory)

PokemonAutomation::NintendoSwitch::command_file_step_json( const CommandFileStep & step): function_lines=26 (advisory above 25, limit 50)
JsonObject json;
json["line"] = (int64_t)step.line;
json["command"] = step.words.empty() ? std::string() : step.words[0];
JsonArray args;
for (size_t c = 1; c < step.words.size(); c++){
args.push_back(step.words[c]);
}
json["args"] = std::move(args);
json["start"] = utc_time(step.start);
json["end"] = utc_time(step.end);
json["duration_ms"] = (int64_t)std::chrono::duration_cast<Milliseconds>(step.end - step.start).count();
if (!step.before.empty()){
json["before"] = step.before.clone();
}
if (!step.after.empty()){
json["after"] = step.after.clone();
}
json["ok"] = !step.error.has_value();
if (step.error){
json["error"] = *step.error;
}
json["screenshot"] = step.screenshot;
// -1: no indentation and no line breaks.
return json.dump(-1);
}

void append_command_file_step(const std::string& path, const CommandFileStep& step){
const std::string line = command_file_step_json(step) + "\n";
FileIO file(Filesystem::Path(path), FileMode::APPEND | FileMode::BINARY);
if (file.is_open()){
file.write(line.data(), line.size());
}
}



} // namespace NintendoSwitch
} // namespace PokemonAutomation
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
/* Command File Recorder
*
* From: https://github.com/PokemonAutomation/
*
* The steps file of a command file: "<outbox>/<name>.steps.jsonl", one JSON
* object per command, appended as each command ends. The journal
* ("<name>.out") is for a person reading along; this file is for tools,
* such as devtools/lab/cfr_steps_to_story.py, which turns a story played by
* hand into story table rows. A line looks like:
*
* {"after":{"lza_dialog":false,"lza_facing":87},"before":{...},
* "command":"lza_move","args":["90","1500"],"duration_ms":1640,
* "end":"2026-11-08T21:04:12.517Z","line":3,"ok":true,
* "screenshot":".../probe_step_L3.jpg","start":"2026-11-08T21:04:10.877Z"}
*
* "before" and "after" hold the games' detectors and readings, and are left
* out when no game registered any. A failed command has "ok":false and an
* "error" message.
*
*/

#ifndef PokemonAutomation_NintendoSwitch_CommandFileRecorder_H
#define PokemonAutomation_NintendoSwitch_CommandFileRecorder_H

#include <optional>
#include <string>
#include <vector>
#include "Common/Cpp/Time.h"
#include "Common/Cpp/Json/JsonObject.h"

namespace PokemonAutomation{
namespace NintendoSwitch{


// One command as it ran.
struct CommandFileStep{
size_t line = 0; // In the command file, from 1.
std::vector<std::string> words; // The command and its arguments.
WallClock start = WallClock::min();
WallClock end = WallClock::min();
JsonObject before; // Detector name -> what it saw. Empty: none registered.
JsonObject after;
std::optional<std::string> error; // Why the command failed; none if it succeeded.
std::string screenshot; // The frame when it ended.
};

// `step` as one line of JSON, without the newline.
std::string command_file_step_json(const CommandFileStep& step);

// Appends `step` to the steps file at `path`.
void append_command_file_step(const std::string& path, const CommandFileStep& step);



} // namespace NintendoSwitch
} // namespace PokemonAutomation
#endif
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
/* Command File Recorder - Tests
*
* From: https://github.com/PokemonAutomation/
*
*/

#include <chrono>
#include <format>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
#include "Common/Cpp/Json/JsonValue.h"
#include "Common/Cpp/TestRunners/UnitTest.h"
#include "NintendoSwitch_CommandFileRecorder.h"
#include "NintendoSwitch_CommandFileRecorder_Tests.h"

namespace PokemonAutomation{
namespace NintendoSwitch{

namespace{

// 2026-11-08T21:04:10.000Z.
constexpr int64_t START_MS = 1794171850000;

struct StepInput{
std::string_view name;
size_t line = 0;
std::vector<std::string> words;
int64_t duration_ms = 0;
std::string before; // The detectors' JSON object; "" for none.
std::string after;
std::optional<std::string> error;
std::string screenshot;
};

struct StepExpectation{
std::string json;
};

struct StepCase{
StepInput input;
StepExpectation expectation;
};

const StepCase STEP_CASES[] = {
{
.input = {
.name = "ok without game state", .line = 2, .words = {"press", "A"}, .duration_ms = 322,
.screenshot = "/outbox/probe_step_L2.jpg",
},
.expectation = {.json =
R"json({"args":["A"],"command":"press","duration_ms":322,"end":"2026-11-08T21:04:10.322Z",)json"
R"json("line":2,"ok":true,"screenshot":"/outbox/probe_step_L2.jpg","start":"2026-11-08T21:04:10.000Z"})json"
},
},
{
.input = {
.name = "failed with game state", .line = 7, .words = {"lza_move", "90", "1500"}, .duration_ms = 1640,
.before = R"json({"lza_dialog":false,"lza_facing":87})json",
.after = R"json({"lza_dialog":true,"lza_facing":null})json",
.error = "run_story_move(): a day/night change cut the run short.",
.screenshot = "/outbox/probe_step_L7.jpg",
},
.expectation = {.json =
R"json({"after":{"lza_dialog":true,"lza_facing":null},"args":["90","1500"],)json"
R"json("before":{"lza_dialog":false,"lza_facing":87},"command":"lza_move","duration_ms":1640,)json"
R"json("end":"2026-11-08T21:04:11.640Z","error":"run_story_move(): a day/night change cut the run short.",)json"
R"json("line":7,"ok":false,"screenshot":"/outbox/probe_step_L7.jpg","start":"2026-11-08T21:04:10.000Z"})json"
},
},
{
.input = {.name = "no arguments", .line = 1, .words = {"lza_battle"}, .duration_ms = 0, .screenshot = "(no video frame)"},
.expectation = {.json =
R"json({"args":[],"command":"lza_battle","duration_ms":0,"end":"2026-11-08T21:04:10.000Z",)json"
R"json("line":1,"ok":true,"screenshot":"(no video frame)","start":"2026-11-08T21:04:10.000Z"})json"
},
},
};

// The object `text` holds, or an empty one for "".
JsonObject json_object(const std::string& text){
if (text.empty()){
return JsonObject();
}
return parse_json(text).to_object_throw().clone();
}

UnitTestResult check_step_case(const StepCase& test){
const StepInput& input = test.input;
const WallClock start{std::chrono::milliseconds(START_MS)};
CommandFileStep step{
.line = input.line,
.words = input.words,
.start = start,
.end = start + std::chrono::milliseconds(input.duration_ms),
.before = json_object(input.before),
.after = json_object(input.after),
.error = input.error,
.screenshot = input.screenshot,
};
const std::string read = command_file_step_json(step);
if (read != test.expectation.json){
return std::format("Expected the line\n{}\nread\n{}", test.expectation.json, read);
}
return true;
}

class StepJsonTest : public UnitTest{
public:
explicit StepJsonTest(const StepCase& test)
: UnitTest("NintendoSwitch::CommandFileRecorder - " + std::string(test.input.name))
, m_test(test)
{}
virtual UnitTestResult run(Logger&, CancellableScope&) const override{
return check_step_case(m_test);
}

private:
const StepCase& m_test;
};

} // namespace


void add_tests_CommandFileRecorder(UnitTestDatabase& database){
for (const StepCase& test : STEP_CASES){
database.add<StepJsonTest>(test);
}
}



} // namespace NintendoSwitch
} // namespace PokemonAutomation
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
/* Command File Recorder - Tests
*
* From: https://github.com/PokemonAutomation/
*
*/

#ifndef PokemonAutomation_NintendoSwitch_CommandFileRecorder_Tests_H
#define PokemonAutomation_NintendoSwitch_CommandFileRecorder_Tests_H

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

namespace PokemonAutomation{
namespace NintendoSwitch{


// The steps file's line format, with no console.
void add_tests_CommandFileRecorder(UnitTestDatabase& database);



} // namespace NintendoSwitch
} // namespace PokemonAutomation
#endif
Loading
Loading