stmm-games-doc  0.32.0
Classes | Public Member Functions | List of all members
stmg::Game Class Reference
Inheritance diagram for stmg::Game:
Inheritance graph
[legend]

Classes

class  CreateLevelCallback
 Level factory callback. More...
 
struct  Init
 

Public Member Functions

 Game (Init &&oInit, CreateLevelCallback &oCreateLevelCallback, const Level::Init &oLevelInit) noexcept
 Constructor. More...
 
void reInit (Init &&oInit, CreateLevelCallback &oCreateLevelCallback, const Level::Init &oLevelInit) noexcept
 Reinitialize game instance. More...
 
const std::string & getName () const noexcept
 The name of the game. More...
 
const AppPreferencesprefs () const noexcept
 
GameOwnerowner () noexcept
 
const GameOwnerowner () const noexcept
 
int32_t getMaxViewTicks () const noexcept
 
int32_t getAdditionalHighscoresWait () const noexcept
 
void setGameView (GameView *p0GameView) noexcept
 Connect to the game view. More...
 
int64_t getGameId () const noexcept
 The game identifier. More...
 
NamedgetNamed () noexcept
 
const NamedgetNamed () const noexcept
 
bool isAllTeamsInOneLevel () const noexcept
 
int32_t getPlayer (int32_t nLevel, int32_t nLevelPlayer) noexcept
 Returns the preference player number from the level player number. More...
 
int32_t getTotLevels () const noexcept
 
shared_ptr< Level > & level (int32_t nLevel) noexcept
 
const shared_ptr< Level > & level (int32_t nLevel) const noexcept
 
const Variablevariable (int32_t nId) const noexcept
 Get a game variable by id. More...
 
Variablevariable (int32_t nId) noexcept
 Get a game variable by id. More...
 
const Variablevariable (int32_t nId, int32_t nLevel, int32_t nLevelTeam, int32_t nMate) const noexcept
 Get variable by context. More...
 
Variablevariable (int32_t nId, int32_t nLevel, int32_t nLevelTeam, int32_t nMate) noexcept
 Get variable by context. More...
 
std::pair< int32_t, OwnerTypevariableIdAndOwner (const std::string &sName) const noexcept
 Get variable id and owner type by name. More...
 
bool hasVariableId (int32_t nId, OwnerType eOwnerType) const noexcept
 Whether a variable id exists. More...
 
int32_t getGameVarIdGameOverTime () const noexcept
 
int32_t getGameVarIdWinnerTeam () const noexcept
 
int32_t getTeamVarIdFinishedTime () const noexcept
 
int32_t getTeamVarIdRank () const noexcept
 
int32_t getTeamVarIdHighscoreRank () const noexcept
 
int32_t getTeamVarIdStatus () const noexcept
 
int32_t getPlayerVarIdFinishedTime () const noexcept
 
int32_t getPlayerVarIdStatus () const noexcept
 
const shared_ptr< Layout > & getLayout () const noexcept
 
const shared_ptr< const Highscore > & getPreGameHighscore () const noexcept
 
Highscore const & getInGameHighscore () const noexcept
 
void interrupt (GameProxy::INTERRUPT_TYPE eInterruptType) noexcept
 
void setLevelView (int32_t nLevel, LevelView *p0View) noexcept
 Set the view for a level. More...
 
void start () noexcept
 Start the game. More...
 
void end () noexcept
 End the game. More...
 
bool isRunning () const noexcept
 Whether the game is running. More...
 
void handleInput (const shared_ptr< stmi::Event > &refEvent) noexcept
 The game's input event handler. More...
 
void handleTimer () noexcept
 The game progress function. More...
 
bool isInGameTick () const noexcept
 
double gameInterval () const noexcept
 The game interval. More...
 
double gameNextInterval () const noexcept
 The next game interval. More...
 
double gameElapsedMillisec () const noexcept
 The elapsed time since the game start in milliseconds. More...
 
int32_t gameElapsed () const noexcept
 The elapsed time since the game start in intervals. More...
 
