#Fusion
#What fusion does
Fusion consumes three identical pets and returns one pet: usually the same species with inherited weight, sometimes an upgrade to a stronger species of the same biome.
FusionService.fuse(player, uids) is the only entry point. It is reached through the Fusion machine in the world (the fusion action on the remote) and gated by three checks before anything is consumed.
#Inputs
| Requirement | Value |
|---|---|
| Pets per fusion | 3 (Config.Fusion.INPUT_COUNT) |
| Species | All three must share a catalogId |
| Ownership | All three must exist in profile.pets |
| Placement | None may be placed in the base |
| State | None may already be reserved by another fusion |
| Cooldown | 1.5 seconds between fusions (Config.Fusion.COOLDOWN) |
| Concurrency | One fusion at a time per player (busy flag) |
Every failure path returns a chat message instead of silently dropping items, and the whole roll runs inside pcall — if anything errors, the pets are restored to inventory and the player is told nothing was lost.
#The upgrade roll
chance = Config.Fusion.UPGRADE_CHANCE[rarity] or 0| Input rarity | Upgrade chance |
|---|---|
| Common | 0.55 |
| Uncommon | 0.50 |
| Rare | 0.45 |
| Epic | 0.38 |
| Legendary | 0.30 |
| Mythic | 0.24 |
| Cosmic | 0.18 |
| Secret | 0.12 |
| Eternal | 0.08 |
| Divine | 0 (no upgrade possible) |
When the roll succeeds, upgradeCandidates builds the candidate list from the same biome and the same source, keeping only rarer pets, and weights each by 1 / (rankDifference). That makes the next rarity tier far more likely than a jump of several tiers.
#Weight and mutation inheritance
| Setting | Value | Effect |
|---|---|---|
WEIGHT_INHERIT | 0.85 | Average input multiplier is scaled down before the result is built |
WEIGHT_BONUS | 1.35 | Then scaled back up — the net effect is that fusing beats selling |
MUTATION_INHERIT_CHANCE | 0.5 | 50% chance to inherit the best input mutation, otherwise a fresh natural roll |
avgMul = mean(pet.weight / pet.baseWeight)
newMul = avgMul × 0.85 × 1.35
mutation = bestMutation(inputs) -- with probability 0.5
| rollNaturalMutation() -- otherwiseThe result is created through MutationService.createPet, so its income is recomputed from weight, size bucket and mutation exactly like a hatched pet. stats.totalFused is incremented, stats.bestIncome is updated if the result is a personal best, and IndexService.register runs so an upgraded species counts as a new discovery.
#Reading a fusion result
The client receives fusionResult with uid, catalogId, name, rarity, mutation, weight, income and an upgraded flag. upgraded is simply newPet.catalogId ~= catalogId — it is what distinguishes "same pet, stronger" from "you rolled the upgrade".
#Practical notes
- Because the upgrade pool is restricted to the same biome and the same source, a fusion can never leap into another biome's pet list.
- Divine inputs cannot upgrade; fusing them is only worth it for weight and mutation inheritance.
- Placed pets must be picked up before they can be fused — the UI rejects the action with "Pick the pet up from your base before fusing."
FusionService.cleanup(player)clears the busy flag and cooldown on leave so a disconnect mid-fusion cannot lock the player out.