Skip to main content

EloUtils

Utilities to compute elo scores for players

local config = EloUtils.createConfig()

local playerOneRating = 1400
local playerTwoRating = 1800

-- Update rating!
playerOneRating, playerTwoRating = EloUtils.getNewElo(
	config,
	playerOneRating,
	playerTwoRating,
	{
		EloMatchResult.PLAYER_ONE_WIN;
	})

-- New rankings!
print(playerOneRating, playerTwoRating)

Types

EloConfig

interface EloConfig {
factornumber
kfactornumber | function
initialnumber
ratingFloornumber
groupMultipleResultAsOneboolean
}

Functions

createConfig

EloUtils.createConfig(
configtable?--

Optional table with defaults

) → EloConfig

Creates a new elo config.

isEloConfig

EloUtils.isEloConfig(configany) → boolean

Returns whether an object is an elo config

getStandardDeviation

EloUtils.getStandardDeviation(eloConfigEloConfig) → number

Gets the standard deviation of the elo curve

getPercentile

EloUtils.getPercentile(
eloConfigEloConfig,
elonumber
) → number

Gets the standard deviation of the elo curve from 0 to 1

percentileToElo

EloUtils.percentileToElo(
eloConfigEloConfig,
percentilenumber
) → number

Gets the standard deviation of the elo curve from 0 to 1

getNewElo

EloUtils.getNewElo(
configEloConfig,
playerOneRatingnumber,
playerTwoRatingnumber,
eloMatchResultList{EloMatchResult}
) → (
number,--

playerOneRating

number--

playerTwoRating

)

Gets the new score for the player and opponent after a series of matches.

getEloChange

EloUtils.getEloChange(
configEloConfig,
playerOneRatingnumber,
playerTwoRatingnumber,
eloMatchResultList{EloMatchResult}
) → (
number,--

playerOneRating

number--

playerTwoRating

)

Gets the change in elo for the given players and the results

getNewPlayerOneScore

EloUtils.getNewPlayerOneScore(
configEloConfig,
playerOneRatingnumber,
playerTwoRatingnumber,
eloMatchResultList{EloMatchResult}
) → ()

Gets the new score for the player after a series of matches.

getPlayerOneExpected

EloUtils.getPlayerOneExpected(
configEloConfig,
playerOneRatingnumber,
playerTwoRatingnumber
) → number

Compute expected score for a player vs. player given the rating.

info

A player's expected score is their probability of winning plus half their probability of drawing. Thus, an expected score of 0.75 could represent a 75% chance of winning, 25% chance of losing, and 0% chance of drawing

getPlayerOneScoreAdjustment

EloUtils.getPlayerOneScoreAdjustment(
configEloConfig,
playerOneRatingnumber,
playerTwoRatingnumber,
eloMatchResultList{EloMatchResult}
) → number

Gets the score adjustment for a given player's base.

fromOpponentPerspective

EloUtils.fromOpponentPerspective(eloMatchResultList{EloMatchResult}) → {number}

Flips the scores for the opponent

countPlayerOneWins

EloUtils.countPlayerOneWins(eloMatchResultList{EloMatchResult}) → {number}

Counts the number of wins for player one

countPlayerTwoWins

EloUtils.countPlayerTwoWins(eloMatchResultList{EloMatchResult}) → {number}

Counts the number of wins for player two

standardKFactorFormula

EloUtils.standardKFactorFormula(ratingnumber) → number

Standard kfactor formula for use in the elo config.

extractKFactor

EloUtils.extractKFactor(
configEloConfig,
ratingnumber
) → number

Computes the kfactor for the given player from the rating