void changedInterval (int32_t nLevel) noexcept
 Signal a level's interval has changed. More...
 
int32_t gameStatusPlayingTeams () noexcept
 The number of teams still playing. More...
 
int32_t gameStatusCompleted (int32_t nCompletedLevel, int32_t nLevelTeam, bool bForceOthersFailed, bool bCreateTexts) noexcept
 Declare team completed the game. More...
 
int32_t gameStatusFailed (int32_t nFailedLevel, int32_t nLevelTeam, bool bForceOtherCompleted, bool bCreateTexts) noexcept
 Declare team failed the game. More...
 
void gameStatusTechnical (int32_t nBadLevel, const std::vector< std::string > &aIssue) noexcept
 Technical game over. More...
 
void othersSend (int32_t nSenderLevel, int32_t nMsg, int32_t nValue) noexcept
 Send a message to other level's receivers. More...
 
shared_ptr< GameSoundcreateSound (int32_t nSoundIdx, int32_t nTeam, int32_t nMate, FPoint oXYPos, double fZPos, bool bListenerRelative, double fVolume01, bool bLooping) noexcept
 Create a game sound. More...
 
void preloadSound (int32_t nSoundIdx) noexcept
 Pre-load a sound. More...
 
bool removeSound (const shared_ptr< GameSound > &refSound) noexcept
 Remove a sound. More...
 
double getSoundScaleX () const noexcept
 The x scale from tiles to sound coordinates. More...
 
double getSoundScaleY () const noexcept
 The y scale from tiles to sound coordinates. More...
 
double getSoundScaleZ () const noexcept
 The z scale from tiles to sound coordinates. More...
 
int32_t getBoardPainterIdx () const noexcept
 The painter to use to draw board tiles. More...
 
int32_t getBlockPainterIdx () const noexcept
 The painter to use to draw block tiles. More...
 
int32_t random (int32_t nFrom, int32_t nTo) noexcept override
 Return a random value within a range. More...
 
void createKeyActionFromXYEvent (int32_t nLevel, int32_t nLevelTeam, int32_t nMate, int32_t nKeyActionId, const shared_ptr< stmi::Event > &refXYEvent) noexcept
 Create a key action input event for a player from an xy event. More...
 
void handleInput (int32_t nTeam, int32_t nMate, const shared_ptr< stmi::Event > &refEvent) noexcept
 Send an input event directly to a player. More...
 
bool getUniqueActiveHumanPlayer (int32_t &nLevel, int32_t &nLevelTeam, int32_t &nMate) noexcept
 Get the unique active human player within a context. More...
 
bool getUniqueActiveHumanPlayer (int32_t &nTeam, int32_t &nMate) noexcept
 Get the unique active human player within a context. More...
 
- Public Member Functions inherited from stmg::RandomSource
virtual ~RandomSource () noexcept=default
 

Constructor & Destructor Documentation

◆ Game()

stmg::Game::Game ( Init &&  oInit,
CreateLevelCallback oCreateLevelCallback,
const Level::Init oLevelInit 
)
noexcept

Constructor.

See Game::reInit().

Member Function Documentation

◆ changedInterval()

void stmg::Game::changedInterval ( int32_t  nLevel)
noexcept

Signal a level's interval has changed.

Parameters
nLevelThe level.

◆ createKeyActionFromXYEvent()

void stmg::Game::createKeyActionFromXYEvent ( int32_t  nLevel,
int32_t  nLevelTeam,
int32_t  nMate,
int32_t  nKeyActionId,
const shared_ptr< stmi::Event > &  refXYEvent 
)
noexcept

Create a key action input event for a player from an xy event.

Note that the creation might fail if a key action with the same id and player is already happening, for example from a (keyboard) key.

Parameters
nLevelThe player's level. Must be >= 0.
nLevelTeamThe player's level team. Must be >= 0.
nMateThe player's mate number within the team. Must be >= 0.
nKeyActionIdThe key action id. Must be valid.
refXYEventThe input event. Must be of type stmi::XYEvent. Cannot be null.

