# geometry
A small mesh kit for building made objects from profiles: trophyKit makes every trophy and podium with it, and any other script can too.
A builder keeps one triangle soup per material slot. Generators append to a slot: `lathe` (a profile revolved round Y), `roundRect` (a profile swept round a rounded rectangle), `slab` (a beveled rounded block), `box`, `extrude` (a star-shaped outline extruded with chamfered faces), `starOutline`, `tube` (a round tube swept along a path), and `voxels` (cells with only exposed faces drawn). `mark` and `apply` move what was added since a mark (with `rotX`, `rotY`, `rotZ`). `finish` welds each slot into `{ positions, normals, uvs, colors, indices }` with normals smoothed under a crease angle, ready for `renderer.mesh.create`; `push` grows a shell for ink outlines.
```luau
local G = require("trophyKit.geometry")
local b = G.new()
G.lathe(G.slot(b, "gold"), { { 0, 0 }, { 0.1, 0 }, { 0.12, 0.3 }, { 0, 0.32 } }, { seg = 48 })
local geos = G.finish(b, { angle = 35 })
local mesh = renderer.mesh.create(geos.gold)
```
# 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:
```luau
local Trophy = require("trophyKit.api")
local ceremony = Trophy.ceremony({ podium = "classic", trophy = "classic", position = { 0, 0, -6 } })
```
3. 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:
| look | what it is | tags |
|---|---|---|
| `classic` | two-handled cup on a stepped ebony and walnut plinth with a nameplate | realistic, classic, cup, metal |
| `star` | faceted star in a ring on a fluted column | realistic, star, arcade, metal |
| `crystal` | tier-tinted crystal shards on a polished metal and ebony plinth | realistic, glass, crystal, modern, premium |
| `pixel` | blocky voxel cup with a red pixel star | retro, pixel, voxel, cartoon |
| `modern` | a sculpted championship cup (the published trophy.bundle) tinted per tier | realistic, 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.
| look | what it is | tags |
|---|---|---|
| `classic` | veined white marble on dark plinths, gold trim bands, gold numbers in gold rings | realistic, classic, marble, gold |
| `cartoon` | chunky rounded yellow, blue and coral steps with cream lids and thick ink outlines | cartoon, toon, bright, outlined |
| `scifi` | gunmetal steps with glowing amber, cyan and magenta seams and a glowing floor ring | sci-fi, neon, glowing, futuristic |
| `pixel` | checkered voxel blocks in gold, silver and bronze tones with pixel-font numbers | retro, 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
```luau
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).