# Spaceships in your game (vehicle.spaceship)

## What it is for

`vehicle.spaceship` gives a game pilotable ships: thrust and brake, pitch, yaw, an optional roll and a boost. Each ship is a
document of the `spaceships` collection (speeds, turn rates, hull, shield, fixed guns). The player either is the ship named by
`playerShip` or a character who boards one. Guns fire through `combat.projectiles` (else `combat.ranged`); hull and shield are the
health and shield of `combat.core`. Enemy ships are `enemy.ai` enemies that fly with the `ship_attack` behaviour. The kit moves
the ships itself and leaves drawing them to the engine. For cars, see the [vehicles guide](guide:vehicles).

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "vehicle.spaceship" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "vehicle.spaceship",
                              config: { "playerShip": "fighter", "start": [0, 10, 0], "cameraDistance": 14 } }
```

It requires `input.actions`, `physics.port` and `game.engine`. Install `combat.core` and `combat.projectiles` for a hull, a shield and
working guns. Define the ships in the `spaceships` collection, with one model per ship (asset `spaceship`, variant = ship id, nose
along +Z).

## First example

<!-- test: kits/vehicle_spaceship/tests/vehicle_spaceship.rs::thrust_accelerates_along_the_nose_up_to_the_top_speed -->
With `playerShip` set, the player flies from the first tick. Full throttle accelerates the ship along its nose up to its `maxSpeed`:

```text
vehicle.spaceship.drive("<entity>", { "throttle": 1 })   // then step the game
vehicle.spaceship.state("<entity>").speed                // 40 once capped, the maxSpeed of that ship
```

## Settings and defaults

| Setting | Type | Default | Meaning |
|---|---|---|---|
| `playerShip` | string | `""` | id of the ship the game starts in; empty: ships are placed and boarded |
| `start`, `startYaw` | vec3, rad | `[0, 12, 0]`, `0` | where that ship starts, and its heading |
| `cameraDistance`, `cameraHeight` | m | `14`, `5` | chase camera behind and above the piloted ship |
| `minAltitude`, `maxAltitude` | m | `0.5`, `0` | lowest height above the ground; ceiling (0: none) |
| `maxPitch` | rad | `1.1` | how far the nose can point up or down |
| `autoLevel` | rad/s | `0.8` | pitch and roll return to level when the stick is released (0: keep the attitude) |
| `collisionSpeed` | m/s | `6` | a hit slower than this costs nothing |
| `collisionDamage` | per m/s | `4` | hull damage per m/s above `collisionSpeed` |
| `boardReach` | m | `4` | how close a character stands to board |
| `boardLabel` | string | `Board {name}` | prompt on a ship |
| `enemyRange`, `enemyStandOff`, `enemyFireRange` | m | `90`, `14`, `45` | `ship_attack`: engage distance, circling distance, firing distance |
| `enemyFireCone` | cosine | `0.9` | `ship_attack`: cosine of the half-angle in which an enemy fires |

A `spaceships` document is `{ id, name, thrust (18), maxSpeed (30), boostSpeed (55), reverseRatio (0.4), brake (2.5), drag (0.5),
pitchRate (1.4), yawRate (1.6), rollRate (2), hull (100), shield (50), shieldRegen (8), shieldDelay (3), guns[], size, scale }`
(defaults in parentheses). A gun is `{ offset, damage (10), speed (90), rate (4), lifetime (2), spread (0.01), look }`, at most 16.
An entry can extend another to make a variant. Input actions: `vehicle.throttle`, `vehicle.steer`, `vehicle.pitch`, `vehicle.roll`,
`vehicle.handbrake`, `vehicle.boost`, `vehicle.fire`.

## Services, events, variables

- `vehicle.spaceship` (service): `ships()`, `piloting()` (view or null), `spawn(ship, at, opts?)`, `board(entity)`, `leave()`,
  `drive(entity, command | null)`, `fire(entity?)`, `boost(on)`, `state(entity)`, `hull(entity)`, `shield(entity)`.
- Events: `spaceship.spawned`, `spaceship.boarded`, `spaceship.left` (reason `key`, `service`, `script`, `destroyed`, `gone`),
  `spaceship.fired`, `spaceship.boost`, `spaceship.collided`, `spaceship.shield` (`down`, `up`), `spaceship.destroyed` (with
  `enemy`), `spaceship.refused` (a hook tap cancelled a decision).
- Variables: `spaceship.piloting`, `spaceship.name`, `spaceship.speed`, `spaceship.hull`, `spaceship.hull.max`, `spaceship.shield`,
  `spaceship.shield.max`, `spaceship.boosting`, `spaceship.kills`, `spaceship.enemies`.
- Content: verbs `spawn_spaceship`, `board_spaceship`, `leave_spaceship`, condition `is_piloting`, and an archetype component
  `spaceship { ship, pilot? }` (`pilot: "player"` puts the player at its controls when the scene starts).

## Hooks and modding

Hooks: `spaceship.board` and `spaceship.leave` (cancellable), `spaceship.fire` (mutable `damage`, `speed`; cancellable, per
shot), `spaceship.boost` (mutable `speed`; cancellable), `spaceship.collide` (mutable `damage`; cancellable, before the damage).
The `spaceships` registry and every setting above are moddable.

## When it does not do what you expect

- The guns are silent: neither `combat.projectiles` nor `combat.ranged` is installed (the log says so once).
- Nothing is piloted at the start: `playerShip` is empty or is not in the `spaceships` collection (a warning is logged once).
- A ship has no hull: `combat.core` is missing.
- An enemy ship does not move: its npc document must run `ship_attack` with a known `params.ship`.

## Limits

Simplified flight, not a physics simulation: the kit integrates motion and ray collisions itself and registers a kinematic box
body. It has no display module: the model comes from the engine and the assets.

## Versions

Kit version 1.0.0 (2026-10-22).