Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

lens-api

/lens-api

Pomaga pisać skrypty TypeScript dla Lens Studio: cykl życia komponentów, dekoratory, dotyk, konwersja ekranu na świat, tworzenie obiektów w czasie działania, klonowanie materiałów, zapytania o scenę i timery.

Repozytorium
ls-extensions ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
01.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
27
Skrypty
11
Komentarze HTML
1
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 01.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co sprawdzić przed instalacją
  • 11 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
  • SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.

Skrypty: resources/scripts/AccessComponentOnChildSceneObjectTS.ts, resources/scripts/AccessComponentOnSceneObjectTS.ts, resources/scripts/AccessCustomComponentsUsingRequiredTS.ts, resources/scripts/AccessCustomComponentsUsingTypenameTS.ts, resources/scripts/AccessJSfromTSwithDeclaration_JSComponentA_Declaration.ts, resources/scripts/AccessJSfromTSwithDeclaration_TSComponentB.ts, resources/scripts/AccessJSf

Co robi i kiedy

Pomaga pisać skrypty TypeScript dla Lens Studio: cykl życia komponentów, dekoratory, dotyk, konwersja ekranu na świat, tworzenie obiektów w czasie działania, klonowanie materiałów, zapytania o scenę i timery.

Oryginalny opis (EN)

Lens Studio TypeScript scripting — component lifecycle, decorators, touch input, screen-to-world conversion, runtime object creation, material cloning, scene queries, and timers. Use when writing any Lens Studio TypeScript script, handling tap/touch events, converting screen to world coordinates, creating objects at runtime, modifying material colors, or debugging null-reference errors in Lens scripts.

Jak działa

  1. Component Anatomy
  2. Decorator Reference
  3. Accessing Other Components
  4. Scene Object Queries
  5. Prefab Instantiation
  6. DelayedCallbackEvent (Timers)
  7. Logging
  8. Enabling / Disabling Scene Objects and Components
  9. Touch Input
  10. Runtime Object Creation
Sekcje z nagłówków SKILL.md, w oryginale · 366 linii, 2 008 słów
Podgląd SKILL.md
---
name: lens-api
description: Lens Studio TypeScript scripting — component lifecycle, decorators, touch input, screen-to-world conversion, runtime object creation, material cloning, scene queries, and timers. Use when writing any Lens Studio TypeScript script, handling tap/touch events, converting screen to world coordinates, creating objects at runtime, modifying material colors, or debugging null-reference errors in Lens scripts.
user-invocable: true
---
<!--
Copyright 2026 Specs Inc.
SPDX-License-Identifier: Apache-2.0
-->

> **LENS RUNTIME ONLY** — This skill covers the **Lens API** (StudioLib),
> which runs inside the AR experience. It is a completely different runtime
> from the **Editor API** (`editor.d.ts` / `pluginSystem`). Never mix them.

| Aspect | Lens API (this skill) | Editor API (`editor-api`) |
|---|---|---|
| Types file | `Support/StudioLib.d.ts` (public LS) or `Support/StudioLib_Internal.d.ts` (internal LS) | `Support/editor.d.ts` |
| Get position | `obj.getTransform().getLocalPosition()` | `obj.localTransform.position` |
| Set position | `obj.getTransform().setLocalPosition(new vec3(...))` | `obj.localTransform.position = new vec3(...)` |
| Get component | `obj.getComponent('Component.RenderMeshVisual')` | `obj.getComponent('RenderMeshVisual')` |
| Rotation | `quat` (radians) | `vec3` Euler in **degrees** |
| Create object | `global.scene.createSceneObject('name')` | `scene.createSceneObject(name)` or `objectOwner.addSceneObject(parent)` |

Mixing the two APIs produces code that compiles but silently fails at runtime — property names look similar but resolve to different things. For example, `obj.localTransform.position` (Editor API) and `obj.getTransform().getLocalPosition()` (Lens API) both access position, but using the wrong one in the wrong runtime returns undefined or throws.

