# Apricot

> Apricot is a 3D engine for Expo apps on iOS and Android: declarative React components for scenes, shapes, models, cameras, lights and motion, rendered with WebGPU.

Apricot is in preview: the API can still change, and the packages (`@apricot/react`, `@apricot/assets`, `@apricot/core`, `@apricot/metro`) are not on npm yet.
Every page below is Markdown. Read "Building with AI" first: it lists the rules that keep generated code correct.

## Getting started

- [Introduction](https://matthiasbrandolin.dev/apricot.md): Apricot is a 3D engine for Expo apps on iOS and Android. You describe a scene with React components; Apricot renders it with WebGPU and keeps it fast on real phones.
- [Installation](https://matthiasbrandolin.dev/apricot/installation.md): Add Apricot to an Expo app. You need a development build, the WebGPU and Reanimated peer libraries, the Apricot config plugin, and one line in metro.config.js.
- [Quick start](https://matthiasbrandolin.dev/apricot/quick-start.md): Build a first Apricot scene step by step, a product card you can tap and swipe, and learn the four ideas you will use everywhere.
- [Building with AI](https://matthiasbrandolin.dev/apricot/ai.md): How to give an AI assistant the Apricot docs, and the rules it must follow to write correct Apricot code on the first try. Paste this page into any assistant before asking it to build a scene.

## Core concepts

- [Scenes](https://matthiasbrandolin.dev/apricot/concepts/scenes.md): What a Scene is, how it starts, when it renders and when it sleeps, which props are fixed at mount, and how to use it as a full screen, a card or a transparent overlay.
- [Coordinates and units](https://matthiasbrandolin.dev/apricot/concepts/coordinates.md): Which way is up, where the camera starts, which values are radians and which are degrees, and the units of every number Apricot takes.
- [Animation and shared values](https://matthiasbrandolin.dev/apricot/concepts/animation.md): The four ways to animate in Apricot (props, shared values, useFrame and behaviors), which props accept Reanimated shared values, and how the render loop stays asleep when nothing moves.
- [Objects, groups and refs](https://matthiasbrandolin.dev/apricot/concepts/objects.md): How the scene tree works, what a SceneObject ref gives you, how groups combine transforms, and who owns and frees geometry and materials.
- [Performance](https://matthiasbrandolin.dev/apricot/concepts/performance.md): The rules that keep Apricot scenes at 60–120 fps on mid-range phones, the costs behind them, and how to measure a scene with the debug HUD and performance report.

## Guides

- [Shapes and materials](https://matthiasbrandolin.dev/apricot/guides/shapes-and-materials.md): Draw boxes, spheres, cylinders and other shapes, dress them in one of 16 physical material presets, animate colours, add images and engraving, and define presets of your own.
- [Lighting, environments and shadows](https://matthiasbrandolin.dev/apricot/guides/lighting.md): Light a scene with a look preset, add procedural reflections with an environment, place your own lights, run a day–night cycle, and turn on shadows and fog.
- [Camera](https://matthiasbrandolin.dev/apricot/guides/camera.md): Frame a subject at any screen size, fly between named views, let users orbit and pinch-zoom, keep the subject clear of your UI, and follow moving objects.
- [Gestures and interaction](https://matthiasbrandolin.dev/apricot/guides/interaction.md): Tap objects, model parts and individual copies; drive the scene from gestures with shared values; build custom drags; and combine scenes with buttons, scroll views and overlays.
- [Loading models](https://matthiasbrandolin.dev/apricot/guides/models.md): Show a .glb model, prepare it with the apricot-models CLI, name its parts once with a model kit, then repaint parts, open doors and lids, play Blender animations and shape keys, and react to taps on parts.
- [Textures](https://matthiasbrandolin.dev/apricot/guides/textures.md): Load PNG and JPEG images as textures with useTexture, use them as colour images or engraving masks, and choose the right options for colour images, masks and repeating patterns.
- [Instances](https://matthiasbrandolin.dev/apricot/guides/instances.md): Draw hundreds or thousands of copies of a shape or model in one draw call each, give every copy its own place, colour and visibility, tell which copy was tapped, and animate copies without React renders.
- [Falling objects](https://matthiasbrandolin.dev/apricot/guides/falling-objects.md): Drop apples, coins or any mesh from above the screen with Pile, let them bounce and heap up at the bottom, mix kinds, tune the physics, replay the drop and stop rendering when everything rests.
- [Vehicles](https://matthiasbrandolin.dev/apricot/guides/vehicles.md): Drive a toy car on the ground plane with throttle and steering from a joystick, keys or code; use the built-in Car or your own .glb with named wheels; chase it with FollowCamera; read its position and speed.
- [Paths, trips and labels](https://matthiasbrandolin.dev/apricot/guides/paths-and-labels.md): Build smooth paths through points, move objects and multi-car trains along them, run timetabled trips that brake into stops and wait, show a live status line, and pin React Native views to points in the scene.
- [Out-of-focus backgrounds](https://matthiasbrandolin.dev/apricot/guides/blur.md): Draw objects softly behind the rest of the scene, as if out of focus, with Blur. A cheap depth-of-field look for hero screens, with falling objects behind a sharp product.
- [Custom geometry and behaviors](https://matthiasbrandolin.dev/apricot/guides/custom.md): Go beyond the built-in pieces. Write reusable per-frame behaviors with defineBehavior, draw your own three.js geometry with Mesh, bake multi-part objects into one draw call, add existing three.js objects, register material presets and studios, and build your own scene components.

## Recipes

- [Recipe: swipe to spin](https://matthiasbrandolin.dev/apricot/recipes/swipe-to-spin.md): Copy-paste hook that spins any object at a resting speed and lets the user fling it faster with a horizontal swipe that coasts and slows down, all on the UI thread.
- [Recipe: falling pile](https://matthiasbrandolin.dev/apricot/recipes/falling-pile.md): Copy-paste component that drops 3D objects over any existing screen for a few seconds and piles them up at the bottom, while the screen below stays fully interactive.
- [Recipe: drive with a joystick](https://matthiasbrandolin.dev/apricot/recipes/drive-joystick.md): Copy-paste on-screen thumbstick that writes throttle and steering into shared values on the UI thread, wired to a Vehicle and a chase camera.
- [Recipe: card tilt](https://matthiasbrandolin.dev/apricot/recipes/card-tilt.md): Copy-paste hook for a metal payment card that turns with a finger, flips on a fling, and leans with the phone's tilt sensor so its reflections move. Seven finishes and an engraved art mask.

## API reference

- [Scene](https://matthiasbrandolin.dev/apricot/reference/scene.md): Reference for <Scene>: every prop with its type and default, the looks and environments, fog and shadow options, loading and lifecycle callbacks, and the ApricotScene object returned by useScene.
- [Objects and shapes](https://matthiasbrandolin.dev/apricot/reference/objects.md): Reference for the built-in shapes (Box, Sphere, Cylinder, Cone, Plane, Torus, Capsule), Mesh, Group and Primitive: every prop, default and orientation, the shared shape props, transform props, SceneObject refs and the Vec3 type.
- [Materials](https://matthiasbrandolin.dev/apricot/reference/materials.md): Reference for materials: all 16 built-in presets with colour, roughness and metalness, the MaterialInput and MaterialOptions types, engraving, definePreset and PresetSpec, useMaterial, useMaterialInput, useMaterialOverrides, createMaterial and PresetMaterial.
- [Lights and environments](https://matthiasbrandolin.dev/apricot/reference/lights.md): Reference for AmbientLight, HemisphereLight, DirectionalLight, PointLight, SpotLight, Environment, defineEnvironment, the built-in studios, SoftBox and StudioOptions, Daylight with its DAY keys, and per-object shadow control.
- [Cameras](https://matthiasbrandolin.dev/apricot/reference/cameras.md): Reference for FitCamera, CameraRig (views, orbit, inset, follow, drift, flyTo and jumpTo), FollowCamera, CAMERA_VIEWS and the CameraView, OrbitOptions, Inset and FollowOptions types.
- [Model](https://matthiasbrandolin.dev/apricot/reference/model.md): Reference for @apricot/react/model: the Model component and every prop, defineModelKit, part selectors, JointPart and InlineJoint, ClipInput, PartPressEvent, useModel, useTexture, useTextureState, TextureOptions, loadModelBytes and the model and texture caches.
- [Motion](https://matthiasbrandolin.dev/apricot/reference/motion.md): Reference for everything that moves objects: Spin, defineBehavior, Vehicle with VehicleOptions and VehicleState, Pile with its physics options, usePath and Path, useTrip and TripHandle, useTripStatus, TripState and FollowPath.
- [Instances](https://matthiasbrandolin.dev/apricot/reference/instances.md): Reference for <Instances>: every prop, the InstanceItem fields, the three ways to give the shape, InstancePressEvent, the InstancesHandle ref for per-frame updates, materials and shadows.
- [Labels and blur](https://matthiasbrandolin.dev/apricot/reference/labels-and-blur.md): Reference for Label (React Native views pinned to points in the scene) and Blur (out-of-focus background layer): every prop and default, and how they behave.
- [Hooks](https://matthiasbrandolin.dev/apricot/reference/hooks.md): Reference for every Apricot hook: useScene, useFrame, useAnimatable, useSceneTouches, useParent, useAttach, useTransform, plus the material, model, texture, path and trip hooks, and the diagnostics helpers. Where each must be called and what it returns.
- [Assets](https://matthiasbrandolin.dev/apricot/reference/assets.md): Reference for @apricot/assets: ready-made objects (Apple, Peach, Coin, MoneyStack, Car, Card, Trees, Ground, ContactShadow, Backdrop, StudioFloor) with every prop and default, their factory functions, and constants such as CARD_SIZE, CARD_FINISHES, CAR_DIMENSIONS and WHEEL_NAMES.
- [Core utilities](https://matthiasbrandolin.dev/apricot/reference/core.md): Reference for @apricot/core: the framework-free engine under @apricot/react. Utilities apps use (seededRandom, disposeObject, mergeColoredParts, setShadow, visibleBox, fitCamera), the classes behind the components, and the @apricot/core/models entry point.
- [Tooling](https://matthiasbrandolin.dev/apricot/reference/tooling.md): Reference for the build-side pieces: the @apricot/react Expo config plugin, withApricot for Metro, and the apricot-models CLI (optimise and inspect .glb files) with its budgets and Node API.

## Help

- [Troubleshooting](https://matthiasbrandolin.dev/apricot/troubleshooting.md): Fixes for common Apricot problems, from setup (Expo Go, minSdk, simulators, Metro) to blank or slow scenes, models that fail to load, objects too small or missing, scenes that do not update, gestures inside scroll views, and every error message Apricot throws.

## Optional

- [All docs in one file](https://matthiasbrandolin.dev/apricot/llms-full.txt): every page above, concatenated.