{"id":"bytebit/player-statistics","name":"player-statistics","scope":"bytebit","platform":"roblox","description":"A generic, type-safe package for Roblox development made with roblox-ts for giving out rewards to players who achieve specified objectives based on their player statistics.","version":"1.0.3","latest":"1.0.3","versions":["1.0.3"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"61ce17c208819b8d32f07c6c97558ade707387665aa6e64667ecc13ba18e980b","likes":0,"downloads":0,"install":"forest install bytebit/player-statistics","url":"https://forest.dev/p/roblox/bytebit/player-statistics","files":"https://api.forest.dev/ai/package/roblox/bytebit/player-statistics/files","readme":"# Player Statistics\n<p align=\"center\">\n\t<a href=\"https://github.com/Bytebit-Org/roblox-PlayerStatistics/actions\">\n        <img src=\"https://github.com/Bytebit-Org/roblox-PlayerStatistics/workflows/CI/badge.svg\" alt=\"CI status\" />\n    </a>\n\t<a href=\"http://makeapullrequest.com\">\n\t\t<img src=\"https://img.shields.io/badge/PRs-welcome-blue.svg\" alt=\"PRs Welcome\" />\n\t</a>\n\t<a href=\"https://opensource.org/licenses/MIT\">\n\t\t<img src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"License: MIT\" />\n\t</a>\n\t<a href=\"https://discord.gg/QEz3v8y\">\n\t\t<img src=\"https://img.shields.io/badge/discord-join-7289DA.svg?logo=discord&longCache=true&style=flat\" alt=\"Discord server\" />\n\t</a>\n</p>\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.3\"\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<StatisticDescription>({\n        defaultValue: 0,\n        updateFunction: math.max,\n    }),\n    \n    numberOfGamesPlayed: identity<StatisticDescription>({\n        defaultValue: 0,\n        updateFunction: StandardStatisticUpdateFunctions.increment,\n    }),\n\n    scoreSum: identity<StatisticDescription>({\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<ReadonlyArray<typeof PlayerStatisticsDefinition>>([\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!","readmeTruncated":false}