Evercyan's Egg Hunt Kit


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.


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.


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.


EggHuntMain: Server script that handles data saving and loading, along with requiring the EggLib and collision groups.


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

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.


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


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.


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


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!


Great job! Now I can make my own egg hunt games. :+1: :slightly_smiling_face:
Also, is there a way to space out the eggs before they drop? Which script is it? So when they drop, they are scattered around the map.


Umm i have done all the Steps for the Setup but it gives me Errors.

Thanks! I’ll definitely be using this. Thanks!

I have fixed it for myself so far now… Except that the Egg List dosent show the Eggs…

You have forgot to put some Folders in… Aswell used 2 different Names in the Scripts for one Folder.

Sorry about that! I was half awake when making this so I somehow had the Eggs folder in Workspace.

Should all be fixed now, just make sure to grab the latest version.



Under each egg’s ‘EggConfig’ ModuleScript, there’s a setting under it called SpawnPositionRandomized. Make sure it is set to true. This will make sure that eggs spawn randomly inside along the egg spawn instead of directly in the center of it (which could be used for things like an egg on a pedestal).

1 Like

Sorry for annoying again but it looks like the Datastore got its issues now…

1 Like

Very sorry about this, I really shouldn’t repeat this haha…

  • Fixed data store issues
  • Added the notification gui since I somehow forgot to add it

Let me know if you need anything else! :slight_smile:


Looks like everything works so far… Except for the Egg list.
I can collect eggs but they wont show up in the Egg list. Not as Icon and not as Progress.

1 Like

This is amazing! Thank you so much, just curious, have you thought about adding badge support? where we can assign a badge ID to be rewarded?

If you open a baseplate and use the latest version of the kit, does this still occur?

1 Like


You can have a badge be awarded to the player when they collect an egg by replacing the placeholder in the EggConfig module with the exact id of the badge.



Yeah i have used the Latest Version of your Kit. Since Models updates Automaticly after the Creator of it Overwrites it with a new one.

1 Like

Wow, this is amzing! great contribution. thank you!

1 Like

I can vouch for this. It seems to work perfect except the egg list. Doesn’t seem to be showing eggs you collect. but if you try collecting the same egg it says you already have it.

I’m not having any luck reproducing this issue.
Are there any errors? Did you try changing the data store name?


So I just logged back in to take a screenshot of a basic default install and now it shows in the list. Initially when I first started it had 1 entry with a black icon and question marks for the name but relogging updated the list. So all seems to be working now.

I am going to add additional eggs and test this much more today cause it looks like an amazing system. So for additional eggs I just duplicate the existing egg and change the serial number, name, rarity in the config for that egg, correct? Then the texture ID of the base egg if I wish? Nothing else needed, it’ll just read additional eggs?

1 Like

Good to hear.

Yes, the bare minimum you have to change to get new eggs to exist is to duplicate any existing egg model, and then change the name and serial. The reason you don’t want overlapping names or serials is because they have to be unique identifiers so the content library will know how to split the eggs apart without any risk of overwriting.

After that, you can freely edit the configuration as needed for further values and customize the egg model. If you plan for the egg to be unanchored to roll around, make sure that you weld it together. The easiest way to do this is to select each part in the egg, then go to Model > Constraints > Create > Weld; this will weld the select parts together.


1 question. The badge system works perfectly for when you find an egg but is there a way to award a badge when you collect all the eggs? I added 10 eggs and it seems to be working perfectly!

1 Like