JaffarPlus
High-performance best-first search optimizer for tool-assisted speedruns
Loading...
Searching...
No Matches
jaffarPlus::Runner Class Referencefinal

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).
 
InputHistorygetInputHistory () const
 The input-history strategy in use (for the StateDb's per-slot manager operations).
 
std::unique_ptr< InputSetparseInputSet (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_tgetInputsFromInputSets (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).
 
GamegetGame () 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< RunnergetRunner (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.
 

Detailed Description

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.

Constructor & Destructor Documentation

◆ Runner()

jaffarPlus::Runner::Runner ( std::unique_ptr< Game > &  game,
const nlohmann::json &  config 
)
inline

Constructs a runner that takes ownership of game and reads its settings from config.

Parameters
gameThe game instance to drive; ownership is moved into the runner.
configRunner 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.

Member Function Documentation

◆ advanceState()

void jaffarPlus::Runner::advanceState ( const InputSet::inputIndex_t  inputIdx)
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.

Parameters
inputIdxThe index of the input to apply for this step.

Definition at line 309 of file runner.hpp.

◆ computeHash()

jaffarCommon::hash::hash_t jaffarPlus::Runner::computeHash ( ) const
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.

Returns
The computed state hash.

Definition at line 426 of file runner.hpp.

◆ deserializeHistory()

void jaffarPlus::Runner::deserializeHistory ( jaffarCommon::deserializer::Base &  deserializer)
inline

Restores only the cold input-history "path" from deserializer.

Definition at line 406 of file runner.hpp.

◆ deserializeHotState()

void jaffarPlus::Runner::deserializeHotState ( jaffarCommon::deserializer::Base &  deserializer)
inline

Restores only the hot game+emulator state from deserializer.

Definition at line 400 of file runner.hpp.

◆ deserializeState()

void jaffarPlus::Runner::deserializeState ( jaffarCommon::deserializer::Base &  deserializer)
inline

Restores the runner state: the game state, the input history, and the input counter.

Parameters
deserializerThe deserializer to read the state from.

Definition at line 372 of file runner.hpp.

◆ getAllowedInputs()

const auto jaffarPlus::Runner::getAllowedInputs ( ) const
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.

Returns
The allowed input indexes.

Definition at line 251 of file runner.hpp.

◆ getCandidateInputs()

const auto jaffarPlus::Runner::getCandidateInputs ( ) const
inline

Returns the inputs currently allowed by the candidate input sets.

Returns
The candidate input indexes whose input sets evaluate to true.

Definition at line 266 of file runner.hpp.

◆ getGame()

Game * jaffarPlus::Runner::getGame ( ) const
inline

Returns a pointer to the owned game instance.

Definition at line 516 of file runner.hpp.

◆ getHashStepToleranceStage()

uint32_t jaffarPlus::Runner::getHashStepToleranceStage ( ) const
inline

Returns the current hash-step-tolerance stage (current input count modulo tolerance + 1).

Definition at line 514 of file runner.hpp.

◆ getHistorySize()

size_t jaffarPlus::Runner::getHistorySize ( ) const
inline

Returns the serialized size of the cold input-history "path", in bytes.

Definition at line 416 of file runner.hpp.

◆ getHotStateSize()

size_t jaffarPlus::Runner::getHotStateSize ( ) const
inline

Returns the serialized size of the hot game+emulator state, in bytes.

Definition at line 409 of file runner.hpp.

◆ getInputHistory()

InputHistory * jaffarPlus::Runner::getInputHistory ( ) const
inline

The input-history strategy in use (for the StateDb's per-slot manager operations).

Definition at line 145 of file runner.hpp.

◆ getInputHistoryConfig()

const nlohmann::json & jaffarPlus::Runner::getInputHistoryConfig ( ) const
inline

The configured "Store Input History" object (used by the engine to build the shared backing).

Definition at line 142 of file runner.hpp.

◆ getInputHistoryString()

std::string jaffarPlus::Runner::getInputHistoryString ( ) const
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.

Returns
The recorded inputs, one per line.
Exceptions
Aruntime error if a recorded input index has no registered string.

Definition at line 456 of file runner.hpp.

◆ getInputIndex()

jaffarPlus::InputSet::inputIndex_t jaffarPlus::Runner::getInputIndex ( const std::string &  input) const
inline

Looks up the index registered for an input string.

Parameters
inputThe input string to look up.
Returns
The index registered for the input.
Exceptions
Alogic error if the input was not previously registered.

Definition at line 274 of file runner.hpp.

◆ getInputsFromInputSets()

std::vector< InputSet::inputIndex_t > jaffarPlus::Runner::getInputsFromInputSets ( const std::vector< std::unique_ptr< InputSet > > &  inputSets) const
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.

Parameters
inputSetsThe input sets to evaluate.
Returns
The concatenated input indexes of the satisfied input sets.

Definition at line 222 of file runner.hpp.

◆ getInputStringFromIndex()

std::string jaffarPlus::Runner::getInputStringFromIndex ( const InputSet::inputIndex_t  input)
inline

Returns the input string registered for an input index.

Parameters
inputThe input index to resolve.
Returns
The registered input string for input.

Definition at line 463 of file runner.hpp.

◆ getRunner()

static std::unique_ptr< Runner > jaffarPlus::Runner::getRunner ( const nlohmann::json &  emulatorConfig,
const nlohmann::json &  gameConfig,
const nlohmann::json &  runnerConfig 
)
inlinestatic

Creates a runner from the emulator, game and runner configurations.

Builds the game via Game::getGame and wraps it in a new runner.

Parameters
emulatorConfigConfiguration for the emulator.
gameConfigConfiguration for the game.
runnerConfigConfiguration for the runner.
Returns
The newly created runner.

Definition at line 527 of file runner.hpp.

◆ getStateSize()

size_t jaffarPlus::Runner::getStateSize ( ) const
inline

Computes the size in bytes of the serialized runner state.

Returns
The contiguous serialized state size in bytes.

Definition at line 384 of file runner.hpp.

◆ getStepCount()

size_t jaffarPlus::Runner::getStepCount ( ) const
inline

Returns the current step counter (number of inputs applied / the state's depth).

Definition at line 354 of file runner.hpp.

◆ initialize()

void jaffarPlus::Runner::initialize ( )
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.

Exceptions
Alogic error if the runner was already initialized.

Definition at line 98 of file runner.hpp.

◆ isInitialized()

bool jaffarPlus::Runner::isInitialized ( ) const
inline

Returns whether the runner has been initialized.

Definition at line 540 of file runner.hpp.

◆ isInputRegistered()

bool jaffarPlus::Runner::isInputRegistered ( const std::string &  inputString)
inline

Reports whether an input string has been registered.

Parameters
inputStringThe input string to test.
Returns
true if the input is registered, false otherwise.

Definition at line 292 of file runner.hpp.

◆ parseInputSet()

std::unique_ptr< InputSet > jaffarPlus::Runner::parseInputSet ( const nlohmann::json &  inputSetJs)
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.

Parameters
inputSetJsJSON object describing the input set ("Conditions", "Inputs", "Stop Input Evaluation").
Returns
The newly created input set.

Definition at line 157 of file runner.hpp.

◆ printInfo()

void jaffarPlus::Runner::printInfo ( ) const
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.

◆ pushInput()

void jaffarPlus::Runner::pushInput ( const InputSet::inputIndex_t  inputIdx)
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.

Parameters
inputIdxThe index of the input that was applied.

Definition at line 338 of file runner.hpp.

◆ registerInput()

InputSet::inputIndex_t jaffarPlus::Runner::registerInput ( const std::string &  input)
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.

Parameters
inputThe input string to register.
Returns
The index assigned to the input.

Definition at line 192 of file runner.hpp.

◆ serializeHistory()

void jaffarPlus::Runner::serializeHistory ( jaffarCommon::serializer::Base &  serializer) const
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.

◆ serializeHotState()

void jaffarPlus::Runner::serializeHotState ( jaffarCommon::serializer::Base &  serializer) const
inline

Serializes only the hot game+emulator state (what the search reads every step) into serializer.

Definition at line 398 of file runner.hpp.

◆ serializeState()

void jaffarPlus::Runner::serializeState ( jaffarCommon::serializer::Base &  serializer) const
inline

Serializes the runner state: the game state, the input history, and the input counter.

Parameters
serializerThe serializer to write the state into.

Definition at line 360 of file runner.hpp.

◆ setInputHistoryBacking()

void jaffarPlus::Runner::setInputHistoryBacking ( const std::shared_ptr< void > &  backing,
const uint32_t  shardId,
const uint32_t  numShards 
)
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.

◆ setSearchStep()

void jaffarPlus::Runner::setSearchStep ( const size_t  searchStep)
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.

◆ setStepCount()

void jaffarPlus::Runner::setStepCount ( const size_t  stepCount)
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.

Member Data Documentation

◆ _allowedInputSets

std::vector<std::unique_ptr<InputSet> > jaffarPlus::Runner::_allowedInputSets
private

Parsed allowed input sets.

Definition at line 594 of file runner.hpp.

◆ _allowedInputSetsJs

std::vector<nlohmann::json> jaffarPlus::Runner::_allowedInputSetsJs
private

JSON descriptions of the allowed input sets (parsed at initialization).

Definition at line 588 of file runner.hpp.

◆ _bypassHashCalculation

bool jaffarPlus::Runner::_bypassHashCalculation
private

Whether computeHash returns the game's direct hash instead of hashing via MetroHash128.

Definition at line 558 of file runner.hpp.

◆ _candidateInputSets

std::vector<std::unique_ptr<InputSet> > jaffarPlus::Runner::_candidateInputSets
private

Parsed candidate input sets.

Definition at line 592 of file runner.hpp.

◆ _candidateInputSetsJs

std::vector<nlohmann::json> jaffarPlus::Runner::_candidateInputSetsJs
private

JSON descriptions of the candidate input sets (parsed at initialization).

Definition at line 590 of file runner.hpp.

◆ _frameskipCustomInput

std::string jaffarPlus::Runner::_frameskipCustomInput
private

The custom input string to apply on skipped frames.

Definition at line 578 of file runner.hpp.

◆ _frameskipCustomInputIdx

InputSet::inputIndex_t jaffarPlus::Runner::_frameskipCustomInputIdx {}
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.

◆ _frameskipRate

size_t jaffarPlus::Runner::_frameskipRate
private

Number of frames to skip after each applied input.

Definition at line 574 of file runner.hpp.

◆ _frameskipUseCustomInput

bool jaffarPlus::Runner::_frameskipUseCustomInput
private

Whether skipped frames use the custom input; false repeats the applied input.

Definition at line 576 of file runner.hpp.

◆ _game

std::unique_ptr<Game> jaffarPlus::Runner::_game
private

The owned game instance driven by the runner.

Definition at line 545 of file runner.hpp.

◆ _hashStepTolerance

uint32_t jaffarPlus::Runner::_hashStepTolerance
private

Hash step tolerance, used to derive the hash-step-tolerance stage.

Definition at line 547 of file runner.hpp.

◆ _historyBacking

std::shared_ptr<void> jaffarPlus::Runner::_historyBacking
private

Shared backing (e.g. the one trie), injected by the engine or owned privately.

Definition at line 554 of file runner.hpp.

◆ _historyNumShards

uint32_t jaffarPlus::Runner::_historyNumShards = 2
private

Shard count of the backing (engine: threadCount+1; standalone: 2).

Definition at line 556 of file runner.hpp.

◆ _historyShardId

uint32_t jaffarPlus::Runner::_historyShardId = 0
private

This runner's contention-free free-list shard (its worker thread id).

Definition at line 555 of file runner.hpp.

◆ _inputHashMap

std::map<jaffarCommon::hash::hash_t, InputSet::inputIndex_t> jaffarPlus::Runner::_inputHashMap
private

Maps an input string's hash to its index.

Definition at line 566 of file runner.hpp.

◆ _inputHistory

std::unique_ptr<InputHistory> jaffarPlus::Runner::_inputHistory
private

The configured strategy instance (built in initialize()).

Definition at line 551 of file runner.hpp.

◆ _inputHistoryConfig

nlohmann::json jaffarPlus::Runner::_inputHistoryConfig
private

The "Store Input History" config object (selects None/Raw/Trie).

Definition at line 550 of file runner.hpp.

◆ _inputStringMap

std::map<InputSet::inputIndex_t, std::string> jaffarPlus::Runner::_inputStringMap
private

Maps an input index back to its input string.

Definition at line 568 of file runner.hpp.

◆ _isInitialized

bool jaffarPlus::Runner::_isInitialized = false
private

Whether the runner has been initialized.

Definition at line 543 of file runner.hpp.

◆ _largestInputSetSize

size_t jaffarPlus::Runner::_largestInputSetSize = 0
private

Largest input set size detected (used for output formatting).

Definition at line 596 of file runner.hpp.

◆ _maxInputIndex

InputSet::inputIndex_t jaffarPlus::Runner::_maxInputIndex = 0
private

One past the highest registered input index; determines the input-history encoding width.

Definition at line 564 of file runner.hpp.

◆ _showAllowedInputs

bool jaffarPlus::Runner::_showAllowedInputs
private

Whether allowed inputs are printed in printInfo.

Definition at line 602 of file runner.hpp.

◆ _showEmptyInputSlots

bool jaffarPlus::Runner::_showEmptyInputSlots
private

Whether placeholders are printed for unused input slots.

Definition at line 600 of file runner.hpp.

◆ _stepCount

size_t jaffarPlus::Runner::_stepCount = 0
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.

◆ _testCandidateInputs

bool jaffarPlus::Runner::_testCandidateInputs
private

Whether candidate input sets are parsed and tested.

Definition at line 598 of file runner.hpp.


The documentation for this class was generated from the following file: