MLFeed: Race Data
This plugin provides other plugins with data about the current race. You might need to install it to make other plugins work.
Requires MLHook (you need to install that plugin too)
Please report performance issues! See bottom of page for who/where.
For Developers
Currently exposed data:
- Sorted Player data
- For each player: LatestCPTime, CPCount, Cached Previous CP Times, Spawn Status, Best Time, Best CP Times, Best Lap Times, Time Lost to Respawns (in total and per CP), NbRespawns
- Sort methods
TimeAttack
: sort by best time
Race
: sorted by race leader
Race_Respawns
: sorted by race leader, but updates ranking immediately when a player respawns to account for time-loss
- Knockout data (for COTD / KO)
- Per-Player Alive and DNF status
- Total Rounds, Current Round, Alive Players, Number of KOs This Round, Next KO Milestone, Number of Players (originally)
- The last record set by the current player
- Ghost Data
- Which ghosts have been loaded, the name of the ghost, and the ghost's checkpoint times.
Additional data exposure available upon request.
Using MLFeed: Race Data
Some plugins already using MLFeed:
Importing to your plugin
Include this in your info.toml
file:
[script]
dependencies = ["MLHook", "MLFeedRaceData"] # need both
see also: https://openplanet.dev/docs/reference/info-toml
Usage: Getting started
Note: it is recommended that you use the Openplanet VSCode extension which will provide autocompletion and documentation for you when using MLFeed.
Main Entry Points
Several feeds are available that provide different information. The functions that provide the feeds are:
auto RaceData = MLFeed::GetRaceData_V2()
auto KoData = MLFeed::GetKoData()
auto GhostData = MLFeed::GetGhostData()
Full docs are below.
Upgrading to v0.4
See the upgrade guide: https://github.com/XertroV/tm-mlfeed-race-data/blob/master/UPGRADE_v0.4.md
Race Data Example
Main type: HookRaceStatsEventsBase_V2
Example usage: doing something on player respawn.
uint lastRespawnCount = 0;
void Update(float dt) {
if (GetApp().CurrentPlayground is null) return;
// Get race data and the local player
auto RaceData = MLFeed::GetRaceData_V2();
auto player = RaceData.GetPlayer_V2(MLFeed::LocalPlayersName);
if (player is null) return;
// check for respawns
if (player.NbRespawnsRequested != lastRespawnCount) {
lastRespawnCount = player.NbRespawnsRequested;
if (lastRespawnCount != 0) {
startnew(OnPlayerRespawn);
}
}
}
void OnPlayerRespawn() {
// do stuff
}
Docs at end
Usage: See Also
The Demo UIs available in (openplanet's) developer mode (via Scripts
menu) & associated source code in the repo.
Exported functions (https://github.com/XertroV/tm-mlfeed-race-data/blob/master/src/MLFeed_Export.as)
Exported classes (https://github.com/XertroV/tm-mlfeed-race-data/blob/master/src/MLFeed_ExportShared.as)
Example Usage - COTD Buffer Time
Example Usage - Race Stats
Example Optional Usage - List Players' PBs
Still curious about how to use something? Read the examples and use github search to find usages! Still not sure? Ask @XertroV on the Openplanet Discord
Boring Stuff
License: Public Domain
Authors: XertroV
Suggestions/feedback: @XertroV on Openplanet discord
Code/issues: https://github.com/XertroV/tm-mlfeed-race-data
GL HF
MLFeed::
Docs
The main exposed functions will get you the feeds.
Those then give you access data to each player/ghost.
Functions, properties, and types are exposed under the MLFeed::
namespace.
Functions
GetGhostData -- const SharedGhostDataHook_V2@ GetGhostData()
Object exposing GhostInfos for each loaded ghost.
This includes record ghosts loaded through the UI, and personal best ghosts.
When a ghost is unloaded from a map, its info is not removed (it remains cached).
Therefore, duplicate ghost infos may be recorded (though measures are taken to prevent this).
The list is cleared on map change.
GetKoData -- const KoDataProxy@ GetKoData()
Your plugin's KoDataProxy@
that exposes KO round information, and each player's spawn info, and lists of players for each sorting method.
You can call this function as often as you like -- it will always return the same proxy instance based on plugin ID.
GetRaceData_V2 -- const HookRaceStatsEventsBase_V2@ GetRaceData_V2()
GetRaceData_V3 -- const HookRaceStatsEventsBase_V3@ GetRaceData_V3()
Exposes checkpoint data, spawn info, and lists of players for each sorting method.
You can call this function as often as you like.
Backwards compatible with RaceDataProxy (except that it's a different type; properties/methods are the same, though.)
Properties
GameTime -- uint GameTime
The current server's GameTime, or 0 if not in a server
LocalPlayersName -- const string LocalPlayersName
returns the name of the local player, or an empty string if this is not yet known
MLFeed::HookRaceStatsEventsBase_V3 (class)
The main class used to access race data.
It exposes 3 sorted lists of players, and general information about the map/race.
Functions
GetPlayer_V2 -- const PlayerCpInfo_V2@ GetPlayer_V2(const string &in name) const
GetPlayer_V3 -- const PlayerCpInfo_V3@ GetPlayer_V3(const string &in name) const
Get a player's info
Properties
CPCount -- uint CPCount
The number of checkpoints each lap.
Linked checkpoints are counted as 1 checkpoint, and goal waypoints are not counted.
CPsToFinish -- uint CPsToFinish
The number of waypoints a player needs to hit to finish the race.
In single lap races, this is 1 more than .CPCount
.
CpCount -- uint CpCount
The number of checkpoints each lap.
Linked checkpoints are counted as 1 checkpoint, and goal waypoints are not counted.
LapCount -- uint LapCount
The number of laps for this map.
LastRecordTime -- int LastRecordTime
When the player sets a new personal best, this is set to that time.
Reset to -1 at the start of each map.
Usage: if (lastRecordTime != RaceData.LastRecordTime) OnNewRecord();
Map -- const string Map
The map UID
SortedPlayers_Race -- const array<PlayerCpInfo_V2>@ SortedPlayers_Race
An array of PlayerCpInfo_V2
s sorted by most checkpoints to fewest.
Note: cast to PlayerCpInfo_V3
to access BestLapTimes
.
SortedPlayers_Race_Respawns -- const array<PlayerCpInfo_V2>@ SortedPlayers_Race_Respawns
An array of PlayerCpInfo_V2
s sorted by most checkpoints to fewest, accounting for player respawns.
Note: cast to PlayerCpInfo_V3
to access BestLapTimes
.
SortedPlayers_TimeAttack -- const array<PlayerCpInfo_V2>@ SortedPlayers_TimeAttack
An array of PlayerCpInfo_V2
s sorted by best time to worst time.
Note: cast to PlayerCpInfo_V3
to access BestLapTimes
.
SpawnCounter -- uint SpawnCounter
This increments by 1 each frame a player spawns.
When players spawn simultaneously, their PlayerCpInfo.spawnIndex values are the same.
This is useful for some sorting methods.
This value is set to 0 on plugin load and never reset.
MLFeed::PlayerCpInfo_V3 (class)
Each's players status in the race, with a focus on CP related info.
Functions
ToString -- string ToString() const
Formatted as: "PlayerCpInfo(name, rr: 17, tr: 3, cp: 5 (0:43.231), Spawned, bt: 0:55.992)"
Properties
BestLapTimes -- const array<uint>@ BestLapTimes
this player's CP times for their best lap this session
BestRaceTimes -- const array<uint>@ BestRaceTimes
this player's CP times for their best performance this session (since the map loaded)
BestTime -- int BestTime
The player's best time this session
CpCount -- int CpCount
How many CPs that player currently has
CpTimes -- const array<int>@ CpTimes
The CP times of that player (including the 0th cp at the 0th index; which will always be 0)
CurrentRaceTime -- int CurrentRaceTime
This player's CurrentRaceTime with latency taken into account
CurrentRaceTimeRaw -- int CurrentRaceTimeRaw
This player's CurrentRaceTime without accounting for latency
IsLocalPlayer -- bool IsLocalPlayer
whether this player corresponds to the physical player playing the game
IsSpawned -- bool IsSpawned
Whether the player is spawned
LastCpOrRespawnTime -- int LastCpOrRespawnTime
Player's last CP time OR their last respawn time if it is greater
LastCpTime -- int LastCpTime
Player's last CP time as on their chronometer
LastRespawnCheckpoint -- uint LastRespawnCheckpoint
the last checkpoint that the player respawned at
LastRespawnRaceTime -- uint LastRespawnRaceTime
the last time this player respawned (measure against CurrentRaceTime)
LastTheoreticalCpTime -- int LastTheoreticalCpTime
get the last CP time of the player minus time lost to respawns
Name -- const string Name
The player's name
NbRespawnsRequested -- uint NbRespawnsRequested
number of times the player has respawned
RaceRank -- uint RaceRank
The player's rank as measured in a race (when all players would spawn at the same time).
RaceRespawnRank -- uint RaceRespawnRank
The player's rank as measured in a race (when all players would spawn at the same time), accounting for respawns.
SpawnIndex -- uint SpawnIndex
The spawn index when the player spawned
SpawnStatus -- SpawnStatus SpawnStatus
The players's spawn status: NotSpawned, Spawning, or Spawned
StartTime -- uint StartTime
when the player spawned (measured against GameTime)
TaRank -- uint TaRank
The player's rank as measured in Time Attack (one more than their index in RaceData.SortedPlayers_TimeAttack
)
TheoreticalRaceTime -- int TheoreticalRaceTime
get the current race time of this player minus time lost to respawns
TimeLostToRespawnByCp -- const array<int>@ TimeLostToRespawnByCp
The time lost due to respawning at each CP
TimeLostToRespawns -- uint TimeLostToRespawns
the amount of time the player has lost due to respawns in total since the start of their current race/attempt
latencyEstimate -- float latencyEstimate
an estimate of the latency in ms between when a player passes a checkpoint and when we learn about it
name -- string name
The player's name
MLFeed::SpawnStatus (enum)
The spawn status of a player.
NotSpawned
Spawning
Spawned
MLFeed::KoDataProxy (class)
Main source of information about KO rounds.
Proxy for the internal type KoFeed::HookKoStatsEvents
.
Functions
GetPlayerState -- const KoPlayerState@ GetPlayerState(const string &in name) const
Get a player's MLFeed::KoPlayerState.
It has only 3 properties: name
, isAlive
, and isDNF
.
Properties
Division -- int Division
The current division number. (Note: possibly inaccurate. Use with caution.)
GameMode -- const string GameMode
The current game mode, e.g., TM_KnockoutDaily_Online
, or TM_TimeAttack_Online
, etc.
KOsMilestone -- int KOsMilestone
KOs per round will change when the number of players is <= KOsMilestone.
KOsNumber -- int KOsNumber
KOs per round.
Map -- const string Map
The current map UID
MapRoundNb -- int MapRoundNb
The current round number for this map.
MapRoundTotal -- int MapRoundTotal
The total number of rounds for this map.
Players -- const array<string> Players
A string[]
of player names. It includes all players in the KO round, even if they've left.
PlayersNb -- int PlayersNb
The number of players participating.
RoundNb -- int RoundNb
The round number over all maps. (I think)
RoundTotal -- int RoundTotal
The total number of rounds over all maps. (I think)
MLFeed::KoPlayerState (class)
A player's state in a KO match
Properties
isAlive -- bool isAlive
Whether the player is still 'in'; false
implies they have been knocked out.
isDNF -- bool isDNF
Whether the player DNF'd or not. This is set to false the round after that player DNFs.
name -- string name
The player's name.
MLFeed::SharedGhostDataHook_V2 (class)
Provides access to ghost info.
This includes record ghosts loaded through the UI, and personal best ghosts.
When a ghost is unloaded from a map, its info is not removed (it remains cached).
Therefore, duplicate ghost infos may be recorded (though measures are taken to prevent this).
V2 adds .IsLocalPlayer and .IsPersonalBest properties to GhostInfo objects.
Properties
Ghosts_V2 -- const array<MLFeed::GhostInfo_V2> Ghosts_V2
Array of GhostInfo_V2s
NbGhosts -- uint NbGhosts
Number of currently loaded ghosts
MLFeed::GhostInfo_V2 (class)
Information about a currently loaded ghost.
Properties
Checkpoints -- const array<uint>@ Checkpoints
Ghost.Result.Checkpoints
IdName -- const string IdName
Ghost.IdName
IdUint -- uint IdUint
Should be equiv to Ghost.Id.Value (experimental)
IsLocalPlayer -- bool IsLocalPlayer
Whether this is the local player (sitting at this computer)
IsPersonalBest -- bool IsPersonalBest
Whether this is a PB ghost (named: 'Personal best')
Nickname -- const string Nickname
Ghost.Nickname
Result_Score -- int Result_Score
Ghost.Result.Score
Result_Time -- int Result_Time
Ghost.Result.Time