Log inGet started
Package

skyhookRace.package

This package holds more than this page lists. See all of its files in its world.

README.md

skyhookRace

A complete co-op sky-island race for 1 to 4 players, as one installable part. Players grapple, swing, let go, pop a wingsuit and glide across floating islands at sunset, collect starfruit for one shared team count, ring bells that raise new routes out of the clouds, outrun a storm front that swallows the islands behind them, and reach the finish for a results table. It is the game the Skyhook world plays, with every rule, layout and number exposed so you can make your own from it.

It holds:

  • The race rules: MatchFlow's lobby, 3-2-1-GO, finish order and a results table (place, time, you), Trapline checkpoints on every main island, falls respawn at your checkpoint, and a race clock that is the storm's own (storm.startDelay + storm.arriveBy).
  • The team starfruit count: one shared count every player sees, fruit taken once for the team.
  • Bells that open new routes: touch or hook a bell and it rings for everyone; its islets rise out of the clouds; one bell can seal the finish until it rings. The objective guides each player to the next bell with a beam, a waypoint and a hint.
  • The finish and the results screen: walking through the finish arch records your time, personal best (saveKit) and XP. Every runner gets their own finish: the race goes on for everyone still flying after the first runner crosses. MatchFlow's results show each runner's time, or what happened to them ("Caught by the storm"), and each player gets their own place toast.
  • The storm and the clock tell one story: stormFrontKit's front follows the islands in order and ends on the finish, catches up with the slowest runner and swallows islands it passes; a caught player is put back on the nearest safe checkpoint ahead of it. It reaches the finish exactly storm.arriveBy seconds after it starts (stormFrontKit arriveBy), and the race clock is storm.startDelay + storm.arriveBy (4:00 by default), so 0:00 on the clock is the storm swallowing the finish, and only then is the race over for anyone still out there.
  • Island layouts: skyhookRace.layouts.sunsetIsles (the default) is plain data you can copy.
  • All the tuning numbers: skyhookRace.tuning, with defaults that play well.
  • Controls: a controlsKit scheme, skyhook, plays on keyboard + mouse, gamepad and touch at once. Every player can remap jump, boost, hook, reel and wingsuit on keys and pad, and move their touch buttons (swap places, left-handed mirror, stick type) in controlsKit's Controls screen (press C, View on a controller, or the Controls button on touch); each player keeps their remaps between visits.
  • Progression: XP, levels, best time and unlockable hook and glider styles (saveKit).

Multiplayer: everything shared is synced. The course and tuning ride in the RaceDirector's synced fields, bells keep a synced rung state, the fruit count is a shared objective and the storm is one shared front, so a player who joins late sees the same open routes, fruit count and storm as everyone else, and races straight away (joinInProgress).

Install it into an empty world

  1. Search ZeroMind for a sky-island grappling-hook race (the package is skyhookRace, guid b129e4fa-6753-4be9-a147-9d48fc887711) and install it, or in the engine shell: zero zeromind installAsset b129e4fa-6753-4be9-a147-9d48fc887711. It lands at /source/skyhookRace.package and brings what it builds on: floatingIslands 1.0.11, grappleKit 1.0.15, glideKit 1.0.16, airMotor 1.0.9, stormFrontKit 1.0.11, MatchFlow 1.4.3, Trapline 1.5.8, pickupsKit 2.3.14, scoreKit 1.4.10, navUiKit 1.3.14, saveKit 1.3.16, platformsKit 1.6.4, juiceKit 1.2.12, cloudburst 1.5.3, worldClockKit 1.7.7 and controlsKit 1.4.2, and through them menusKit, soundstage, barsKit, SecondWind and Lifeline. It is a large install (about 6,600 files) and takes a minute or more; "waiting for content" warnings while it lands are normal.

  2. Make a scene for the race, build the race in it, then switch players on. In this order, checking each before the next:

    a. In the engine shell: zero scene create --startup race empty. You should see an empty scene named race, which the world now starts in.

    b. Open its build file, scenes/race.scene/build.luau, and replace everything in it with:

    function content()
        require("skyhookRace.race").build()
    end
    

    Save. You should see, within a few seconds, Sunset Isles' islands, the sea of clouds and the sunset sky. The build also placed the race's player (body, camera, hook, wingsuit) and four spawns on the start island.

    c. Once the islands are there, switch players on (an empty scene starts with them off): zero scene player spawns. You should see the report list one prototype, DefaultSocialPlayer, four spawns Spawn0 to Spawn3, and intent: spawns. Run it only after the build has landed: before it, the command authors a plain player of its own, with no hook or wingsuit, beside the race's.

    Why a new scene rather than the world's starter scenes/main.scene? The starter scene carries editor edits on its own floor, camera and player; replacing its contents leaves those edits pointing at things that are gone, and the rebuild stops on them. A fresh empty scene has none.

  3. Press Play. You should see the lobby count down, then GO, a glowing ring over the first gap (the ring to aim at next is always lit for you), and the storm rolling in behind you. You finish by reaching the finish island: within race.finishRadius (9 m) of its centre and no more than race.finishHeight (12 m) above its top.

