Implemented Elo Function Algorithm for Player Skils Measurement. by Cyber-Mitch · Pull Request #13 · Netwalls/breakshot-contracts

Cyber-Mitch · 2025-04-29T22:32:55Z

Elo Rating System Features and Unit Tests

This section describes the newly implemented Elo rating system features for the Snooket game smart contract, a Dojo-based project on StarkNet that enhances competitive gameplay by tracking player skill levels. It covers the Elo rating functionality, its integration into the game, and the unit tests added to verify correctness. The features are implemented in src/systems/Snooknet.cairo and src/model/game_model.cairo, with tests in src/tests/test_world.cairo. Fixes for issues like u32_sub Overflow and model registration errors are also included.

Implemented Features

1. PlayerRating Model

Description: A new model to store each player's Elo rating, enabling skill-based ranking and leaderboard functionality.

Details:

Defined in src/model/game_model.cairo:

#[derive(Model, Copy, Drop, Serde)]
#[dojo::model(namespace = "Snooknet")]
pub struct PlayerRating {
    #[key]
    pub player: ContractAddress,
    pub rating: u32,
}

Uses the player's ContractAddress as the key and a u32 rating (default: 1500).
Namespaced under "Snooknet" to align with the Dojo world configuration.

Purpose: Provides persistent storage for player ratings, queryable for leaderboards or matchmaking.

2. Rating Initialization

Description: Automatically initializes player ratings to 1500 when they first participate in a match.

Details:

Implemented in the ensure_player_rating function in src/systems/Snooknet.cairo:

fn ensure_player_rating(ref self: ContractState, player: ContractAddress) {
    let mut world = self.world_default();
    let mut rating: PlayerRating = world.read_model(player);
    if rating.rating == 0 {
        rating.rating = 1500;
        world.write_model(@rating);
    }
}

Called during create_match to ensure both players have valid ratings before the game starts.

Purpose: Ensures new players start with a standard Elo rating, enabling immediate participation in ranked matches.

3. Elo Rating Calculation

Description: Implements an Elo rating system to update player ratings based on match outcomes (win, loss, or draw), reflecting player performance.

Details:

Two functions in src/systems/Snooknet.cairo within the InternalImpl block:

elo_function: Calculates new ratings for win/loss scenarios.

fn elo_function(
    ref self: ContractState,
    player1: ContractAddress,
    player2: ContractAddress,
    winner: ContractAddress
) -> (u32, u32) {
    let mut world = self.world_default();
    let rating1: PlayerRating = world.read_model(player1);
    let rating2: PlayerRating = world.read_model(player2);
    let r1 = rating1.rating;
    let r2 = rating2.rating;
    let k = 32_u32;
    let expected1 = self.calculate_expected(r1, r2);
    let expected2 = self.calculate_expected(r2, r1);
    let (score1, score2) = if winner == player1 {
        (1000_u32, 0_u32)
    } else {
        (0_u32, 1000_u32)
    };
    let new_rating1 = if score1 >= expected1 {
        let delta = (score1 - expected1) * k / 1000;
        r1 + delta
    } else {
        let delta = self.safe_subtract(expected1, score1) * k / 1000;
        let min_rating = 100_u32;
        if r1 <= delta {
            min_rating
        } else {
            r1 - delta
        }
    };
    let new_rating2 = if score2 >= expected2 {
        let delta = (score2 - expected2) * k / 1000;
        r2 + delta
    } else {
        let delta = self.safe_subtract(expected2, score2) * k / 1000;
        let min_rating = 100_u32;
        if r2 <= delta {
            min_rating
        } else {
            r2 - delta
        }
    };
    (new_rating1, new_rating2)
}

Reads current ratings from PlayerRating models.
Calculates expected scores (0–1000) using calculate_expected.
Assigns scores: 1000 (winner), 0 (loser).
Adjusts ratings with K = 32, scaling deltas by 1000 for integer arithmetic.
Uses safe_subtract to prevent underflow when score < expected_score.
Clamps ratings to a minimum of 100.

elo_function_draw: Handles rating updates for draws.

