Skip to content

Score Generations

Jump to bottom
Gabriel edited this page May 20, 2022 · 6 revisions

Adding support to mods

Score Generations will scan your list of active mods on boot to check if any of them contain ScoreGenerations.ini in the mod root (alongside mod.ini) - upon detection, it'll load it and merge with the last written settings and rank tables.

Guidelines

  • If you want to add a custom score system to your mod, include ScoreGenerations.ini containing only the Score section.
  • If you want to add a custom bonus algorithm to your mod, include ScoreGenerations.ini containing only the bonus sections and ScoreGenerations.lua in the mod root.
  • If you want to add support for the score counter to your HUD mod, include ScoreGenerations.ini containing only the Developer section with customXNCP enabled (this is only necessary if you've modified the layout of the HUD).
  • If you want to add ranking support to your mod, include ScoreGenerations.ini containing only the rank tables and nothing else.

You probably get the idea by reading the former - you only need to include what you've changed in ScoreGenerations.ini for your changes to be made, rather than overwriting the entire file and someone else's preferences unnecessarily.

Creating rank tables

Score Generations allows you to create score requirements for ranks per stage, as well as time requirements to acquire a time bonus.

To create a rank table, you must create a new section in ScoreGenerations.ini manually using the name of the stage ID, but with a hash (#) at the beginning.

[#ghz200]
minSeconds=160
maxSeconds=660
A=45000
B=30000
C=15000

Lua scripting

Score Generations allows you to script your own algorithms for calculating time, ring and velocity bonuses.

You can make use of the exposed variables in your own ScoreGenerations.lua script which you can include with your mod alongside ScoreGenerations.ini.

  • totalRingCount - total number of rings obtained by the player.
  • totalEnemies - total number of enemies destroyed by the player.
  • totalPhysics - total number of physics objects destroyed by the player.
  • totalPointMarkers - total number of checkpoints passed by the player.
  • totalRedRings - total number of red rings obtained by the player.
  • totalRainbowRings - total number of rainbow rings passed by the player.
  • totalItemBoxes - total number of item boxes obtained by the player.
  • totalSuperRings - total number of super rings obtained by the player.
  • totalTricks - total number of tricks performed by the player.
  • totalDashRings - total number of dash rings passed by the player.
  • totalQuickSteps - total number of quick steps performed by the player.
  • totalDrifts - total number of drifts performed by the player.
  • totalBalloons - total number of balloons destroyed by the player.
  • totalVelocity - total velocity built up throughout the stage when passing checkpoints.
  • maxVelocity - the highest velocity recorded in the stage.
  • ringCount - number of rings the player finished with.
  • minutes - minutes on the timer.
  • seconds - seconds on the timer.
  • milliseconds - milliseconds on the timer.
  • elapsedTime - total amount of time passed in seconds.
  • score - total score the player finished with.
  • scoreLimit - the maximum amount of score the player can obtain.
  • minSeconds - elapsed time in seconds the player must finish below for a higher time bonus.
  • maxSeconds - elapsed time in seconds the player must finish below for a time bonus.
  • stageID - the current stage ID.

If you need to use any math extensions, there are five included with Score Generations' math library, but you can always implement your own in your Lua script.

  • math.round(num) - returns the input number rounded to the nearest integer.
  • math.sign(num) - returns either a positive or a negative number to indicate whether or not the input number was either.
  • math.clamp(num, min, max) - returns the input number clamped to the minimum or maximum value.
  • math.lerp(from, to, t) - returns the input number linearly interpolated between from and to by t.
  • math.isNaN(number) - returns whether or not the input number was actually a number.

To call a function you've written in Lua, just call it as you would normally in the fields for the bonus algorithms in the configuration - Score Generations will automatically use the return keyword.

If you need to see the result of any of the exposed variables, enable the Lua Debugger option in the configuration and enter the results screen - it'll spit out some debug information into the console.

Using the API

Score Generations provides a simple API that you can use in your C++ DLL mod. It's so simple that it's just a few header files you drop into your project and you're ready to go. You'll need to include it somewhere though.

  • void AddScore(int scoreToReward) - adds score to the current score counter.
  • void SetScore(int score) - sets the current score counter to the input number.
  • void ForceConfiguration(const char* path) - forces a ScoreGenerations.ini configuration to load from the input path (this should be used in PostInit).
  • int GetScore() - returns the current score.
  • int GetTotalScore() - computes and returns the current total score.
  • int GetRank() - returns the current rank based on the total score (this can be cast to RankType).
  • bool IsStageForbidden() - returns whether or not the current stage ID is forbidden.
  • int ComputeTimeBonus() - computes and returns the current time bonus.
  • int ComputeRingBonus() - computes and returns the current ring bonus.
  • int ComputeSpeedBonus() - computes and returns the current speed bonus.
  • int ComputeUserBonus() - computes and returns the current user bonus.
  • Statistics::Totals GetStatistics() - returns the table of statistics for current totals.
  • Tables::ScoreTable GetScoreTable() - returns the score table.
  • std::unordered_map<std::string, Tables::RankTable> GetRankTables() - returns the rank tables as an unordered map.
  • Tables::BonusTable GetBonusTable() - returns the bonus table.
  • Tables::MultiplierTable GetMultiplierTable() - returns the multiplier table.
  • Tables::TimerTable GetTimerTable() - returns the timer table.
  • void SetVisibility(bool isVisible) - sets the visibility of the score counter (requires stage reload).
  • bool GetVisibility() - gets the visibility of the score counter.
  • bool IsAttached() - checks if the Score Generations module is loaded and returns if it is.

All of the above functions will return if Score Generations isn't loaded, since the functions will be null pointers. Please ensure that ScoreGenerations.dll is attached and up-to-date before running these functions.

Clone this wiki locally