# Network physics: shared deterministic simulation (net.physics)

## What it is for

Shares one deterministic rigid-body simulation between the server and every client, with boxes, spheres, capsules, ground, gravity, collisions, forces and impulses that run identically everywhere.

It needs `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: "net.physics" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "net.physics",
                              config: { "gravity": [0, -9.81, 0], "ground": true } }
```

## First example

<!-- test: kits/net_physics/tests/net_physics.rs::the_options_are_handed_over_as_given -->
This is the body of the passing test `the_options_are_handed_over_as_given`; the helper functions it calls are defined at the top of the same test file.

```rust
#[test]
fn the_options_are_handed_over_as_given() {
    let mut s = world(
        json!({"gravity": [0, -3.7, 0], "ground": false, "groundY": -2, "hz": 60, "iterations": 8, "worldLimit": 500}),
    );
    assert_eq!(
        config_of(&mut s).unwrap(),
        json!({"gravity": [0, -3.7, 0], "ground": false, "groundY": -2, "hz": 60, "iterations": 8, "worldLimit": 500})
    );
}
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `gravity` | array | `[0, -9.81, 0]` |  | Gravity (m/s², canonical space: +Y up). |
| `ground` | boolean | `true` |  | A static ground plane at groundY. |
| `groundY` | number | `0` | -100000–100000 | Height of the ground plane (m). |
| `groundHalfExtent` | number | `10000` | 1–100000 | Half-size of the ground box (m). |
| `groundThickness` | number | `1` | 0.01–100 | Thickness of the ground box under groundY (m). |
| `groundFriction` | number | `0.5` | 0–100 | Friction coefficient of the ground. |
| `hz` |  | `0` |  | Fixed simulation rate (Hz). |
| `iterations` | integer | `4` | 1–64 | Solver iterations per step. |
| `worldLimit` | number | `100000` | 1–100000 | Bodies placed beyond ±worldLimit m are refused (the protocol ceiling is 100000 m: f32 keeps centimetres there). |
| `maxSpeed` | number | `10000` | 1–10000 | Bodies given a linear or angular speed beyond this (m/s, rad/s) are refused (protocol ceiling 10000). |
| `bodies` | array | `[]` |  | Initial bodies of the shared world (server side for claim / authoritative; every peer for rollback, ids from 108: the physics… |

## Services, events, variables

- Service `net.physics`: Deterministic shared rigid-body world of the network core (sync `physics: shared`).
- Events emitted:
  - `net.contact` (`a`, `b`, `impulse`) — Two bodies touched during the last step (web runtime, opt-in).
- Variables:
  - `net.physics.bodies` (number) — Shared bodies

## Hooks and modding

This kit declares no hook and no collection to mod.

## Engines

Declared targets: `web`, `godot`, `unity`, `unreal`. `gripforge kit api net.physics` lists the exact settings and services of your version.

## Versions

Kit version 1.1.0.