fn elo_function_draw(
    ref self: ContractState,
    player1: ContractAddress,
    player2: ContractAddress
) -> (u32, u32) {
    let mut world = self.world_default();
    let rating1: PlayerRating = world.read_model(player1);
    let rating2: PlayerRating = world.read_model(player2);
    let r1 = rating1.rating;
    let r2 = rating2.rating;
    let k = 32_u32;
    let expected1 = self.calculate_expected(r1, r2);
    let expected2 = self.calculate_expected(r2, r1);
    let score = 500_u32;
    let new_rating1 = if score >= expected1 {
        let delta = (score - expected1) * k / 1000;
        r1 + delta
    } else {
        let delta = self.safe_subtract(expected1, score) * k / 1000;
        let min_rating = 100_u32;
        if r1 <= delta {
            min_rating
        } else {
            r1 - delta
        }
    };
    let new_rating2 = if score >= expected2 {
        let delta = (score - expected2) * k / 1000;
        r2 + delta
    } else {
        let delta = self.safe_subtract(expected2, score) * k / 1000;
        let min_rating = 100_u32;
        if r2 <= delta {
            min_rating
        } else {
            r2 - delta
        }
    };
    (new_rating1, new_rating2)
}

Assigns a score of 500 to both players for a draw.
Adjusts ratings similarly, using safe_subtract and clamping to 100.

Safe Subtraction:

fn safe_subtract(self: @ContractState, a: u32, b: u32) -> u32 {
    if a >= b {
        a - b
    } else {
        0_u32
    }
}

Prevents u32 underflow by returning 0 when a < b.

Expected Score Calculation:

fn calculate_expected(self: @ContractState, r1: u32, r2: u32) -> u32 {
    if r1 > r2 {
        let diff = r1 - r2;
        if diff > 400 {
            1000_u32
        } else {
            500_u32 + (diff * 5) / 4
        }
    } else {
        let diff = r2 - r1;
        if diff > 400 {
            0_u32
        } else {
            500_u32 - (diff * 5) / 4
        }
    }
}

Approximates the Elo expected probability using a linear function, scaled to 0–1000.

Purpose: Dynamically adjusts player ratings to reflect performance, ensuring competitive gameplay.

4. RatingUpdated Event

Description: Emits a RatingUpdated event whenever a player's rating changes after a match.

Details:

Defined in src/systems/Snooknet.cairo:

#[derive(Copy, Drop, Serde)]
#[dojo::event]
pub struct RatingUpdated {
    #[key]
    pub player: ContractAddress,
    pub new_rating: u32,
}

Emitted in end_match after updating ratings for both players.

Purpose: Allows off-chain systems (e.g., frontends or analytics) to track rating changes and update leaderboards.

5. Integration with `end_match`

Description: Modified the end_match function to incorporate Elo rating updates after a game concludes.

Details:

Updated in src/systems/Snooknet.cairo to call elo_function for wins/losses or elo_function_draw for draws:

fn end_match(ref self: ContractState, game_id: u32, winner: ContractAddress) {
    let mut world = self.world_default();
    let mut game: Game = world.read_model(game_id);
    let caller = get_caller_address();
    let timestamp = get_block_timestamp();
    assert((caller == game.player1) || (caller == game.player2), 'Not a Player');
    assert(
        (winner == game.player1) || (winner == game.player2) || (winner == contract_address_const::<0x0>()),
        'Invalid winner'
    );
    assert(game.state != GameState::Finished, 'Game already ended');
    game.winner = winner;
    game.state = GameState::Finished;
    game.updated_at = get_block_timestamp();
    if winner != contract_address_const::<0x0>() {
        let (new_rating1, new_rating2) = self.elo_function(game.player1, game.player2, winner);
        let mut rating1: PlayerRating = world.read_model(game.player1);
        let mut rating2: PlayerRating = world.read_model(game.player2);
        rating1.rating = new_rating1;
        rating2.rating = new_rating2;
        world.write_model(@rating1);
        world.write_model(@rating2);
        world.emit_event(@RatingUpdated { player: game.player1, new_rating: new_rating1 });
        world.emit_event(@RatingUpdated { player: game.player2, new_rating: new_rating2 });
    } else {
        let (new_rating1, new_rating2) = self.elo_function_draw(game.player1, game.player2);
        let mut rating1: PlayerRating = world.read_model(game.player1);
        let mut rating2: PlayerRating = world.read_model(game.player2);
        rating1.rating = new_rating1;
        rating2.rating = new_rating2;
        world.write_model(@rating1);
        world.write_model(@rating2);
        world.emit_event(@RatingUpdated { player: game.player1, new_rating: new_rating1 });
        world.emit_event(@RatingUpdated { player: game.player2, new_rating: new_rating2 });
    }
    world.write_model(@game);
    world.emit_event(@Winner { game_id, winner });
    world.emit_event(@GameEnded { game_id, timestamp });
}

