# world global

> The physical world of a running match, generated from the shipped declarations.

Generated from the declarations in `@disko-game/build/types`. `world` is
usable only while a match runs, between the `start` and `stop` events. See
[World & physics](/games/world-and-physics) for a guide.

## The `world` global

The physical world of the running match.

```ts
declare const world: Disko.World;
```

## World

### Disko.Filtered

Collision groups shared by every collidable object.

```ts
interface Filtered {
    addGroup(group: string): void;
    removeGroup(group: string): void;
    setAcceptedGroups(groups: readonly string[]): void;
}
```

| Member | Description |
| --- | --- |
| `setAcceptedGroups()` | Only objects in one of these groups collide with this one. |

### Disko.Collidable

Shared collision settings.

```ts
interface Collidable extends Filtered {
    setRestitution(value: number): void;
    setSensor(sensor: boolean): void;
}
```

### Disko.CollisionState

Collision properties of contact geometry, as read by `state()`.

```ts
interface CollisionState {
    readonly restitution: number;
    readonly groups: readonly string[];
    readonly acceptedGroups: readonly string[];
    readonly sensor: boolean;
}
```

| Member | Description |
| --- | --- |
| `groups` | Sorted memberships. |
| `acceptedGroups` | Sorted accepted groups. |

### Disko.DiscState

A disc's state at the current tick.

```ts
interface DiscState {
    readonly kind: "disc";
    readonly position: Vector;
    readonly velocity: Vector;
    readonly gravity: Vector;
    readonly radius: number;
    readonly inverseMass: number;
    readonly damping: number;
    readonly collision: CollisionState;
}
```

| Member | Description |
| --- | --- |
| `velocity` | Per-tick displacement. |
| `gravity` | Per-tick acceleration. |
| `inverseMass` | Reciprocal mass; zero is immune to contact response. |

### Disko.PlaneState

A plane's state.

```ts
interface PlaneState {
    readonly kind: "plane";
    readonly normal: Vector;
    readonly distance: number;
    readonly collision: CollisionState;
}
```

| Member | Description |
| --- | --- |
| `normal` | Normalized inward direction. |

### Disko.VertexState

A vertex's state.

```ts
interface VertexState {
    readonly kind: "vertex";
    readonly position: Vector;
    readonly collision: CollisionState;
}
```

### Disko.SegmentState

A segment's state. `start` and `end` are the vertices' engine handles.

```ts
interface SegmentState {
    readonly kind: "segment";
    readonly start: number;
    readonly end: number;
    readonly curve: number | null;
    readonly bias: number;
    readonly collision: CollisionState;
}
```

| Member | Description |
| --- | --- |
| `curve` | Curve factor, or `null` for a straight segment. |

### Disko.JointState

A joint's state. `first` and `second` are the discs' engine handles.

```ts
interface JointState {
    readonly kind: "joint";
    readonly first: number;
    readonly second: number;
    readonly distance: {
        readonly kind: "exact";
        readonly value: number;
    } | {
        readonly kind: "range";
        readonly min: number;
        readonly max: number;
    };
    readonly strength: {
        readonly kind: "rigid";
    } | {
        readonly kind: "finite";
        readonly value: number;
    };
}
```

### Disko.CrossingState

A crossing's state.

```ts
interface CrossingState {
    readonly kind: "crossing";
    readonly start: Vector;
    readonly end: Vector;
    readonly groups: readonly string[];
    readonly acceptedGroups: readonly string[];
}
```

| Member | Description |
| --- | --- |
| `groups` | Sorted memberships. |
| `acceptedGroups` | Sorted accepted groups. |

### Disko.PhysicalState

The physical state of an object at the current tick.

```ts
type PhysicalState = DiscState | PlaneState | VertexState | SegmentState | JointState | CrossingState;
```

### Disko.DiscAppearance

Paint of a disc. Colors are `#rrggbb` or `#rrggbbaa`.

```ts
interface DiscAppearance {
    readonly fill: string;
    readonly stroke: string;
    readonly strokeWidth: number;
}
```

| Member | Description |
| --- | --- |
| `strokeWidth` | Outline width in CSS pixels, 0 to 64; zero hides it. |

### Disko.Disc

A physical disc.

```ts
interface Disc extends Collidable {
    readonly kind: "disc";
    state(): DiscState;
    setVelocity(velocity: Vector): void;
    setPosition(position: Vector): void;
    setGravity(gravity: Vector): void;
    setDamping(damping: number): void;
    setMass(mass: number): void;
    setInverseMass(inverseMass: number): void;
    setRadius(radius: number): void;
    setAvatar(avatar: string | PackageAsset | null): void;
    setAppearance(appearance: DiscAppearance): void;
    setLayer(layer: string): void;
    setRotation(radians: number): void;
    setAngularVelocity(radiansPerTick: number): void;
}
```

### Disko.Plane

An infinite collision plane.

```ts
interface Plane extends Collidable {
    readonly kind: "plane";
    state(): PlaneState;
    setNormal(normal: Vector): void;
    setDistance(distance: number): void;
}
```

### Disko.Vertex

A fixed collision point, also the endpoint of segments.

```ts
interface Vertex extends Collidable {
    readonly kind: "vertex";
    state(): VertexState;
    setPosition(position: Vector): void;
}
```

### Disko.Segment

A straight or curved segment between two vertices.

```ts
interface Segment extends Collidable {
    readonly kind: "segment";
    readonly start: Vertex;
    readonly end: Vertex;
    state(): SegmentState;
    setCurve(curve?: number | null): void;
    setBias(bias: number): void;
}
```

| Member | Description |
| --- | --- |
| `setCurve()` | Curvature in radians; `null` for a straight segment. |

### Disko.Joint

A distance constraint between two discs.

