Interface IArenaRatingService

Namespace

FishMMO.Database.Npgsql.Services.Interfaces

Assembly

FishMMO-DB.dll

Service interface for ranked arena seasons and per-season ratings.

public interface IArenaRatingService

Remarks

Ratings are keyed by season; a new season starts everyone over. The rating maths lives in the shared ArenaRating rules, not here — this service only stores the results and answers the leaderboard.

Methods

FetchRatingsAsync(long, IReadOnlyList<long>, CancellationToken)

Reads the given characters' ratings in a season. Characters with none are absent.

Task<DatabaseResult<IReadOnlyList<ArenaRatingData>>> FetchRatingsAsync(long seasonId, IReadOnlyList<long> characterIds, CancellationToken cancellationToken = default)

Parameters

seasonId long

characterIds IReadOnlyList<long>

cancellationToken CancellationToken

Returns

Task<DatabaseResult<IReadOnlyList<ArenaRatingData>>>

FetchTopAsync(long, int, CancellationToken)

The highest rated characters of a season, with their names resolved by the caller.

Task<DatabaseResult<IReadOnlyList<ArenaRatingData>>> FetchTopAsync(long seasonId, int limit, CancellationToken cancellationToken = default)

Parameters

seasonId long

limit int

cancellationToken CancellationToken

Returns

Task<DatabaseResult<IReadOnlyList<ArenaRatingData>>>

GetOrCreateActiveSeasonAsync(CancellationToken)

The active season, creating a first one when none exists.

Task<DatabaseResult<ArenaSeasonData>> GetOrCreateActiveSeasonAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task<DatabaseResult<ArenaSeasonData>>

Remarks

Called once per ranked match formed and once per board opened, so the answer is cheap: one indexed read, and an insert only on a fresh database.

StartNewSeasonAsync(string, DateTime?, CancellationToken)

Ends the active season and starts a new one. Ratings of the old season are kept.

Task<DatabaseResult<ArenaSeasonData>> StartNewSeasonAsync(string name, DateTime? endsUtc, CancellationToken cancellationToken = default)

Parameters

name string

Display name of the new season.

endsUtc DateTime?

When the new season ends, or null for open-ended.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult<ArenaSeasonData>>

UpsertRatingsAsync(long, IReadOnlyList<(long characterId, int newRating, bool won)>, CancellationToken)

Writes ratings after a ranked match, in one statement.

Task<DatabaseResult<int>> UpsertRatingsAsync(long seasonId, IReadOnlyList<(long characterId, int newRating, bool won)> results, CancellationToken cancellationToken = default)

Parameters

seasonId long

Season the match counted towards.

results IReadOnlyList<(long characterId, int newRating, bool won)>

Per character: the new rating and whether they won.

cancellationToken CancellationToken

Returns

Task<DatabaseResult<int>>

Remarks

An upsert: a character's first ranked game inserts their row. Peak rating is kept at the higher of the old and new values by the statement itself.