Integrates rating updates and event emissions with existing game-ending logic.

Purpose: Ensures ratings reflect match outcomes seamlessly within the game flow.

Fixes and Optimizations

1. Model Registration Issue

Issue: Tests failed with "Resource ... is registered but not as model" due to missing namespace specification for the PlayerRating model.

Fix: Added namespace = "Snooknet" to the PlayerRating model in src/model/game_model.cairo:

#[dojo::model(namespace = "Snooknet")]

Updated test_world.cairo to register PlayerRating and RatingUpdated:

TestResource::Model(m_PlayerRating::TEST_CLASS_HASH),
TestResource::Event(Snooknet::e_RatingUpdated::TEST_CLASS_HASH),

Impact: Resolved ENTRYPOINT_FAILED errors by ensuring proper model registration in the Dojo world.

2. u32_sub Overflow Error

Issue: Tests test_end_game and test_rating_update_after_win failed with u32_sub Overflow due to unsafe subtractions in elo_function (e.g., score1 - expected1 when score1 = 0).
Fix: Introduced safe_subtract and modified elo_function and elo_function_draw to handle negative adjustments:
- Split rating changes into positive and negative cases.
- Used safe_subtract to compute deltas without underflow.
- Clamped ratings to a minimum of 100.
Impact: Eliminated overflow errors, ensuring robust rating calculations.

Unit Tests

The following unit tests were added to src/tests/test_world.cairo to verify the Elo rating system features, covering initialization, rating updates, and edge cases.

Test Setup

File: src/tests/test_world.cairo

Updates:

Added PlayerRating model registration: TestResource::Model(m_PlayerRating::TEST_CLASS_HASH).
Added RatingUpdated event registration: TestResource::Event(Snooknet::e_RatingUpdated::TEST_CLASS_HASH).
Namespace: "Snooknet" for consistency.

Relevant namespace_def snippet:

fn namespace_def() -> NamespaceDef {
    let ndef = NamespaceDef {
        namespace: "Snooknet",
        resources: [
            TestResource::Model(m_PlayerRating::TEST_CLASS_HASH),
            TestResource::Event(Snooknet::e_RatingUpdated::TEST_CLASS_HASH),
            // ... other resources ...
        ].span(),
    };
    ndef
}

Tests Added

Test: test_player_rating_initialization

Description: Verifies that player ratings are initialized to 1500 when a game is created.

Implementation:

#[test]
fn test_player_rating_initialization() {
    let caller_1 = contract_address_const::<'aji'>();
    let player_1 = contract_address_const::<'player'>();
    let ndef = namespace_def();
    let mut world = spawn_test_world([ndef].span());
    world.sync_perms_and_inits(contract_defs());
    let (contract_address, _) = world.dns(@"Snooknet").unwrap();
    let actions_system = ISnooknetDispatcher { contract_address };
    testing::set_contract_address(caller_1);
    let game_id = actions_system.create_match(player_1, 400);
    let rating1: PlayerRating = world.read_model(caller_1);
    let rating2: PlayerRating = world.read_model(player_1);
    assert(rating1.rating == 1500, 'Player 1 rating not initialized');
    assert(rating2.rating == 1500, 'Player 2 rating not initialized');
}

