Abstract base class for a JaffarPlus game. More...

#include <game.hpp>

Public Types
enum	stateType_t { normal = 0 , win = 1 , fail = 2 }
	Classification of the current game state, derived from the satisfied rules. More...

Public Member Functions
	Game (std::unique_ptr< Emulator > emulator, const nlohmann::json &config)
	Constructs a game from an already created emulator and a configuration object.

std::string	getRegisteredPropertyNames () const
	Returns a comma-separated list of the property names registered for this game.

void	initialize ()
	Initializes the game: emulator, properties, rules and the first state update.

	Game ()=delete
	Default construction is disabled; a game requires an emulator and config.

void	advanceState (const InputSet::inputIndex_t input)
	Advances the game state by applying a single input.

void	serializeState (jaffarCommon::serializer::Base &serializer) const
	Serializes the full game state.

void	deserializeState (jaffarCommon::deserializer::Base &deserializer)
	Restores the full game state previously written by serializeState.

void	computeHash (MetroHash128 &hashEngine) const
	Updates a hash engine with the current state's distinguishing data.

void	printInfo () const
	Prints the current game state to the logger.

void	evaluateRules ()
	Evaluates the rule set against the current state.

void	runGameSpecificRuleActions ()
	Runs the registered actions of every currently satisfied rule.

void	updateGameStateType ()
	Recomputes the state type and checkpoint level from the satisfied rules.

void	updateReward ()
	Recomputes the current state's reward from the satisfied rules.

std::unique_ptr< Condition >	parseCondition (const nlohmann::json &conditionJs)
	Parses a single rule condition from JSON into a typed Condition.

Emulator *	getEmulator () const
	Returns a pointer to the internal emulator.

float	getFrameRate () const
	Returns the configured frame rate.

float	getReward () const
	Returns the current state's reward.