◆ createSound()

shared_ptr<GameSound> stmg::Game::createSound ( int32_t  nSoundIdx,
int32_t  nTeam,
int32_t  nMate,
FPoint  oXYPos,
double  fZPos,
bool  bListenerRelative,
double  fVolume01,
bool  bLooping 
)
noexcept

Create a game sound.

The team or mate select the player(s) that should hear the sound. When nTeam is not -1, the sound can only be heard in per player sound mode, or there is only one human player and nTeamand nMate select it (or its team).

Parameters
nSoundIdxThe sound index according to Named::sounds(). Must be valid.
nTeamThe team or -1 if a sound directed to all.
nMateThe team or -1 if a sound directed to all ot team.
oXYPosThe position of the sound on the board. Absolute or relative to the listener.
fZPosThe z position of the sound.
bListenerRelativeWhether oXYPos is relative to the listener.
fVolume01The volume. Must be from 0.0 (inaudible) to 1.0 (max).
bLoopingWhether the sound should continuously repeat.
Returns
The created sound or null if not supported.

◆ end()

void stmg::Game::end ( )
noexcept

End the game.

Calling this function when the game is not running is an error.

◆ gameElapsed()

int32_t stmg::Game::gameElapsed ( ) const
inlinenoexcept

The elapsed time since the game start in intervals.

Returns
The elapsed time (ticks).

◆ gameElapsedMillisec()

double stmg::Game::gameElapsedMillisec ( ) const
inlinenoexcept

The elapsed time since the game start in milliseconds.

Returns
The elapsed time (milliseconds).

◆ gameInterval()

double stmg::Game::gameInterval ( ) const
inlinenoexcept

The game interval.

In a game tick the current interval cannot be changed. Levels can only determine the next game interval.

The game's interval is a function of each level's interval. Currently it is always set to the minimum of all levels.

Returns
The interval in millisec.

◆ gameNextInterval()

double stmg::Game::gameNextInterval ( ) const
inlinenoexcept

The next game interval.

The game's interval is a function of each level's interval. Currently it is always set to the minimum of all levels.

Returns
The next interval in millisec.

◆ gameStatusCompleted()

int32_t stmg::Game::gameStatusCompleted ( int32_t  nCompletedLevel,
int32_t  nLevelTeam,
bool  bForceOthersFailed,
bool  bCreateTexts 
)
noexcept

Declare team completed the game.

The first team that completes the game has rank 1, the second rank 2, etc.

Parameters
nCompletedLevelThe level of the team that completed the game.
nLevelTeamThe level team that completed the game.
bForceOthersFailedWhether other still playing teams status is set to failed.
bCreateTextsWhether to create default texts.
Returns
The rank (1 is first to complete).

◆ gameStatusFailed()

int32_t stmg::Game::gameStatusFailed ( int32_t  nFailedLevel,
int32_t  nLevelTeam,
bool  bForceOtherCompleted,
bool  bCreateTexts 
)
noexcept

Declare team failed the game.

The first team that fails the game has rank "prefs().getTotTeams()", the second has rank "prefs().getTotTeams() - 1", etc.

Parameters
nFailedLevelThe level of the team that failed the game.
nLevelTeamThe level team that failed the game.
bForceOtherCompletedWhether other still playing team status is set to completed.
bCreateTextsWhether to create default texts.
Returns
The rank (1 is last to fail).

◆ gameStatusPlayingTeams()

int32_t stmg::Game::gameStatusPlayingTeams ( )
noexcept

The number of teams still playing.

Returns
The number of teams that haven't completed or failed the game.

◆ gameStatusTechnical()

void stmg::Game::gameStatusTechnical ( int32_t  nBadLevel,
const std::vector< std::string > &  aIssue 
)
noexcept

Technical game over.

Parameters
nBadLevelThe level in which a technical issue occurred.
aIssueThe strings describing the issue.

◆ getAdditionalHighscoresWait()

