# 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.
```luau
-- 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):
```luau
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`)
| Call | What 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.