A tiny race of your own

Make a module for your course: a folder /source/myCourse.module with this init.luau (positions are { x, height, z } in metres; roles are start, checkpoint, finish and rest):

local L = {}
L.name = "Tiny Hop"
L.islands = {
	{ id = "start", label = "Start", role = "start", theme = "start", pos = { 0, 0, 0 }, radius = 16, depth = 18, seed = 1, shape = "mesa" },
	{ id = "middle", label = "Middle Isle", role = "checkpoint", theme = "waterfall", pos = { 0, 4, 45 }, radius = 14, depth = 18, seed = 2, shape = "round" },
	{ id = "finish", label = "Finish Isle", role = "finish", theme = "finish", pos = { 0, 8, 90 }, radius = 14, depth = 18, seed = 3, shape = "spire" },
}
L.anchors = {   -- hook points over the gaps
	{ name = "Hook_1", pos = { 0, 20, 24 }, look = "ring" },
	{ name = "Hook_2", pos = { 0, 24, 68 }, look = "ring" },
}
return L

Then build it instead of Sunset Isles in scenes/race.scene/build.luau:

function content()
    require("skyhookRace.race").build({ layout = require("myCourse") })
end

Bells, air currents, zip lines and the rest are optional; copy them from skyhookRace.layouts.sunsetIsles when you want them. In a script, the local runner is layers.active.players.localPlayer.avatar, and require("MatchFlow.api").find():getStandings() lists who has finished and their times.

Controls (defaults, all remappable): walk with WASD / left stick, look with the mouse / right stick, jump with Space / A (press it again in the air to open the wingsuit), boost with Left Shift / L3 (a sprint on foot, a dive for speed with the wingsuit open), fire and release the hook with the left mouse button or E / RT, hold the right mouse button or Q / LT to reel in, open and fold the wingsuit with G / LB, steer it with the stick or WASD. C (View on a pad) opens the Controls screen. On a phone: a floating stick on the left, drag the right half to look, Hook / Jump / Wingsuit / Reel / Boost on the right.

Change it

For a whole course of your own in stages (survey, design the islands and bells, build the layout, tune the storm, race it solo and with two players until clean), start the workflow that ships in this package: zero workflow start --name skyhookRace.build-a-sky-island-race-course (args: course, name).

function content()
    require("skyhookRace.race").build({
        layout = require("myCourse"),                -- your own course (copy sunsetIsles)
        tuning = {                                   -- any subset of skyhookRace.tuning.defaults
            race = { lobbySeconds = 5 },
            storm = { maxSpeed = 8, startDelay = 10, arriveBy = 290 },   -- the clock reads 5:00
            hook = { range = 60 },
            glide = { style = "paraglider" },
        },
    })
