#Zones & Map

#How a zone is defined

Config.Zones is the single source of truth. Each entry carries an id, a display name, a play order, a Speed requirement, an X range that splits the world into strips, the guardian for that biome and an incomeBase used for index rewards and fallback pet income.

ZoneService.init tags world geometry with the SAE_ZoneId attribute so props can look up their biome. Floor parts named Map1…Map12 map by number; anything else is assigned by footprint (X * Z ≥ 3000, Z ≥ 60, Y ≤ 10) together with the X range. A biome with no tagged tile only produces a warning — zone lookups still work from the X ranges alone.

#	Zone	Speed required	X range	Guardian	Guardian speed	Income base
1	Forest	0	48–168	Chicken	25	1
2	Lake	900	168–287	Swan	32	6
3	Desert	10,000	287–487	Scorpion	40	35
4	Jungle	40,000	487–688	Tiger	49	200
5	Snow	170,000	688–988	Yeti	58	1,200
6	Volcano	700,000	988–1288	Cerberus	68	7,000
7	Abyss Ocean	2,500,000	1288–1588	Moby	79	40,000
8	Prehistoric	17,500,000	1588–1938	T-Rex	91	250,000
9	Cosmic	700,000,000	1938–2388	Cosmic Skeleton	104	1,500,000
10	Cherry Blossom	2,500,000,000	2388–2938	Oni Tiger	118	9,000,000
11	Titan Temple	7,000,000,000	2938–3488	Gorilla King	131	50,000,000
12	Angels & Demons	20,000,000,000	3540–4090	Angel & Demon	142	300,000,000

The world is bounded on the Z axis by Config.ZONE_Z_MIN = -66 and Config.ZONE_Z_MAX = 80. Points far outside that band resolve to no zone at all, which is how the safe area and the Rift arena stay "nowhere".

#Zone gates

Config.ZoneAccess.SPEED_GATE is false in this build. With it off, ZoneService.hasAccess always returns true, so nobody is pushed back and every zone teleport is allowed. Set it to true to enforce the Speed requirements: the checker then runs every 0.25 seconds, moves a player back to the highest zone they have unlocked (8-stud margin) and notifies with a four-second cooldown.

Teleporting is separate — it is blocked while carrying an egg or stunned, and a successful teleport drops the character at the biome centre ((xMin + xMax) / 2, Z between −66 and 80).

#One guardian per biome

Config.Guardian.ONE_PER_ZONE = true, so a biome builds a single guardian no matter how many nests it has. Its home is the big nest in that biome, clamped inside the zone with a ZONE_MARGIN of 5 studs, and it returns there at 75% speed when a chase ends.

Config.GuardianStats holds the walk speed used both by the NPC and by the "can I outrun it" maths. Speeds climb from 25 (Chicken) to 142 (Angel & Demon) — always below Config.Movement.MAX_WALK_SPEED of 150, which keeps the late biomes tense instead of impossible.

#Names, emoji and colour

Config.ZoneLook holds the short label, emoji and colour each biome uses on the HUD banner, the region banner and hatch announcements. Display names used in messages come from Config.Zones[].pl.

#Derived per-zone helpers

At the bottom of Config, a loop adds three computed fields to every zone:

guardianWalkSpeed — copied from Config.GuardianStats.
escapeSpeedReq — the Speed a carrier would need to outrun that guardian, from Config.EscapeSpeedFor(zoneId, 2.0).
maxCarryRatio — the heaviest egg weight ratio that still leaves room to escape.

These fields are informational in this build: EggCarryService.carryPenaltyFor returns 0, so carrying no longer slows a player down and the escape maths is not part of the live chase. Keep them consistent if you reintroduce a carry penalty.

#World layout

Instance	Purpose
`Workspace.Spawn`	Spawn pads plus `SafeZone`, the volume that delivers a carried egg and ends a chase
`Workspace.Base1`…`Base7`	Player bases. Server capacity follows the number of bases — a join with no free base is kicked
`Workspace.Map.Region1`…`Region12`, `AngelsMap`, `DemonsMap`, `Other`	Authored geometry per biome
`Workspace.EggNest`, `Workspace.Eggs`	Runtime nest and world-egg folders filled by `EggSpawnService`
`Workspace.Pets`, `Workspace.Treadmills`, `Workspace.SellLoot`	Placed pets, treadmill parts, sell stall
`Workspace.Holograms`, `Workspace.SpeedSigns`, `Workspace.SpecialRegions`	Labels, zone signs and event trigger regions
`Workspace.Leaderboard1`, `Workspace.NightWall`, `Workspace.Decorations`	Physical leaderboard, night wall, scenery

#Nests

Config.Eggs.NESTS_PER_ZONE is 6 and the last one in each biome is the big nest (BIG_EGG_NEST_INDEX = 6) that hosts the guardian. Nests are spread across 28–96% of the zone's X span at three Z offsets, kept clear of a 15×8×15 stud box, and hold EGGS_PER_NEST = 1 egg.

#Streaming

Nests, guardians and growing eggs are parented with ModelStreamingMode = Atomic when Workspace.StreamingEnabled is true, so a streaming client never receives half of a model. If you add models that spawn in the world, follow the same pattern.