int32_t stmg::Game::getAdditionalHighscoresWait ( ) const
inlinenoexcept

◆ getBlockPainterIdx()

int32_t stmg::Game::getBlockPainterIdx ( ) const
inlinenoexcept

The painter to use to draw block tiles.

Returns
The painter index into named().painters() or -1.

◆ getBoardPainterIdx()

int32_t stmg::Game::getBoardPainterIdx ( ) const
inlinenoexcept

The painter to use to draw board tiles.

Returns
The painter index into named().painters() or -1.

◆ getGameId()

int64_t stmg::Game::getGameId ( ) const
inlinenoexcept

The game identifier.

The game id is a unique number set when the game is started.

Returns
The game id.

◆ getGameVarIdGameOverTime()

int32_t stmg::Game::getGameVarIdGameOverTime ( ) const
inlinenoexcept

◆ getGameVarIdWinnerTeam()

int32_t stmg::Game::getGameVarIdWinnerTeam ( ) const
inlinenoexcept

◆ getInGameHighscore()

Highscore const& stmg::Game::getInGameHighscore ( ) const
inlinenoexcept

◆ getLayout()

const shared_ptr<Layout>& stmg::Game::getLayout ( ) const
noexcept

◆ getMaxViewTicks()

int32_t stmg::Game::getMaxViewTicks ( ) const
inlinenoexcept

◆ getName()

const std::string& stmg::Game::getName ( ) const
inlinenoexcept

The name of the game.

Returns
The name.

◆ getNamed() [1/2]

Named& stmg::Game::getNamed ( )
inlinenoexcept

◆ getNamed() [2/2]

const Named& stmg::Game::getNamed ( ) const
inlinenoexcept

◆ getPlayer()

int32_t stmg::Game::getPlayer ( int32_t  nLevel,
int32_t  nLevelPlayer 
)
noexcept

Returns the preference player number from the level player number.

Parameters
nLevelThe level. Must be >= 0 and < getTotLevels().
nLevelPlayerThe level player.
Returns
The preference player.

◆ getPlayerVarIdFinishedTime()

int32_t stmg::Game::getPlayerVarIdFinishedTime ( ) const
inlinenoexcept

◆ getPlayerVarIdStatus()

int32_t stmg::Game::getPlayerVarIdStatus ( ) const
inlinenoexcept

◆ getPreGameHighscore()

const shared_ptr<const Highscore>& stmg::Game::getPreGameHighscore ( ) const
inlinenoexcept

◆ getSoundScaleX()

double stmg::Game::getSoundScaleX ( ) const
inlinenoexcept

The x scale from tiles to sound coordinates.

Returns
The x scale.

◆ getSoundScaleY()

double stmg::Game::getSoundScaleY ( ) const
inlinenoexcept

The y scale from tiles to sound coordinates.

Returns
The y scale.

◆ getSoundScaleZ()

double stmg::Game::getSoundScaleZ ( ) const
inlinenoexcept

The z scale from tiles to sound coordinates.

Returns
The z scale.

◆ getTeamVarIdFinishedTime()

int32_t stmg::Game::getTeamVarIdFinishedTime ( ) const
inlinenoexcept

◆ getTeamVarIdHighscoreRank()

int32_t stmg::Game::getTeamVarIdHighscoreRank ( ) const
inlinenoexcept

◆ getTeamVarIdRank()

int32_t stmg::Game::getTeamVarIdRank ( ) const
inlinenoexcept

◆ getTeamVarIdStatus()

int32_t stmg::Game::getTeamVarIdStatus ( ) const
inlinenoexcept

◆ getTotLevels()

int32_t stmg::Game::getTotLevels ( ) const
inlinenoexcept

◆ getUniqueActiveHumanPlayer() [1/2]

bool stmg::Game::getUniqueActiveHumanPlayer ( int32_t &  nLevel,
int32_t &  nLevelTeam,
int32_t &  nMate 
)
noexcept

Get the unique active human player within a context.

