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.

Turn it on #

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:

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 #

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).