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 workshop — Build a world in your browser, tune every prop, edit it as JSON or live TSX, put one component in the lab, customise a person in the avatar studio, and share it all as a link.
  • The World provider — <World> sets up the canvas, lighting, physics, and controls — every component lives inside it.
  • Runek for agents — The fast path for a coding agent: find components, install them, write a world as JSON, check it, and preview 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.
  • Placing things on uneven ground — Anchor nodes to the terrain, drop them in the editor, and catch buried or floating props with runek check-world.
  • Embedding a world in an app — Host a world beside ordinary UI, in a browser or a desktop webview. Content security policy, lazy loading, input that yields to the page, pausing, and figures driven by app state.
  • 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

  • ArcadeCabinet — An upright arcade cabinet cut to the classic profile, with a lit marquee, joystick and buttons, and a screen running a pixel game laid out from the seed: invaders, falling blocks, a maze, a snake, or a paddle duel.
  • 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.
  • CeilingLight — A ceiling fitting hanging from its origin: a flush dome, a pendant shade on a cord, or an aimed spot can. Can light only after dusk.
  • Chair — Chair with seat, back, and legs.
  • Chandelier — A hanging chandelier: a chain, a turned brass body, one or two rings of curved arms with candle bulbs, and optional glass drops. Instanced, with one shared light; can light only after dusk.
  • ChessBoard — A chess board with a full set of turned pieces, set from a FEN position or played out from the seed into a mid-game, on a table top or its own pedestal.
  • 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.
  • CoffeeMachine — A countertop coffee machine, espresso or drip, with a cup or carafe and a few puffs of steam. Sits on a Counter.
  • 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. With hob, a kitchen stove: a glass cooktop and an oven door.
  • Crate — Slatted wooden crate with seeded plank shades; stacks via a cuboid collider.
  • CurvedWall — An arc of wall around the origin — solid concrete or a floor-to-ceiling glass curtain wall with mullions. Compose several arcs to leave door gaps; chords carry cuboid colliders.
  • Desk — A work desk: a top over slim legs, a drawer pedestal, or side panels, with a modesty panel at the back. Base and drawers seeded, each pinnable. One cuboid collider.
  • DeskLamp — A banker's desk lamp: a brass base and stem under a cased glass shade with a pull chain, pooling light on the desk. Can light only after dusk.
  • 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).
  • Fridge — A kitchen fridge with a top or bottom freezer or one tall door, bar handles, and a seeded enamel or steel finish.
  • GameConsole — A games console (tower, slab, or cube) with up to four controllers laid out in front, to sit under a TV.
  • 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.
  • Interactable — Wrap anything to make it something the player can act on: walk within range and a prompt shows its actions with the keys the world binds to them; press one and onAction gets its id. Only the nearest in range takes the key, and keys yield to text fields.
  • 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.
  • Monitor — A desk monitor on a foot, plate, or legs. Switched on, the screen glows in its own color with a few seeded windows and lines of text on it, all geometry, or shows a texture the app hands it.
  • Ocean — Camera-following animated-shader ocean that reaches the world fog horizon (no textures); sits at the world ground.
  • OfficeChair — A swivel office chair: five-star base on casters, gas column, padded seat, low or high back, optional arms. Seats a Person in sit or type pose.
  • Palm — A coconut palm: leaning bowed trunk and a full crown of feathery fronds, young ones standing up and old ones arching down, deterministic from seed.
  • Path — A meandering ribbon trail from seeded waypoints; decorative, laid just over the ground.
  • Person — A sculpted, clothed, skinned figure generated from a seed: one continuous body with a sculpted face, lidded eyes that follow you, and hands with fingers, in three style templates (stylized by default, realistic, anime). Every part is configurable as plain JSON: the body (build, tone, height), the face (eyes, brows, nose, lips, blush), hair, and clothing as ordered layers (shirts, sweaters, vests, coats, dresses, robes, trousers, jeans, skirts, shoes, boots, belts, scarves, capes) that fit any body. Role presets, swappable cosmetic skins, hats and accessories, poses, idle breathing and blinking. Give it a patrol or a wander radius and it walks: a route that is a pure function of the clock, following the ground, with a walk cycle and a step aside for the player and other walkers. A route with a departure time is a one-way trip (to a desk, to bed) that reports its arrival, and actions put a key prompt over it (Talk, Info) when the player comes near. Meshes build in the background, coarse first, with full detail near the camera. Place one at a spawn point, or use it as the Player's third-person body.
  • PictureLight — A brass picture light on one or two arms that washes the face below it: over a picture on a wall, or on the top of a bookshelf. Can light only after dusk.
  • 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.
  • Pool — A built swimming pool flush with the deck: coping rim, walkable plastered basin with corner exit steps, and a translucent water surface.
  • PoolTable — A pool table with rails, cushions, six pockets, and sixteen instanced balls, racked or scattered mid-game.
  • Portal — A travel gate: a glowing vortex around a dark core 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.
  • Poster — A wall print of seeded flat art (shapes, color bands, a retro sunset, mountain peaks) with an optional caption and a slim or wide frame.
  • Rift — A pair of linked rifts torn in the air, ragged and edged in iridescent, glitter-shedding light. Each shows the other end live and in parallax, and walking into either carries you to the other: walkable shortcuts within one world (use Portal for other worlds or pages).
  • 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.
  • Screen — A display of any size (a phone, a monitor, a TV, a digital frame, a billboard) on a wall, a stand, a desk foot, or in a frame. Shows a seeded picture or desktop, a text banner, animated static, or a color, or a texture the app hands it.
  • 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).
  • Slab — A rounded structural plate (pill or ellipse) for curved-modernist decks, cantilevered roofs, terraces, or a lawn disc. Walkable, with a single convex-hull collider.
  • Sofa — A sofa seating one to four: upholstered frame, seat and back cushions in soft shades of the fabric, square, rolled, or slim arms, pegs or a plinth, and throw pillows. Seeded, each choice pinnable.
  • Staircase — Stepped staircase with per-step colliders: solid (a built-in stair on a floor) or floating (thin treads on sloped stringers, open underneath, to span a void).
  • Stool — A round bar stool: a disc seat on three splayed legs; a thin cylinder collider.
  • Table — Table with a top on four legs, or on pedestals with rounded ends for a conference table.
  • TableTennis — A regulation table tennis table with its lines, a net, a folding undercarriage, and paddles and a ball left on it.
  • Tableware — Tableware to set a table: a plate, bowl, glass, cup, or water jug turned from a profile, or a whole place setting. Drinks fill to a line; plates and bowls stack.
  • 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. Its surface is queryable (`useGround`, anchors, `runek check-world`).
  • TikiTorch — A bamboo tiki torch with a woven head and a flickering flame and light, for a beach path or a garden. Can burn only after dusk.
  • Trees — L-system trees grown by a 3D turtle, deterministic from seed.
  • Tv — A flat-screen TV on a stand, a low media console, or a wall. Switched on, it shows a seeded picture (sky, sun, hills) drawn from flat shapes, or a texture the app hands it.
  • 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.
  • Whiteboard — A whiteboard on a rolling stand or a wall, with seeded marker diagrams (boxes, arrows, lines of writing) and optional text across the top.
  • 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 / info / validate / check-world / preview / skill: pull editable component source into your project and check your worlds.
  • Changelog — Every published release and the unreleased changes on main.