Lantern Peak: A Storybook Mountain Platformer
README.md
platformer3dKit
Make a 3D platformer in the spirit of Mario 3D World or A Hat in Time. A course timer that starts on GO and remembers each player's best time per level, a coin counter that shows 12 / 30, a finish you touch, an intro banner with a 3-2-1-GO, Restart, a results card with your time, coins, deaths and a medal against par, and Retry and Next buttons. Every piece comes in many styles that share one interface, and one setting, theme, switches the whole set.
It is glue: it ties together the platformer kits already published on ZeroMind and installs them with it, so a level gets their checkpoints, traps, platforms and coins as they are.
Install
- In the editor: open the ZeroMind panel, search platformer3dKit and press Install.
- Ask your agent: "install the platformer3dKit package", or install package guid
30b1c40a-c999-423a-9b4d-55ac97fa56ef.
One install brings the kit and every part in the table below; then follow Try it in a new world for a playable course in a few minutes. To see a finished course first, play Beechwood Summit in the kit's own world, Summit Sprint.
| You get | It comes from | Version |
|---|---|---|
| checkpoints, death and respawn at your last checkpoint, traps, kill zones, lives | Trapline (on SecondWind and Lifeline) | Trapline 1.5.4, SecondWind 1.4.4 |
| moving, crumbling, spring, rotating, rope, conveyor, elevator and updraft platforms | platformsKit | 1.6.1 |
| coins each player collects for themselves | pickupsKit (mode = "perPlayer") | 2.3.8 |
| Retry giving you (and only you) your coins back | pickupsGiveBack | 1.0.0 |
| the 3-2-1-GO with sound | MatchFlow (Countdown) | 1.3.1 |
| keeper-checked run times, splits, the best-times board, star and grade ratings | scoreKit | 1.4.8 |
| keyboard, gamepad and touch controls that move each player's own character | controlsKit (platformer scheme and ControlsMover) | 1.2.4 |
| toasts | navUiKit | 1.2.1 |
| effects (confetti, dust, flashes, slow motion) | juiceKit | 1.2.8 |
| bars (the minimal timer's par line, Trapline's lives) | barsKit | 1.4.3 |
| music and the mix | soundstage | 2.1.3 |
| the timer, coin counter, banner, results card, medals, finish, the level flow and the themes | this kit |
These are the versions the kit is built and tested against; an install brings the versions their own worlds publish. The Beechwood Summit showcase also uses forestKit 0.2.27, clearedForest 1.0.0 and toonBlocks 1.1.11, which the kit itself does not install.
Try it in a new world
Install platformer3dKit (see Install above; it brings every kit in the table with it). Open scenes/main.scene/build.luau and paste this at the end of content(), just before its last end:
local P3D = require("platformer3dKit.api")
P3D.setup({ theme = "cartoon" })
-- a level that starts where the player spawns and runs down +Z
local lvl = P3D.level({ id = "first", title = "First Steps", subtitle = "World 1-1", par = 25 })
P3D.coinLine(lvl, { 0, 0.8, 4 }, { 0, 0.8, 10 }, 4)
P3D.checkpoint(lvl, { 3, 0, 13 }, { label = "Halfway" })
entity.spawn("Spikes", { position = { -2, 0, 15 } })
.component.add(asset.resolve("Trapline.Hazard", "component"), { look = "spikes" })
P3D.coinArc(lvl, { 0, 0.8, 16 }, { 0, 0.8, 21 }, 4, 1.5)
P3D.finish(lvl, { 0, 0, 24 }, { look = "checkeredFlag" })
Press Play. "First Steps" sweeps in, 3-2-1-GO counts down, and the clock starts. Collect the coins (0 / 8 counts up in the top right), touch the flag at the halfway mark, step round the spikes (step on them and you come back at the flag) and touch the checkered flag. The results card shows your time, 8 / 8 coins, deaths, and stars against the 25 s par. Press Retry (or R) to run again with the clock and coins reset, or Next (Enter).
Change theme = "cartoon" to "fantasy", "scifi", "pixel", "minimal", "cozy", "realistic" or "horror" and every piece changes with it.
Styles
Every family shares one interface, so a world switches between styles with one setting and nothing else changes. P3D.styles() lists every style ({ family, id, name, theme, tags, description }); P3D.styles("timer") lists one family. The gallery scene in this kit's world shows them all side by side, every card drawing the same live time and coin count so only the look differs (press G to hide the page and see the 3D finishes with their names), and the StyleGallery component puts the same page in any scene.
| family | setting | styles |
|---|---|---|
| course timer | timer | digital digital clock, stopwatch, dial, splits split times, line thin minimal line, pixel, hologram sci-fi, hourglass fantasy, chronograph racing chronograph, bloodClock horror |
| coin counter | coins | cartoon, gem, pixel, minimal, scifi, fantasy, realistic, horror |
| finish | finish | checkeredFlag, goalRing, starPedestal star on a pedestal, portal, trophy, finishArch, pixelFlagpole, summitBell, timingGantry motorsport gantry, cryptGate horror |
| intro banner | banner | cartoon, fantasy parchment, scifi, pixel, minimal, cozy, realistic broadcast, horror |
| results card | results | cartoon, fantasy parchment, scifi, pixel, minimal, cozy, realistic broadcast, horror |
| medal scheme | medal | medals gold/silver/bronze, stars 0-3 stars, grades S/A/B/C/D |
That is 47 styles (10 timers, 8 coin counters, 10 finishes, 8 banners, 8 results cards, 3 medal schemes) and 8 themes that pick one of each.
Themes set every family at once, plus the installed kits' looks:
| theme | timer | coins | banner / results | medal | finish | also |
|---|---|---|---|---|---|---|
cartoon | stopwatch | cartoon | cartoon | stars | checkeredFlag | Trapline cartoon, hearts, cartoon countdown |
fantasy | hourglass | fantasy | fantasy | medals | summitBell | Trapline fantasy, potions, fantasy countdown |
scifi | hologram | scifi | scifi | grades | portal | Trapline sci-fi, pips, hologram countdown |
pixel | pixel | pixel | pixel | stars | pixelFlagpole | Trapline pixel, pixel hearts, pixel countdown |
minimal | line | minimal | minimal | grades | finishArch | counter lives, minimal countdown |
cozy | dial | gem | cozy | medals | starPedestal | balloons lives, cartoon countdown |
realistic | chronograph | realistic | realistic | medals | timingGantry | Trapline sci-fi, shields lives, broadcast countdown, realistic platforms, synthwave music |
horror | bloodClock | horror | horror | grades | cryptGate | Trapline fantasy, candles lives, bold countdown, horror music |
P3D.setTheme("pixel") -- the whole set, for every player (the shared Platformer setting)
P3D.setStyle("timer", "dial") -- one family; "auto" follows the theme again
P3D.setStyle("finish", "portal") -- every Finish whose look is "auto"
In the editor the same switches are fields on the Platformer entity: theme, and timer, coins, banner, results, medal, finish, countdown (each auto or a style id). A Finish has its own look; a Level can carry its own theme.
Building a level
All of these go in a scene's build.luau, inside content():
| call | what it places |
|---|---|
P3D.setup(opts) | once per scene: the Platformer settings (synced), Trapline's Course and lives display, scoreKit's keeper. opts: theme, any family, lives (5), fallLimitY (-25), introSeconds (2.6), countdownSeconds (3), loop (true), music (true), touchControls (true), feel (true), firstLevel, autoStart (true: a player who joins starts the first level by itself; false: they stay idle until the game calls P3D.start(id), for a title screen or level select first). |
P3D.level{ id, title, subtitle, par, position, yaw, next, order, theme } | a level: its start is position facing yaw degrees. par is the time medals are rated against. next is the level Next goes to. Returns a handle the calls below take. |
P3D.checkpoint(lvl, pos, { label, yaw, look }) | a Trapline checkpoint, numbered along the level. You come back in front of it (its +Z side). |
P3D.coin(lvl, pos), coinLine(lvl, a, b, n), coinArc(lvl, a, b, n, height), coinRing(lvl, centre, r, n) | coins only you can take, counted toward the level's total. |
P3D.finish(lvl, pos, { look, yaw }) | the finish. |
Traps, kill zones and platforms are the installed kits' own components, placed as their READMEs show:
entity.spawn("Saw", { position = { 0, 0, 30 } }).component.add(asset.resolve("Trapline.Hazard", "component"), { look = "saw" })
entity.spawn("Pit", { position = { 0, -3, 40 } }).component.add(asset.resolve("Trapline.KillZone", "component"), { sizeX = 8, sizeY = 4, sizeZ = 6 })
require("platformsKit.api").spawn("crumble", "cartoon", { position = { 0, 2, 50 } })
The player spawn should stand on the first level's start; a player who joins starts that level.
The level flow
Each player has their own run, on their own machine:
- Intro: the level's banner (title, subtitle, par and your best), the player held still.
- 3-2-1-GO: MatchFlow's countdown in the theme's style, with its sounds. The clock starts on GO and scoreKit starts a keeper-checked run.
- The run: coins count toward the level's total; a checkpoint records a split (shown by the
splitstimer); dying brings you back at your last checkpoint (Trapline) and counts a death. R restarts. - Finish: touching the finish stops the clock, plays the finish's celebration and juiceKit confetti, and saves your best time for that level in your own player store (
runtime_data). - Results: time, best (with NEW BEST), par, coins
x / total, deaths and the medal, stars or grade. Retry (R) puts you back at the start with the clock and coins reset; Next (Enter) takes you to the level'snext(or back to the first withloop).
Running out of Trapline lives ends the run: the clock stops where it is and Trapline's GAME OVER card comes up. Its Try Again (or R / Enter) is a full fresh run: back at the level's start line (not your last checkpoint), lives full, checkpoints cleared, clock and coins reset, and a new 3-2-1-GO.
Feel and feedback
Controls. With touchControls on (the default) the kit switches on controlsKit's platformer scheme (keyboard, gamepad and touch) and gives each player's body controlsKit's ControlsMover, running at 6 m/s at full stick (the speed the guides' gap sizes are measured at). The mover only drives the body your own machine owns, and it is paused during the intro, countdown and results, so nobody can walk off before GO. Jumping, air control, coyote time and the 0.3 m step height are the engine's CharacterController.
With feel on (the default), each player's own machine also adds, on top of the installed kits' own effects:
- Camera: the follow camera aims a little higher (you see over ledges), sits a little wider and is damped vertically, so it no longer bobs with every jump. The controller's jump, air control and coyote time are left as the engine ships them: courses are tuned to them.
- Landings: a dust puff where you land after a real jump, and a small camera kick after a long fall (juiceKit).
- Coins: pickupsKit's coin pop on every coin, and when you take the last coin of a level a flash and an "All N coins!" toast.
- Checkpoints: Trapline's checkpoint flag and confetti, and, once you have a best run, a toast with your split and how far ahead or behind your best split you are.
- Finish: a short slow-motion beat, the finish's own celebration, a level-up burst and confetti.
- Sound mix: music at 60% and ambience at 75% under the effects while you run, ducked further while the results card is up and back on Retry or Next (soundstage's mix).
- Results card: the time and the coins count up as the card comes in, then the medal, stars or grade and NEW BEST land. Only the kit's card shows: scoreKit's own time-trial card is taken down while it is up.
P3D.setup({ feel = false }) (or feel off on the Platformer entity) turns the camera, landing and coin/checkpoint extras off.
Runtime API
local P3D = require("platformer3dKit.api"). Everything acts on the local player.
| call | |
|---|---|
P3D.start(levelId?) | start a level with its intro |
P3D.restart() | the current level again: start, clock and coins reset, countdown |
P3D.next() | the next level |
P3D.stop() | end your run and go back to idle (no clock or HUD, held still until the next P3D.start); emits stop. For a game's own level select or main menu |
P3D.state() | { levelId, phase, elapsed, coins, totalCoins, deaths, best, par, time, rating, newBest }; phase is idle, intro, countdown, running, gameover, finished or results |
P3D.best(levelId) | your best run of a level: { time, coins, totalCoins, deaths, tier, splits } |
P3D.on(event, fn) | start, countdown, go, coin, checkpoint, death, gameover, finish, results, restart, level, theme or "*"; returns an unsubscribe function |
P3D.setTheme, P3D.setStyle, P3D.styles | see Styles |
The renderers are plain functions over data, for your own UI: require("platformer3dKit.timers").render(id, data, opts), and the same for coins, banners, results and medals (medals.rate(scheme, time, par) rates a time through scoreKit). require("platformer3dKit.finishes").build(root, id) builds a finish look under any entity.
Multiplayer
- Your run is yours. Each machine runs its own player's intro, clock, coins, deaths and results. Coins are pickupsKit
perPlayerpickups: everyone takes their own copy, and Retry gives back only your coins (pickupsGiveBack clears your claim on the machine that owns each coin). - Your checkpoint is yours. Trapline keeps a checkpoint and lives per player, so a death sends you, and only you, back to your last checkpoint.
- Your controls are yours. Every body carries a
ControlsMover, but each one only follows the controls of the machine that owns that body. - Everyone sees the same world. platformsKit platforms and Trapline traps run on the shared clock, so at the same moment every player sees them in the same place. A trap far from any player may stand still on that player's screen; it is in step again when they come near.
- Best times are kept per player and per level in each player's own
runtime_datastore, which only that account can write. Runs also go to scoreKit's best-times board (platformer_times), timed on the keeper.
Guides
Three guides ship inside this package, in platformer3dKit.package/guides/:
- How to make a 3D platformer with platformer3dKit: what the kit is, how its pieces fit with the kits it installs, the level flow, styles and themes, and multiplayer.
- Make a platformer level with checkpoints and coins: laying out a course, checkpoints and respawn, coins and their total, traps, pits and platforms, par times and testing.
- Example: build a second short course from an empty world: every step from a new world to a playable two-level game with this kit.
Parts
- Components:
Platformer(settings and the flow driver),Level,Finish,StyleGallery. - Modules:
api(front door),flow,themes,ui(palettes and helpers),timers,coins,banners,results,medals,finishes. - Tests:
platformer3dKitsuite intests/(15 tests: themes, style catalogue, every renderer on desktop and phone, medal rating, finish looks, time formatting, level-building helpers, Retry coin give-back). Run in edit mode:tools.use("tests", "run", { suite = "platformer3dKit" }).
Known limits
- Installing takes a while (#21420): the kit brings twelve parts and their own dependencies in one install. A fresh install took about 29 s on desktop; expect longer on a slow connection.
- The forest course loads slowly in a web browser (#22751): meshes load slowly on the web, so the Beechwood Summit showcase (a forest of beech trees) takes noticeably longer to appear in a browser tab than on desktop. The kit itself has no heavy meshes; a course built without the forest is not affected.
- scoreKit keeps one best-times board per world, not one per level: the kit's own per-level bests are kept in each player's store, and the shared board mixes levels. Give each level its own scene with its own
boardif a per-level world leaderboard matters.