Reference

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 for a guide.

The `world` global

The physical world of the running match.

declare const world: Disko.World;

World

Disko.Filtered

Collision groups shared by every collidable object.

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.

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

Disko.CollisionState

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

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.

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.

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.

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.

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.

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.

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.

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

Disko.DiscAppearance

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

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.

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.

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.

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

Disko.Segment

A straight or curved segment between two vertices.

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.

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

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

Disko.PhysicalObject

Any physical object.

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

Disko.DiscOptions

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

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

Disko.VertexOptions

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

Disko.SegmentOptions

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

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

Disko.CrossingOptions

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.

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

Disko.VisualAudience

Which players see a world visual. Exclusions take precedence.

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.

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.

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

type VisualAppearance = TextVisualAppearance | RingVisualAppearance;

Disko.VisualOptions

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.

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.

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

Disko.World

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

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.

The world global