{"id":18809906,"url":"https://github.com/bytebit-org/roblox-rewardcontainers","last_synced_at":"2026-02-28T15:31:40.284Z","repository":{"id":54205686,"uuid":"342955097","full_name":"Bytebit-Org/roblox-RewardContainers","owner":"Bytebit-Org","description":"A generic, type-safe library for Roblox game development, written using roblox-ts, for granting rewards to players through containers.","archived":false,"fork":false,"pushed_at":"2021-11-02T15:37:47.000Z","size":166,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-04T03:05:40.907Z","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-27T20:46:44.000Z","updated_at":"2024-04-06T15:26:45.000Z","dependencies_parsed_at":"2022-08-13T09:10:42.685Z","dependency_job_id":null,"html_url":"https://github.com/Bytebit-Org/roblox-RewardContainers","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Bytebit-Org/roblox-RewardContainers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bytebit-Org%2Froblox-RewardContainers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bytebit-Org%2Froblox-RewardContainers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bytebit-Org%2Froblox-RewardContainers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bytebit-Org%2Froblox-RewardContainers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bytebit-Org","download_url":"https://codeload.github.com/Bytebit-Org/roblox-RewardContainers/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bytebit-Org%2Froblox-RewardContainers/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263437342,"owners_count":23466367,"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:09.203Z","updated_at":"2025-10-26T12:04:46.572Z","avatar_url":"https://github.com/Bytebit-Org.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Reward Containers\n\u003cp align=\"center\"\u003e\n\t\u003ca href=\"https://github.com/Bytebit-Org/roblox-RewardContainers/actions\"\u003e\n        \u003cimg src=\"https://github.com/Bytebit-Org/roblox-RewardContainers/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\nReward Containers is a package for Roblox game developers with built-in persistence (as makes sense) that can be swapped modularly to fit into any game's persistence schemes.\nReward Containers provide a framework for granting your players rewards. From simple things like badges to virtual currency and even loot boxes.\nThe point to Reward Containers is to provide a simple, modular system for rewarding players in games.\n\n## Installation\n### roblox-ts\nSimply install to your [roblox-ts](https://roblox-ts.com/) project as follows:\n```\nnpm i @rbxts/reward-containers\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```\nRewardContainers = \"bytebit/reward-containers@1.0.1\"\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-RewardContainers/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/7881094056/Reward-Containers-Package)\n\n## Documentation\nDocumentation can be found [here](https://github.com/Bytebit-Org/roblox-RewardContainers/tree/master/docs), is included in the TypeScript files directly, and was generated using [TypeDoc](https://typedoc.org/).\n\n## Example\nLet's see how to use this system to build a daily rewards system where users can come in, open their rewards, and then they lock for 24 hours. To start, we need to define our reward granters by their reward type in a map, like so:\n\n```ts\nimport { VirtualCurrencyRewardGranter } from \"@rbxts/reward-containers\";\n\ntype CurrencyType = \"coins\" | \"gems\";\n\n// Note we are assuming the currencyService here. In reality, this callback should be implemented to your game's specifications for virtual currency\nconst virtualCurrencyRewardGranter = VirtualCurrencyRewardGranter.create\u003cCurrencyType\u003e(\n\t(rewardedPlayer, currencyType, value) =\u003e\n\t\tcurrencyService.awardCurrencyToPlayerAsync(rewardedPlayer, currencyType, value),\n);\n\nconst rewardGrantersByType = new Map([[\"VirtualCurrency\", virtualCurrencyRewardGranter]]);\n```\n\nNote that you can implement your own reward granters and use them here! `VirtualCurrencyRewardGranter` and `BadgeRewardGranter` are provided as part of the package and can serve as examples.\n\nFor this daily reward system, we'll be granting players one random reward every day they join from a list of rewards. You could list more, but for now let's just put an 80% chance at 100 coins and a 20% chance at 100 gems, like so:\n\n```ts\nimport { WeightedRewardsSelector } from \"@rbxts/reward-containers\";\n\nconst rewardsSelector = WeightedRewardsSelector.create(\n    1, // maximumNumberOfRewards\n    [\n        {\n            reward: {\n                type: \"VirtualCurrency\",\n                currencyType: \"coins\",\n                value: 100,\n            },\n            weight: 80,\n        },\n        {\n            reward: {\n                type: \"VirtualCurrency\",\n                currencyType: \"gems\",\n                value: 100,\n            },\n            weight: 20,\n        },\n    ],\n    1, // value\n)\n```\n\nThe last thing we'll need before we're ready to create our reward container is a rewards opening coordinator. We'll use the standard one, like so:\n\n```ts\nimport { StandardRewardsOpeningCoordinator } from \"@rbxts/reward-containers\";\n\nconst rewardsOpeningCoordinator = StandardRewardsOpeningCoordinator.create(rewardGrantersByType, rewardsSelector);\n```\n\nAnd now we're ready to set up our reward container that will have a 24-hour recurrence interval - aka our daily reward container! These need to be tied to a player, so we'll set this up in a player added handler.\n\n```ts\nimport { Players } from \"@rbxts/services\";\nimport { RecurringTimeLockedRewardContainer } from \"@rbxts/reward-containers\";\n\nPlayers.PlayerAdded.Connect((player) =\u003e {\n    const rewardContainerForPlayer = RecurringTimeLockedRewardContainer.create(\n        \"DailyRewardContainer\", // name\n        24 * 60 * 60, // recurrenceIntervalInSeconds - set to 24 hours in seconds\n        player, // rewardedPlayer\n        rewardsOpeningCoordinator,\n    );\n});\n```\n\nNow just hook this up to your system for communicating to things to the client and providing a UI, and you're done!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytebit-org%2Froblox-rewardcontainers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytebit-org%2Froblox-rewardcontainers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytebit-org%2Froblox-rewardcontainers/lists"}