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 {
factor: number
kfactor: number | function
initial: number
ratingFloor: number
groupMultipleResultAsOne: boolean
}

Functions​

createConfig​

EloUtils.createConfig(
config: table?--

Optional table with defaults

) → EloConfig

Creates a new elo config.

isEloConfig​

EloUtils.isEloConfig(config: any) → boolean

Returns whether an object is an elo config

getStandardDeviation​

EloUtils.getStandardDeviation(eloConfig: EloConfig) → number

Gets the standard deviation of the elo curve

getPercentile​

EloUtils.getPercentile(
eloConfig: EloConfig,
elo: number
) → number

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

percentileToElo​

EloUtils.percentileToElo(
eloConfig: EloConfig,
percentile: number
) → number

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

getNewElo​

EloUtils.getNewElo(
config: EloConfig,
playerOneRating: number,
playerTwoRating: number,
eloMatchResultList: {EloMatchResult}
) → (
number,--

playerOneRating

number--

playerTwoRating

)

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

getEloChange​

EloUtils.getEloChange(
config: EloConfig,
playerOneRating: number,
playerTwoRating: number,
eloMatchResultList: {EloMatchResult}
) → (
number,--

playerOneRating

number--

playerTwoRating

)

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

getNewPlayerOneScore​

EloUtils.getNewPlayerOneScore(
config: EloConfig,
playerOneRating: number,
playerTwoRating: number,
eloMatchResultList: {EloMatchResult}
) → ()

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

getPlayerOneExpected​

EloUtils.getPlayerOneExpected(
config: EloConfig,
playerOneRating: number,
playerTwoRating: number
) → 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(
config: EloConfig,
playerOneRating: number,
playerTwoRating: number,
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(rating: number) → number

Standard kfactor formula for use in the elo config.

extractKFactor​

EloUtils.extractKFactor(
config: EloConfig,
rating: number
) → 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": 66,
                "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": 84,
                "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": 99,
                "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": 112,
                "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": 129,
                "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": 153,
                "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": 185,
                "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": 206,
                "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": 236,
                "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": 254,
                "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": 297,
                "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": 315,
                "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": 333,
                "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": 351,
                "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": 368,
                "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": 45,
                "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": 25,
        "path": "src/elo/src/Shared/EloUtils.lua"
    }
}