Scavenger Hunt
Scavenger Hunt
The ScavengerHunt developer module gives players an inherently gamified way to explore your experience, organically introducing them to the entire place. Player progress is persistent, so scavenger hunts can continue across sessions.
This module utilizes articles/Data store|data stores
. To test it in Studio, make sure Enable Studio Access to API Services is enabled from the Security section of the Game Settings window.
Module Usage
Installation
To use the ScavengerHunt module in an experience:
- Visit the ScavengerHunt marketplace page, click the green Get button, and confirm the transaction.
- In Studio, open the toolbox (View → Toolbox).
- Select your toolbox Inventory section.

- Locate the module item and click it or drag-and-drop it into the 3D view.
- In the Explorer window, move the entire ScavengerHunt folder into ServerScriptService. Upon running the experience, the module will distribute itself to various services and begin running.

Advanced Installation Options »
This and other developer modules come with an Install script that runs the installer and distributes the contents of the module to the same services that the folders are named after.

The Install script can be utilized as follows:
EnableLogging
— Set to true
to enable debug logging for the current developer module. This lets you see how the module gets distributed, along with how each package is linked.
InstallStarted
— Fires when the installer first starts up. You can hook into this event to run any pre-install steps.
InstallFinished
— Fires when the installer has finished installing the module. By this point, the contents of each service folder has been distributed. You can also hook into this event to run any post-install steps.
Instance/Destroy|Destroy()
run on it immediately after this event is fired.
Install()
— Installs the given developer module by overlaying each of the service folders over existing services. For example, a folder named ReplicatedStorage containing a ScavengerHunt script will be distributed to game.ReplicatedStorage.ScavengerHunt
when installing.
Using Tokens
The scavenger hunt module uses tokens as the items which players search for and collect. The module comes with one token model that you can position in the 3D world.
- Locate the Token1 mesh inside the Workspace folder of the module’s main folder.

- Move Token1 into the top-level Workspace hierarchy and position it where desired.
- Give the token a unique name; this name is how the module tracks which tokens each player has collected.
- To add more tokens, duplicate an existing token and give it a unique name.
If you don’t want to use the bundled mesh tokens, any Model
or BasePart
will work, as long as it meets the following criteria:
- Assign the model or part a
CollectionService
tag of ScavengerHuntPart; the Tag Editor plugin is useful for doing so. - Include a child
StringValue
instance set to the “flavor text” to display when the token is collected.

BasePart

Model
The module will automatically disable the BasePart/CanCollide
property of tokens at runtime so that players do not physically collide with them. As such, all tokens should be anchored so they do not fall through the world geometry.
Using Regions
Regions differ slightly from tokens, as large areas that are marked as “collected” once the player enters them. Additionally, when a player leaves the region, the flavor text modal automatically dismisses and the region itself is removed from the workspace.
- Create an anchored part around the region, such as a block or sphere. The module will automatically disable the
BasePart|CanCollide|CanCollide
property on runtime so players do not physically collide with the region. - Give it a unique name. This name is how the module tracks which regions each player has entered.
- Assign the part a
CollectionService
tag of ScavengerHuntPart; the Tag Editor plugin is useful for doing so. - Include a child
StringValue
instance set to the “flavor text” to display when the region is entered.

