Log inGet started
Package

airMotor.package

README.md

airMotor 1.0.9

Keep the player's momentum. The engine's built-in CharacterController bleeds any fling down to walking speed in a fraction of a second, because in the air it eases toward the walk the stick asks for. airMotor drives the controller so the body moves at exactly the velocity you ask for, and when you let go it keeps flying on the speed it had, falling under gravity with a little stick steering, until it lands.

It is the shared base for movement parts that fly the player: grappling hooks (Grapple Kit), gliders and wingsuits (Glide Kit), launch pads, boost rings, slingshots, cannons and dashes. One owner steers a body at a time, so a hook releasing into a glider into a boost ring hands the player along with no speed lost and no two parts fighting over the controller.

  • Works on the normal built-in player (@builtin::avatars.humanoid or any body with a CharacterController), on desktop, browser, gamepad and touch.
  • Multiplayer-safe: it only drives the body on the peer that owns it; other players see the motion through the controller's own transform sync.
  • Ships LaunchPad, a pad component built on it, and a demo scene.

Install

Search ZeroMind for airMotor ("keep momentum when the player is launched") and install airMotor.package (package guid b92d5ebf-4151-4bb9-b63c-c12d07cc03b6). No dependencies.

Quick start

Run it on each peer for its own player, once that player has spawned: a scene's entrypoint.luau localPlayerReady, a component's update, an input handler. localBody() is nil until the local player's body exists (a few seconds into play on a new world), so check it first; the strict checker refuses the calls without that check.

-- scenes/main.scene/entrypoint.luau
local Motor = require("airMotor.api")

function localPlayerReady(player)
    local body = Motor.localBody()             -- the local player's controller entity, or nil
    if not body then return end
    Motor.launch(body, vector.create(0, 14, 18))   -- a fling that keeps its speed until it lands
end

A part that steers the body every frame (a hook, a glider):

local body = Motor.localBody()
if body and Motor.claim(body, "myGlider", 2) then    -- higher priority wins
    -- each frame:
    Motor.setVelocity(body, "myGlider", vector.create(0, -2, 15))
    -- when done:
    Motor.release(body, "myGlider")             -- coasts on its momentum
end

API (airMotor.api)

CallWhat it does
localBody()The local player's body entity id (the entity with the CharacterController).
claim(body, owner, priority?)Take the body. Refused while a higher-priority owner holds it.
holds(body, owner)Does owner hold it now?
setVelocity(body, owner, v)The exact world velocity for this frame (owner only).
release(body, owner, {coast?, velocity?})Let go; coasts on its momentum unless coast=false.
impulse(body, dv) / launch(body, v)Add / set velocity; an idle body starts coasting.
velocity(body), mode(body), owner(body), grounded(body)Read back the state.
stick(body)The player's stick as a flat world direction, 0..1, for steering.
setCoast(body, {gravity, drag, steer})Tune the coast.
on(body, fn(event, data))claimed, lost, released, impulse, landed (speed, airTime).
reset(body)Hand the body back to the controller at once (respawns, teleports).

The AirMotor component is added to the body for you; its mode, owner and speed fields read back what is driving it.

How it works

Runs at executionOrder = -105: after controlsKit's ControlsMover (-120) writes the walk and before the controller (-100) reads its bus. Horizontal speed is exact by raising airControlFactor to 40 and writing v / 40; vertical speed is exact by setting the controller's gravity to (vy - lastVy) / dt, and lift-off from the ground is one jump impulse. The controller's own wall and ground passes still run, so a body that hits a wall stops against it and the motor carries what really happened. The controller's own stats are put back when the motor goes idle.

Guides (shipped in guides/)

  • How to keep momentum when the player is launched, swung or flung
  • Example: build a small launch pad and momentum level (from an empty world, with the player scene template)

Changelog

  • 1.0.9: The package description says what airMotor gives you and how to install it. No change to how it plays.

  • 1.0.8: A driven body never ends a frame inside rock. Before applying a velocity, the motor sweeps the body's own capsule (its controller's height and radius, plus CAPSULE_MARGIN) along the frame's move; a move that would cross a collider stops at its surface and slides along it. A fast swing or dive could otherwise end a frame inside an island's rock, and the physics shoved the body out wherever the rock was thinnest: a jump of 10-30 m in one frame, then shaking as a rope pulled it back. The vertical speed is also set with a frame time of at least 1/60 s (capped at 300 m/s²), so a very short frame after a long one no longer throws the body. Measured in two-player races: no unexplained jumps; a 48 m/s wingsuit release still glides at 51-53 m/s and landings land. Both guides name 1.0.8.

  • 1.0.7: Documentation only: both guides open by naming the version they describe (1.0.7). The api's VERSION is 1.0.7. Behaviour is unchanged.

  • 1.0.6: Documentation only: the example level now runs along -Z, the way the default player and camera face when play starts. As written before, walking forward took the player off the back of the start block, away from the first pad. Checked in a brand-new world: holding W for 2 s carries the player over all three pads onto the goal (16.5 m up, 90 m out). The api's VERSION is 1.0.6.

  • 1.0.5: Documentation only: both guides open with a "Part of airMotor" line naming the ZeroMind package and how to install it, and their descriptions name the kit. The api's VERSION is 1.0.5. Behaviour is unchanged.

  • 1.0.4: Documentation only: the README Quick start now runs as written. It passed Motor.localBody() straight to launch, but that returns nil until the player spawns, so the strict checker refused the snippet (expected string, got nil | string) and it never said where to put it. It now sits in a scene's localPlayerReady with a nil check. Checked by installing into a brand-new empty world and following the README: an 18 m/s launch still carries 15.7 m/s after 3.2 s of flight. The api's VERSION is 1.0.4. Behaviour is unchanged.

  • 1.0.3: Documentation only: guides renamed after what they help you do, the example rewritten on the player scene template and the jetpack recipe moved to input-map handlers (the old one called an input api that does not exist); the api's VERSION constant now matches the package. Behaviour is unchanged from 1.0.1.

  • 1.0.2: Documentation only: no long dashes in the docs and comments, world notes added. Behaviour is unchanged from 1.0.1.

  • 1.0.1: A release / impulse / launch velocity is no longer cut back to last frame's motion on its first frame (release boosts and mid-air impulses now keep their speed), and the grounded lift-off frame no longer moves at 40x the horizontal speed.

  • 1.0.0: First release.