Parameters
nLevel(Input) The level context (if >=0) or -1. (Output) The level of the found player.
nLevelTeam(Input) The level team context (if >=0) or -1. (Output) The level team of the found player.
nMate(Input) The mate number context (if >=0) or -1. (Output) The mate number of the found player.
Returns
Whether there is an active player and it is only one.

◆ getUniqueActiveHumanPlayer() [2/2]

bool stmg::Game::getUniqueActiveHumanPlayer ( int32_t &  nTeam,
int32_t &  nMate 
)
noexcept

Get the unique active human player within a context.

Parameters
nTeam(Input) The team context (if >=0) or -1. (Output) The team of the found player.
nMate(Input) The mate number context (if >=0) or -1. (Output) The mate number of the found player.
Returns
Whether there is an active player and it is only one.

◆ handleInput() [1/2]

void stmg::Game::handleInput ( const shared_ptr< stmi::Event > &  refEvent)
noexcept

The game's input event handler.

Called by the device manager listener. All input events go through here.

Parameters
refEventThe event. Cannot be null.

◆ handleInput() [2/2]

void stmg::Game::handleInput ( int32_t  nTeam,
int32_t  nMate,
const shared_ptr< stmi::Event > &  refEvent 
)
inlinenoexcept

Send an input event directly to a player.

This function is called by LevelShowWidget.

Parameters
nTeamThe player's team. Must be >= 0.
nMateThe player's mate number within the team. Must be >= 0.
refEventThe input event. Cannot be null.

◆ handleTimer()

void stmg::Game::handleTimer ( )
noexcept

The game progress function.

This is the game tick.

◆ hasVariableId()

bool stmg::Game::hasVariableId ( int32_t  nId,
OwnerType  eOwnerType 
) const
noexcept

Whether a variable id exists.

Parameters
nIdThe id.
eOwnerTypeThe owner type.
Returns
Whether it is defined.

◆ interrupt()

void stmg::Game::interrupt ( GameProxy::INTERRUPT_TYPE  eInterruptType)
noexcept

◆ isAllTeamsInOneLevel()

bool stmg::Game::isAllTeamsInOneLevel ( ) const
inlinenoexcept

◆ isInGameTick()

bool stmg::Game::isInGameTick ( ) const
inlinenoexcept

◆ isRunning()

bool stmg::Game::isRunning ( ) const
noexcept

Whether the game is running.

◆ level() [1/2]

shared_ptr<Level>& stmg::Game::level ( int32_t  nLevel)
inlinenoexcept

◆ level() [2/2]

const shared_ptr<Level>& stmg::Game::level ( int32_t  nLevel) const
inlinenoexcept

◆ othersSend()

void stmg::Game::othersSend ( int32_t  nSenderLevel,
int32_t  nMsg,
int32_t  nValue 
)
noexcept

Send a message to other level's receivers.

Parameters
nSenderLevelThe sender level. Usually the level of the event calling this function.
nMsgThe message.
nValueThe value.

◆ owner() [1/2]

GameOwner& stmg::Game::owner ( )
inlinenoexcept

◆ owner() [2/2]

const GameOwner& stmg::Game::owner ( ) const
inlinenoexcept

◆ prefs()

const AppPreferences& stmg::Game::prefs ( ) const
inlinenoexcept

◆ preloadSound()

void stmg::Game::preloadSound ( int32_t  nSoundIdx)
noexcept

Pre-load a sound.

Makes sure that subsequent calls to createSound with th e same nSoundIdx are as fast as possible.

Parameters
nSoundIdxThe sound index according to Named::sounds(). Must be valid.

◆ random()

int32_t stmg::Game::random ( int32_t  nFrom,
int32_t  nTo 
)
overridevirtualnoexcept

Return a random value within a range.

All entities within the game should use the same implementation of this function to generate random numbers (and not keep a personal generator alongside) so that the sequences can potentially be recorded and reproduced for debugging.

Parameters
nFromThe first of the possible values.
nToThe last of the possible values.
Returns
The random value >= nFrom and <= nTo.

