![]() |
JaffarPlus
High-performance best-first search optimizer for tool-assisted speedruns
|
Owns a Game instance and advances it according to configured inputs. More...
#include <runner.hpp>
Public Member Functions | |
| Runner (std::unique_ptr< Game > &game, const nlohmann::json &config) | |
Constructs a runner that takes ownership of game and reads its settings from config. | |
| void | initialize () |
| Initializes the runner: initializes the game, parses input sets, and registers inputs. | |
| void | setInputHistoryBacking (const std::shared_ptr< void > &backing, const uint32_t shardId, const uint32_t numShards) |
| Injects the shared input-history backing (e.g. | |
| const nlohmann::json & | getInputHistoryConfig () const |
| The configured "Store Input History" object (used by the engine to build the shared backing). | |
| InputHistory * | getInputHistory () const |
| The input-history strategy in use (for the StateDb's per-slot manager operations). | |
| std::unique_ptr< InputSet > | parseInputSet (const nlohmann::json &inputSetJs) |
| Builds an InputSet from its JSON description. | |
| InputSet::inputIndex_t | registerInput (const std::string &input) |
| Registers an input string and returns its numeric index. | |
| std::vector< InputSet::inputIndex_t > | getInputsFromInputSets (const std::vector< std::unique_ptr< InputSet > > &inputSets) const |
| Collects the input indexes of every input set whose conditions currently evaluate to true. | |
| const auto | getAllowedInputs () const |
| Returns the inputs currently allowed for the game's state. | |
| const auto | getCandidateInputs () const |
| Returns the inputs currently allowed by the candidate input sets. | |
| jaffarPlus::InputSet::inputIndex_t | getInputIndex (const std::string &input) const |
| Looks up the index registered for an input string. | |
| bool | isInputRegistered (const std::string &inputString) |
| Reports whether an input string has been registered. | |
| void | advanceState (const InputSet::inputIndex_t inputIdx) |
| Advances the game by one input, then by the configured number of frameskip frames. | |
| void | pushInput (const InputSet::inputIndex_t inputIdx) |
| Records an applied input into the input history at the current step, and advances the step counter. | |
| void | setStepCount (const size_t stepCount) |
| Sets the step counter directly (its input-count value). | |
| void | setSearchStep (const size_t searchStep) |
| Sets the step counter from a search step. | |
| size_t | getStepCount () const |
| Returns the current step counter (number of inputs applied / the state's depth). | |
| void | serializeState (jaffarCommon::serializer::Base &serializer) const |
| Serializes the runner state: the game state, the input history, and the input counter. | |
| void | deserializeState (jaffarCommon::deserializer::Base &deserializer) |
| Restores the runner state: the game state, the input history, and the input counter. | |
| size_t | getStateSize () const |
| Computes the size in bytes of the serialized runner state. | |
| void | serializeHotState (jaffarCommon::serializer::Base &serializer) const |
Serializes only the hot game+emulator state (what the search reads every step) into serializer. | |
| void | deserializeHotState (jaffarCommon::deserializer::Base &deserializer) |
Restores only the hot game+emulator state from deserializer. | |
| void | serializeHistory (jaffarCommon::serializer::Base &serializer) const |
Serializes only the cold input-history "path" (written once at state creation, read at solution time) into serializer. | |
| void | deserializeHistory (jaffarCommon::deserializer::Base &deserializer) |
Restores only the cold input-history "path" from deserializer. | |
| size_t | getHotStateSize () const |
| Returns the serialized size of the hot game+emulator state, in bytes. | |
| size_t | getHistorySize () const |
| Returns the serialized size of the cold input-history "path", in bytes. | |
| jaffarCommon::hash::hash_t | computeHash () const |
| Computes a hash of the current runner state. | |
| std::string | getInputHistoryString () const |
| Builds a newline-separated string of the recorded input history. | |
| std::string | getInputStringFromIndex (const InputSet::inputIndex_t input) |
| Returns the input string registered for an input index. | |
| void | printInfo () const |
| Logs runner state information. | |
| uint32_t | getHashStepToleranceStage () const |
| Returns the current hash-step-tolerance stage (current input count modulo tolerance + 1). | |
| Game * | getGame () const |
| Returns a pointer to the owned game instance. | |
| bool | isInitialized () const |
| Returns whether the runner has been initialized. | |
Static Public Member Functions | |
| static std::unique_ptr< Runner > | getRunner (const nlohmann::json &emulatorConfig, const nlohmann::json &gameConfig, const nlohmann::json &runnerConfig) |
| Creates a runner from the emulator, game and runner configurations. | |
Private Attributes | |
| bool | _isInitialized = false |
| Whether the runner has been initialized. | |
| std::unique_ptr< Game > | _game |
| The owned game instance driven by the runner. | |
| uint32_t | _hashStepTolerance |
| Hash step tolerance, used to derive the hash-step-tolerance stage. | |
| nlohmann::json | _inputHistoryConfig |
| The "Store Input History" config object (selects None/Raw/Trie). | |
| std::unique_ptr< InputHistory > | _inputHistory |
| The configured strategy instance (built in initialize()). | |
| size_t | _stepCount = 0 |
| Inputs applied so far (the state's depth). | |
| std::shared_ptr< void > | _historyBacking |
| Shared backing (e.g. the one trie), injected by the engine or owned privately. | |
| uint32_t | _historyShardId = 0 |
| This runner's contention-free free-list shard (its worker thread id). | |
| uint32_t | _historyNumShards = 2 |
| Shard count of the backing (engine: threadCount+1; standalone: 2). | |
| bool | _bypassHashCalculation |
| Whether computeHash returns the game's direct hash instead of hashing via MetroHash128. | |
| InputSet::inputIndex_t | _maxInputIndex = 0 |
| One past the highest registered input index; determines the input-history encoding width. | |
| std::map< jaffarCommon::hash::hash_t, InputSet::inputIndex_t > | _inputHashMap |
| Maps an input string's hash to its index. | |
| std::map< InputSet::inputIndex_t, std::string > | _inputStringMap |
| Maps an input index back to its input string. | |
| size_t | _frameskipRate |
| Number of frames to skip after each applied input. | |
| bool | _frameskipUseCustomInput |
| Whether skipped frames use the custom input; false repeats the applied input. | |
| std::string | _frameskipCustomInput |
| The custom input string to apply on skipped frames. | |
| InputSet::inputIndex_t | _frameskipCustomInputIdx {} |
| Resolved index of the custom frameskip input, computed once at initialize() so advanceState() does not re-hash + re-look-up the input string on every skipped frame. | |
| std::vector< nlohmann::json > | _allowedInputSetsJs |
| JSON descriptions of the allowed input sets (parsed at initialization). | |
| std::vector< nlohmann::json > | _candidateInputSetsJs |
| JSON descriptions of the candidate input sets (parsed at initialization). | |
| std::vector< std::unique_ptr< InputSet > > | _candidateInputSets |
| Parsed candidate input sets. | |
| std::vector< std::unique_ptr< InputSet > > | _allowedInputSets |
| Parsed allowed input sets. | |
| size_t | _largestInputSetSize = 0 |
| Largest input set size detected (used for output formatting). | |
| bool | _testCandidateInputs |
| Whether candidate input sets are parsed and tested. | |
| bool | _showEmptyInputSlots |
| Whether placeholders are printed for unused input slots. | |
| bool | _showAllowedInputs |
| Whether allowed inputs are printed in printInfo. | |
Owns a Game instance and advances it according to configured inputs.
The runner parses allowed and candidate input sets from the configuration, registers every input string to a numeric index, and on each step advances the game by one input (plus any configured frameskip frames). It can record the sequence of applied inputs as a bit-packed input history, serialize/deserialize its state together with the game's, and compute a hash of the current state.
Definition at line 37 of file runner.hpp.
|
inline |
Constructs a runner that takes ownership of game and reads its settings from config.
| game | The game instance to drive; ownership is moved into the runner. |
| config | Runner configuration object, supplying the keys "Hash Step Tolerance", "Store Input History" (with "Enabled" and "Max Size"), "Allowed Input Sets", "Show Allowed Inputs", "Show Empty Input Slots", "Test Candidate Inputs", "Candidate Input Sets", "Frameskip" (with "Rate", "Use Custom Input", "Custom Input") and "Bypass Hash Calculation". |
Definition at line 49 of file runner.hpp.
|
inline |
Advances the game by one input, then by the configured number of frameskip frames.
Applies inputIdx to the game and records it in the input history. Then, for each of the _frameskipRate skipped frames, advances the game with either the custom frameskip input (when "Use Custom Input" is set) or the same inputIdx, recording each in the input history.
| inputIdx | The index of the input to apply for this step. |
Definition at line 309 of file runner.hpp.
|
inline |
Computes a hash of the current runner state.
When "Bypass Hash Calculation" is enabled, returns the game's direct state hash. Otherwise, hashes the current hash-step-tolerance stage together with the game's hash contribution using MetroHash128.
Definition at line 426 of file runner.hpp.
|
inline |
Restores only the cold input-history "path" from deserializer.
Definition at line 406 of file runner.hpp.
|
inline |
Restores only the hot game+emulator state from deserializer.
Definition at line 400 of file runner.hpp.
|
inline |
Restores the runner state: the game state, the input history, and the input counter.
| deserializer | The deserializer to read the state from. |
Definition at line 372 of file runner.hpp.
|
inline |
Returns the inputs currently allowed for the game's state.
Collects the inputs from the allowed input sets and appends any additional inputs supplied by the game via Game::getAdditionalAllowedInputs.
Definition at line 251 of file runner.hpp.
|
inline |
Returns the inputs currently allowed by the candidate input sets.
Definition at line 266 of file runner.hpp.
|
inline |
Returns a pointer to the owned game instance.
Definition at line 516 of file runner.hpp.
|
inline |
Returns the current hash-step-tolerance stage (current input count modulo tolerance + 1).
Definition at line 514 of file runner.hpp.
|
inline |
Returns the serialized size of the cold input-history "path", in bytes.
Definition at line 416 of file runner.hpp.
|
inline |
Returns the serialized size of the hot game+emulator state, in bytes.
Definition at line 409 of file runner.hpp.
|
inline |
The input-history strategy in use (for the StateDb's per-slot manager operations).
Definition at line 145 of file runner.hpp.
|
inline |
The configured "Store Input History" object (used by the engine to build the shared backing).
Definition at line 142 of file runner.hpp.
|
inline |
Builds a newline-separated string of the recorded input history.
Returns an empty string when input history is disabled. Otherwise concatenates the input string for each recorded step up to the current input count or the history capacity.
| A | runtime error if a recorded input index has no registered string. |
Definition at line 456 of file runner.hpp.
|
inline |
Looks up the index registered for an input string.
| input | The input string to look up. |
| A | logic error if the input was not previously registered. |
Definition at line 274 of file runner.hpp.
|
inline |
Collects the input indexes of every input set whose conditions currently evaluate to true.
Iterates the given input sets in order; for each set that evaluates to true, its input indexes are appended to the result. If a satisfied set has its stop-evaluation flag set, iteration stops after that set.
| inputSets | The input sets to evaluate. |
Definition at line 222 of file runner.hpp.
|
inline |
Returns the input string registered for an input index.
| input | The input index to resolve. |
input. Definition at line 463 of file runner.hpp.
|
inlinestatic |
Creates a runner from the emulator, game and runner configurations.
Builds the game via Game::getGame and wraps it in a new runner.
| emulatorConfig | Configuration for the emulator. |
| gameConfig | Configuration for the game. |
| runnerConfig | Configuration for the runner. |
Definition at line 527 of file runner.hpp.
|
inline |
Computes the size in bytes of the serialized runner state.
Definition at line 384 of file runner.hpp.
|
inline |
Returns the current step counter (number of inputs applied / the state's depth).
Definition at line 354 of file runner.hpp.
|
inline |
Initializes the runner: initializes the game, parses input sets, and registers inputs.
Initializes the game if needed, parses the allowed input sets (and candidate input sets when "Test Candidate Inputs" is enabled), registers the inputs declared by the game's code, resolves the custom frameskip input index, and allocates the bit-packed input-history storage when input history is enabled.
| A | logic error if the runner was already initialized. |
Definition at line 98 of file runner.hpp.
|
inline |
Returns whether the runner has been initialized.
Definition at line 540 of file runner.hpp.
|
inline |
Reports whether an input string has been registered.
| inputString | The input string to test. |
Definition at line 292 of file runner.hpp.
|
inline |
Builds an InputSet from its JSON description.
Parses the set's "Conditions" (via the game's condition parser) and "Inputs" (each registered via registerInput), updates _largestInputSetSize, and applies the "Stop Input Evaluation" flag.
| inputSetJs | JSON object describing the input set ("Conditions", "Inputs", "Stop Input Evaluation"). |
Definition at line 157 of file runner.hpp.
|
inline |
Logs runner state information.
Logs input-history configuration, the current input count, the state hash, the hash-step-tolerance stage and the frameskip rate. When "Show Allowed Inputs" is set, also logs the currently allowed inputs (with empty-slot placeholders when "Show Empty Input Slots" is set).
Definition at line 472 of file runner.hpp.
|
inline |
Records an applied input into the input history at the current step, and advances the step counter.
The runner owns the step counter (it is what feeds Hash Step Tolerance and is NOT serialized into every state – see setSearchStep). The configured strategy stores the input at position _stepCount (subject to its own capacity rules); the runner then advances the counter.
| inputIdx | The index of the input that was applied. |
Definition at line 338 of file runner.hpp.
|
inline |
Registers an input string and returns its numeric index.
Obtains the index from the emulator, records the hash->index and index->string mappings, and updates _maxInputIndex. Registering an already-registered input returns its prior index.
| input | The input string to register. |
Definition at line 192 of file runner.hpp.
|
inline |
Serializes only the cold input-history "path" (written once at state creation, read at solution time) into serializer.
Definition at line 404 of file runner.hpp.
|
inline |
Serializes only the hot game+emulator state (what the search reads every step) into serializer.
Definition at line 398 of file runner.hpp.
|
inline |
Serializes the runner state: the game state, the input history, and the input counter.
| serializer | The serializer to write the state into. |
Definition at line 360 of file runner.hpp.
|
inline |
Injects the shared input-history backing (e.g.
the engine's one trie) plus this runner's free-list shard (its worker thread id) and the shard count, so all workers share one structure while allocating/freeing contention-free. Must be called before initialize.
Definition at line 134 of file runner.hpp.
|
inline |
Sets the step counter from a search step.
Since every state at search step N shares the same depth, the engine/driver supply N here instead of serializing the counter per state. Accounts for frameskip (each search step records 1 + _frameskipRate inputs).
Definition at line 351 of file runner.hpp.
|
inline |
Sets the step counter directly (its input-count value).
Used when restoring a snapshot whose depth was recorded at capture (best/worst/win/manual), and by the player as it replays.
Definition at line 346 of file runner.hpp.
|
private |
Parsed allowed input sets.
Definition at line 594 of file runner.hpp.
|
private |
JSON descriptions of the allowed input sets (parsed at initialization).
Definition at line 588 of file runner.hpp.
|
private |
Whether computeHash returns the game's direct hash instead of hashing via MetroHash128.
Definition at line 558 of file runner.hpp.
|
private |
Parsed candidate input sets.
Definition at line 592 of file runner.hpp.
|
private |
JSON descriptions of the candidate input sets (parsed at initialization).
Definition at line 590 of file runner.hpp.
|
private |
The custom input string to apply on skipped frames.
Definition at line 578 of file runner.hpp.
|
private |
Resolved index of the custom frameskip input, computed once at initialize() so advanceState() does not re-hash + re-look-up the input string on every skipped frame.
Definition at line 582 of file runner.hpp.
|
private |
Number of frames to skip after each applied input.
Definition at line 574 of file runner.hpp.
|
private |
Whether skipped frames use the custom input; false repeats the applied input.
Definition at line 576 of file runner.hpp.
|
private |
The owned game instance driven by the runner.
Definition at line 545 of file runner.hpp.
|
private |
Hash step tolerance, used to derive the hash-step-tolerance stage.
Definition at line 547 of file runner.hpp.
|
private |
Shared backing (e.g. the one trie), injected by the engine or owned privately.
Definition at line 554 of file runner.hpp.
|
private |
Shard count of the backing (engine: threadCount+1; standalone: 2).
Definition at line 556 of file runner.hpp.
|
private |
This runner's contention-free free-list shard (its worker thread id).
Definition at line 555 of file runner.hpp.
|
private |
Maps an input string's hash to its index.
Definition at line 566 of file runner.hpp.
|
private |
The configured strategy instance (built in initialize()).
Definition at line 551 of file runner.hpp.
|
private |
The "Store Input History" config object (selects None/Raw/Trie).
Definition at line 550 of file runner.hpp.
|
private |
Maps an input index back to its input string.
Definition at line 568 of file runner.hpp.
|
private |
Whether the runner has been initialized.
Definition at line 543 of file runner.hpp.
|
private |
Largest input set size detected (used for output formatting).
Definition at line 596 of file runner.hpp.
|
private |
One past the highest registered input index; determines the input-history encoding width.
Definition at line 564 of file runner.hpp.
|
private |
Whether allowed inputs are printed in printInfo.
Definition at line 602 of file runner.hpp.
|
private |
Whether placeholders are printed for unused input slots.
Definition at line 600 of file runner.hpp.
|
private |
Inputs applied so far (the state's depth).
Runner-owned, NOT serialized; set per search step by the engine/driver (setSearchStep) or the player, and advanced by pushInput. Feeds Hash Step Tolerance and bounds solution reconstruction.
Definition at line 552 of file runner.hpp.
|
private |
Whether candidate input sets are parsed and tested.
Definition at line 598 of file runner.hpp.