This project uses Lens Studio. Scripts can be written in JavaScript (ES2021 compliant) or TypeScript.
This file gives you the minimum to be productive. For the full agent workflow, install the Lens Studio agent toolkit.
You can verify the toolkit is available by checking whether lens-studio-router exists in the project.
When you need multiple skills, invoke them in a single message — sequential loading adds minutes of dead time.
Never use curl, fetch, wget, HTTP POST, or any direct HTTP/REST call to interact with Lens Studio. Always use the Lens Studio MCP tools provided in your tool list — refer to them by bare name (e.g. the ExecuteEditorCode and scene-graphql tools). Your runtime exposes them under its own prefix: Claude Code as mcp__lens-studio__<Tool> (deferred — load the schema with ToolSearch before first use), Codex as mcp__lens_studio.<Tool>, Cursor under its own namespace (both surfaced directly). If an MCP tool fails or is genuinely unavailable, stop and report the error to the user — do not work around it with raw HTTP requests to the Lens Studio MCP server or any other endpoint. The MCP tools handle authentication, serialization, and error handling; bypassing them causes silent failures.
- The global execution context is the
scriptobject in JavaScript, orthisin TypeScript components. - UI inputs are defined using comment-based decorators (
// @input) in JavaScript, or@inputdecorators in TypeScript. - Do not use
windowordocumentobjects; this is a unique runtime, not a browser. - All components must extend
BaseScriptComponentin TypeScript. - Lens Studio uses a right-handed coordinate system: +X is right, +Y is up, -Z is forward.
- World units are in centimeters (cm). Rotation uses degrees in the Editor API but radians at runtime.
- Always work with files inside the
Assets/directory — this is where all project resources live. - Never modify files in
Cache/— it contains auto-generated data regenerated by Lens Studio. ReadingCache/TypeScript/Src/Packagesis useful for package TypeScript source and type references.
ProjectName/
├── Project.esproj
│ Main project manifest. Update through Lens Studio tools; do not hand-edit unless explicitly asked.
├── Assets/
│ Primary workspace for scripts, prefabs, materials, textures, and other user-authored assets.
├── Cache/
│ Generated by Lens Studio. Do not modify. Read `Cache/TypeScript/Src/Packages` only when you need package source or type references.
├── Support/
│ Generated TypeScript definitions. Read these for Lens API and Editor API references; do not commit generated changes.
├── PluginsUserPreferences/
│ Local plugin settings. Ignore unless the user is debugging plugin configuration.
└── Workspaces/
Local editor workspace state. Ignore.
Lens Studio runs scripts by Scene Hierarchy order: scripts on SceneObjects higher in the hierarchy run before those lower down. Keep shared helpers such as managers near the top when other scripts depend on their initialization.
At Lens start, developer-subscribable script events run around internal engine phases in this order: OnAwakeEvent, OnStartEvent, UpdateEvent, physics update, animation update, then LateUpdateEvent. Subscribe scripts to OnAwakeEvent, OnStartEvent, UpdateEvent, or LateUpdateEvent; physics update and animation update are engine phases, not events to bind directly. UpdateEvent and LateUpdateEvent repeat each frame; use LateUpdateEvent for work that must run after normal updates, physics, and animation.
Runtime-created scripts, such as components added with createComponent or objects created with ObjectPrefab.instantiate, run their startup lifecycle inline at the point they are created. OnEnableEvent runs only when a SceneObject is enabled by hand or code, not during normal initialization; OnDisableEvent runs only when disabled, not when destroyed. OnDestroyEvent runs immediately after destroy() is called.
Lens Studio also uses Scene Hierarchy order for rendering: SceneObjects higher in the hierarchy render first, and lower siblings render later/on top. Use hierarchy order, Render Targets, or Screen Texture to build custom compositing flows; Lens Studio uses forward rendering only.
The Lens API (StudioLib.d.ts) and the Editor API (editor.d.ts) are completely separate APIs:
| Lens API | Editor API | |
|---|---|---|
| Purpose | Build AR experiences (Lens scripts) | Control the Lens Studio application |
| Language | TypeScript or JavaScript | TypeScript (via ExecuteEditorCode) |
| Runtime | Inside the Lens | Inside the editor |
| Example | mat.mainPass.baseColor |
PassInfo property access |
Do not mix them — property names and access patterns differ. When a task needs to inspect or modify Lens Studio editor state, run Editor API code through ExecuteEditorCode/RunEditorCode; first verify each call against the Support/editor.d.ts type definitions.
When positioning objects relative to each other:
- Introspect first — read positions and scales of existing objects before placing new ones.
- Calculate offsets — account for object radii (scale/2) plus buffer to avoid overlap.
- Never default to (0,0,0) — always calculate positions relative to existing objects.
The Preview Panel shows live runtime transforms; the Scene Panel shows authored editor transforms. Runtime script, tracking, interaction, or parent changes can move objects in Preview without updating Scene values, so distinguish runtime positions from scene positions when debugging placement.
- Keep the user oriented. Before long scripts or batches of tool calls, say what you're about to do, then add brief status updates between longer sequences so the session does not feel stuck.
Verify assumptions early — a quick prototype can save hours of debugging a plan built on wrong foundations. Build incrementally: confirm each layer renders before adding the next.