# Vehicle doors (vehicle.doors)

Part of the vehicle family: see the [vehicles guide](guide:vehicles) for the cars themselves.

## What it is for

Opens and closes the doors of a car one by one, smoothly and reversibly. The kit keeps the state of each door (`Door_FL`, `Door_FR`, `Door_RL`, `Door_RR`) on the vehicle, moves it to its target in `duration` seconds and saves it. The model of the car turns on its hinges, the parts named `gf_door`; without them the state still runs and nothing moves. It does not cut a fused mesh, and the character animation of getting in belongs to `vehicle.enter_exit`.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "vehicle.doors" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "vehicle.doors",
                              config: { "duration": 0.6, "hold": 0.8, "driverDoor": "Door_FL" } }
```

It requires `vehicle.drive` (installed with `vehicle.driveable`) and `game.engine`, and works with `vehicle.enter_exit` and a vehicle model prepared with door hinges.

## First example

<!-- test: kits/game_engine/host/tests/vehicle_doors.rs::a_door_opens_in_duration_and_only_on_a_vehicle -->
With `{ "duration": 0.5 }`, `set(vehicle, "Door_FL", true)` answers `true` on a vehicle and `false` on a non-vehicle entity or on an unknown door such as `Trunk`. The door reaches its target half a second later: `vehicle.door.changed` is emitted with `{ vehicle, door: "Door_FL", open: true }` and `state(vehicle)` reads `{ Door_FL: { amount: 1, target: 1, hold: null } }`.

## Settings and defaults

| Setting | Default | Meaning |
|---|---|---|
| `duration` | 0.7 | Seconds for a door to swing fully open or closed, 0.15 to 3 |
| `hold` | 0.5 | Seconds a cycled door stays open before closing by itself, 0 to 5 |
| `autoOnEnterExit` | `true` | Cycle the driver door when a character enters or leaves without the door sequence of `vehicle.enter_exit` |
| `driverDoor` | `Door_FL` | The driver door: `Door_FL` or `Door_FR` |

## Services, events, hooks

- `vehicle.doors` (service): `set(vehicle, door, open, by?)` opens or closes a door and returns `false` for an unknown door, a non-vehicle or a refusal; `cycle(vehicle, door?, by?)` opens, holds and closes (the driver door by default); `state(vehicle)` returns `{ <door>: { amount, target, hold } }`, `amount` going from 0 to 1.
- `vehicle.door.changed` (event): a door reached its target, `{ vehicle, door, open }`.
- `vehicle.door.refused` (event): a tap of the hook cancelled a change, `{ vehicle, door, open, reason }`. Never emitted without a tap.
- Listens to `vehicle.entered`, `vehicle.exited` and `entity.despawned` (the state of a removed car is forgotten).
- `vehicle.door` (hook): payload `{ vehicle, door, open, cycle, hold, by }`; `hold` is mutable (0 to 5) and the hook is cancellable. It runs once when a change is requested (`set`, `cycle`, the verb, the automatic cycle), never while the door moves and not for the closing that ends a cycle. Cancelled: the door keeps its state and the request answers `false`.

In game.engine content, an archetype of a car can carry the component `doors`: `{ "open": ["Door_FL"] }` for the doors standing open when it appears (scene data, not asked to the hook). The verb `set_door` opens or closes one: `{ "set_door": { "instance": "car_1", "door": "Door_FL", "open": true } }` (`open` defaults to `true`). The state of an instance is mirrored as `door_fl`, `door_fr`, `door_rl` and `door_rr`.

## Hooks and modding

```json
{ "id": "locked", "hook": "vehicle.door", "match": { "vehicle": "e12", "open": true }, "cancel": true, "reason": "locked" }
```

A mod can override every setting. With `vehicle.enter_exit`, a door refused at the start of a sequenced entry sends the character back on foot.

## Engines

The same rules, events and save run on the web and in the native player, and in Godot, Unity and Unreal, which turn the `gf_door` hinges of the imported model natively (with an optional physics hinge). No hinge: the state only.

## When it does not do what you expect

| Symptom | Cause and fix |
|---|---|
| The door does not move on screen | the model has no `gf_door` parts (the state still runs); use a model prepared with hinges |
| `set` answers `false` | the entity is not a vehicle, the door name is not one of the four, or a tap of `vehicle.door` refused |
| The driver door does not open on entry | `autoOnEnterExit` is `false`, or the entry is sequenced by `vehicle.enter_exit` |

## Limits

No door collision and no sliding doors. A fused car body cannot be split by this kit.

## Versions

Kit 1.3.0: the hook `vehicle.door` and moddable settings; 1.2.0 added the `doors` component and the verb `set_door`.