Purpose: Ensures new players start with the default Elo rating of 1500.

Test: test_rating_update_after_win

Description: Checks that a winner’s rating increases and the loser’s rating decreases after a match.

Implementation:

#[test]
fn test_rating_update_after_win() {
    let caller_1 = contract_address_const::<'aji'>();
    let player_1 = contract_address_const::<'player'>();
    let ndef = namespace_def();
    let mut world = spawn_test_world([ndef].span());
    world.sync_perms_and_inits(contract_defs());
    let (contract_address, _) = world.dns(@"Snooknet").unwrap();
    let actions_system = ISnooknetDispatcher { contract_address };
    testing::set_contract_address(caller_1);
    let game_id = actions_system.create_match(player_1, 400);
    testing::set_contract_address(caller_1);
    actions_system.end_match(game_id, caller_1);
    let rating1: PlayerRating = world.read_model(caller_1);
    let rating2: PlayerRating = world.read_model(player_1);
    assert(rating1.rating > 1500, 'Winner rating not increased');
    assert(rating2.rating >= 100, 'Loser rating too low');
    assert(rating2.rating < 1500, 'Loser rating not decreased');
}

Purpose: Validates Elo rating adjustments for win/loss scenarios.

Test: test_rating_update_after_draw

Description: Ensures that player ratings remain unchanged (or adjust minimally) after a draw.

Implementation:

#[test]
fn test_rating_update_after_draw() {
    let caller_1 = contract_address_const::<'aji'>();
    let player_1 = contract_address_const::<'player'>();
    let ndef = namespace_def();
    let mut world = spawn_test_world([ndef].span());
    world.sync_perms_and_inits(contract_defs());
    let (contract_address, _) = world.dns(@"Snooknet").unwrap();
    let actions_system = ISnooknetDispatcher { contract_address };
    testing::set_contract_address(caller_1);
    let game_id = actions_system.create_match(player_1, 400);
    testing::set_contract_address(caller_1);
    actions_system.end_match(game_id, contract_address_const::<0x0>());
    let rating1: PlayerRating = world.read_model(caller_1);
    let rating2: PlayerRating = world.read_model(player_1);
    assert(rating1.rating == 1500, 'Player 1 rating changed in draw');
    assert(rating2.rating == 1500, 'Player 2 rating changed in draw');
}

Purpose: Confirms that draws do not significantly alter ratings for equal-rated players.

Test: test_end_game_already_ended

Description: Verifies that attempting to end an already finished game results in a panic.

Implementation:

#[test]
#[should_panic]
fn test_end_game_already_ended() {
    let caller_1 = contract_address_const::<'aji'>();
    let player_1 = contract_address_const::<'player'>();
    let ndef = namespace_def();
    let mut world = spawn_test_world([ndef].span());
    world.sync_perms_and_inits(contract_defs());
    let (contract_address, _) = world.dns(@"Snooknet").unwrap();
    let actions_system = ISnooknetDispatcher { contract_address };
    testing::set_contract_address(caller_1);
    let game_id = actions_system.create_match(player_1, 400);
    testing::set_contract_address(caller_1);
    actions_system.end_match(game_id, caller_1);
    actions_system.end_match(game_id, caller_1);
}

Purpose: Ensures the contract prevents duplicate game endings, maintaining state integrity.

Test: test_invalid_winner

Description: Confirms that ending a game with an invalid winner (not a participant) causes a panic.

Implementation:

#[test]
#[should_panic]
fn test_invalid_winner() {
    let caller_1 = contract_address_const::<'aji'>();
    let player_1 = contract_address_const::<'player'>();
    let invalid_winner = contract_address_const::<'invalid'>();
    let ndef = namespace_def();
    let mut world = spawn_test_world([ndef].span());
    world.sync_perms_and_inits(contract_defs());
    let (contract_address, _) = world.dns(@"Snooknet").unwrap();
    let actions_system = ISnooknetDispatcher { contract_address };
    testing::set_contract_address(caller_1);
    let game_id = actions_system.create_match(player_1, 400);
    testing::set_contract_address(caller_1);
    actions_system.end_match(game_id, invalid_winner);
}

