{"id":"playcurrent/shards","name":"shards","scope":"playcurrent","platform":"roblox","description":"Put Roblox players into defined regions to optimize matchmaking latency.","version":"0.1.0","latest":"0.1.0","versions":["0.1.0"],"license":"MPL-2.0","licenseRating":"caution","licenseCaveats":["File-level copyleft: if you modify this package's own source files, those modified files must be made available under MPL-2.0. Using it unmodified in a closed-source game is fine."],"licenseVerified":false,"dependencies":{},"integrity":"c9538b2320a5d624a78f0f0fb2fb49e3d397ea00afbccd0968bd0587eeff49b8","likes":0,"downloads":0,"install":"forest install playcurrent/shards","url":"https://forest.dev/p/roblox/playcurrent/shards","files":"https://api.forest.dev/ai/package/roblox/playcurrent/shards/files","readme":"

\n\t\n\t\t\n\t\t\n\t\n

\n\nShards are a set of country groups that either roughly match up to where Roblox's server infrastructure is located or\nhelp to group up countries that, whilst may connect to a certain server region, don't geographically exist there (for\ninstance, African countries tend to connect to Europe). This package helps faciliate the use of shards in games by\nproviding a thin API wrapper around the shard data and giving a mechanism to automatically fetch updated shard lists.\n\nWhen you get a shard for a player, you can feed that into a matchmaking system to pair them up with players in the same\ngeneral region, meaning that players get better ping and experience. This is ideal for competitive or ping-dependent games,\nbut is also just good generally for a smoother experience for everyone. This also means that you will (in the best\nconditions) create reserved servers in the best region for all of the players on a match.\n\nIn the spirit of eating our own dog food, this library is used in [Basketball: Zero](https://www.roblox.com/games/130739873848552/-)\nfor ranked matchmaking, and has been working extremely well, improving latency issues and matching people with others in\ntheir own regions.\n\n## Documentation\n\n```lua\nlocal Shards = require(...)\n\n-- load the latest shard data from the default source, you should ideally do this once but\n-- you can do it as many times as you like\n--\n-- NOTE: if this does fail, it will use the version of the data built in to your version of\n-- the library instead\nShards.loadRemoteShardData()\n\n-- if you want to load data from a custom source, you can do that too:\nShards.loadRemoteShardData(\"https://example.org/shards.json\")\n\nlocal shardId = Shards.getShardForPlayer(game.Players.lewisakura)\n-- if you have a specific country code already (ex. trying to get the server's shard ID\n-- instead), you can do that too:\nShards.getShardForCountry(\"US\")\n\n-- the shardId is a numerical ID representing the shard, so to get a display name, you can\n-- use getShardName:\nprint(shardId) -- 1\nprint(Shards.getShardName(shardId)) -- North America\n```\n\n## Installation\n\n### Wally Package\n\n```toml\nShards = \"playcurrent/shards@0.1.0\"\n```\n\n### RBXM Module\n\nPop over to the [releases](https://github.com/playcurrent/shards/releases)!\n\n## FAQ\n\n### Why a package?\n\nThe biggest benefit is that the shard data can be updated remotely, so if an unexpected country code shows up or if\nRoblox releases new server regions, we can quickly update games to start using the new entries without needing to release\na game update. Plus, it provides a small little API for people to use to make it easier.\n\n### Why do shards have numerical IDs?\n\nA lot of matchmaking systems actually have quite a hard time with strings. For instance, Amazon's GameLift FlexMatch\n(funnily enough, what we use at BB:Z) really does not play nice with string equality in expansion rules, so a numerical\nID is provided as an alternative.\n\n> Logo modified from Crystal Shard, under CC-BY-SA-4.0 by [Chanut is Industries](https://dribbble.com/Chanut-is-Industries)\n","readmeTruncated":false}