Documentation

Compose, walk, and edit procedural 3D worlds in React Three Fiber.

⌖ Explore the library in 3D →

intro

  • What is Runek? — A source registry of procedural 3D components for React Three Fiber — shadcn for 3D worlds.

guide

  • Getting started — Pull components into your project with the CLI and compose your first walkable world.
  • The World provider — <World> sets up the canvas, lighting, physics, and controls — every component lives inside it.
  • The component contract — Every Runek component is a pure, deterministic function of its props — here are the rules.
  • Seeded determinism — Same seed → same world, on every machine and every render. The seeded RNG and its helpers.
  • Units & colliders — One unit is one meter; colliders track gameplay surface, not visual detail.
  • The building kit — Compose buildings from parts — walls with openings, slabs with stairwells, stackable levels — and ship arrangements as composites.
  • Worlds as data — Because every component is a pure function of props, a whole world serializes to plain JSON.
  • World-to-world travel — Portal is a sensor gate that fires when the avatar (or a vehicle) walks through it — wire it to swap worlds, change levels, or teleport.

component

  • Arch — Freestanding gateway: two piers and a semicircular arch of voussoirs. Composes with Wall.
  • Barrel — Staved barrel bellied at the middle, banded by metal hoops; convex-hull collider.
  • Bed — Bed with a frame, mattress, pillows, and a headboard.
  • Bench — Slatted bench with an optional backrest; indoor or outdoor seating.
  • Birds — A loose flock circling overhead, each bird flapping on its own seeded orbit.
  • Book — A single procedural book — standing, lying, or open — with a seeded cover and optional click interaction; the standalone sibling of Bookshelf's instanced spines.
  • Bookshelf — Procedurally generated bookshelf with seeded books and one cuboid collider.
  • Bridge — Plank deck spanning a gap, optionally arched, with railings and slab colliders that follow the deck.
  • Bush — Clustered foliage blobs, seeded; the mid-height density between Grass and Trees.
  • Campfire — Stone ring, a tepee of logs, and an animated flame with a warm flickering light.
  • Chair — Chair with seat, back, and legs.
  • Cliff — A rocky promontory: a low-poly, seed-jittered truncated cone with a flattish plateau and a convex-hull collider.
  • Clock — Procedural analog wall clock; hands track the system clock or a given IANA timezone.
  • Clouds — Drifting clouds built from clustered soft blobs (no textures); layer above a Sky.
  • Compass — A screen-fixed HUD compass: a glassy dial in a corner of the canvas whose rose card swings with the camera heading, with a fixed lubber line and an optional wind + bearing readout — works with any traversal that drives the camera (on foot or at a vehicle's chase-cam).
  • Counter — A service / bar counter: a solid body under a worktop that overhangs the front; one cuboid collider.
  • Crate — Slatted wooden crate with seeded plank shades; stacks via a cuboid collider.
  • Dock — A plank jetty on pilings reaching out over water; walkable deck colliders, side stringers, and seaward mooring posts.
  • Door — Door panel within a frame.
  • Fence — Posts and rails with seeded weathering; encloses yards and paths. One footprint collider.
  • Flag — A cloth flag on a pole; the cloth ripples per-frame, pinned at the luff. Thin pole collider.
  • Floor — Flat floor slab with a fixed collider; optional stairwell opening.
  • Flowers — Instanced seeded wildflowers (stem + colored head) scattered over a patch.
  • Fountain — Two-tier stone fountain with gently rippling water (a per-frame bob, no textures).
  • Grass — Instanced grass blades (seeded scatter).
  • Hedge — A trimmed green wall with seeded surface tufts; blocks like a Wall.
  • House — Composite: a two-level dwelling arranged from parts (Levels, Door, Windows, Staircase, gable Roof, Plant). Unpack to customize.
  • Hut — A round hut: a post-ribbed wall on a stone base, a framed doorway and window, under a shaggy thatch cone; one cylinder collider.
  • Lake — Procedural animated-shader water surface (no textures); place its surface at or below ground level.
  • Lamp — Lamp that emits a point light.
  • Level — A stackable wall ring plus optional slab: per-side openings, sides that can be omitted, and a stairwell hole — the unit a building is composed from.
  • LightRig — Sun + hemisphere/ground fill with shadow configuration.
  • Ocean — Camera-following animated-shader ocean that reaches the world fog horizon (no textures); sits at the world ground.
  • Path — A meandering ribbon trail from seeded waypoints; decorative, laid just over the ground.
  • Pillar — Column with a plinth, a tapered (optionally fluted) shaft, and a capital.
  • Plant — Potted plant: a tapered planter and a seeded cluster of foliage.
  • Player — First/third-person character controller (ecctrl wrapper). WASD moves; mouse-drag or the arrow keys steer the camera in either view. Reads the world's `avatar` setting for its default view and the world's `controls` for key bindings.
  • Portal — A travel gate: a glowing sensor ring that fires onEnter (or navigates to a destination) when the avatar or a vehicle passes through — for world-to-world travel, level transitions, and teleports.
  • Road — A paved street: a flat stone deck with low kerbs, draped on the ground like Path; decorative (no collider).
  • Rocks — Faceted rocks with convex-hull colliders (seeded scatter).
  • Roof — Flat or gable roof.
  • Room — Composite: four walls and a floor with a doorway, arranged from one Level. Unpack to customize.
  • Rug — Procedural striped rug (seeded stripes, no textures).
  • Sailboat — A small procedural sailboat: a station-built low-poly hull, mast, boom, and mainsail, floating at the waterline with a gentle moored bob.
  • Shelf — Wall shelf with planks.
  • Shore — Sloped beach/shore strip to meet a Lake.
  • Sign — In-world text rendered in a world font (the one font-using component); falls back to the default bundled in @runek/core.
  • Signpost — A wooden post-and-plank signboard carrying a name in the world's display font; the post sits behind the board so the text reads clean.
  • Sky — Procedural atmosphere (drei Sky).
  • Staircase — Stepped staircase with per-step colliders.
  • Stool — A round bar stool: a disc seat on three splayed legs; a thin cylinder collider.
  • Table — Table with a top and four legs.
  • Tent — An A-frame ridge tent: striped wind-rippled fabric, entrance flaps pinned open, guy ropes and stakes; solid sides and back, open front.
  • Terrain — Procedural fbm-displaced ground with a matching trimesh collider, a flat build-pad option, and an optional radial island falloff.
  • Trees — L-system trees grown by a 3D turtle, deterministic from seed.
  • Wall — Wall segment with door/window openings and a fixed collider.
  • Well — Stone well with a dark pool, posts, a little pyramid roof, and a bucket on a rope.
  • Windmill — A tapered tower with a conical cap and four sails that turn each frame; tower collider, seeded blade phase.
  • Window — Window with frame and translucent pane.

reference

  • CLI reference — runek init / add / list — pull editable component source into your project.
  • Changelog — Every published release and the unreleased changes on main.