Show raw api
{
    "functions": [
        {
            "name": "createConfig",
            "desc": "Creates a new elo config.",
            "params": [
                {
                    "name": "config",
                    "desc": "Optional table with defaults",
                    "lua_type": "table?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "EloConfig"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 48,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        },
        {
            "name": "isEloConfig",
            "desc": "Returns whether an object is an elo config",
            "params": [
                {
                    "name": "config",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 66,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        },
        {
            "name": "getStandardDeviation",
            "desc": "Gets the standard deviation of the elo curve",
            "params": [
                {
                    "name": "eloConfig",
                    "desc": "",
                    "lua_type": "EloConfig"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 81,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        },
        {
            "name": "getPercentile",
            "desc": "Gets the standard deviation of the elo curve from 0 to 1",
            "params": [
                {
                    "name": "eloConfig",
                    "desc": "",
                    "lua_type": "EloConfig"
                },
                {
                    "name": "elo",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 94,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        },
        {
            "name": "percentileToElo",
            "desc": "Gets the standard deviation of the elo curve from 0 to 1",
            "params": [
                {
                    "name": "eloConfig",
                    "desc": "",
                    "lua_type": "EloConfig"
                },
                {
                    "name": "percentile",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 111,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        },
        {
            "name": "getNewElo",
            "desc": "Gets the new score for the player and opponent after a series of matches.",
            "params": [
                {
                    "name": "config",
                    "desc": "",
                    "lua_type": "EloConfig"
                },
                {
                    "name": "playerOneRating",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "playerTwoRating",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "eloMatchResultList",
                    "desc": "",
                    "lua_type": "{ EloMatchResult }"
                }
            ],
            "returns": [
                {
                    "desc": "playerOneRating",
                    "lua_type": "number"
                },
                {
                    "desc": "playerTwoRating",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 131,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        },
        {
            "name": "getEloChange",
            "desc": "Gets the change in elo for the given players and the results",
            "params": [
                {
                    "name": "config",
                    "desc": "",
                    "lua_type": "EloConfig"
                },
                {
                    "name": "playerOneRating",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "playerTwoRating",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "eloMatchResultList",
                    "desc": "",
                    "lua_type": "{ EloMatchResult }"
                }
            ],
            "returns": [
                {
                    "desc": "playerOneRating",
                    "lua_type": "number"
                },
                {
                    "desc": "playerTwoRating",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 152,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        },
        {
            "name": "getNewPlayerOneScore",
            "desc": "Gets the new score for the player after a series of matches.",
            "params": [
                {
                    "name": "config",
                    "desc": "",
                    "lua_type": "EloConfig"
                },
                {
                    "name": "playerOneRating",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "playerTwoRating",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "eloMatchResultList",
                    "desc": "",
                    "lua_type": "{ EloMatchResult }"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 172,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        },
        {
            "name": "getPlayerOneExpected",
            "desc": "Compute expected score for a player vs. player given the rating.\n\n:::info\nA player's expected score is their probability of winning plus half their probability of drawing. Thus, an expected score of 0.75 could represent a 75% chance of winning, 25% chance of losing, and 0% chance of drawing\n:::",
            "params": [
                {
                    "name": "config",
                    "desc": "",
                    "lua_type": "EloConfig"
                },
                {
                    "name": "playerOneRating",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "playerTwoRating",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 193,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        },
        {
            "name": "getPlayerOneScoreAdjustment",
            "desc": "Gets the score adjustment for a given player's base.",
            "params": [
                {
                    "name": "config",
                    "desc": "",
                    "lua_type": "EloConfig"
                },
                {
                    "name": "playerOneRating",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "playerTwoRating",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "eloMatchResultList",
                    "desc": "",
                    "lua_type": "{ EloMatchResult }"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 211,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        },
        {
            "name": "fromOpponentPerspective",
            "desc": "Flips the scores for the opponent",
            "params": [
                {
                    "name": "eloMatchResultList",
                    "desc": "",
                    "lua_type": "{ EloMatchResult }"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ number }"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 249,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        },
        {
            "name": "countPlayerOneWins",
            "desc": "Counts the number of wins for player one",
            "params": [
                {
                    "name": "eloMatchResultList",
                    "desc": "",
                    "lua_type": "{ EloMatchResult }"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ number }"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 267,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        },
        {
            "name": "countPlayerTwoWins",
            "desc": "Counts the number of wins for player two",
            "params": [
                {
                    "name": "eloMatchResultList",
                    "desc": "",
                    "lua_type": "{ EloMatchResult }"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ number }"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 285,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        },
        {
            "name": "standardKFactorFormula",
            "desc": "Standard kfactor formula for use in the elo config.",
            "params": [
                {
                    "name": "rating",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 303,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        },
        {
            "name": "extractKFactor",
            "desc": "Computes the kfactor for the given player from the rating",
            "params": [
                {
                    "name": "config",
                    "desc": "",
                    "lua_type": "EloConfig"
                },
                {
                    "name": "rating",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 320,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "EloConfig",
            "desc": "",
            "fields": [
                {
                    "name": "factor",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "kfactor",
                    "lua_type": "number | function",
                    "desc": ""
                },
                {
                    "name": "initial",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "ratingFloor",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "groupMultipleResultAsOne",
                    "lua_type": "boolean",
                    "desc": ""
                }
            ],
            "source": {
                "line": 42,
                "path": "src/elo/src/Shared/EloUtils.lua"
            }
        }
    ],
    "name": "EloUtils",
    "desc": "Utilities to compute elo scores for players\n\n```lua\nlocal config = EloUtils.createConfig()\n\nlocal playerOneRating = 1400\nlocal playerTwoRating = 1800\n\n-- Update rating!\nplayerOneRating, playerTwoRating = EloUtils.getNewElo(\n\tconfig,\n\tplayerOneRating,\n\tplayerTwoRating,\n\t{\n\t\tEloMatchResult.PLAYER_ONE_WIN;\n\t})\n\n-- New rankings!\nprint(playerOneRating, playerTwoRating)\n```",
    "source": {
        "line": 24,
        "path": "src/elo/src/Shared/EloUtils.lua"
    }
}