This skill and its `references/` files are the primary source for the Lens runtime API. For specific type signatures not covered here, check the Lens API types file in the project's `Support/` directory — its filename depends on the LS edition: `StudioLib.d.ts` in public Lens Studio, `StudioLib_Internal.d.ts` in internal Lens Studio (some internal projects ship both). Discover it with `Glob pattern="**/Support/StudioLib*.d.ts"` rather than hardcoding either name. Read the matching reference file first (see table at bottom).

---

# Lens Studio Scripting — Reference Guide

---

## Component Anatomy

```typescript
import { SomeModule } from 'SpectaclesInteractionKit.lspkg/SomeModule'

@component
export class MyComponent extends BaseScriptComponent {
  // --- Inspector-exposed inputs ---
  @input
  @hint('Drag a scene object here')
  targetObject: SceneObject

  @input
  speed: number = 1.0

  @input
  @allowUndefined         // makes the field optional in the inspector
  optionalAudio: AudioComponent

  @input
  @label('Display Name') // rename the field label in the inspector
  internalProp: number = 0

  // --- Private state ---
  private elapsedTime: number = 0

  // --- Lifecycle ---
  onAwake(): void {
    // Called once at construction time. Set up events here.
    this.createEvent('OnStartEvent').bind(() => this.onStart())
    this.createEvent('UpdateEvent').bind(() => this.onUpdate())
  }

  private onStart(): void {
    // Called once the scene is fully loaded.
    // Reference other components here rather than in onAwake.
    if (!this.targetObject) {
      console.log('[MyComponent] ERROR: targetObject not assigned')
      return
    }
  }

  private onUpdate(): void {
    // Called every frame.
    this.elapsedTime += getDeltaTime()
  }

  onDestroy(): void {
    // Called when the scene object this component belongs to is destroyed.
    // Use to unsubscribe events, clean up sessions, etc.
  }
}
```

### Lifecycle order reference

| Event name | When it fires | Typical use |
|---|---|---|
| `onAwake` | Component constructs | Wire up event listeners |
| `OnStartEvent` | Scene finishes loading | Access other components |
| `UpdateEvent` | Every rendered frame | Per-frame logic |
| `DelayedCallbackEvent` | After N seconds | Timers, deferred actions |
| `OnEnableEvent` | Component or object becomes enabled | React to visibility on |
| `OnDisableEvent` | Component or object becomes disabled | React to visibility off |
| `TurnOnEvent` | Lens turns on (**deprecated** — use `OnStartEvent`) | Legacy lens-on handler |
| `TurnOffEvent` | Lens turns off | Legacy lens-off handler |
| `onDestroy` | Scene object is destroyed | Clean up resources |

---

## Decorator Reference

| Decorator | Effect |
|---|---|
| `@component` | Registers the class as a Lens Studio component |
| `@input` | Exposes the property in the Lens Studio Inspector |
| `@hint('text')` | Adds a tooltip to the inspector field |
| `@allowUndefined` | Prevents validation errors for optional inputs |
| `@label('Display Name')` | Renames the field label shown in the inspector |

### Input arrays

To expose a list of assets or objects in the inspector:

```typescript
@input
myObjects: SceneObject[]  // shown as a resizable list in the inspector

@input
audioTracks: AudioTrackAsset[]
```

---

## Accessing Other Components

For cross-component access patterns — `getComponent` on the same/child object, the TS-to-TS `@input` typed as the class (preferred, no cast), the `getComponent(X.getTypeName()) as X` lookup, TS-to-JS, and `require('LensStudio:...')` for built-in modules — see `references/component-access-patterns.md`.

---

## Scene Object Queries

```typescript
// Preferred: expose the object via @input and assign in the Inspector
// (no runtime name search needed)
@input
targetObject: SceneObject

// Manual recursive name search — there is no built-in findByName or findChild
function findByName(parent: SceneObject, name: string): SceneObject | null {
  if (parent.name === name) return parent
  const count = parent.getChildrenCount()
  for (let i = 0; i < count; i++) {
    const found = findByName(parent.getChild(i), name)
    if (found) return found
  }
  return null
}

// Search across all root objects
function findInScene(name: string): SceneObject | null {
  const rootCount = global.scene.getRootObjectsCount()
  for (let i = 0; i < rootCount; i++) {
    const found = findByName(global.scene.getRootObject(i), name)
    if (found) return found
  }
  return null
}

// Iterate all root objects
const rootCount = global.scene.getRootObjectsCount()
for (let i = 0; i < rootCount; i++) {
  const root = global.scene.getRootObject(i)
}

// Iterate children
const count = parent.getChildrenCount()
for (let i = 0; i < count; i++) {
  const child = parent.getChild(i)
}

// Create a new empty scene object
const newObj = global.scene.createSceneObject('NewObject')
newObj.setParent(this.sceneObject)
```