Implements stmg::RandomSource.

◆ reInit()

void stmg::Game::reInit ( Init &&  oInit,
CreateLevelCallback oCreateLevelCallback,
const Level::Init oLevelInit 
)
noexcept

Reinitialize game instance.

If the random number source is null, the game creates its own instance.

Allowed characters for the game name are alphanumeric, '-' and '_'.

Variable names must be unique among all owner types (for example there cannot be a variable named Points for both team and player). The names must also not start with "__" (reserved).

The callback oCreateLevelCallback is only used during the call.

If oInit.m_refHighscoresDefinition is defined it is used to determine the ranking among the teams. Its constraints and eligibilities are not evaluated.

If oInit.m_refHighscore is defined it represents the saved highscores prior the game start. This can be used to inform the player(s) where it stands during a game.

If both oInit.m_refHighscoresDefinition and oInit.m_refHighscore are defined oInit.m_refHighscore->getHighscoresDefinition() must be equivalent to oInit.m_refHighscoresDefinition.

The oInit.m_refHighscoresDefinition.getMaxScores() cannot be lower than the number of teams playing.

Parameters
oInitThe initialization data.
oCreateLevelCallbackThe callback function that creates level instances.
oLevelInitThe level initialization object.

◆ removeSound()

bool stmg::Game::removeSound ( const shared_ptr< GameSound > &  refSound)
noexcept

Remove a sound.

In order for the sound to be recycled the caller should also remove reference to it.

Parameters
refSoundThe sound. Cannot be null.
Returns
Whether the sound was still active.

◆ setGameView()

void stmg::Game::setGameView ( GameView p0GameView)
inlinenoexcept

Connect to the game view.

Parameters
p0GameViewCan be null.

◆ setLevelView()

void stmg::Game::setLevelView ( int32_t  nLevel,
LevelView p0View 
)
inlinenoexcept

Set the view for a level.

Parameters
nLevelThe level. Must >= 0 and < getTotLevels().
p0ViewThe view. Can be null.

◆ start()

void stmg::Game::start ( )
noexcept

Start the game.

Calling this function when the game is running is an error.

◆ variable() [1/4]

const Variable& stmg::Game::variable ( int32_t  nId) const
noexcept

Get a game variable by id.

Parameters
nIdThe id. Must be valid.
Returns
The variable. Its address is stable throughout a game.

◆ variable() [2/4]

Variable& stmg::Game::variable ( int32_t  nId)
noexcept

Get a game variable by id.

Parameters
nIdThe id. Must be valid.
Returns
The variable. Its address is stable throughout a game.

◆ variable() [3/4]

const Variable& stmg::Game::variable ( int32_t  nId,
int32_t  nLevel,
int32_t  nLevelTeam,
int32_t  nMate 
) const
noexcept

Get variable by context.

Parameters
nIdThe id. Must be valid for the context defined by nLevel, nLevelTeam and nMate.
nLevelThe level. Must exist or -1 for game variables.
nLevelTeamThe level team. Must exist or -1 for game variables.
nMateThe mate. Must exist or -1 for game or team variables.
Returns
The variable. Its address is stable throughout a game.

◆ variable() [4/4]

Variable& stmg::Game::variable ( int32_t  nId,
int32_t  nLevel,
int32_t  nLevelTeam,
int32_t  nMate 
)
noexcept

Get variable by context.

Parameters
nIdThe id. Must be valid for the context defined by nLevel, nLevelTeam and nMate.
nLevelThe level. Must exist or -1 for game variables.
nLevelTeamThe level team. Must exist or -1 for game variables.
nMateThe mate. Must exist or -1 for game or team variables.
Returns
The variable. Its address is stable throughout a game.

◆ variableIdAndOwner()

std::pair<int32_t, OwnerType> stmg::Game::variableIdAndOwner ( const std::string &  sName) const
noexcept

Get variable id and owner type by name.

Parameters
sNameThe name. Cannot be empty.
Returns
The variable id and owner type or -1 and undefined if not found.