Log inGet started
Package

trophyKit.package

Newest version

README.md

trophyKit

Trophies and podiums for any game's prize ceremony: gold, silver and bronze trophies in five looks, three-step winners' podiums in four looks, and confetti over the winner. One line puts each in your world, and everything is built from numbers on every player's machine, so it works in multiplayer out of the box.

Try it in five minutes

  1. Install trophyKit from ZeroMind (search "trophyKit" or "trophies and podiums").
  2. Open your scene's build.luau (a new world has scenes/main.scene/build.luau) and add these lines at the end of its content() function:
local Trophy = require("trophyKit.api")
local ceremony = Trophy.ceremony({ podium = "classic", trophy = "classic", position = { 0, 0, -6 } })
  1. Look at the scene: a marble podium with a gold, silver and bronze cup on its steps and confetti falling over first place. Press Play and the cups turn on their bases.

Want your karts on it instead? ceremony.tops[1] is the top of the winner's step: kart.position = ceremony.tops[1].

To see every look side by side, run zero scene load trophyKit.gallery.

What you get

Trophies (Trophy.looks()), each in tier 1 gold, 2 silver and 3 bronze:

lookwhat it istags
classictwo-handled cup on a stepped ebony and walnut plinth with a nameplaterealistic, classic, cup, metal
starfaceted star in a ring on a fluted columnrealistic, star, arcade, metal
crystaltier-tinted crystal shards on a polished metal and ebony plinthrealistic, glass, crystal, modern, premium
pixelblocky voxel cup with a red pixel starretro, pixel, voxel, cartoon
moderna sculpted championship cup (the published trophy.bundle) tinted per tierrealistic, modern, premium, sculpted

A trophy at scale 1 is about 0.55 m tall; pass scale = 2 for one a driver can lift over their head.

Podiums (Trophy.podiumLooks()), three steps laid out 2-1-3 from the left as seen from the front (+Z), numbered, solid, each step top 3.1 m wide and 2.7 m deep (room for a 2 m by 1.5 m car or kart). First place is 1.3 m high, second 0.85 m, third 0.55 m.

lookwhat it istags
classicveined white marble on dark plinths, gold trim bands, gold numbers in gold ringsrealistic, classic, marble, gold
cartoonchunky rounded yellow, blue and coral steps with cream lids and thick ink outlinescartoon, toon, bright, outlined
scifigunmetal steps with glowing amber, cyan and magenta seams and a glowing floor ringsci-fi, neon, glowing, futuristic
pixelcheckered voxel blocks in gold, silver and bronze tones with pixel-font numbersretro, pixel, voxel, cartoon

Celebration: confetti in party, gold, silver or bronze colours plus twinkling sparkles, raining or fired in a burst. All of it is one mesh, so it costs one draw call.

API

local Trophy = require("trophyKit.api")

-- a trophy: tier 1/2/3 or "gold"/"silver"/"bronze", a look, options
local cup = Trophy.spawn("gold", "star", {
	position = { 0, 1.3, 0 }, scale = 2,
	spin = true, spinSpeed = 40,   -- turns while the game plays
	parent = nil, synced = true,   -- synced: every player sees it
})

-- a podium: answers the entity and the world positions of the step tops
local stage, tops = Trophy.podium("scifi", { position = { 0, 0, 0 }, rotation = nil, synced = true })
winnerKart.position = tops[1]
secondKart.position = tops[2]
thirdKart.position = tops[3]

-- confetti over the winner ("rain" keeps falling, "burst" fires once)
local party = Trophy.celebrate({ position = tops[1], palette = "gold", mode = "rain" })
party.component.get("Celebration"):burst()

-- everything at once: podium, a trophy over each step, confetti
local c = Trophy.ceremony({ podium = "cartoon", trophy = "pixel", position = { 0, 0, 0 }, trophyScale = 1.6 })

Trophy.looks()           -- { "classic", "star", "crystal", "pixel", "modern" }
Trophy.podiumLooks()     -- { "classic", "cartoon", "scifi", "pixel" }
Trophy.catalog()         -- every look: { kind, look, label, tags, about }
Trophy.catalog("retro")  -- only looks tagged retro
Trophy.tier(2)           -- { place = 2, name = "silver", label = "2nd", colour = {...}, ... }
Trophy.stepTops(stage)   -- step tops again, after you move the podium

Errors name the problem: an unknown look raises an error that tells you to call Trophy.looks().

Multiplayer

Trophy, Podium and Celebration are components that rebuild their geometry from their fields (look, tier, numbers, palette and so on) on every peer. Spawn with synced = true (or entity.setSynced(true)) and every player gets the same trophy from a couple of small fields; the meshes never cross the network. Changing look or tier on a synced trophy restyles it for everyone. The confetti shower is seeded, so each player sees the same one.

What is inside

  • api module: the calls above.
  • Trophy, Podium, Celebration components: put them on any entity in a scene or in the inspector.
  • shapes module: the geometry of every look, as builders you can extend with your own look.
  • geometry module: a small mesh kit (lathe, rounded-rectangle sweeps, beveled slabs, beveled extrusions, swept tubes, voxels, crease-angle normals) usable for any made object.
  • materials: gold, silver, bronze, ebony, walnut, procedural veined marble, crystal glass per tier, glows, toon paint and ink outline.
  • gallery scene: every look and tier, labelled.

Credits: the marble shader is adapted from mow_marble (world Cold Start, MIT). The mesh soup follows torqueCars' meshkit (Torque Valley, MIT). The modern look is the trophy.bundle from Rogue Ice (MIT).