---

## Prefab Instantiation

- Synchronous: `const instance = this.prefab.instantiate(parent)` (`null` = root), then set `instance.name` / `instance.getTransform().setWorldPosition(...)`.
- Async (non-blocking, large prefabs): `instantiateAsync` **returns void — use the callback argument, NOT `.then()`**: `this.prefab.instantiateAsync(parent, (instance) => {...}, (err) => {...}, (_p) => {})`.
- Tear down with `instance.destroy()`.

For circle/line/grid/sphere spawn layouts, pooling, and delayed destruction, see `references/instantiation-patterns.md`.

---

## DelayedCallbackEvent (Timers)

```typescript
// One-shot delay
const delayedEvent = this.createEvent('DelayedCallbackEvent')
delayedEvent.bind(() => {
  console.log('2 seconds elapsed')
  doSomething()
})
delayedEvent.reset(2) // seconds

// Repeating timer: call reset() again at the end of the callback
delayedEvent.bind(() => {
  tick()
  delayedEvent.reset(1) // re-fire after 1 second
})
delayedEvent.reset(1)

// Cancel a scheduled event
delayedEvent.enabled = false
```

---

## Logging

Lens Studio exposes the standard `console` namespace (`declare namespace console` in the d.ts) with `.log`, `.info`, `.warn`, `.error`, `.debug`, and `.trace`. Use these for new code:

```typescript
console.log('Simple message: ' + value)
console.info(`Template literal: ${object.name}`)
console.warn('Recoverable issue: ' + reason)
console.error('Fatal issue: ' + err)
```

The legacy `print(message)` global still exists but carries no severity level — prefer `console.*` so the log can be filtered by level.

---

## Enabling / Disabling Scene Objects and Components

```typescript
// Show / hide a whole object and all its children
sceneObject.enabled = false

// Disable only a component without hiding the object
meshVisual.enabled = false

// Toggle
sceneObject.enabled = !sceneObject.enabled
```

`OnEnableEvent` fires when a component (or its scene object) becomes enabled; `OnDisableEvent` fires when it becomes disabled. Both fire on the component, not on children. Note: `TurnOnEvent`/`TurnOffEvent` are **Lens** lifecycle events (Lens turns on/off), not object enable/disable events — do not confuse them.

---

## Touch Input

### TapEvent (simplest — phone Lenses)

```typescript
this.createEvent('TapEvent').bind((eventData) => {
  // getTapPosition() returns NORMALIZED [0-1] coordinates, NOT pixels
  // (0,0) = top-left, (1,1) = bottom-right
  const tapPos: vec2 = eventData.getTapPosition()
  console.log('Tapped at: ' + tapPos.x + ', ' + tapPos.y)
})
```

### Screen-to-world conversion

Convert a normalized screen position to a 3D world point:

```typescript
// Screen [0-1] → World position (depth = distance from camera's near plane)
const worldPos: vec3 = camera.screenSpaceToWorldSpace(tapPos, depth)

// World → Screen [0-1]
const screenPos: vec2 = camera.worldSpaceToScreenSpace(worldPoint)
```

`getTapPosition()` and `screenSpaceToWorldSpace()` use the **same normalized coordinate system** — pass one directly to the other with no conversion needed. This handles rotated cameras, orthographic projection, and aspect ratio automatically. Do not write manual projection math.

The `depth` parameter is the distance from the camera's **near clipping plane** (not the camera itself) along the view direction. In practice: if your camera is at height 100 with `near = 1`, and your target surface is at y=0, use `depth = 99` (camera height minus near distance). For orthographic cameras, the exact depth matters less since there's no perspective distortion — any depth that lands on the target plane works.