end
  • Tuning (skyhookRace.tuning): race, bells, fruit, hook, glide, storm, progression, world, score. Leave out what you don't change. storm.arriveBy sets how long the race lasts (the clock is storm.startDelay + storm.arriveBy); storm = { enabled = false } races without the storm, on race.roundSeconds. A layout can carry its own tuning table too (Sunset Isles sets its ring heights there); it sits between the defaults and the tuning you pass to build.
  • Layouts (skyhookRace.layouts.sunsetIsles): islands with a role (start, checkpoint, finish, rest), a look and a shape. Islands are grown by the floatingIslands part: give an island any of its looks (meadow, waterfall, farmland, crystal, fortress, marble, snowy, autumn, mesa, volcanic, lowpoly, pixel) and shapes (round, stone, stepping, ridge, arch, ring, cluster), or a Skyhook theme (start, waterfall, windmill, crystal, fortress, finish, islet: a look plus Sunset Isles' own ground and cliff materials), and the shape numbers (radius, depth, seed, stretch, bumps, hanging, roots, crags, debris). Also bellRoutes (islets each bell raises); bells (in order, with where and hint, opensFinish); air (thermals, updrafts, rings); anchors, zipLines, slingshots, crumbleStones, hookShells; stormStart; and an optional decorate(ctx) for set pieces. The same seed is the same island on every machine.
  • Dressing: tuning.world.dressing = false drops Sunset Isles' own props, falls and per-island ambience, so you can dress the islands yourself. The sunset atmosphere (sky haze and grade, cloud sea, horizon islands, cloud wisps, open-sky wind) still builds for any course; tuning.world.atmosphere = false drops it too.

What is inside

PartWhat it does
race.modulebuild(options): the whole race into a scene
tuning.moduleevery number, defaults and merge(overrides)
course.modulea layout as a course (roles, route, start, finish), to and from JSON
layouts/sunsetIsles.modulethe default course
islands.moduleone floating island per layout entry, grown by floatingIslands (look, shape, theme)
controls.modulethe skyhook controlsKit scheme (move, look, jump, boost, hook, reel, wingsuit), turning it into grappleKit / glideKit calls, and controlsKit's Controls screen
RaceDirector.componentruns the race on every peer: phases, objectives, bells guide, storm rescue, finish, results, music, progression, controls
Bell.component / bellNet.modulea bell that rings for the team and raises its route
Starfruit.componentthe glowing fruit drawn for a shared pickup
input/airthe map the hook's swing pump and the wingsuit's steering read move from under the scheme
env/dressing, sunset atmosphere, cloud sea, waterfall water
art/the meshes, materials, sounds and music the race uses

Guides

  • how-skyhook-is-built-and-how-to-change-it: how the parts fit and where to change each thing.
  • example-make-your-own-sky-island-race-level: build a small race of your own, step by step.

Read one with guides { path = "skyhookRace.package/guides/<name>" }.

What's new in 1.5.1

  • A package description that says what you get and how to install it, here and in each part it is built on: grappleKit 1.0.15, glideKit 1.0.16, airMotor 1.0.9, stormFrontKit 1.0.11 and floatingIslands 1.0.11 (description and version only; floatingIslands also ships fresh previews).
  • Fresh preview pictures for the runner suits, the bell beams, the amethyst and cyan crystals and the four new cloud seas. The released ones were out of date, so every world that installed the race redrew them and then reported the install as changed. No change to how the race plays.

What's new in 1.5.0

  • The ring to aim at is lit. Each runner's next ring glows inside a pulsing ball of light on their own screen (grappleKit 1.0.15's cue), and the gap rings use grappleKit's new halo look, a ring of cool light that reads against a warm sky. hook.anchorLook picks another look for the whole course (ring, lantern, star, beacon, balloon, or themed for 1.4's per-island looks); hook.cueNextRing = false turns the glow off.
  • Soft clouds instead of pale rectangles. The cloud wisps over the cloud sea are cloudburst 1.5.3 cloud banks: round, ragged at the rim and soft underneath, from near and far.
  • Five sky moods in one line. world.mood = "sunset" (the default), "dawn", "noon", "night" or "storm" sets the sky, the light, the haze and the cloud sea together (skyhookRace.moods). The sun now stands where the course wants it through worldClockKit 1.7.7's own sunBearing, sunTilt and ambientBoost, so the race no longer overrides the clock's sun.
  • Island and bell styles in one line. world.islandStyle regrows every island from another set of floatingIslands looks (winter, autumn, volcanic, meadow, lowpoly, pixel); bells.style gives every bell another body and beam (bronze, gold, crystal, amethyst).
  • A fresh course plays well out of the box. Leave storm.arriveBy out and the clock comes from the course's own length (storm.autoPace, never under 1:30; Sunset Isles keeps its 4:00). The launch ring never hangs further out than the hook can reach from the edge.
  • Starfruit come back through pickupsKit, and score through scoreKit. Each race's fruit returns with pickupsKit 2.3.14's restore; every runner's fruit is scored by scoreKit 1.4.10's pickup scorer on the machine keeping the score, whoever took it. The race's own workarounds are gone.
  • One health stack. Trapline 1.5.8 reaches Lifeline through SecondWind 1.4.8, and loads barsKit only when a hearts or pips lives display is drawn (Skyhook draws none).
  • The README and the example guide go step by step, each step saying what you should see: build the race, then switch players on (the order matters), turning off Sunset Isles' dressing for your own course, how checkpoints and the line to the next ring stay clear of props, and aiming at the lit ring ahead. The guide's numbers match its course (18 starfruit, a 2:40 clock).

