# Runek

> Runek is a source registry of procedural 3D components for React Three Fiber ("shadcn for 3D worlds"). You pull a component's TypeScript source into your project with the CLI and own it. Every component builds its geometry from props plus a `seed`, with no binary assets, so a whole walkable world is plain JSON data.

- Install source with `npx @runek/cli add <name>` (`init` once first). Components import the small runtime, `@runek/core` (the `<World>` provider, seeded rng, world data), from npm.
- A world is JSON: `{ "version": 1, "nodes": [{ "type": "Bench", "props": { "position": [0, 0, 0] } }] }`. `type` is the PascalCase component name; every prop goes under `props`.
- Same `seed`, same geometry, everywhere. Units are meters, Y is up, rotations are radians.
- Check a world with `npx @runek/cli validate world.json` (names, props, values) and `npx @runek/cli check-world world.json` (things buried in or floating above the ground).
- Coding agents: start with [Runek for agents](https://runek.nullorder.org/docs/for-agents.md).

## Docs

- [What is Runek?](https://runek.nullorder.org/docs/what-is-runek.md): A source registry of procedural 3D components for React Three Fiber — shadcn for 3D worlds.
- [Getting started](https://runek.nullorder.org/docs/getting-started.md): Pull components into your project with the CLI and compose your first walkable world.
- [The workshop](https://runek.nullorder.org/docs/the-workshop.md): Build a world in your browser, tune every prop, edit it as JSON or live TSX, put one component in the lab, and share it all as a link.
- [The World provider](https://runek.nullorder.org/docs/the-world-provider.md): <World> sets up the canvas, lighting, physics, and controls — every component lives inside it.
- [Runek for agents](https://runek.nullorder.org/docs/for-agents.md): The fast path for a coding agent: find components, install them, write a world as JSON, check it, and preview it.
- [The component contract](https://runek.nullorder.org/docs/the-component-contract.md): Every Runek component is a pure, deterministic function of its props — here are the rules.
- [Seeded determinism](https://runek.nullorder.org/docs/seeded-determinism.md): Same seed → same world, on every machine and every render. The seeded RNG and its helpers.
- [Units & colliders](https://runek.nullorder.org/docs/units-and-colliders.md): One unit is one meter; colliders track gameplay surface, not visual detail.
- [The building kit](https://runek.nullorder.org/docs/building-kit.md): Compose buildings from parts — walls with openings, slabs with stairwells, stackable levels — and ship arrangements as composites.
- [Worlds as data](https://runek.nullorder.org/docs/worlds-as-data.md): Because every component is a pure function of props, a whole world serializes to plain JSON.
- [Placing things on uneven ground](https://runek.nullorder.org/docs/placing-things-on-uneven-ground.md): 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](https://runek.nullorder.org/docs/embedding-a-world.md): 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](https://runek.nullorder.org/docs/world-to-world-travel.md): 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.
- [CLI reference](https://runek.nullorder.org/docs/cli.md): runek init / add / list / info / validate / check-world / preview / skill: pull editable component source into your project and check your worlds.

## Components

- [Player (`player`, character)](https://runek.nullorder.org/docs/components/player.md): 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 (`portal`, systems)](https://runek.nullorder.org/docs/components/portal.md): 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.
- [Compass (`compass`, systems)](https://runek.nullorder.org/docs/components/compass.md): 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).
- [Terrain (`terrain`, terrain)](https://runek.nullorder.org/docs/components/terrain.md): 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`).
- [Room (`room`, structures)](https://runek.nullorder.org/docs/components/room.md): Composite: four walls and a floor with a doorway, arranged from one Level. Unpack to customize.
- [House (`house`, structures)](https://runek.nullorder.org/docs/components/house.md): Composite: a two-level dwelling arranged from parts (Levels, Door, Windows, Staircase, gable Roof, Plant). Unpack to customize.
- [Hut (`hut`, structures)](https://runek.nullorder.org/docs/components/hut.md): A round hut: a post-ribbed wall on a stone base, a framed doorway and window, under a shaggy thatch cone; one cylinder collider.
- [Wall (`wall`, structures)](https://runek.nullorder.org/docs/components/wall.md): Wall segment with door/window openings and a fixed collider.
- [Floor (`floor`, structures)](https://runek.nullorder.org/docs/components/floor.md): Flat floor slab with a fixed collider; optional stairwell opening.
- [CurvedWall (`curvedwall`, structures)](https://runek.nullorder.org/docs/components/curvedwall.md): 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.
- [Slab (`slab`, structures)](https://runek.nullorder.org/docs/components/slab.md): 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.
- [Level (`level`, structures)](https://runek.nullorder.org/docs/components/level.md): 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.
- [Roof (`roof`, structures)](https://runek.nullorder.org/docs/components/roof.md): Flat or gable roof.
- [Door (`door`, structures)](https://runek.nullorder.org/docs/components/door.md): Door panel within a frame.
- [Window (`window`, structures)](https://runek.nullorder.org/docs/components/window.md): Window with frame and translucent pane.
- [Staircase (`staircase`, structures)](https://runek.nullorder.org/docs/components/staircase.md): Stepped staircase with per-step colliders.
- [Stool (`stool`, interiors)](https://runek.nullorder.org/docs/components/stool.md): A round bar stool: a disc seat on three splayed legs; a thin cylinder collider.
- [Table (`table`, interiors)](https://runek.nullorder.org/docs/components/table.md): Table with a top on four legs, or on pedestals with rounded ends for a conference table.
- [Tent (`tent`, structures)](https://runek.nullorder.org/docs/components/tent.md): An A-frame ridge tent: striped wind-rippled fabric, entrance flaps pinned open, guy ropes and stakes; solid sides and back, open front.
- [Chair (`chair`, interiors)](https://runek.nullorder.org/docs/components/chair.md): Chair with seat, back, and legs.
- [Counter (`counter`, interiors)](https://runek.nullorder.org/docs/components/counter.md): 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.
- [Clock (`clock`, interiors)](https://runek.nullorder.org/docs/components/clock.md): Procedural analog wall clock; hands track the system clock or a given IANA timezone.
- [Sign (`sign`, interiors)](https://runek.nullorder.org/docs/components/sign.md): In-world text rendered in a world font (the one font-using component); falls back to the default bundled in @runek/core.
- [Signpost (`signpost`, structures)](https://runek.nullorder.org/docs/components/signpost.md): 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.
- [Lamp (`lamp`, interiors)](https://runek.nullorder.org/docs/components/lamp.md): Lamp that emits a point light.
- [Rug (`rug`, interiors)](https://runek.nullorder.org/docs/components/rug.md): Procedural striped rug (seeded stripes, no textures).
- [Shelf (`shelf`, interiors)](https://runek.nullorder.org/docs/components/shelf.md): Wall shelf with planks.
- [Bookshelf (`bookshelf`, interiors)](https://runek.nullorder.org/docs/components/bookshelf.md): Procedurally generated bookshelf with seeded books and one cuboid collider.
- [Book (`book`, interiors)](https://runek.nullorder.org/docs/components/book.md): A single procedural book — standing, lying, or open — with a seeded cover and optional click interaction; the standalone sibling of Bookshelf's instanced spines.
- [Lake (`lake`, water)](https://runek.nullorder.org/docs/components/lake.md): Procedural animated-shader water surface (no textures); place its surface at or below ground level.
- [Pool (`pool`, water)](https://runek.nullorder.org/docs/components/pool.md): A built swimming pool flush with the deck: coping rim, walkable plastered basin with corner exit steps, and a translucent water surface.
- [Ocean (`ocean`, water)](https://runek.nullorder.org/docs/components/ocean.md): Camera-following animated-shader ocean that reaches the world fog horizon (no textures); sits at the world ground.
- [Shore (`shore`, water)](https://runek.nullorder.org/docs/components/shore.md): Sloped beach/shore strip to meet a Lake.
- [Sailboat (`sailboat`, water)](https://runek.nullorder.org/docs/components/sailboat.md): A small procedural sailboat: a station-built low-poly hull, mast, boom, and mainsail, floating at the waterline with a gentle moored bob.
- [Rocks (`rocks`, environment)](https://runek.nullorder.org/docs/components/rocks.md): Faceted rocks with convex-hull colliders (seeded scatter).
- [Cliff (`cliff`, terrain)](https://runek.nullorder.org/docs/components/cliff.md): A rocky promontory: a low-poly, seed-jittered truncated cone with a flattish plateau and a convex-hull collider.
- [Sky (`sky`, environment)](https://runek.nullorder.org/docs/components/sky.md): Procedural atmosphere (drei Sky).
- [Grass (`grass`, environment)](https://runek.nullorder.org/docs/components/grass.md): Instanced grass blades (seeded scatter).
- [Trees (`trees`, vegetation)](https://runek.nullorder.org/docs/components/trees.md): L-system trees grown by a 3D turtle, deterministic from seed.
- [Palm (`palm`, vegetation)](https://runek.nullorder.org/docs/components/palm.md): A coconut palm: leaning bowed trunk and a crown of drooping instanced fronds, deterministic from seed.
- [LightRig (`lightrig`, systems)](https://runek.nullorder.org/docs/components/lightrig.md): Sun + hemisphere/ground fill with shadow configuration.
- [Fence (`fence`, structures)](https://runek.nullorder.org/docs/components/fence.md): Posts and rails with seeded weathering; encloses yards and paths. One footprint collider.
- [Flag (`flag`, structures)](https://runek.nullorder.org/docs/components/flag.md): A cloth flag on a pole; the cloth ripples per-frame, pinned at the luff. Thin pole collider.
- [Bridge (`bridge`, structures)](https://runek.nullorder.org/docs/components/bridge.md): Plank deck spanning a gap, optionally arched, with railings and slab colliders that follow the deck.
- [Arch (`arch`, structures)](https://runek.nullorder.org/docs/components/arch.md): Freestanding gateway: two piers and a semicircular arch of voussoirs. Composes with Wall.
- [Pillar (`pillar`, structures)](https://runek.nullorder.org/docs/components/pillar.md): Column with a plinth, a tapered (optionally fluted) shaft, and a capital.
- [Well (`well`, structures)](https://runek.nullorder.org/docs/components/well.md): Stone well with a dark pool, posts, a little pyramid roof, and a bucket on a rope.
- [Windmill (`windmill`, structures)](https://runek.nullorder.org/docs/components/windmill.md): A tapered tower with a conical cap and four sails that turn each frame; tower collider, seeded blade phase.
- [Dock (`dock`, structures)](https://runek.nullorder.org/docs/components/dock.md): A plank jetty on pilings reaching out over water; walkable deck colliders, side stringers, and seaward mooring posts.
- [Path (`path`, terrain)](https://runek.nullorder.org/docs/components/path.md): A meandering ribbon trail from seeded waypoints; decorative, laid just over the ground.
- [Road (`road`, structures)](https://runek.nullorder.org/docs/components/road.md): A paved street: a flat stone deck with low kerbs, draped on the ground like Path; decorative (no collider).
- [Bush (`bush`, vegetation)](https://runek.nullorder.org/docs/components/bush.md): Clustered foliage blobs, seeded; the mid-height density between Grass and Trees.
- [Flowers (`flowers`, vegetation)](https://runek.nullorder.org/docs/components/flowers.md): Instanced seeded wildflowers (stem + colored head) scattered over a patch.
- [Hedge (`hedge`, vegetation)](https://runek.nullorder.org/docs/components/hedge.md): A trimmed green wall with seeded surface tufts; blocks like a Wall.
- [Fountain (`fountain`, water)](https://runek.nullorder.org/docs/components/fountain.md): Two-tier stone fountain with gently rippling water (a per-frame bob, no textures).
- [Bench (`bench`, interiors)](https://runek.nullorder.org/docs/components/bench.md): Slatted bench with an optional backrest; indoor or outdoor seating.
- [Bed (`bed`, interiors)](https://runek.nullorder.org/docs/components/bed.md): Bed with a frame, mattress, pillows, and a headboard.
- [Desk (`desk`, interiors)](https://runek.nullorder.org/docs/components/desk.md): 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.
- [Monitor (`monitor`, interiors)](https://runek.nullorder.org/docs/components/monitor.md): 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.
- [Sofa (`sofa`, interiors)](https://runek.nullorder.org/docs/components/sofa.md): 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.
- [OfficeChair (`officechair`, interiors)](https://runek.nullorder.org/docs/components/officechair.md): 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.
- [Tv (`tv`, interiors)](https://runek.nullorder.org/docs/components/tv.md): 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.
- [Whiteboard (`whiteboard`, interiors)](https://runek.nullorder.org/docs/components/whiteboard.md): A whiteboard on a rolling stand or a wall, with seeded marker diagrams (boxes, arrows, lines of writing) and optional text across the top.
- [Fridge (`fridge`, interiors)](https://runek.nullorder.org/docs/components/fridge.md): A kitchen fridge with a top or bottom freezer or one tall door, bar handles, and a seeded enamel or steel finish.
- [CoffeeMachine (`coffeemachine`, interiors)](https://runek.nullorder.org/docs/components/coffeemachine.md): A countertop coffee machine, espresso or drip, with a cup or carafe and a few puffs of steam. Sits on a Counter.
- [ArcadeCabinet (`arcadecabinet`, interiors)](https://runek.nullorder.org/docs/components/arcadecabinet.md): An upright arcade cabinet cut to the classic profile, with a lit marquee, joystick and buttons, and a screen running a seeded pixel game.
- [PoolTable (`pooltable`, interiors)](https://runek.nullorder.org/docs/components/pooltable.md): A pool table with rails, cushions, six pockets, and sixteen instanced balls, racked or scattered mid-game.
- [Crate (`crate`, interiors)](https://runek.nullorder.org/docs/components/crate.md): Slatted wooden crate with seeded plank shades; stacks via a cuboid collider.
- [Barrel (`barrel`, interiors)](https://runek.nullorder.org/docs/components/barrel.md): Staved barrel bellied at the middle, banded by metal hoops; convex-hull collider.
- [Plant (`plant`, interiors)](https://runek.nullorder.org/docs/components/plant.md): Potted plant: a tapered planter and a seeded cluster of foliage.
- [Clouds (`clouds`, environment)](https://runek.nullorder.org/docs/components/clouds.md): Drifting clouds built from clustered soft blobs (no textures); layer above a Sky.
- [Campfire (`campfire`, environment)](https://runek.nullorder.org/docs/components/campfire.md): Stone ring, a tepee of logs, and an animated flame with a warm flickering light.
- [Birds (`birds`, environment)](https://runek.nullorder.org/docs/components/birds.md): A loose flock circling overhead, each bird flapping on its own seeded orbit.
- [Interactable (`interactable`, systems)](https://runek.nullorder.org/docs/components/interactable.md): 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.
- [Person (`person`, character)](https://runek.nullorder.org/docs/components/person.md): 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.

## Machine-readable

- [Registry index](https://runek.nullorder.org/r/registry.json): every component name, title, category, and description
- [Prop schema](https://runek.nullorder.org/r/props.json): every prop of every component, with types, defaults, and docs, keyed by world-data `type`
- [World JSON Schema](https://runek.nullorder.org/r/world.schema.json): set it as `"$schema"` in a world file for validation and completion
- [Component manifest](https://runek.nullorder.org/r/components/bench.json): one per component at `/r/components/<name>.json`: inlined source plus dependencies
- [Agent skill](https://runek.nullorder.org/r/agents/SKILL.md): a ready-made skill for coding agents (`npx @runek/cli skill` installs it)
- [Full docs in one file](https://runek.nullorder.org/llms-full.txt)

## Optional

- [Changelog](https://runek.nullorder.org/docs/changelog.md): every release and the unreleased changes