For more complex touch handling, use `TouchStartEvent`, `TouchMoveEvent`, and `TouchEndEvent` — these give per-finger tracking for drag, multi-touch, and gesture interactions. See `references/2d-ui.md` for patterns.

---

## Runtime Object Creation

### Create a visible 3D object from scratch

```typescript
// In a @component class with these inputs:
// @input templateMesh: RenderMesh
// @input baseMaterial: Material

// 1. Create the scene object (global.scene is ScriptScene, not SceneObject)
const obj = global.scene.createSceneObject('MyObject')
obj.setParent(this.sceneObject) // optional — defaults to root

// 2. Add a RenderMeshVisual and assign a mesh
const rmv = obj.createComponent('Component.RenderMeshVisual') as RenderMeshVisual
rmv.mesh = this.templateMesh

// 3. Clone the material before modifying — see references/materials-shaders.md
//    (materials are shared assets; modifying one in place recolors every object using it)

// 4. Position the object
obj.getTransform().setLocalPosition(new vec3(10, 0, -5))
obj.getTransform().setLocalScale(new vec3(2, 2, 2))
```

For the clone → `clearMaterials` → `addMaterial` workflow, `mainMaterial`/`mainPass` access shortcuts, and why cloning is mandatory, see `references/materials-shaders.md`.

---

## Cross-Script Communication

Lens Studio does not have a global event bus. Use callback arrays or direct `@input` wiring:

```typescript
type OnScoreUpdate = (score: number) => void

@component
export class ScoreManager extends BaseScriptComponent {
  private listeners: OnScoreUpdate[] = []

  addScoreListener(fn: OnScoreUpdate): void {
    this.listeners.push(fn)
  }

  updateScore(score: number): void {
    this.listeners.forEach(fn => fn(score))
  }
}
```

> `createEvent()` only accepts built-in event type strings (e.g. `'UpdateEvent'`, `'TapEvent'`, `'OnEnableEvent'`). It cannot create custom-named events.

---

## Common Gotchas

- **`getComponent` in `onAwake`**: calling `getComponent` on the *same* SceneObject works in `onAwake`, but accessing *other* objects or `@input` references that may not be initialized yet is unsafe. Use `OnStartEvent` for cross-object lookups.
- **`@input` arrays** need a matching type annotation and are assigned from the Inspector list.
- **`null` vs `undefined`**: Lens Studio uses `null` more than `undefined`; check with `isNull(val)` or `val !== null`.
- **`getDeltaTime()`** returns frame delta in seconds — always use it for frame-rate-independent motion.
- **`this` inside callbacks**: if using a plain `function() {}` callback (not an arrow function), `this` will be wrong. Either use arrow functions or assign `const self = this` before the callback.
- **Destroying objects mid-update** can cause frame errors — defer with a `DelayedCallbackEvent` set to 0 delay if needed.
- **Component caching**: call `getComponent` once in `OnStartEvent` and store the result; calling it every frame is expensive.
- **`onDestroy` fires on the scene object being destroyed**, not when only a component is removed; if you need component-level cleanup, use `OnDisableEvent` or a manual teardown method.
- **Script initialization order**: components on the same frame initialize roughly in scene-hierarchy order. If two components in the same frame need each other in `onAwake`, use `OnStartEvent` instead.
- **`global.scene.createSceneObject(name)`** is on `ScriptScene` (accessed via `global.scene`), not on `SceneObject`. This is the only way to create scene objects at runtime.

---

## Reference Files