```ts
interface Joint {
    readonly kind: "joint";
    readonly first: Disc;
    readonly second: Disc;
    state(): JointState;
    setDistance(distance: number | {
        readonly min: number;
        readonly max: number;
    }): void;
    setStrength(strength: number | "rigid"): void;
}
```

### Disko.Crossing

A line that reports discs crossing it (`crossing` events).

```ts
interface Crossing extends Filtered {
    readonly kind: "crossing";
    state(): CrossingState;
}
```

### Disko.PhysicalObject

Any physical object.

```ts
type PhysicalObject = Disc | Plane | Vertex | Segment | Joint | Crossing;
```

### Disko.DiscOptions

```ts
interface DiscOptions {
    readonly x?: number;
    readonly y?: number;
    readonly radius?: number;
    readonly velocityX?: number;
    readonly velocityY?: number;
    readonly gravity?: Vector;
    readonly mass?: number;
    readonly damping?: number;
    readonly groups?: readonly string[];
    readonly sensor?: boolean;
}
```

### Disko.PlaneOptions

```ts
interface PlaneOptions {
    readonly normal?: Vector;
    readonly distance?: number;
    readonly restitution?: number;
    readonly groups?: readonly string[];
    readonly sensor?: boolean;
}
```

### Disko.VertexOptions

```ts
interface VertexOptions {
    readonly x?: number;
    readonly y?: number;
    readonly restitution?: number;
    readonly groups?: readonly string[];
    readonly sensor?: boolean;
}
```

### Disko.SegmentOptions

```ts
interface SegmentOptions {
    readonly start: Vertex;
    readonly end: Vertex;
    readonly curve?: number | null;
    readonly bias?: number;
    readonly restitution?: number;
    readonly groups?: readonly string[];
    readonly sensor?: boolean;
}
```

### Disko.JointOptions

```ts
interface JointOptions {
    readonly first: Disc;
    readonly second: Disc;
    readonly distance?: number | {
        readonly min: number;
        readonly max: number;
    };
    readonly strength?: number | "rigid";
}
```

### Disko.CrossingOptions

```ts
interface CrossingOptions {
    readonly start: Vector;
    readonly end: Vector;
    readonly groups?: readonly string[];
}
```

| Member | Description |
| --- | --- |
| `groups` | Named memberships, in addition to the default membership. |

### Disko.VisualAnchor

Where a world visual is drawn.

```ts
type VisualAnchor = {
    readonly body: Disc;
    readonly offset?: Vector;
} | {
    readonly position: Vector;
};
```

### Disko.VisualAudience

Which players see a world visual. Exclusions take precedence.

```ts
interface VisualAudience {
    readonly include?: readonly Player[];
    readonly exclude?: readonly Player[];
}
```

| Member | Description |
| --- | --- |
| `include` | Omitted: everyone; empty: nobody. |

### Disko.TextVisualAppearance

Upright centered text, outlined for readability.

```ts
interface TextVisualAppearance {
    readonly type: "text";
    readonly text: string;
    readonly size: number;
    readonly sizing?: "world" | "screen";
    readonly color: string;
}
```

| Member | Description |
| --- | --- |
| `text` | At most 256 UTF-8 bytes; no control characters. |
| `sizing` | `world` (default) follows camera zoom; `screen` is CSS pixels. |
| `color` | `#rrggbb` or `#rrggbbaa`. |

### Disko.RingVisualAppearance

A circular stroke, without collisions.

```ts
interface RingVisualAppearance {
    readonly type: "ring";
    readonly radius: number | {
        readonly bodyRadius: true;
        readonly gap: number;
    };
    readonly width: number;
    readonly color: string;
}
```

| Member | Description |
| --- | --- |
| `radius` | A fixed radius, or the anchor body's radius plus a gap. |
| `width` | Stroke width in world units. |
| `color` | `#rrggbb` or `#rrggbbaa`. |

### Disko.VisualAppearance

```ts
type VisualAppearance = TextVisualAppearance | RingVisualAppearance;
```

### Disko.VisualOptions

```ts
interface VisualOptions {
    readonly anchor: VisualAnchor;
    readonly appearance: VisualAppearance;
    readonly layer?: string;
    readonly order?: "behind-body" | "above-body";
    readonly audience?: VisualAudience;
}
```

| Member | Description |
| --- | --- |
| `layer` | Named rendering layer; exclusive with `order`. |
| `order` | Relative to the anchor body; attached visuals default to above it. |

### Disko.VisualPatch

A change to a world visual. An appearance of the same `type` is merged into the current one; a different `type` replaces it.

```ts
interface VisualPatch {
    readonly anchor?: VisualAnchor;
    readonly appearance?: Partial<TextVisualAppearance> | Partial<RingVisualAppearance>;
    readonly layer?: string;
    readonly order?: "behind-body" | "above-body";
    readonly audience?: VisualAudience;
}
```

### Disko.Visual

A non-physical world visual, such as a name label or a ring.

```ts
interface Visual {
    update(patch: VisualPatch): void;
    destroy(): void;
}
```

### Disko.World

The physical world of the running match. Only usable between `start` and `stop`.

```ts
interface World {
    createDisc(options?: DiscOptions): Disc;
    createPlane(options?: PlaneOptions): Plane;
    createVertex(options?: VertexOptions): Vertex;
    createSegment(options: SegmentOptions): Segment;
    createJoint(options: JointOptions): Joint;
    crossing(options: CrossingOptions): Crossing;
    visual(options: VisualOptions): Visual;
    setLayerOrder(layers: readonly string[]): void;
    destroy(object: PhysicalObject): void;
}
```

| Member | Description |
| --- | --- |
| `setLayerOrder()` | Draw order of disc layers, back to front. |