grappleKit.package
- .metadata444 B
- GrappleDisplay.component
- GrappleHook.component
- GrapplePoint.component
- README.md18.9 KB
- Slingshot.component
- ZipLine.component
- api.module
- art
- build-a-grappling-hook-level.workflow
- catalog.module
- grapple.inputMap
- grappleGallery.scene
- guides
- looks.module
- materials
- package.yaml947 B
- rope.module
- swing.module
- tests
This package holds more than this page lists. See all of its files in its world.
README.md
grappleKit 1.0.15
grappleKit gives your player a grappling hook. Aim, fire, latch and swing like a real pendulum that keeps and builds momentum, reel in, let go for a fling (with a boost for a well-timed release), ride zip lines and get launched by slingshots. Ten hook styles in four families, twelve rope looks you can put on any head, four feels, six grapple point looks, keyboard + mouse, gamepad and touch, and every player sees every other player's rope in multiplayer.
Built on airMotor (installed with it), which drives the engine's built-in CharacterController with exact air velocity, so a release flings you and keeps your speed until you land. A glider built on airMotor can take over the moment you let go.
The 35 variants
| Kind | Count | Names |
|---|---|---|
| Hook styles (head + sound + default rope) | 10 | classic, harpoon, ninja, vine, energy, frost, steampunk, plunger, magnet, pixel |
| Rope looks (any rope on any head) | 12 | hemp, steel, vine, energy, brass, candy, ninja, pixel, bungee, laser, frost, gold |
| Feels | 4 | arcade, floaty, heavy, acrobatic |
| Grapple point looks | 6 | ring, hook, branch, crystal, balloon, beacon |
| Other anchor kinds | 3 | ZipLine, Slingshot, grappleable surfaces |
| Total | 35 |
The styles are grouped in 4 families (Classic, Magic, Gadget, Retro), and since the rope is independent of the head, the 10 heads and 12 ropes make 120 hook combinations before you pick a feel. Every one of these is in the grappleKit.grappleGallery scene, side by side and labelled.
Changelog
1.0.15
- The package description says what grappleKit gives you and how to install it. Takes airMotor 1.0.9 (its description says the same; no code change).
grappleKit.apireportsVERSION = "1.0.15".
1.0.14
- Three new anchor looks:
halo(a ring of cool light that reads against any sky, from far away),lantern(a lit lantern hanging on a chain) andstar(a gold star with a bright heart).lookswaps between all nine. GrapplePoint.cue: mark the anchor to go for next, on this machine only. A pulsing ball of crossed light rings round it reads from far away; a game sets it per player (skyhookRace lights each runner's next ring).grappleKit.apireportsVERSION = "1.0.14".
1.0.13
- A moving anchor never flings the runner. 1.0.12 took a moving anchor's velocity as its step divided by the frame time; on a short frame after a long one that turned an ordinary windmill-sail movement into a 100 m/s fling (a runner was thrown 400 m off course, others jumped 18-74 m and shook as the rope pulled back). The anchor's velocity is now its step over at least 1/30 s, smoothed and capped at 25 m/s. Measured in two-player races: no jumps on the sail rings.
- Both guides name the version they describe (1.0.13). Takes airMotor 1.0.8 (its capsule sweep keeps a swing from ending a frame inside rock).
grappleKit.apireportsVERSION = "1.0.13".
1.0.12
- A low or moving anchor swings smoothly. Latched to an anchor only a few metres above the ground (a windmill sail ring at the bottom of its turn), the swing arc ran into the island: the speed collapsed, the body was pulled back and thrown back and forth metres between frames as the ground and the rope fought. Now the rope is capped so the bottom of the arc clears the ground under the anchor by 1.6 m (sampled every 0.2 s), a grounded body is never driven down into the ground, and a moving anchor's own motion is taken out of the swing (the pivot carries the body instead of yanking the rope; a jump of 3 m or more in one frame, a respawn or teleport, counts as still).
- Both guides name the version they describe (1.0.12). Takes airMotor 1.0.7.
grappleKit.apireportsVERSION = "1.0.12".
1.0.11
- The hook goes for anchors, not the ground at your feet: with surfaces hookable (
surfaceTag), a shot with no anchor in the aim cone latched onto the ground just ahead, on a rope of a few metres, and pinned the player in place. Now an anchor slightly wider of the aim (twice the cone) is tried first, and a surface is hooked onlysurfaceMinDistance(8 m) or more away andsurfaceMinRise(2 m) or more above the player. Test: "surfaces are hooked only where you can swing". - No error when a ray hits a collider that is not an entity: the surface check called
entity(id)on the ray's hit id, which logs an error for a collider that is not its own entity; it now asksentity.existsfirst. - New: the
build-a-grappling-hook-levelworkflow, for the whole job in stages (survey, plan, build, play until it flows). grappleKit.apireportsVERSION = "1.0.11".
1.0.10
- Really brings airMotor 1.0.6: the pinned dependency is now airMotor 1.0.6 (1.0.9's notes said it took 1.0.6, but its package still pinned 1.0.3, so a fresh install got 1.0.3). glideKit 1.0.11 pins the same 1.0.6, so a world with both runs one airMotor.
- The README title names the current version (it still said 1.0.8).
grappleKit.apireportsVERSION = "1.0.10". Behaviour is unchanged.
1.0.9
moveMapfield: the map whosemovestick pumps the swing (default: the engine's walking map, as before). A controlsKit scheme stands the walking map down, which silenced the pump in 1.0.8; a game on a controlsKit scheme pointsmoveMapat a map of its own with amovecontrol (Skyhook does). Built and tested against airMotor 1.0.6, but the package still pinned 1.0.3; fixed in 1.0.10.grappleKit.apireportsVERSION = "1.0.9".
1.0.8
- Example guide works in a brand-new world: step 2 now remakes
scenes.mainclean before writing the level. A new world's seeded starter scene carries recorded edits, so the rewrittenbuild.luauwas refused ("composition has structural conflicts") and no islands appeared. Checked by installing into a new empty world and following the guide: E latches the beacon, the swing and the release fling work. grappleKit.apireportsVERSION = "1.0.8". Behaviour is unchanged.
1.0.7
- Guides say which kit they belong to: both guides open with a "Part of grappleKit" line naming the ZeroMind package and how to install it, and their descriptions name the kit.
grappleKit.apireportsVERSION = "1.0.7".
1.0.6
- Quick start fixed: the zip line and slingshot in the Quick start now have positions. Without them both landed at the origin, right on a new world's spawn, so the first press latched onto the slingshot under your feet instead of the ring. Checked by installing 1.0.5 and 1.0.6 into a brand-new empty world and following the README.
grappleKit.apireportsVERSION = "1.0.6".
1.0.5
- Guides renamed after what you want to do:
how-to-add-a-grappling-hook-to-my-gameandexample-build-a-small-grappling-hook-swinging-level(the old kit-named guides are gone). Both checked against the 1.0.5 fields, api and events; the example level was rebuilt and played in the grappleKit world. - airMotor 1.0.3 is now the pinned dependency, so a world with grappleKit and glideKit runs one airMotor.
grappleKit.apireportsVERSION = "1.0.5".
1.0.4
- Aiming marker fix: the aim marker no longer errors (
worldRotation: argument 2 must be finite, got NaN). Its rotation came fromquatFromY, which divided by a zero-length axis when the target sat on the camera, the direction was zero, or a point was NaN. Every rotation grappleKit writes (marker, rope segments, hook head, grapple points, zip line cable) now goes through finite-safe helpers (Swing.safeQuat,Swing.q4,Swing.safeVec,Swing.finite), and the marker hides when there is no valid target. A target or anchor with no finite point is ignored instead of fired at. - Guides renamed:
how-to-use-grapplekit-to-add-a-grappling-hook-to-my-gameandexample-building-a-small-level-or-game-with-grapplekit-from-an-empty-world. - airMotor 1.0.2 is now the pinned dependency.
- Descriptions match the kit: 10 styles in 4 families, 12 rope looks, 4 feels, 6 grapple point looks, zip lines, slingshots, grappleable surfaces, 35 variants.
- Tests: new degenerate-input tests (zero vector, same point, NaN and inf, nil anchor, degenerate rope ends); 22 tests.
1.0.3
- Feels: exactly four listed feels:
arcade(unchanged, now the default),floaty(low gravity, long hang, gentle reel),heavy(strong gravity, big momentum, slow reel) andacrobatic(fast reel, big release boost, tight short ropes, quick cooldown for chaining). The 1.0.x namesclassic,realisticandzippystill resolve as hidden aliases, so older worlds move the same. - Rope field:
GrappleHook.rope(andGrapple.setRope,GrappleDisplay.rope) puts any rope look on any hook head;""keeps the style's own rope. The catalog now keeps hook heads and ropes in separate tables (heads,ropes), and each style names its default rope. - New rope looks:
bungee,laser,frost,gold(12 in all). - New styles:
frost(ice shard on a crystal string) andmagnet(horseshoe magnet on a bungee cord), with heads built from primitives. - Families: Classic (classic, harpoon, ninja), Magic (vine, energy, frost), Gadget (steampunk, plunger, magnet), Retro (pixel), with
families(),stylesIn(family)andfamilyOf(style). - Grapple point looks:
balloon(floats, bobs and sways; the rope follows it) andbeacon(a glowing light post). Both glow with emissive materials, not lights. - Gallery: every style under its family banner, every rope on the same head, every grapple point look and the four feel pads, each labelled; blue pads switch your rope.
- Guides: the example guide is now
example-building-a-small-level-or-game-with-grapplekit-from-an-empty-world; both guides cover feels, ropes, families and the new looks, and show stoppingGrapple.onlisteners inonUnloadso a second play session starts clean. - Tests: run green inside the grappleKit world; new tests for the feels, the rope field, families and the point looks (19 tests).
1.0.2
Smoother chains. A grab made at speed keeps the momentum you brought: the latch kick now only helps a slow grab and fades to nothing at autoSwingSpeed. A timed release still adds its boost along your motion, but its upward lift fades when the swing is already throwing you up, so it flings you onward instead of straight into the sky.
1.0.1
Built on airMotor 1.0.1 (release boosts and mid-air impulses keep their speed; clean lift-off from the ground).
Install
Search ZeroMind for grappleKit and install grappleKit.package, or:
tools.use("zeromind", "installAsset", "434aaae1-e089-4d8a-96b5-7eaa59d3016d")
(zero zeromind installAsset 434aaae1-e089-4d8a-96b5-7eaa59d3016d in the engine shell.) It lands at /source/grappleKit.package with airMotor beside it. Open the grappleKit.grappleGallery scene to see every variant and play the test course.
Quick start
For a whole swinging level in stages (survey, plan the anchors, build, swing it until it flows), start the workflow that ships in this package: zero workflow start --name grappleKit.build-a-grappling-hook-level (args: level, style).
In your scene's build.luau, give the player prototype's body a hook and place a few anchors:
body.component.add("GrappleHook", { style = "classic", feel = "arcade" }) -- on the PlayerPrototype's body
local ring = entity.spawn("ring")
ring.localPosition = { 0, 14, 20 }
ring.component.add("GrapplePoint", { look = "ring" }) -- swing from it
local zip = entity.spawn("zip")
zip.localPosition = { 14, 10, 10 } -- the cable's high end
zip.component.add("ZipLine", { endOffset = { x = 30, y = -6, z = 20 }, speed = 18 })
local sling = entity.spawn("sling")
sling.localPosition = { -14, 10, 20 }
sling.component.add("Slingshot", { launch = { x = 0, y = 14, z = 18 } })
Give every anchor a position up and away from the PlayerSpawn: an anchor left at the origin sits under a new world's spawn, and the hook picks it first.
Press Play: look up toward an anchor (move the mouse; the aim follows the camera) and press left mouse or E / right trigger / Hook; press again to let go. Hold right mouse / left trigger / Reel to reel in. Push the move stick along the swing to pump it.
GrappleHook fields
| Field | Default | What it does |
|---|---|---|
style | classic | Hook head, sounds and default rope (see Styles). Synced, swap it live. |
rope | "" | Rope look, independent of the head (see Rope looks). "" = the style's own. Synced. |
feel | arcade | How it moves you (see Feels). Synced. |
hookEnabled | true | Off: cannot fire, a latched hook lets go. |
holdToSwing | false | true: hold the button to stay on, let go to release. false: press to fire, press again to release. |
range / assist | 0 | Override the feel's max range (m) / aim-assist cone (degrees). |
surfaceTag | grappleable | Any collider whose entity (or a parent) has this attribute true is hookable where the camera ray hits. "" = off. |
anySurface | false | Hook any collider. |
surfaceMinDistance | 8 | A surface (not an anchor) is hooked only this far away or more, so the ground just ahead is never hooked. 0 = no limit. |
surfaceMinRise | 2 | A surface is hooked only this many metres or more above the player's centre. |
useInput / inputMap | true / grappleKit.grapple | Read the controls; off = drive it from code only. |
moveMap | @builtin::inputMaps.default | The map whose move stick pumps the swing. Under a controlsKit scheme (which stands the walking map down) point it at a map of your own with a move control. |
handBone | Hand_R | Bone the rope leaves from. |
sounds, volume, reticle | Sound on/off and level; the ring shown on the picked anchor. |
Read-only synced state: phase (idle, flying, latched, zip, retract), hookPoint, ropeLength, anchorId, chain (latches in a row without landing), and speed (owner).
Styles and families
| Family | Styles |
|---|---|
| Classic | classic iron hook on braided hemp, harpoon barbed harpoon on steel cable, ninja kusarigama sickle on a fine dark chain |
| Magic | vine magic vine with leaves and a glowing bloom, energy sci-fi emitter with a pulsing cyan tether, frost ice shard on a string of glowing crystals |
| Gadget | steampunk brass claw on a brass-and-copper chain, plunger cartoon plunger on a candy-striped rope, magnet horseshoe magnet on a bungee cord |
| Retro | pixel blocky hook on a chunky line that snaps to a voxel grid |
Each has its own hook head and fire / latch / release sounds. Catalog.families(), Catalog.stylesIn("magic") and Catalog.familyOf("magnet") read the grouping (also on grappleKit.api). Add your own: registerStyle("pirate", { head = "classic", rope = "gold", family = "classic" }), registerHead, registerRope, registerFamily. The 1.0.x form with head and rope fields inline still works.
Rope looks
hemp braided rope, steel cable, vine leafy vine, energy cyan beam, brass chain, candy cartoon rubber rope, ninja fine chain, pixel voxel line, bungee cord, laser red laser, frost ice crystals, gold chain. Set rope on the hook (or Grapple.setRope(nil, "laser")) to wear any of them on any head.
Feels
| Feel | Character |
|---|---|
arcade (default) | Strong pull, swings keep themselves going, big release boost, wide aim cone. |
floaty | Low gravity, long lazy hangs, a gentle reel, releases that sail far. |
heavy | Strong gravity and big momentum, slow reel, no help: weighty. |
acrobatic | Fast reel, tight short ropes, big release boost, near-instant cooldown for chaining. |
classic, realistic and zippy (from 1.0.x) still resolve but are not listed. registerFeel(name, overrides, base?) adds yours (every number is documented in catalog.module).
Anchors
- GrapplePoint: a hookable anchor.
look=ring,hook,branch,crystal,balloon(bobs;bobsets how far),beacon(a glowing post; the lamp is the latch point) ornone(use your own model);weightbiases aim assist; outlined while aimed at. - ZipLine: a cable to
endOffset; ride it towardspeed, downhill or along your momentum, flung on at the end. - Slingshot: release near the bottom of the swing (or reel in) to launch along
launch. - Surfaces: set attribute
grappleable = trueon any entity with a collider. - GrappleDisplay: a static line of any style and rope, for galleries and props.
Events and API
local Grapple = require("grappleKit.api")
local stop = Grapple.on("latched", function(e) print(e.anchorKind, e.chain, e.isLocal) end)
Grapple.on("released", function(e) if e.timed then print("perfect release!", e.speed) end end)
Grapple.fire() -- the local player's hook at the aimed anchor (or Grapple.fire(nil, anchorEntityId))
Grapple.release(); Grapple.setReel(nil, true); Grapple.setStyle(nil, "vine"); Grapple.setRope(nil, "gold"); Grapple.setFeel(nil, "heavy")
Grapple.families(); Grapple.stylesIn("gadget"); Grapple.phase(); Grapple.anchor(id)
Grapple.on returns a function that stops listening: call it in your onUnload / onDestroy, so replaying does not stack handlers. Events: fired, missed, latched (anchorId, anchorKind, point, ropeLength, chain), released (speed, timed, boost, chain), broke (reason), zipStart, zipEnd (speed), slingshot (speed), landed (chain, airTime). Each carries body, style and isLocal.
Controls
The grappleKit.grapple input map: grapple = left mouse or E / right trigger or right bumper / a Hook touch button; reel = right mouse or Q / left trigger or left bumper / a Reel touch button. It sits in its own grapple group, so it stays live beside the walking map and beside a controlsKit scheme. The move stick pumps the swing: the walking map's move by default, or the move of the map in moveMap.
Multiplayer
Each player has their own hook; physics runs only on the owner's peer (through airMotor). style, rope, feel, phase, hookPoint, ropeLength, anchorId and the shot's start are Sync fields, so every peer draws every rope, head and style, and late joiners see ropes that are attached right now. Remote hooks fire the same events on every peer with isLocal = false.
Guides (in the package)
- How to add a grappling hook to my game (
grappleKit.package/guides/how-to-add-a-grappling-hook-to-my-game) - Example: build a small grappling hook swinging level (
grappleKit.package/guides/example-build-a-small-grappling-hook-swinging-level)