| Your script involves... | Read first |
|---|---|
| Touch input, tap events, drag, UI widgets | `references/2d-ui.md` |
| Material colors, textures, blend modes, shaders | `references/materials-shaders.md` |
| Spawning objects, prefab instantiation, pooling | `references/instantiation-patterns.md` |
| Math, coordinates, camera projection, rotations | `references/math.md` |
| Face tracking, expressions, landmarks | `references/face-tracking.md` |
| VFX, particle systems | `references/vfx.md` |
| Physics raycasting, surface alignment (Specs) | `references/world-query.md` |
| Bitmoji, Dynamic Response | `references/user-context.md` |
| Performance optimization, profiling | `references/performance.md` |
| Debugging — compile/runtime errors, `@input` not assigned, missing component, event timing | `references/debugging.md` |
| Cross-script access, TS-to-JS, require() | `references/component-access-patterns.md` |
| Geometry helpers, line drawing, dot product | `references/runtime-geometry-patterns.md` |
| Specs build-flow runtime patterns — `requireAsset` semantics, GLB 100× scale formula, SIK `.lspkg` imports + `getTypeName()`, root −Z / child +Z depth idiom, `isNull()`, audio playback modes, `faceDirection` yaw | `references/specs-runtime-patterns.md` |
| Quick API lookup (method signatures) | `references/api-cheatsheet.md` |
| Naming, file organization, Inspector layout (`@ui.label`/`@ui.group_start`), import order, DO-NOTs | `references/conventions.md` |
| Reading and interpreting Lens Studio log output you wrote with `console.*` / `print()` | sibling skill `ls-clad:lens-log-analysis` |
| Constructing or mutating mesh geometry at runtime (`MeshBuilder` — lathe, extrude, primitives, dynamic vertex updates, skinned meshes) | sibling skill `ls-clad:mesh-builder-scripting` |
Pliki w paczce (27)
  • SKILL.md 15 KB
  • references/2d-ui.md 9 KB
  • references/api-cheatsheet.md 8 KB
  • references/component-access-patterns.md 6 KB
  • references/conventions.md 6 KB
  • references/debugging.md 6 KB
  • references/face-tracking.md 9 KB
  • references/instantiation-patterns.md 2 KB
  • references/materials-shaders.md 10 KB
  • references/math.md 8 KB
  • references/performance.md 7 KB
  • references/runtime-geometry-patterns.md 2 KB
  • references/specs-runtime-patterns.md 6 KB
  • references/user-context.md 6 KB
  • references/vfx.md 7 KB
  • references/world-query.md 8 KB
  • resources/scripts/AccessComponentOnChildSceneObjectTS.ts 2 KB
  • resources/scripts/AccessComponentOnSceneObjectTS.ts 2 KB
  • resources/scripts/AccessCustomComponentsUsingRequiredTS.ts 2 KB
  • resources/scripts/AccessCustomComponentsUsingTypenameTS.ts 2 KB
  • resources/scripts/AccessJSfromTSwithDeclaration_JSComponentA_Declaration.ts 1 KB
  • resources/scripts/AccessJSfromTSwithDeclaration_TSComponentB.ts 2 KB
  • resources/scripts/AccessJSfromTSwithouthDeclaration_TSComponentB.ts 4 KB
  • resources/scripts/AccessTSfromJS_TSComponentA.ts 2 KB
  • resources/scripts/AccessTSfromTS_TSComponentA.ts 3 KB
  • resources/scripts/AccessTSfromTS_TSComponentB.ts 4 KB
  • resources/scripts/CustomComponentTS.ts 1 KB

Wersje

W bazie nie ma innych skilli o nazwie lens-api.

Migawka bazy z 13.11.2026 · wersja paczki 661ea24168ed (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100materials
    Opisuje tworzenie i konfigurację materiałów w Lens Studio: kolory, właściwości PBR, przypisywanie do obiektów oraz różnicę między API edytora i API środowiska wykonawczego, której pomylenie powoduje ciche błędy.
  • 100mesh-builder-scripting
    Opisuje API MeshBuilder w Lens Studio do budowania i zmiany siatek w TypeScript w czasie działania: prymitywy, lathe, extrude, tube, siatki ze szkieletem i kolory wierzchołków.
  • 95yapyak-app
    Podpowiada zasady pisania kodu aplikacji TypeScript: typy zwracane, wartości null i timery w oknie.
  • 90new
    Tworzy nową soczewkę dla wtyczki, gdy retrospektywa zaproponowała ją albo powtarzający się temat nie ma jeszcze soczewki.
  • 100test-studio-script-runner
    Wyjaśnia narzędzie Script Runner w dev/test-studio i pomaga dodawać, edytować, uruchamiać oraz dokumentować skrypty, ich zmienne i skrypty Sanity Studio działające w przeglądarce.
  • 91miniworld-ugc-30
    Podpowiada skrypty Lua dla Mini World UGC 3.0: wyzwalacze, komponenty, interfejs, zdarzenia, dane K/V i interfejsy API.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.