Phaser home
Log inCreate a game

← Expansion packsArcade

Phaser AE

Torus land

Pro packv3.0.0-03DArcade

A wrapping heightfield world over a sea: the land meets itself at every seam, so a flyer that keeps going comes back round. It is generated from a seed, queried by your rules, reshaped while the game runs, and drawn by the terrain renderer from the very same heights.

This is a Pro pack. Upgrade to Phaser Pro to use it in your games.See Phaser Pro →

Released October 19, 2026

Torus land: a screenshot of its demo
A note about these graphics

Expansion packs don't come with graphics. This screenshot is one way of drawing what the pack does, made for its demo: none of the sprites, tiles or backgrounds in it are in the pack.

That's by design. A pack is a game's logic, mechanics and effects, and it works with whatever art you give it. Some packs draw effects, backdrops or 3D scenes of their own, but none carries a game's sprites.

So the look is yours. Make the art on phaser.io, bring your own, or let your agent draw it in code: the same pack can look like anything.

The pack

torusLand

function torusLand(): Pack<{ torusLand: typeof api }>

Install the torus-land API (game.torusLand).

Helpers

advanceShaping

function advanceShaping(list: Shaping[], land: Land, dt: number): Shaping[]

Advance every shaping by dt, applying its change to the land; returns those still running.

LAND_SHAPES

const LAND_SHAPES: readonly LandShape[]

Built-in landform generators, all periodic over the torus.

landShapeFn

function landShapeFn(shape: LandShape, seed: number, size: number, featureSize: number): (x: number, z: number) => number

A periodic landform function for a shape: world x/z in, a normalised 0..1 height out. cells lattice cells span the world (rounded from the feature size), which is the noise's period, so the land meets itself at the seam.

shapingField

function shapingField(s: Shaping, t: number, dx: number, dz: number): number

The displacement a shaping has made by time t at an offset from its centre. Quake: rolling waves that heave the ground up and down while it lasts and leave it permanently broken into ridges and hollows. Volcano: a cone that grows from the ground with a crater in its top. Raise: a smooth mound (or a hollow when amount is negative).

Classes

Land

class Land

The land: heights, sea, queries and live reshaping.

  • readonly field: Heightfield — The heights (shared with the renderer by reference).
  • readonly size: number — World units a side (the torus period).
  • readonly cell: number — World units per grid cell.
  • readonly cells: number — Grid cells a side.
  • readonly sea: number — The sea's level (world y).
  • readonly floor: number — Lowest a sample may be pushed (the sea bed floor).
  • readonly ceiling: number — Highest a sample may be pushed.
  • constructor(def: LandDef)
  • delta(a: number, b: number): number — The torus offset from a to b on one axis (shortest way round).
  • wrap(v: number): number — A coordinate brought into [-size/2, size/2).
  • distance(ax: number, az: number, bx: number, bz: number): number — Horizontal distance across the torus.
  • heightAt(x: number, z: number): number — The land's height (the sea bed under water).
  • groundAt(x: number, z: number): number — What a flyer or a walker meets: the land, or the sea's surface over water.
  • isWater(x: number, z: number): boolean — Is this point over water.
  • relief(x: number, z: number, radius: number): number — Relief (max - min height) over a square footprint of radius, sampled at cell spacing; Infinity over water.
  • normalAt(x: number, z: number): { x: number; y: number; z: number } — The surface normal (for tilting things that stand on it).
  • edit(edits: readonly TerrainEdit[]): void — Apply terrain-3d brush edits (raise, flatten, landform...) at world points; heights stay inside floor..ceiling.
  • displace(x: number, z: number, radius: number, fn: (dx: number, dz: number) => number): void — Add a displacement field over a disc: fn(dx, dz) returns the change at an offset from the centre (world units). Used for the time-varying spells (an earthquake's heave, a volcano's cone growing).
  • each(x: number, z: number, radius: number, visit: (index: number, dx: number, dz: number) => void): void — Visit every grid sample within radius of a point (wrapped), with its offset from the point.
  • mark(minX: number, minZ: number, maxX: number, maxZ: number): void — Record a changed region for the renderer.
  • takeDirty(): DirtyRect[] — The regions changed since the last call (merged per step by the caller).
  • heights(): Float32Array — The heights, for a snapshot.
  • setHeights(h: Float32Array): void — Restore heights from a snapshot (marks the whole world dirty).

Types

DirtyRect

interface DirtyRect

A world rectangle whose heights changed (it may run past the edge of the torus; it wraps).

  • minX: number — Left edge in world x; may be below -size/2, in which case the region wraps.
  • minZ: number — Near edge in world z; may be below -size/2, in which case the region wraps.
  • maxX: number — Right edge in world x; may pass size/2, in which case the region wraps.
  • maxZ: number — Far edge in world z; may pass size/2, in which case the region wraps.

LandDef

interface LandDef

How a world's land is made.

  • cells: number — Grid cells (tiles) a side; the world is a torus this many tiles round.
  • cell: number — World units per tile.
  • sea?: number — The sea's level (world y). Default 0.
  • height: number — How high the highest land stands above the sea (world units).
  • seaDepth?: number — How deep the sea bed falls below the sea (world units). Default 0.35 x height.
  • featureSize?: number — World units per large landform feature (rounded so a whole number tile the torus). Default size / 6.
  • landFraction?: number — The fraction of the world that stands above the sea, 0..1. Default 0.45.
  • shape?: LandShape | ((x: number, z: number) => number) — A built-in landform or your own periodic function (x, z) -> 0..1 that repeats every cells * cell.
  • seed: number — The landform seed.

LandShape

type LandShape = "archipelago" | "continent" | "highlands" | "lagoon" | "flat"

A built-in landform (all tile the torus).

Shaping

interface Shaping

A land-shaping effect in progress.

  • kind: "quake" | "volcano" | "raise" | "crater" — Which effect: 'quake' heaves and cracks a belt, 'volcano' grows a cone, 'raise' lifts or lowers a disc, 'crater' digs a bowl.
  • x: number — World x of the centre, in world units.
  • z: number — World z of the centre, in world units.
  • radius: number — Radius of the affected disc (world units); for a quake, the half-width of its belt.
  • dirX: number — A quake's line: unit direction and length (world units), centred on x/z. 0 for a disc.
  • dirZ: number — A quake's belt direction, z component of a unit vector; 0 for a disc.
  • length: number — A quake belt's length in world units, centred on x/z; 0 for a disc.
  • t: number — Seconds since it began.
  • duration: number — How long it lasts (seconds).
  • amount: number — Peak height change (world units; negative lowers for raise).
  • seed: number — Noise seed (the quake's cracks).
  • owner: number — Who cast it (an owner id), or -1.