virtual std::string	getTraceLine () const
	One line of a per-step trace for `player --dumpTrace` (space-separated coordinates the game wants to record, e.g.

virtual float	getFloorReward () const
	Reward used for the Reference Reward Floor comparison: the un-biased progress reward, WITHOUT any eviction-only ranking penalty (e.g.

stateType_t	getStateType () const
	Returns the current state type (normal, win or fail).

size_t	getCheckpointLevel () const
	Returns the current state's checkpoint level.

size_t	getCheckpointTolerance () const
	Returns the current state's checkpoint tolerance.

bool	isSaveSolution () const
	Indicates whether the current state should trigger a save solution.

ssize_t	getSaveSolutionPrevLastRuleIdx () const
	Returns the previous last rule index that set a save solution.

ssize_t	getSaveSolutionCurrentLastRuleIdx () const
	Returns the current last rule index that set a save solution.

const std::string	getSaveSolutionPath () const
	Returns the save path of the rule that activated the current save solution.

std::string	getName () const
	Returns the game name used at runtime.

bool	isInitialized () const
	Returns whether the game has been initialized.

virtual jaffarCommon::hash::hash_t	getStateInputHash ()
	Returns a hash identifying the current state for new-input discovery.

virtual void	getAdditionalAllowedInputs (std::vector< InputSet::inputIndex_t > &allowedInputSet)
	Lets a game contribute additional allowed inputs based on game-specific decisions.

virtual std::set< std::string >	getAllPossibleInputs ()
	Reports all possible inputs the game might require.

virtual void	playerPrintCommands () const
	Prints the game's player-specific commands, if any.

virtual bool	playerParseCommand (const int command)
	Handles a game-specific player command.

virtual jaffarCommon::hash::hash_t	getDirectStateHash () const
	Returns the state hash directly, without going through a hashing engine.

Static Public Member Functions
static std::unique_ptr< Game >	getGame (const nlohmann::json &emulatorConfig, const nlohmann::json &gameConfig)
	Factory that constructs the concrete game matching the given configuration.

Protected Member Functions
void	finalizeGameConfig ()
	Asserts that every key in the game configuration has been recognized.

void *	registerGameProperty (const std::string &name, void *const pointer, const Property::datatype_t dataType, const Property::endianness_t endianness)
	Registers a game property so it can be referenced by name in rules and printing/hashing.

void	parseRules (const nlohmann::json &rulesJson)
	Parses the full rule array, builds the rule objects and resolves cross-references.

void	parseRule (Rule &rule, const nlohmann::json &ruleJs)
	Parses a single rule's conditions, actions and "Satisfies" labels into a Rule.

void	parseRuleAction (Rule &rule, const nlohmann::json &actionJs)
	Parses a single rule action from JSON and applies it to the rule.

void	satisfyRule (Rule &rule)
	Marks a rule as satisfied, recursively satisfying the rules it satisfies first.

virtual void	initializeImpl ()
	Game-specific initialization hook, called during initialize.

virtual void	registerGameProperties ()=0
	Registers the game's properties (via registerGameProperty).

virtual void	serializeStateImpl (jaffarCommon::serializer::Base &serializer) const =0
	Serializes game-specific state.

virtual void	deserializeStateImpl (jaffarCommon::deserializer::Base &deserializer)=0
	Restores game-specific state previously written by serializeStateImpl.

virtual float	calculateGameSpecificReward () const =0
	Computes the game-specific contribution to the state reward.

virtual void	computeAdditionalHashing (MetroHash128 &hashEngine) const =0
	Adds game-specific data into the hash engine.

virtual void	printInfoImpl () const =0
	Prints game-specific state information to the logger.

virtual void	advanceStateImpl (const InputSet::inputIndex_t input)=0
	Advances the game state by applying the given input.

virtual bool	parseRuleActionImpl (Rule &rule, const std::string &actionType, const nlohmann::json &actionJs)=0
	Parses and applies a game-specific rule action.

virtual void	stateUpdatePreHook ()
	Optional hook run before a state update (advance/deserialize). Base does nothing.

virtual void	stateUpdatePostHook ()
	Optional hook run after a state update (advance/deserialize). Base does nothing.

virtual void	ruleUpdatePreHook ()
	Optional hook run before rule evaluation/restoration. Base does nothing.

virtual void	ruleUpdatePostHook ()
	Optional hook run after rule evaluation/restoration. Base does nothing.

Protected Attributes
stateType_t	_stateType = stateType_t::normal
	Current game state type. Initialized to normal because it is read (printInfo) and serialized for the initial state before updateGameStateType() first assigns it.

float	_reward = 0.0
	Current game state reward.

size_t	_checkpointLevel = 0
	Current state's checkpoint level.

size_t	_checkpointTolerance = 0
	Tolerance recorded for checkpoint states.

ssize_t	_saveSolutionCurrentLastRuleIdx = -1
	Previous last rule index that activated a save solution (preserved to mark the state where it changes); save state activates only when a rule id exceeds it.

ssize_t	_saveSolutionCurrentLastRuleId = -1
	Current last rule index that activated a save solution; save state activates only when a rule id is bigger than the previous one. -1 when none.

const std::unique_ptr< Emulator >	_emulator
	Underlying emulator instance.

std::vector< std::unique_ptr< Rule > >	_rules
	Game script rules, kept in a vector to preserve ordering.

std::vector< uint8_t >	_rulesStatus
	Bit vector indicating whether each rule has been satisfied.

std::vector< std::string >	_printablePropertyNames
	Parsed property names configured to be printed.

std::vector< std::string >	_hashablePropertyNames
	Parsed property names configured to be hashed.

std::vector< const Property * >	_propertyHashVector
	Properties used to hash/distinguish states, ordered.

std::vector< const Property * >	_propertyPrintVector
	Properties printed for game information, ordered.

std::map< jaffarCommon::hash::hash_t, std::unique_ptr< Property > >	_propertyMap
	All registered properties, indexed by name hash.

float	_frameRate
	Frame rate to play the game with, required for correct playback.

bool	_bypassEmulatorState
	When true, the game handles state save/load entirely, bypassing the emulator.

std::string	_gameName
	Game name (for runtime use).

nlohmann::json	_rulesJs
	Temporary storage of the rules JSON for delayed parsing.

nlohmann::json	_gameConfigRemaining
	Mutable working copy of the game config; recognized keys are popped, leftovers are unrecognized. See finalizeGameConfig().

bool	_isInitialized = false
	Whether the game has been initialized.

Detailed Description

Abstract base class for a JaffarPlus game.

A game wraps an Emulator and exposes the search-facing interface: it advances and (de)serializes state, computes state hashes, evaluates a configured rule set, and tracks the derived state type, reward, checkpoint level and save-solution information. Concrete games subclass it and implement the pure-virtual hooks (e.g. registerGameProperties, advanceStateImpl, serializeStateImpl, deserializeStateImpl, calculateGameSpecificReward, computeAdditionalHashing, printInfoImpl and parseRuleActionImpl).

Definition at line 38 of file game.hpp.

Member Enumeration Documentation

◆ stateType_t

enum jaffarPlus::Game::stateType_t

Classification of the current game state, derived from the satisfied rules.

Enumerator
normal	No win or fail rule is currently satisfied.
win	A win rule is currently satisfied.
fail	A fail rule is currently satisfied.

Definition at line 42 of file game.hpp.

Constructor & Destructor Documentation

◆ Game()

jaffarPlus::Game::Game	(	std::unique_ptr< Emulator >	emulator,
		const nlohmann::json &	config
	)

inline

Constructs a game from an already created emulator and a configuration object.

Parameters

emulator	The emulator instance this game takes ownership of.
config	Game configuration JSON, providing "Game Name", "Frame Rate", "Bypass Emulator State", "Print Properties", "Hash Properties" and "Rules".

Definition at line 55 of file game.hpp.

Member Function Documentation

◆ advanceState()

void jaffarPlus::Game::advanceState ( const InputSet::inputIndex_t input )

inline

Advances the game state by applying a single input.

Runs the pre-update hook, snapshots the previous save-solution rule id, calls advanceStateImpl with the input, then runs the post-update hook.

Parameters

input The input index to apply for this step.

Definition at line 164 of file game.hpp.

◆ advanceStateImpl()

virtual void jaffarPlus::Game::advanceStateImpl ( const InputSet::inputIndex_t input )

protectedpure virtual

Advances the game state by applying the given input.

Must be implemented.

Parameters

input The input index to apply for this step.

◆ calculateGameSpecificReward()

virtual float jaffarPlus::Game::calculateGameSpecificReward ( ) const

protectedpure virtual

Computes the game-specific contribution to the state reward.

Must be implemented.

Returns: The game-specific reward to add to the rule-based reward.

◆ computeAdditionalHashing()

virtual void jaffarPlus::Game::computeAdditionalHashing ( MetroHash128 & hashEngine ) const

protectedpure virtual

Adds game-specific data into the hash engine.

Must be implemented.

Parameters

hashEngine The hash engine to update with game-specific data.

◆ computeHash()

void jaffarPlus::Game::computeHash ( MetroHash128 & hashEngine ) const

inline

Updates a hash engine with the current state's distinguishing data.

Feeds each hashable property's bytes into the engine, then calls computeAdditionalHashing for any game-specific contribution.

Parameters

hashEngine The hash engine to update.

Definition at line 273 of file game.hpp.

◆ deserializeState()

void jaffarPlus::Game::deserializeState ( jaffarCommon::deserializer::Base & deserializer )

inline

Restores the full game state previously written by serializeState.

Runs the pre-update hook, restores the emulator state (unless bypassed) and game-specific data via deserializeStateImpl, runs the post-update hook, then pops the reward, checkpoint level, save-solution rule ids and state type. Finally runs the pre-rule hook, restores the rule status vector, re-runs game-specific rule actions and runs the post-rule hook.

Parameters

deserializer The deserializer to pop state from.

Definition at line 224 of file game.hpp.

◆ deserializeStateImpl()

virtual void jaffarPlus::Game::deserializeStateImpl ( jaffarCommon::deserializer::Base & deserializer )

protectedpure virtual

Restores game-specific state previously written by serializeStateImpl.

Must be implemented.

Parameters

deserializer The deserializer to pop game-specific state from.

◆ evaluateRules()

void jaffarPlus::Game::evaluateRules ( )

inline

Evaluates the rule set against the current state.

Runs the pre-rule hook, then for each not-yet-satisfied rule evaluates its conditions and, if met, marks it satisfied via satisfyRule. Afterwards runs game-specific rule actions and the post-rule hook.

Definition at line 351 of file game.hpp.

◆ finalizeGameConfig()

void jaffarPlus::Game::finalizeGameConfig ( )

inlineprotected

Asserts that every key in the game configuration has been recognized.

Call this at the END of a derived core's constructor, after it has consumed all of its own configuration keys (via the jaffarCommon::json::pop* helpers) from _gameConfigRemaining. The base ctor has already popped the common keys (Game Name, Frame Rate, Bypass Emulator State, Print Properties, Hash Properties, Rules), so anything still present is an unrecognized key (a typo or unsupported option) and is reported by name. Cores that do not call this remain lenient (opt-in strict validation).

Definition at line 681 of file game.hpp.

◆ getAdditionalAllowedInputs()

virtual void jaffarPlus::Game::getAdditionalAllowedInputs ( std::vector< InputSet::inputIndex_t > & allowedInputSet )

inlinevirtual

Lets a game contribute additional allowed inputs based on game-specific decisions.

Base implementation does nothing; games may override it to append inputs.

Parameters

allowedInputSet The set of allowed input indices to extend.

Definition at line 645 of file game.hpp.

◆ getAllPossibleInputs()

virtual std::set< std::string > jaffarPlus::Game::getAllPossibleInputs ( )

inlinevirtual

Reports all possible inputs the game might require.

Base implementation returns an empty set; games may override it.

Returns: The set of possible input names.

Definition at line 652 of file game.hpp.

◆ getCheckpointLevel()

size_t jaffarPlus::Game::getCheckpointLevel ( ) const

inline

Returns the current state's checkpoint level.

Definition at line 604 of file game.hpp.

◆ getCheckpointTolerance()

size_t jaffarPlus::Game::getCheckpointTolerance ( ) const

inline

Returns the current state's checkpoint tolerance.

Definition at line 607 of file game.hpp.

◆ getDirectStateHash()

virtual jaffarCommon::hash::hash_t jaffarPlus::Game::getDirectStateHash ( ) const

inlinevirtual

Returns the state hash directly, without going through a hashing engine.

Base implementation returns a default (empty) hash; games may override it.

Returns: The direct state hash.

Definition at line 668 of file game.hpp.

◆ getEmulator()

Emulator * jaffarPlus::Game::getEmulator ( ) const

inline

Returns a pointer to the internal emulator.

Definition at line 570 of file game.hpp.

◆ getFloorReward()

virtual float jaffarPlus::Game::getFloorReward ( ) const

inlinevirtual

Reward used for the Reference Reward Floor comparison: the un-biased progress reward, WITHOUT any eviction-only ranking penalty (e.g.

a trace magnet). Defaults to the full reward; a game that subtracts a ranking-only bias from its reward overrides this to add that bias back, so the floor measures true progress (position) and never false-cancels a position-correct-but-biased state.

Definition at line 598 of file game.hpp.

◆ getFrameRate()

float jaffarPlus::Game::getFrameRate ( ) const

inline

Returns the configured frame rate.

Definition at line 581 of file game.hpp.

◆ getGame()

static std::unique_ptr< Game > jaffarPlus::Game::getGame	(	const nlohmann::json &	emulatorConfig,
		const nlohmann::json &	gameConfig
	)

static

Factory that constructs the concrete game matching the given configuration.

Parameters

emulatorConfig	The emulator configuration JSON.
gameConfig	The game configuration JSON.

Returns: An owning pointer to the constructed game.

◆ getName()

std::string jaffarPlus::Game::getName ( ) const

inline

Returns the game name used at runtime.

Definition at line 628 of file game.hpp.

◆ getRegisteredPropertyNames()

std::string jaffarPlus::Game::getRegisteredPropertyNames ( ) const

inline

Returns a comma-separated list of the property names registered for this game.

Intended for use in error messages when a configured property name is not found.

Returns: The registered property names joined by ", ".

Definition at line 84 of file game.hpp.

◆ getReward()

float jaffarPlus::Game::getReward ( ) const

inline

Returns the current state's reward.

Definition at line 584 of file game.hpp.

◆ getSaveSolutionCurrentLastRuleIdx()

ssize_t jaffarPlus::Game::getSaveSolutionCurrentLastRuleIdx ( ) const

inline

Returns the current last rule index that set a save solution.

Definition at line 619 of file game.hpp.

◆ getSaveSolutionPath()

const std::string jaffarPlus::Game::getSaveSolutionPath ( ) const

inline

Returns the save path of the rule that activated the current save solution.

Returns: The save-solution path, or an empty string if the state is not a save solution.

Definition at line 625 of file game.hpp.

◆ getSaveSolutionPrevLastRuleIdx()

ssize_t jaffarPlus::Game::getSaveSolutionPrevLastRuleIdx ( ) const

inline

Returns the previous last rule index that set a save solution.

Definition at line 616 of file game.hpp.

◆ getStateInputHash()

virtual jaffarCommon::hash::hash_t jaffarPlus::Game::getStateInputHash ( )

inlinevirtual

Returns a hash identifying the current state for new-input discovery.

Base implementation returns a default (empty) hash; games may override it.

Returns: The state input hash.

Definition at line 638 of file game.hpp.

◆ getStateType()

stateType_t jaffarPlus::Game::getStateType ( ) const

inline

Returns the current state type (normal, win or fail).

Definition at line 601 of file game.hpp.

◆ getTraceLine()

virtual std::string jaffarPlus::Game::getTraceLine ( ) const

inlinevirtual

One line of a per-step trace for player --dumpTrace (space-separated coordinates the game wants to record, e.g.

for a trace-magnet reference). Default is empty; games override to emit their coordinates.

Definition at line 590 of file game.hpp.

◆ initialize()

void jaffarPlus::Game::initialize ( )

inline

Initializes the game: emulator, properties, rules and the first state update.

Initializes the emulator if needed, calls registerGameProperties, resolves the configured printable and hashable property names to property pointers, parses the rules, runs the pre-/post-update hooks around initializeImpl, and marks the game as initialized.

Exceptions

A	logic error if the game was already initialized, or if a configured printable or hashable property name is not registered.

Definition at line 100 of file game.hpp.

◆ initializeImpl()

virtual void jaffarPlus::Game::initializeImpl ( )

inlineprotectedvirtual

Game-specific initialization hook, called during initialize.

Base implementation does nothing; games may override it.

Definition at line 898 of file game.hpp.

◆ isInitialized()

bool jaffarPlus::Game::isInitialized ( ) const

inline

Returns whether the game has been initialized.

Definition at line 631 of file game.hpp.

◆ isSaveSolution()

bool jaffarPlus::Game::isSaveSolution ( ) const

inline

Indicates whether the current state should trigger a save solution.

Returns: true if the current save-solution rule id is greater than the previous one.

Definition at line 613 of file game.hpp.

◆ parseCondition()

std::unique_ptr< Condition > jaffarPlus::Game::parseCondition ( const nlohmann::json & conditionJs )

inline

Parses a single rule condition from JSON into a typed Condition.

Resolves the "Op" operator and the "Property" first operand (which must be registered), then interprets "Value": a number or boolean becomes an immediate second operand, while a string is treated as the name of a second registered property. The condition is instantiated as a _vCondition specialized to the first property's datatype.

Parameters

conditionJs The condition JSON object, expected to contain "Op", "Property" and "Value".

Returns: An owning pointer to the constructed condition.

Exceptions

A	logic error if the operator is unknown, a referenced property is not declared, the "Value" key is missing, or its format/type is invalid.

Definition at line 485 of file game.hpp.

◆ parseRule()

void jaffarPlus::Game::parseRule	(	Rule &	rule,
		const nlohmann::json &	ruleJs
	)

inlineprotected

Parses a single rule's conditions, actions and "Satisfies" labels into a Rule.

Reads the "Conditions", "Actions" and "Satisfies" arrays: each condition is parsed via parseCondition and added to the rule, each action via parseRuleAction, and each satisfies entry (which must be a number) is added as a satisfy-rule label.

Parameters

rule	The rule to populate.
ruleJs	The rule JSON object.

Exceptions

A	logic error if a "Satisfies" entry is not a number (and from the called parsers).

Definition at line 775 of file game.hpp.

◆ parseRuleAction()

void jaffarPlus::Game::parseRuleAction	(	Rule &	rule,
		const nlohmann::json &	actionJs
	)

inlineprotected

Parses a single rule action from JSON and applies it to the rule.

Recognizes the built-in action types "Add Reward", "Trigger Fail", "Trigger Win", "Trigger Checkpoint" (with "Tolerance") and "Trigger Save Solution" (with "Path"). Any other action type is delegated to the game-specific parseRuleActionImpl.

Parameters

rule	The rule to apply the action to.
actionJs	The action JSON object, expected to contain "Type".

Exceptions

A	logic error if the action type is not recognized by either the built-ins or the game-specific parser.

Definition at line 814 of file game.hpp.

◆ parseRuleActionImpl()

virtual bool jaffarPlus::Game::parseRuleActionImpl	(	Rule &	rule,
		const std::string &	actionType,
		const nlohmann::json &	actionJs
	)

protectedpure virtual

Parses and applies a game-specific rule action.

Must be implemented.

Parameters

rule	The rule to apply the action to.
actionType	The action type string that was not matched by the built-in actions.
actionJs	The action JSON object.

Returns: true if the action type was recognized and applied; false otherwise.

◆ parseRules()

void jaffarPlus::Game::parseRules ( const nlohmann::json & rulesJson )

inlineprotected

Parses the full rule array, builds the rule objects and resolves cross-references.

Clears any existing rules, then for each JSON entry creates a Rule with its label and parses it via parseRule. Afterwards it resolves each rule's "Satisfies" labels into pointers to the referenced rules, and sizes/clears the rule status bit vector.

Parameters

rulesJson The array of rule JSON objects.

Exceptions

A	logic error if a rule entry is not an object, or if a referenced "Satisfies" label does not exist.

Definition at line 716 of file game.hpp.

◆ playerParseCommand()

virtual bool jaffarPlus::Game::playerParseCommand ( const int command )

inlinevirtual

Handles a game-specific player command.

Parameters

command The command code to handle.

Returns: true if the command was recognized and handled; base implementation returns false.

Definition at line 661 of file game.hpp.

◆ playerPrintCommands()

virtual void jaffarPlus::Game::playerPrintCommands ( ) const

inlinevirtual

Prints the game's player-specific commands, if any.

Base implementation does nothing.

Definition at line 655 of file game.hpp.

◆ printInfo()

void jaffarPlus::Game::printInfo ( ) const

inline

Prints the current game state to the logger.

Logs the state type, reward, per-rule satisfaction bits, and each printable property's value (formatted by datatype), then calls printInfoImpl for game-specific output.

Definition at line 288 of file game.hpp.

◆ printInfoImpl()

virtual void jaffarPlus::Game::printInfoImpl ( ) const

protectedpure virtual

Prints game-specific state information to the logger.

Must be implemented.

◆ registerGameProperties()

virtual void jaffarPlus::Game::registerGameProperties ( )

protectedpure virtual

Registers the game's properties (via registerGameProperty).

Must be implemented.

◆ registerGameProperty()

void * jaffarPlus::Game::registerGameProperty	(	const std::string &	name,
		void *const	pointer,
		const Property::datatype_t	dataType,
		const Property::endianness_t	endianness
	)

inlineprotected

Registers a game property so it can be referenced by name in rules and printing/hashing.

Parameters

name	The property name (used to compute the indexing hash).
pointer	Pointer to the underlying memory the property reads/writes.
dataType	The property's datatype.
endianness	The property's byte endianness.

Returns: The same pointer that was passed in (returned as a convenience).

Definition at line 691 of file game.hpp.

◆ ruleUpdatePostHook()

virtual void jaffarPlus::Game::ruleUpdatePostHook ( )

inlineprotectedvirtual

Optional hook run after rule evaluation/restoration. Base does nothing.

Definition at line 956 of file game.hpp.

◆ ruleUpdatePreHook()

virtual void jaffarPlus::Game::ruleUpdatePreHook ( )

inlineprotectedvirtual

Optional hook run before rule evaluation/restoration. Base does nothing.

Definition at line 954 of file game.hpp.

◆ runGameSpecificRuleActions()

void jaffarPlus::Game::runGameSpecificRuleActions ( )

inline

Runs the registered actions of every currently satisfied rule.

Definition at line 383 of file game.hpp.

◆ satisfyRule()

void jaffarPlus::Game::satisfyRule ( Rule & rule )

inlineprotected

Marks a rule as satisfied, recursively satisfying the rules it satisfies first.

For each sub-rule in this rule's satisfy list that is not yet satisfied, recurses into satisfyRule, then sets this rule's status bit to satisfied.

Parameters

rule	The rule to mark as satisfied.

Definition at line 875 of file game.hpp.

◆ serializeState()

void jaffarPlus::Game::serializeState ( jaffarCommon::serializer::Base & serializer ) const

inline

Serializes the full game state.

Serializes the emulator state (unless emulator state is bypassed), then game-specific data via serializeStateImpl, followed by the reward, checkpoint level, save-solution rule ids, state type and rule status vector.

Parameters

serializer The serializer to push state into.

Definition at line 187 of file game.hpp.

◆ serializeStateImpl()

virtual void jaffarPlus::Game::serializeStateImpl ( jaffarCommon::serializer::Base & serializer ) const

protectedpure virtual

Serializes game-specific state.

Must be implemented.

Parameters

serializer The serializer to push game-specific state into.

◆ stateUpdatePostHook()

virtual void jaffarPlus::Game::stateUpdatePostHook ( )

inlineprotectedvirtual

Optional hook run after a state update (advance/deserialize). Base does nothing.

Definition at line 952 of file game.hpp.

◆ stateUpdatePreHook()

virtual void jaffarPlus::Game::stateUpdatePreHook ( )

inlineprotectedvirtual

Optional hook run before a state update (advance/deserialize). Base does nothing.

Definition at line 950 of file game.hpp.

◆ updateGameStateType()

void jaffarPlus::Game::updateGameStateType ( )

inline

Recomputes the state type and checkpoint level from the satisfied rules.

Resets the state type to normal and the checkpoint level to zero, then iterates the satisfied rules: checkpoint rules increment the checkpoint level and record their tolerance, save-solution rules update the current save-solution rule id when their index exceeds the previous one, win rules set the state type to win, and fail rules set it to fail.

Definition at line 405 of file game.hpp.

◆ updateReward()

void jaffarPlus::Game::updateReward ( )

inline

Recomputes the current state's reward from the satisfied rules.

Resets the reward to zero, sums the reward of every satisfied rule, and adds the game-specific reward from calculateGameSpecificReward.

Definition at line 447 of file game.hpp.

Member Data Documentation

◆ _bypassEmulatorState

bool jaffarPlus::Game::_bypassEmulatorState

protected

When true, the game handles state save/load entirely, bypassing the emulator.

Definition at line 992 of file game.hpp.

◆ _checkpointLevel

size_t jaffarPlus::Game::_checkpointLevel = 0

protected

Current state's checkpoint level.

Definition at line 963 of file game.hpp.

◆ _checkpointTolerance

size_t jaffarPlus::Game::_checkpointTolerance = 0

protected

Tolerance recorded for checkpoint states.

Definition at line 965 of file game.hpp.

◆ _emulator

const std::unique_ptr<Emulator> jaffarPlus::Game::_emulator

protected

Underlying emulator instance.

Definition at line 974 of file game.hpp.

◆ _frameRate

float jaffarPlus::Game::_frameRate

protected

Frame rate to play the game with, required for correct playback.

Definition at line 990 of file game.hpp.

◆ _gameConfigRemaining

nlohmann::json jaffarPlus::Game::_gameConfigRemaining

protected

Mutable working copy of the game config; recognized keys are popped, leftovers are unrecognized. See finalizeGameConfig().

Definition at line 999 of file game.hpp.

◆ _gameName

std::string jaffarPlus::Game::_gameName

protected

Game name (for runtime use).

Definition at line 994 of file game.hpp.

◆ _hashablePropertyNames

std::vector<std::string> jaffarPlus::Game::_hashablePropertyNames

protected

Parsed property names configured to be hashed.

Definition at line 982 of file game.hpp.

◆ _isInitialized

bool jaffarPlus::Game::_isInitialized = false

protected

Whether the game has been initialized.

Definition at line 1001 of file game.hpp.

◆ _printablePropertyNames

std::vector<std::string> jaffarPlus::Game::_printablePropertyNames

protected

Parsed property names configured to be printed.

Definition at line 980 of file game.hpp.

◆ _propertyHashVector

std::vector<const Property*> jaffarPlus::Game::_propertyHashVector

protected

Properties used to hash/distinguish states, ordered.

Definition at line 984 of file game.hpp.

◆ _propertyMap

std::map<jaffarCommon::hash::hash_t, std::unique_ptr<Property> > jaffarPlus::Game::_propertyMap

protected

All registered properties, indexed by name hash.

Definition at line 988 of file game.hpp.

◆ _propertyPrintVector

std::vector<const Property*> jaffarPlus::Game::_propertyPrintVector

protected

Properties printed for game information, ordered.

Definition at line 986 of file game.hpp.

◆ _reward

float jaffarPlus::Game::_reward = 0.0

protected

Current game state reward.

Definition at line 961 of file game.hpp.

◆ _rules

std::vector<std::unique_ptr<Rule> > jaffarPlus::Game::_rules

protected

Game script rules, kept in a vector to preserve ordering.

Definition at line 976 of file game.hpp.

◆ _rulesJs

nlohmann::json jaffarPlus::Game::_rulesJs

protected

Temporary storage of the rules JSON for delayed parsing.

Definition at line 996 of file game.hpp.

◆ _rulesStatus

std::vector<uint8_t> jaffarPlus::Game::_rulesStatus

protected

Bit vector indicating whether each rule has been satisfied.

Definition at line 978 of file game.hpp.

◆ _saveSolutionCurrentLastRuleId

ssize_t jaffarPlus::Game::_saveSolutionCurrentLastRuleId = -1

protected

Current last rule index that activated a save solution; save state activates only when a rule id is bigger than the previous one. -1 when none.

Definition at line 972 of file game.hpp.

◆ _saveSolutionCurrentLastRuleIdx

ssize_t jaffarPlus::Game::_saveSolutionCurrentLastRuleIdx = -1

protected

Previous last rule index that activated a save solution (preserved to mark the state where it changes); save state activates only when a rule id exceeds it.

-1 when none.

Definition at line 969 of file game.hpp.

◆ _stateType

stateType_t jaffarPlus::Game::_stateType = stateType_t::normal

protected

Current game state type. Initialized to normal because it is read (printInfo) and serialized for the initial state before updateGameStateType() first assigns it.

Definition at line 959 of file game.hpp.

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

game.hpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ stateType_t

Constructor & Destructor Documentation

◆ Game()

Member Function Documentation

◆ advanceState()

◆ advanceStateImpl()

◆ calculateGameSpecificReward()

◆ computeAdditionalHashing()

◆ computeHash()

◆ deserializeState()

◆ deserializeStateImpl()

◆ evaluateRules()

◆ finalizeGameConfig()

◆ getAdditionalAllowedInputs()

◆ getAllPossibleInputs()

◆ getCheckpointLevel()

◆ getCheckpointTolerance()

◆ getDirectStateHash()

◆ getEmulator()

◆ getFloorReward()

◆ getFrameRate()

◆ getGame()

◆ getName()

◆ getRegisteredPropertyNames()

◆ getReward()

◆ getSaveSolutionCurrentLastRuleIdx()

◆ getSaveSolutionPath()

◆ getSaveSolutionPrevLastRuleIdx()

◆ getStateInputHash()

◆ getStateType()

◆ getTraceLine()

◆ initialize()

◆ initializeImpl()

◆ isInitialized()

◆ isSaveSolution()

◆ parseCondition()

◆ parseRule()

◆ parseRuleAction()

◆ parseRuleActionImpl()

◆ parseRules()

◆ playerParseCommand()

◆ playerPrintCommands()

◆ printInfo()

◆ printInfoImpl()

◆ registerGameProperties()

◆ registerGameProperty()

◆ ruleUpdatePostHook()

◆ ruleUpdatePreHook()

◆ runGameSpecificRuleActions()

◆ satisfyRule()

◆ serializeState()

◆ serializeStateImpl()

◆ stateUpdatePostHook()

◆ stateUpdatePreHook()

◆ updateGameStateType()

◆ updateReward()

Member Data Documentation

◆ _bypassEmulatorState

◆ _checkpointLevel

◆ _checkpointTolerance

◆ _emulator

◆ _frameRate

◆ _gameConfigRemaining

◆ _gameName

◆ _hashablePropertyNames

◆ _isInitialized

◆ _printablePropertyNames

◆ _propertyHashVector

◆ _propertyMap

◆ _propertyPrintVector

◆ _reward

◆ _rules

◆ _rulesJs