Log inGet started
Package

grandPrixKit.package

Newest version

README.md

grandPrixKit

A whole kart racing grand prix for any Zero world: kart select, a cup of races against AI rivals and friends, points and standings that build up race by race, and a podium where someone lifts the trophy. It sits on top of racingKit (tracks, laps, AI drivers, item boxes, countdown, race HUD) and adds only what a grand prix needs.

  • Cups: a cup is several races in a row, on one track or many, each with its own mood (dawn, noon, night, a dust storm ...). Five formats, picked with one setting: classic (3 races), grand (4), single (1), reverse (3, every track driven the other way round), endurance (5 long races, alternating direction).
  • Points: seven points systems from championshipKit, picked with one setting: classicKart (15, 12, 10 ... 1), motorsport (25, 18, 15 ... plus a fastest lap point), motoGP, arcade (one point per racer beaten), podium (5, 3, 1), winnerTakesAll, and elimination (the last finisher of each race drops out). Standings carry over between races; ties go to most wins, then most seconds, then thirds, then the latest race.
  • Kart select: every player picks a vehicle (Go-Kart, Dune Buggy, Roadster, Muscle, Monster: five vehiclesKit bodies tuned onto one kart racing scale), a look (toy, low poly, realistic) and a paint (twelve), with stat bars for speed, acceleration, handling and weight computed from the numbers each kart really drives with. Six styles, one setting: garage (a workshop turntable), grid (a fighting game roster), carousel (a spinning carousel), arcade (a pixel arcade cabinet), hangar (a sci-fi hangar), minimal (a plain list).
  • Standings after each race and at the end of the cup, in five styles: broadcast (TV graphics), podium (ceremony plates), pixel (8-bit scoreboard), cartoon, minimal. Rows slide, points count up, place changes show as arrows.
  • Podium ceremony: the top three's own karts on trophyKit's podium, gold, silver and bronze trophies, confetti and a circling camera. Trophy looks: classic, star, crystal, pixel, modern; podium looks: classic, cartoon, scifi, pixel.
  • The race itself is racingKit's: traffic-light countdown, laps through ordered checkpoints, live positions, AI rivals with four personalities, item boxes, six HUD looks. grandPrixKit adds a navUiKit minimap with every kart in its paint colour, and an optional menusKit title screen.
  • Multiplayer: the machine in charge of the race runs the cup; everyone sees the same entrants, picks, positions and points. A player who joins mid-race watches (lobbyKit's spectator camera, Q/E or the shoulder buttons to switch kart) and races from the next race. Keyboard, gamepad and touch work everywhere.

First example: racing about a minute after the install

Measured in a brand new world: the install took just under five minutes on a busy machine. The steps below then took about a minute, and the race started 17 seconds after pressing Ready.

  1. Install grandPrixKit from ZeroMind (search "grandPrixKit" or "kart racing grand prix"). It brings racingKit, vehiclesKit, MatchFlow, championshipKit, trophyKit and the kits they use. A big install takes a few minutes; wait for /source/grandPrixKit.package to appear.
  2. Open the scene's scenes/main.scene/build.luau, which has a ground and a player. (A world made with no scene at all gets one with zero scene create --startup main player in the shell.) If it has a crate or lamp post lines, delete them: they stand on the track. Then add these lines at the end of its content() function, just before its final end:
    local Racing = require("racingKit.api")
    local GP = require("grandPrixKit.api")
    ground.localScale = { 400, 0.2, 400 }   -- room to race

    -- a track: control points in lap order, { x, height, z }
    Racing.track({ { 0, 0, 0 }, { 70, 0, 0 }, { 110, 0, -40 }, { 80, 0, -100 }, { 0, 0, -110 }, { -50, 0, -60 } },
        { name = "FirstTrack", surface = "asphalt", gates = "arch", width = 12 })

    -- a three-race cup against five AI rivals
    GP.setup({ cupName = "First Cup", tracks = { "FirstTrack" }, format = "classic", points = "classicKart", karts = 6 })
  1. Press Play. The kart select opens: pick a vehicle, look and paint (arrows or WASD, the d-pad or stick, or tap), then press Enter (gamepad A, or the Ready button). The traffic lights count down and the race is on: W/S drive and brake, A/D steer, Shift boost, Ctrl drift, Q fires your item, R puts you back on your wheels. After the race the standings show the points; after the third race, the podium.

Now change one word and save: points = "elimination" and the last finisher drops out after each race; format = "reverse" drives the cup the other way round; selectStyle = "arcade" and standingsStyle = "pixel" turn the screens 8-bit.

Setup options (GP.setup)

OptionDefaultWhat it does
tracksthe first trackRaceTrack entity names, raced in order and repeated to fill the format
formatclassicclassic, grand, single, reverse, endurance
pointsclassicKartclassicKart, motorsport, motoGP, arcade, podium, winnerTakesAll, elimination
moodsnoneone per race, cycled: dawn, midday, dusk, night, storm with desertKit; any moodKit mood otherwise
moodDriverautodesert, moodKit, none; auto uses desertKit's clock when the scene has a desert, else moodKit
laps3laps per race (endurance adds two)
karts6grid size; players take the first slots, AI rivals the rest
ai, aiNamesmixedracingKit personalities by slot (careful, aggressive, itemHappy, rubberBand) and their names
itemBoxes3rows of item boxes (0 for none)
cupNameGrand Prixthe cup's name on every screen
selectStylegaragekart select style
standingsStylebroadcaststandings style
trophyLook, podiumLookclassictrophyKit looks
hud, countdownbroadcast, trafficLightracingKit HUD look, MatchFlow countdown style
titlenonea menusKit title screen first: a string, or { title, subtitle, theme, layout, gallery }; players join the cup by pressing Play. gallery names an entity: the title then offers "Style Gallery", which takes the player there (a showroom of styles, a garage), and TitleScreen:show() brings the title back
selectSeconds, standingsSeconds, podiumSeconds45, 14, 30how long each screen stays up (select closes early once every player is ready; standings and podium move on when every player presses Continue)

Every option is also a field on the GrandPrix entity, so a world can change it in the inspector or from a script and the next cup uses it. Styles switch at once.

Pieces

PieceWhat it is
GrandPrix componentruns the cup: phases, entrants and picks, seating, race setup, scoring, moods
KartSelect componentthe kart select screen in six styles, with its 3D stage and camera
Standings componentthe standings screens in five styles
Podium componentthe 3D trophy ceremony
TitleScreen componentan optional menusKit title
RaceMinimap componentthe navUiKit minimap during races
grandPrixKit.apisetup, find, catalog, sample
grandPrixKit.kartsthe vehicle classes, looks, paints and their stats; add your own
grandPrixKit.cupsthe cup formats; add your own
grandPrixKit.selectStyles, grandPrixKit.standingsStylesthe screen style catalogs with tags

From code: local gp = require("grandPrixKit.api").find(), then gp:getPhase(), gp:getTable(), gp:getLastRace(), gp:cupInfo(), gp:getEntrants(), gp:setPick{...}, gp:setReady(true), gp:startNow(), gp:requestContinue(). The shapes are in grandPrixKit.api, and GP.sample(kind) gives made-up data in the same shapes for building a screen of your own.

How it fits with the other kits

KitGives
racingKittracks, checkpoints, laps, live positions, AI drivers, item boxes, race HUD
vehiclesKitthe karts, their controls on keyboard, gamepad and touch, cameras, speedometer
MatchFlowthe countdown, race clock and finish order, held between races
championshipKitpoints systems, standings across races, tie-breaks, elimination
trophyKittrophies and podium stages
lobbyKitthe spectator camera for players without a kart
navUiKitthe minimap
menusKitthe title screen (optional)
desertKit, moodKitmoods per race (optional)

Guides

  • How to make a kart racer with grandPrixKit (grandPrixKit.package/guides/how-to-make-a-kart-racing-game-with-a-grand-prix-cup): what it is, how it fits with the other kits, what to do first.
  • Example: from an empty world to a second track in your cup (grandPrixKit.package/guides/example-add-a-second-track-to-your-kart-racing-cup).

Showcase

The world this kit is published from, Grand Prix Garage, is the Sunbake Cup: a hand-shaped circuit round a natural rock arch on a desert salt flat (desertKit), in toonBlocks' Saturday-morning cartoon look, raced at dawn, noon and night, from the title screen through kart select, three races and the podium.

Its title screen also opens the Style Gallery: one hall with every style side by side. The six kart select styles and five standings styles are framed on the walls, the seven points systems and five cup formats are on boards, and every trophy look (in gold, silver and bronze) and podium look stands in the middle. Each one is captioned with the one setting that picks it. Step up to any frame and press E (X on a gamepad, or tap) to open that screen live.

Every style, one setting each

PartSettingChoices
Kart selectselectStylegarage, grid, carousel, arcade, hangar, minimal
StandingsstandingsStylebroadcast, podium, pixel, cartoon, minimal
PointspointsclassicKart, motorsport, motoGP, arcade, podium, winnerTakesAll, elimination
Cup formatformatclassic, grand, single, reverse, endurance
TrophiestrophyLookclassic, star, crystal, pixel, modern
PodiumpodiumLookclassic, cartoon, scifi, pixel
Race HUDhudbroadcast, scifi, cartoon, pixel, minimal, neon

Each is an option of GP.setup and a field of the GrandPrix entity. The screen styles switch at once, even mid-cup. Points and format take effect from the next cup.

Version

0.3.3: needs racingKit 1.0.13, which brings vehiclesKit 1.0.10 and aiDrivers 1.1.9: a player who picks a different vehicle at the kart select now drives it in a multiplayer race (before, the kart sat still at full throttle on the machine of the player driving it).

0.3.2: the first example says what really happens (about a minute of steps once the install is done, with the times measured in a brand new world).

0.3.1: a test suite (grandPrixKitTests, 16 tests: formats, karts, points and tie-breaks, elimination, style catalogs, sample data, docs shipping, one version); barsKit and moodKit declared as dependencies so an install brings everything the kit uses.

0.3.0: the title screen can offer a "Style Gallery" choice (title.gallery, an entity to take the player to) and TitleScreen:show() reopens it; a table of every style and the one setting that picks it.

0.2.2: players stay in the cup when the room renumbers its peers (a reconnect): each machine asks to join again under its new id, and the host drops ids that left.

0.2.1: elimination cups take knocked-out karts off the grid and players keep their slot all cup; the example guide (a second track in your cup); README first example works in a brand-new world.

0.2.0: the podium ceremony, race HUD and driving HUD step aside outside races, moods held for the whole race, the cup timer survives a host change, title screen and podium position options.

0.1.0: first release.