What's new in 1.4.9

  • Your own course keeps the sunset. The example guide's world.dressing = false (the right call for a custom layout, since Sunset Isles' props are placed for its islands) also dropped the sky haze, colour grade, cloud sea, horizon islands and cloud wisps, leaving a flat pink fog. Those are now env/dressing's buildAtmosphere and build for any course unless world.atmosphere = false. Sunset Isles with the default dressing builds exactly as before.
  • The next-bell message shows once. At every countdown "Next: <bell>" was shown twice (the twice-a-second refresh and the forced refresh a second later both announced it). It now shows once per bell; the waypoint and objective still refresh.
  • The example guide counts its starfruit right: its course shows Team starfruit 0/18, not 0/12.
  • The example guide says when to switch players on. An empty scene starts with players off, so zero scene player spawns is still needed, but only after the build has landed: run before it, it authored a plain player and spawn of its own beside the race's, and a joiner could come in with no hook or wingsuit. The guide and this README now say to run it once the islands are in the scene.
  • A fall respawns you at your own checkpoint. Any runner below y -60 was "rescued" as if the storm had caught them, and sent to the checkpoint nearest to where they fell, reached or not: falling off past an island put you on the next one (or two) ahead, skipping checkpoints, bells and whole gaps, with a "The storm caught you!" toast. A fall now goes to Trapline's respawn at your own checkpoint (or the start); the rescue only steps in when that spot has been swallowed, and then picks the first safe checkpoint in course order, not the nearest.
  • Flying high over the finish no longer finishes the race. The line counted at any height above the finish island (a fling 50 m over it recorded a finish). It now counts up to race.finishHeight (12 m) over the island's top.
  • You can aim at the ring ahead, as the guide says. Each gap's launch ring hung 17 m up, close to the departure rim: from the edge it sat far above where the follow camera can look, so the reticle took the higher re-hook ring instead. The launch ring now hangs over the middle of the gap at 11 m (hook.launchAlong 0.5, hook.launchHeight 11), and the re-hook ring over the arrival rim (hook.rehookAlong 0.95), still ahead when you let go of the launch swing. Checked with real input: every run-up locked the ring ahead, and a full lap finished in 1:38.8. Sunset Isles keeps its own rings (17 m, 0.3 and 0.8 across), tuned and raced for its long gaps: a layout can now carry its own tuning, laid between the defaults and the game's tuning, and Sunset Isles uses it.
  • Custom courses keep the race clear of props. With world.dressing = false each island grows its look's dressing from floatingIslands, which placed rocks and trees anywhere, including between a checkpoint and the next gap's rings (the reticle then jumped to a bell 57 degrees off). The build now gives every island clear zones (FloatingIsland.clear, new in floatingIslands 1.0.11, which this release takes): a lane toward each neighbouring main island, the checkpoint and any bell standing on it. Sunset Isles with the default dressing is unchanged.
  • Hooking a bell from the ground rings it and lets go. The hook rang the bell and then swung you toward it, which pulled a runner standing on Lantern Rock toward the Wind Bell's crag. Now a runner who was standing gets a ring shot: the bell rings and they stay where they stood. A runner already in the air keeps the swing, since the bell hooks also carry you up to the crags and towers.

What's new in 1.4.8

  • Takes stormFrontKit 1.0.11, whose two guides now say which version they describe. The README's install list and both guides name it. Text and the dependency pin only: play, layouts, tuning and every file of 1.4.7 are unchanged.

What's new in 1.4.7

  • Installs match the release exactly. Eleven preview pictures in 1.4.6 (the six runner suits, the two crystal materials, and the cloud-sea, waterfall pool and waterfall sheet shaders) were rendered before their assets' last change, so every world that installed the kit redrew them and then showed the install as changed from the release. They are re-rendered and current. Takes floatingIslands 1.0.9 (the same fix for its island rock shader). Play, layouts and tuning are unchanged from 1.4.6.

What's new in 1.4.6

  • A new hook or glider style waits until you land. An unlock earned mid-race is saved at once and equipped when you are standing on the ground with the glider closed and the hook idle, so a wingsuit is never swapped for a canopy in the air (that cut a 25 m/s glide to 11). The unlock listener is removed when the race director goes away, so restarts never stack handlers.
  • A starfruit no longer flashes a big pale ball in front of the camera. Takes juiceKit 1.2.12, whose cartoon look draws its pickup glow as a soft glow instead of a solid ball.
  • Courses of your own build without Sunset Isles' waterfall. The default dressing skipped no set piece, so a layout without a waterfall island and its waterfall_crag stopped with "attempt to index nil with 'theme'". The falls, river, pool and their sound now appear only when those two islands exist; the tiny course above builds and races to the finish.
  • Takes saveKit 1.3.16. The README names every part and version it brings, warns that the install is large, and gives a tiny course; the guides name the installed versions. Older changes are in CHANGELOG.md.