Hi,
Last year I created an egg hunt system for one of my game’s events. Due to there being a lack of high quality resources for egg hunts, I decided to release it as an open-source community resource!
It functions more like an older egg drop, though it shouldn’t be that hard to adjust it to your needs.
Getting Started
To get started, drag all of the contents of the folders to the corresponding service. After you’re done, you can discard the main folder that came with the model. Everything should already be set up now!
Here’s a quick run through of what each Instance does.
Workspace:
EggSpawns: This folder houses models and is where eggs will spawn. Models consist of multiple invisible parts for more complex shapes for a certain area. You’ll be able to either have eggs spawn in any of the spawn groups, in a specific one, or any other way you implement spawning with EggLib’s SpawnEgg
function. Eggs spawn within a set interval range
EggHolder: This is a folder that will get added when a server is started. It simply holds any eggs directly under it that are currently in the game. This is how the eggdar menu reads off the eggs that are in the server.
ReplicatedStorage:
Eggs: This folder is where one copy of each egg is stored, along with its configuration, so that it can spawn in the world when ready. There’s a helpful iteration function already in place so you can nest eggs as deep as you want in the folder and it should still be read from. Each egg needs a base part, named ‘EggBase’, along with the egg model’s primary part being the EggBase part, and a configuration, EggConfig. Double click the EggConfig to open up a configuration. Here is where you change the settings for each egg, from its name to its serial to its spawn config. There’s helpful information about what each setting does at the bottom.
Note: Make sure that each egg has its own unique numerical Serial. This is used internally to store data and spawn eggs.
Modules: A folder containing replicated modules for the game to work including my own implementation of MouseOverModule for the client-sided GUI, and a library used to get egg instances and to pull information from a serial or name.
Remotes: A folder containing remotes used to interact with the client. Example: Client-sided notifications.
PlayerEggHuntData: An empty Configuration that gets filled up when players join with their egg collection data. I’d suggest not touching this unless if you know what you’re doing.
ServerScriptService:
EggHuntMain: Server script that handles data saving and loading, along with requiring the EggLib and collision groups.
ServerStorage:
EggLib: This is the main library of the game which makes everything work from the spawning of eggs to awarding them. Comes with a simple API.
Exposed API
SpawnEgg
This function will spawn an egg in Workspace under EggHolder.
> EggLib:SpawnEgg(table EggInstance, bool SpawnedAutomatically, Vector3 CustomPosition)
- EggInstance: EggInstance table with information about an egg, retrieved from
EggHuntContentLib:Get(number Serial / string Name)
. - SpawnedAutomatically:
true
is you’re spawning the egg from the automatic loop at the bottom of the EggLib library,false
if you’re spawning it manually (Ex: Egg spawning staff). - CustomPosition: If the egg is being spawned manually, you can use the CustomPosition parameter to spawn the egg
Returns tuple: EggObject, OnTouched
- EggObject is the instance of the egg in Workspace.
- OnTouched is a bindable event that can be listened to like
OnTouched.Event:Wait()
that fires when the egg is touched.
DestroyEgg
This function will destroy any given EggObject and its leftover connections with it.
> EggLib:DestroyEgg(instance EggObject)
- EggObject: The egg model instance under Workspace.
Returns: nil
CanPlayerTakeEgg
This function will destroy any given EggObject and its leftover connections with it.
> EggLib:CanPlayerTakeEgg(instance Player, table EggInstance, instance EggObject)
- Player: The player instance that we’re using for this function.
- EggInstance: EggInstance table with information about an egg, retrieved from
EggHuntContentLib:Get(number Serial / string Name)
. - EggObject: The egg model instance under Workspace. This is optional to avoid awarding an egg to a player which might have its collection disabled.
Returns: bool CanTake
- CanTake:
true
is the player is able to collect the egg and passes the requirements,false
if they are unable to take the egg under normal circumstances.
AwardEgg
This function will award an egg to a player, and destroy it if the EggObject is passed through.
To award yourself every egg, simply iterate through all EggInstances and pass it through to this function.
> EggLib:AwardEgg(instance Player, table EggInstance, instance EggObject)
- Player: The player instance that we’re using for this function.
- EggInstance: EggInstance table with information about an egg, retrieved from
EggHuntContentLib:Get(number Serial / string Name)
. - EggObject: The egg model instance under Workspace. Pass this to destroy the collected egg.
Returns: nil
StarterGui:
EggPanel: This is the GUI on the client which contains the egg checklist and the EggDar. The egg checklist displays a list of every egg in the game and shows a completely black image if they don’t have it, along with a category list. The EggDar is unlocked with a gamepass, so you might have to go into the script and tweak it near the top for your own ID, and there’s also a weird viewport peek feature I kept in just for the heck of it. You can easily disable it if you wish, or even add more onto it.
If there’s any information you would like added or bugs that need fixed please let me know either through DM or replying here. Hopefully this will be of use to someone!