Log inGet started
Package

platformer3dKit.package

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 getIt comes fromVersion
checkpoints, death and respawn at your last checkpoint, traps, kill zones, livesTrapline (on SecondWind and Lifeline)Trapline 1.5.4, SecondWind 1.4.4
moving, crumbling, spring, rotating, rope, conveyor, elevator and updraft platformsplatformsKit1.6.1
coins each player collects for themselvespickupsKit (mode = "perPlayer")2.3.8
Retry giving you (and only you) your coins backpickupsGiveBack1.0.0
the 3-2-1-GO with soundMatchFlow (Countdown)1.3.1
keeper-checked run times, splits, the best-times board, star and grade ratingsscoreKit1.4.8
keyboard, gamepad and touch controls that move each player's own charactercontrolsKit (platformer scheme and ControlsMover)1.2.4
toastsnavUiKit1.2.1
effects (confetti, dust, flashes, slow motion)juiceKit1.2.8
bars (the minimal timer's par line, Trapline's lives)barsKit1.4.3
music and the mixsoundstage2.1.3
the timer, coin counter, banner, results card, medals, finish, the level flow and the themesthis 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.

familysettingstyles
course timertimerdigital digital clock, stopwatch, dial, splits split times, line thin minimal line, pixel, hologram sci-fi, hourglass fantasy, chronograph racing chronograph, bloodClock horror
coin countercoinscartoon, gem, pixel, minimal, scifi, fantasy, realistic, horror
finishfinishcheckeredFlag, goalRing, starPedestal star on a pedestal, portal, trophy, finishArch, pixelFlagpole, summitBell, timingGantry motorsport gantry, cryptGate horror
intro bannerbannercartoon, fantasy parchment, scifi, pixel, minimal, cozy, realistic broadcast, horror
results cardresultscartoon, fantasy parchment, scifi, pixel, minimal, cozy, realistic broadcast, horror
medal schememedalmedals 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:

themetimercoinsbanner / resultsmedalfinishalso
cartoonstopwatchcartooncartoonstarscheckeredFlagTrapline cartoon, hearts, cartoon countdown
fantasyhourglassfantasyfantasymedalssummitBellTrapline fantasy, potions, fantasy countdown
scifihologramscifiscifigradesportalTrapline sci-fi, pips, hologram countdown
pixelpixelpixelpixelstarspixelFlagpoleTrapline pixel, pixel hearts, pixel countdown
minimallineminimalminimalgradesfinishArchcounter lives, minimal countdown
cozydialgemcozymedalsstarPedestalballoons lives, cartoon countdown
realisticchronographrealisticrealisticmedalstimingGantryTrapline sci-fi, shields lives, broadcast countdown, realistic platforms, synthwave music
horrorbloodClockhorrorhorrorgradescryptGateTrapline 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():

callwhat 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:

  1. Intro: the level's banner (title, subtitle, par and your best), the player held still.
  2. 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.
  3. The run: coins count toward the level's total; a checkpoint records a split (shown by the splits timer); dying brings you back at your last checkpoint (Trapline) and counts a death. R restarts.
  4. 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).
  5. 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's next (or back to the first with loop).

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.stylessee 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 perPlayer pickups: 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_data store, 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: platformer3dKit suite in tests/ (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 board if a per-level world leaderboard matters.