{"id":18809898,"url":"https://github.com/bytebit-org/roblox-playerstatistics","last_synced_at":"2025-04-13T20:30:00.833Z","repository":{"id":54212756,"uuid":"340761285","full_name":"Bytebit-Org/roblox-PlayerStatistics","owner":"Bytebit-Org","description":"A type-safe player statistics library meant to make it easy to post events and have those events automatically update any number of statistic values","archived":false,"fork":false,"pushed_at":"2022-03-21T19:56:20.000Z","size":176,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-31T11:19:19.196Z","etag":null,"topics":["game-development","lua","npm-package","roblox","roblox-ts"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bytebit-Org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-02-20T21:54:09.000Z","updated_at":"2022-02-13T23:34:04.000Z","dependencies_parsed_at":"2022-08-13T09:20:27.036Z","dependency_job_id":null,"html_url":"https://github.com/Bytebit-Org/roblox-PlayerStatistics","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bytebit-Org%2Froblox-PlayerStatistics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bytebit-Org%2Froblox-PlayerStatistics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bytebit-Org%2Froblox-PlayerStatistics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bytebit-Org%2Froblox-PlayerStatistics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bytebit-Org","download_url":"https://codeload.github.com/Bytebit-Org/roblox-PlayerStatistics/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223602799,"owners_count":17171990,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["game-development","lua","npm-package","roblox","roblox-ts"],"created_at":"2024-11-07T23:18:08.394Z","updated_at":"2024-11-07T23:18:09.175Z","avatar_url":"https://github.com/Bytebit-Org.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Player Statistics\n\u003cp align=\"center\"\u003e\n\t\u003ca href=\"https://github.com/Bytebit-Org/roblox-PlayerStatistics/actions\"\u003e\n        \u003cimg src=\"https://github.com/Bytebit-Org/roblox-PlayerStatistics/workflows/CI/badge.svg\" alt=\"CI status\" /\u003e\n    \u003c/a\u003e\n\t\u003ca href=\"http://makeapullrequest.com\"\u003e\n\t\t\u003cimg src=\"https://img.shields.io/badge/PRs-welcome-blue.svg\" alt=\"PRs Welcome\" /\u003e\n\t\u003c/a\u003e\n\t\u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\n\t\t\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"License: MIT\" /\u003e\n\t\u003c/a\u003e\n\t\u003ca href=\"https://discord.gg/QEz3v8y\"\u003e\n\t\t\u003cimg src=\"https://img.shields.io/badge/discord-join-7289DA.svg?logo=discord\u0026longCache=true\u0026style=flat\" alt=\"Discord server\" /\u003e\n\t\u003c/a\u003e\n\u003c/p\u003e\n\nPlayer Statistics is a package for Roblox game developers with built-in persistence that can be swapped modularly to fit into any game's persistence schemes.\nDefine your game's statistics for players and the events that cause updates with two simple definition files, then use one line of code to post events.\nStatistics will be updated according to your definition files and automatically persisted upon player's leaving the game or the game closing.\n\n## Installation\n### roblox-ts\nSimply install to your [roblox-ts](https://roblox-ts.com/) project as follows:\n```\nnpm i @rbxts/player-statistics\n```\n\n### Wally\n[Wally](https://github.com/UpliftGames/wally/) users can install this package by adding the following line to their `Wally.toml` under `[dependencies]`:\n```\nPlayerStatistics = \"bytebit/player-statistics@1.0.4\"\n```\n\nThen just run `wally install`.\n\n### From model file\nModel files are uploaded to every release as `.rbxmx` files. You can download the file from the [Releases page](https://github.com/Bytebit-Org/roblox-PlayerStatistics/releases) and load it into your project however you see fit.\n\n### From model asset\nNew versions of the asset are uploaded with every release. The asset can be added to your Roblox Inventory and then inserted into your Place via Toolbox by getting it [here.](https://www.roblox.com/library/7881304458/Player-Statistics-Package)\n\n## Documentation\nDocumentation can be found [here](https://github.com/Bytebit-Org/roblox-PlayerStatistics/tree/master/docs), is included in the TypeScript files directly, and was generated using [TypeDoc](https://typedoc.org/).\n\n## Example\nLet's create an example keeping track of a player's high score and their average score, which can be tracked using the total points and the number of times they've played. The first step is to define these statistics in a definition file like so:\n\n```ts\nimport { StatisticDefinition, StandardStatisticUpdateFunctions } from \"@rbxts/player-statistics\";\n\nexport const PlayerStatisticsDefinition = {\n    highScore: identity\u003cStatisticDescription\u003e({\n        defaultValue: 0,\n        updateFunction: math.max,\n    }),\n    \n    numberOfGamesPlayed: identity\u003cStatisticDescription\u003e({\n        defaultValue: 0,\n        updateFunction: StandardStatisticUpdateFunctions.increment,\n    }),\n\n    scoreSum: identity\u003cStatisticDescription\u003e({\n        defaultValue: 0,\n        updateFunction: StandardStatisticUpdateFunctions.sum,\n    }),\n};\n```\n\nAnd now we can define a single event which will be associated with all three of our statistics, as shown:\n\n```ts\nimport { PlayerStatisticsDefinition } from \"./PlayerStatisticsDefinition\";\n\nexport const PlayerStatisticEventsDefinition = {\n    gameCompleted: identity\u003cReadonlyArray\u003ctypeof PlayerStatisticsDefinition\u003e\u003e([\n        \"highScore\",\n        \"numberOfGamesPlayed\",\n        \"scoreSum\"\n    ]),\n};\n```\n\nAnd now we simply wire this up in our game's bootstrapping code, complete with persistence:\n\n```ts\nimport { DataStoreService } from \"@rbxts/services\";\nimport { DataStorePlayerStatisticsPersistenceLayer, PlayerStatisticsProvider } from \"@rbxts/player-statistics\";\nimport { PlayerStatisticsDefinition } from \"./data/PlayerStatisticsDefinition\";\nimport { PlayerStatisticEventsDefinition } from \"./data/PlayerStatisticEventsDefinition\";\n\nconst playerStatisticsDataStore = DataStoreService.GetDataStore(\"PlayerStatistics\");\nconst playerStatisticsPersistenceLayer = DataStorePlayerStatisticsPersistenceLayer.create(playerStatisticsDataStore);\nconst playerStatisticsProvider = PlayerStatisticsProvider.create(\n    PlayerStatisticEventsDefinition,\n    playerStatisticsPersistenceLayer,\n    PlayerStatisticsDefinition\n);\n```\n\nFinally, after a game is completed, we call this one simple line of code:\n\n```ts\nplayerStatisticsProvider.recordEvent(player, \"gameCompleted\", playerScore);\n```\n\nAnd suddenly all three of our statistics will be updated and persisted when the player leaves or the server closes!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytebit-org%2Froblox-playerstatistics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytebit-org%2Froblox-playerstatistics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytebit-org%2Froblox-playerstatistics/lists"}