Purpose: Validates that only valid players or the zero address can be declared winners.

Testing Instructions

To run the tests and verify the Elo rating system:

Ensure dependencies are installed (e.g., scarb).
Build the project:
```
sozo build
```
Run the tests:
```
sozo test
```
Verify that the tests pass, particularly the five new tests for the Elo rating system.

Summary

The new `Elo algorithm rating system feature` function implemented enhances the Snooket game by introducing skill-based player rankings, implemented through the `PlayerRating` model, `elo_function`, `elo_function_draw`, and `RatingUpdated` event. The system handles Cairo’s unsigned integer constraints with `safe_subtract` and minimum rating clamping. Fixes for model registration and `u32` overflow issues ensure reliability, and the test suite validates initialization, rating updates, and edge cases, ensuring a robust competitive experience.

This Closes #9

Cyber-Mitch · 2025-04-29T22:36:29Z

Hello @GoSTEAN I've made I'm done and I've made a PR now.

GoSTEAN · 2025-04-30T14:02:53Z

@Cyber-Mitch

fix the error.

you have 48hrs to do so

Cyber-Mitch · 2025-04-30T14:09:08Z

@Cyber-Mitch

fix the error.
you have 48hrs to do so

What error is that exactly? Everything worked from my end before i pused. SO i don't think that is coming from my end @GoSTEAN

Cyber-Mitch · 2025-04-30T14:48:41Z

@GoSTEAN I checked. The previous code you merged actually failed before you merged, the somehow the ci.yml file was change when the person pushed. You can check the PR yourself, and see the changes the previous person made changed the CI from what it was.

Cyber-Mitch · 2025-04-30T15:24:13Z

Hey @GoSTEAN I have check change back the what the first person changed in the CI.yml. I took back to the original.

GoSTEAN · 2025-04-30T19:14:43Z

@Cyber-Mitch resolve conflict
ci successfully fixed

Cyber-Mitch · 2025-04-30T19:55:54Z

@Cyber-Mitch resolve conflict ci successfully fixed

Okay on it @GoSTEAN

Cyber-Mitch closed this Apr 30, 2025

Cyber-Mitch force-pushed the feat/elo_function branch from 7f61849 to 7b98350 Compare April 30, 2025 20:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implemented Elo Function Algorithm for Player Skils Measurement.#13

Implemented Elo Function Algorithm for Player Skils Measurement.#13
Cyber-Mitch wants to merge 0 commit intoNetwalls:mainfrom
Cyber-Mitch:feat/elo_function

Cyber-Mitch commented Apr 29, 2025

Uh oh!

Cyber-Mitch commented Apr 29, 2025

Uh oh!

GoSTEAN commented Apr 30, 2025

Uh oh!

Cyber-Mitch commented Apr 30, 2025

Uh oh!

Cyber-Mitch commented Apr 30, 2025

Uh oh!

Cyber-Mitch commented Apr 30, 2025

Uh oh!

GoSTEAN commented Apr 30, 2025

Uh oh!

Cyber-Mitch commented Apr 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Cyber-Mitch commented Apr 29, 2025

Elo Rating System Features and Unit Tests

Implemented Features

1. PlayerRating Model

2. Rating Initialization

3. Elo Rating Calculation

4. RatingUpdated Event

5. Integration with end_match

Fixes and Optimizations

1. Model Registration Issue

2. u32_sub Overflow Error

Unit Tests

Test Setup

Tests Added

Testing Instructions

Summary

Uh oh!

Cyber-Mitch commented Apr 29, 2025

Uh oh!

GoSTEAN commented Apr 30, 2025

Uh oh!

Cyber-Mitch commented Apr 30, 2025

Uh oh!

Cyber-Mitch commented Apr 30, 2025

Uh oh!

Cyber-Mitch commented Apr 30, 2025

Uh oh!

GoSTEAN commented Apr 30, 2025

Uh oh!

Cyber-Mitch commented Apr 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

5. Integration with `end_match`