The CollectionService
tag name can be changed dynamically by setting a different value for tokenTag in a configureServer() call.
Configuration
The module is preconfigured to work for most use cases, but it can be easily customized. For example, to change the token rotation speed and customize the modal info message:
- In StarterPlayerScripts, create a new
LocalScript
and rename it to ConfigureScavengerHunt. - Paste the following code into the new script.
Collection Events
Every time a player collects a token or enters a region, the collected event fires. You can listen to this event from a server-side Script
and respond accordingly. The connected function receives the Player
that collided with the token or entered the region and that token or region’s name.
Similarly, when a player collects all tokens or enters all tagged regions, the allCollected event fires and the connected function receives the associated Player
. This function is only fired once per player and it can be used to reward that player with a articles/Badges Special Game Awards|badge
, access to a new area, in-experience currency, etc.
Custom GUI
This module exposes several options to customize its default GUI, but you can opt to display custom GUI elements instead.
When useCustomModals is set to true in the configureClient() function, the showInfoModal event fires every time the player activates the token tracker. Similarly, the showCompleteModal event fires when the player has collected everything in the scavenger hunt. Both of these events can be listened to in a LocalScript
.
GUI Visibility
By default, the scavenger hunt hides all ScreenGui|ScreenGuis
and CoreGui|CoreGuis
(except for the player list) when the info modal or completion modal appears. If you want to override this auto-hiding behavior and programmatically decide which GUIs should remain visible, include the hideOtherGuis and showOtherGuis callbacks and respond with your own custom logic.
API Reference
Functions
configureClient()
void
configureClient
(
|
Overrides default client-side configuration options. This function can only be called from a LocalScript
.
Key | Description | Default |
---|---|---|
autoDismissTime | Time in seconds before the modal automatically dismisses itself or navigates to the next page if there is one. Set to 0 to disable. | 20 |
closeModalGamepad | Gamepad button used to close modals. | Enum.KeyCode.ButtonA |
closeModalKeyboard | Keyboard key used to close modals. | Enum.KeyCode.E |
completeModalText | Text to show on the modal that appears after clicking the token tracker when the scavenger hunt is complete. | "Thanks for participating!" |
infoModalText | Text to show on the modal that appears after clicking the token tracker. | "Find all the tokens to complete the hunt" |
tokenRotationSpeed | Speed at which the tokens rotate, in degrees per second. Set to 0 to prevent rotation. | 20 |
nextArrowImage | Image used to indicate there are more modal pages to show after the current modal page. | "rbxassetid://8167172095" |
openTokenTrackerGamepad | Gamepad button used to show the modals that appear after activating the token tracker. | Enum.KeyCode.ButtonY |
openTokenTrackerKeyboard | Keyboard key used to show the modals that appear after activating the token tracker. | Enum.KeyCode.Y |
openTokenTrackerGamepadButtonImage | Image for the gamepad button that is used to activate the token tracker. | "rbxassetid://8025860488" |
regionIcon | Icon to display next to the token tracker when entering regions. | "rbxassetid://8073794624" |
tokenIcon | Icon to display next to the token tracker when collecting tokens. | "rbxassetid://8073794477" |
tokenTrackerPositionSmallDevice | Position of the token tracker UI on small devices such as phones. | UDim2.new(1, 0, 0, 84) |
tokenTrackerPositionLargeDevice | Position of the token tracker UI on larger devices like tablets and PC. | UDim2.new(1, 0, 1, -16) |
useRegions | Instead of tokens, use regions. | false |
Key | Description | Default |
---|---|---|
modal.backgroundColor | Background color of the modals. | Color3.fromRGB(0, 0, 0) |
modal.font | Font of the text that appears in a modal. | Enum.Font.GothamSemibold |
modal.textColor | Color of the text that appears in a modal. | Color3.fromRGB(255, 255, 255) |
modal.textSize | Size of the text that appears in a modal. | 16 |
useCustomModals | If true, default modals are not displayed. This lets you show custom modals as outlined in Custom GUI. | false |
useCustomTokenTracker | If true, the default token tracker is not displayed. This lets you show a custom token tracker GUI instead. | false |
configureServer()
void
configureServer
(
|
Overrides default server-side configuration options. This function can only be called from a Script
.
Key | Description | Default |
---|---|---|
tokenTag | The tag used by CollectionService to find all the tokens or regions used in the scavenger hunt. |
"ScavengerHuntPart" |
datastoreName | Name of the DataStore used by the scavenger hunt to store each player's collection progress. |
"ScavengerHuntTokens" |
disable()
void
disable
()
|
Hides all UI for the scavenger hunt, disconnects all input event listeners, and prevents players from collecting tokens or interacting with regions. This function can only be called from a Script
.
enable()
void
enable
()
|
Shows all UI for the scavenger hunt, connects all input event listeners, and allows players to collect tokens and interact with regions. This function can only be called from a Script
.
Events
collected
RBXScriptConnection
collected
(
|
Fires when a player collides with a token or enters a region. The connected function will receive the Player
that collided with the token or entered the region and the name of the token that was collided into or the region that was entered. This event can only be connected in a Script
.
allCollected
RBXScriptConnection
allCollected
(
|
Fires when a player collects all tokens or enters all regions in the scavenger hunt. The connected function will receive the Player
that collected all tokens, and it is only ever fired once per player. This event can only be connected in a Script
.
showInfoModal
RBXScriptConnection
showInfoModal
()
|
Fires when the player clicks on the token tracker when the useCustomModals configuration option is set to true. This event can only be connected in a LocalScript
.
showCompleteModal
RBXScriptConnection
showCompleteModal
()
|
Fires when the player clicks on the token tracker when the useCustomModals configuration option is set to true and the player has collected all tokens in the scavenger hunt. This event can only be connected in a LocalScript
.
Callbacks
hideOtherGuis
hideOtherGuis
()
|
This callback runs immediately before a modal is displayed, letting you disable entire ScreenGui|ScreenGuis
or elements within them before the modal is shown. See GUI Visibility for details and sample code.
showOtherGuis
showOtherGuis
()
|
This callback runs immediately after a modal has been dismissed, letting you re-enable entire ScreenGui|ScreenGuis
or elements within. See GUI Visibility for details and sample code.
Previous Surface Art Next Social Interactions