# Mounts (mount.ride)

## What it is for

Adds rideable creatures: a mount is a document with walk, trot and gallop speeds, turning, stamina, jump and saddlebags; the player walks up to ride, dismounts with the same key and whistles to call it.

It needs `input.actions`, `character.control`, `physics.port`, `game.engine`; installing it brings them in.

## Turn it on

Install the kit in a project, then change a setting (the values shown are its defaults):

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "mount.ride" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "mount.ride",
                              config: { "reach": 3, "rideLabel": "Ride {name}" } }
```

## First example

The kit has no dedicated test yet; this installs it and sets two of its settings to their defaults.

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "mount.ride" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "mount.ride",
                              config: { "reach": 3, "rideLabel": "Ride {name}" } }
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `reach` | number | `3` | 1–10 | How close the player stands to ride (interaction prompt and mount(entity)). |
| `rideLabel` | string | `"Ride {name}"` |  | Prompt on a mount; {name} is its name. |
| `callRange` | number | `80` | 0–1000 | A mount within this distance walks to the player when called; further away it appears behind the player (0: never appears, only… |
| `recoverRatio` | number | `0.3` | 0–1 | An exhausted mount gallops again once its stamina is back to this share of the maximum. |
| `gravity` | number | `20` | 1–60 | Fall acceleration while riding (m/s²). |
| `bagsLabel` | string | `"Saddlebags"` |  | Name of the saddlebag container (storage.containers). |
| `arriveDistance` | number | `2.5` | 0.5–50 | A called mount stops this far from the player. |
| `appearDistance` | number | `6` | 1–100 | How far behind the player a mount called from beyond callRange appears. |
| `dismountSide` | number | `1.3` | 0–5 | How far to the left of the mount the rider stands after getting off. |
| `reverseRatio` | number | `0.6` | 0–1 | Backing speed as a share of the walk speed. |

## Services, events, variables

- Service `mount.ride`: mounts(), riding() → view|null, mount(entity), dismount(), call(entity?), gait(), stamina(entity?), owned(), spawn(mount, at, opts?), bags(entity?), openBags(), gallop(on) → held from a button as the sprint key.
- Events emitted:
  - `mount.mounted` (`entity`, `mount`, `rider`)
  - `mount.dismounted` (`entity`, `mount`, `rider`)
  - `mount.gait` (`entity`, `gait`)
  - `mount.jumped` (`entity`)
  - `mount.exhausted` (`entity`) — The gallop emptied the stamina: trot only until recoverRatio is back.
  - `mount.recovered` (`entity`)
  - `mount.called` (`entity`, `distance`, `teleported`)
  - `mount.arrived` (`entity`)
  - `mount.refused` (`entity`, `mount`, `rider`, `decision`, `reason`) — A tap of one of the kit's hooks cancelled a decision (never emitted without a tap).
- Events listened to: `interaction.requested`, `entity.spawned`
- Variables:
  - `mount.riding` (boolean) — Riding
  - `mount.name` (string) — Mount name
  - `mount.gait` (string) — Mount gait
  - `mount.stamina` (number) — Mount stamina
  - `mount.stamina.max` (number) — Mount stamina maximum
  - `mount.speed` (number) — Mount speed
- Verbs of the scripting layer:
  - `spawn_mount` (action) — Stand a mount in the world (default: beside the player).
  - `dismount` (action) — The player gets off the mount.
  - `is_riding` (condition) — The player rides (a mount of that document when given).
- Input actions: `mount_call`

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `mount.mount` (cancellable) — The player is about to get on the mount entity (document mount), in reach and free; owned says it is already the player's.
  - `mount.dismount` (cancellable) — The rider is about to get off (the interact key when it is pressed, the dismount action, dismount()); gait and speed are the mount's now.
  - `mount.jump` (fields a tap may change: `speed`, `cost`; cancellable) — The ridden mount is about to jump (the jump key was pressed, it stands on the ground and has the stamina of its document): speed is the take-off speed in m/s, cost the stamina spent.
  - `mount.gallop` (cancellable) — The ridden mount is about to break into a gallop (sprint held, not exhausted).
  - `mount.call` (fields a tap may change: `teleport`; cancellable) — The player calls the mount entity, distance metres away.
- Moddable settings: `reach`, `rideLabel`, `callRange`, `recoverRatio`, `gravity`, `bagsLabel`, `arriveDistance`, `appearDistance`, `dismountSide`, `reverseRatio`
- Moddable collections: `mounts`
- Components: `mount`

## Engines

Declared targets: `web`, `rust`. `gripforge kit api mount.ride` lists the exact settings and services of your version.

## Versions

Kit version 1.3.0.