Skip to content
Skills Library
Programming · Building & coding

physics

/physics

Build or debug Lens Studio physics — gravity, collisions, joints, raycast input, trigger zones, force-driven motion, and physics-driven AR (objects colliding with face/hand/world mesh). Use when wiring `BodyComponent`/`ColliderComponent`/`ConstraintComponent`/`WorldComponent`, building ragdolls, vehicles, breakables, or draggable props, debugging tunneling/constraints, or using `Physics.ForceMode`/`createGlobalProbe`/`addPointConstraint`/`WorldSettingsAsset`/`Matter`/`Filter`. Fires on `.esproj` with `Physics.*` or code like `body.addForce`/`probe.rayCast`. SKIP for other engines (Unity, Unrea

Licence
Apache-2.0
Last repository change
01.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
0
HTML comments
1
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 01.09.2026, without references to retired models or APIs.

Licence

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

What to check before installing
  • SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Build or debug Lens Studio physics — gravity, collisions, joints, raycast input, trigger zones, force-driven motion, and physics-driven AR (objects colliding with face/hand/world mesh). Use when wiring `BodyComponent`/`ColliderComponent`/`ConstraintComponent`/`WorldComponent`, building ragdolls, vehicles, breakables, or draggable props, debugging tunneling/constraints, or using `Physics.ForceMode`/`createGlobalProbe`/`addPointConstraint`/`WorldSettingsAsset`/`Matter`/`Filter`. Fires on `.esproj` with `Physics.*` or code like `body.addForce`/`probe.rayCast`. SKIP for other engines (Unity, Unrea

Original author description

Build or debug Lens Studio physics — gravity, collisions, joints, raycast input, trigger zones, force-driven motion, and physics-driven AR (objects colliding with face/hand/world mesh). Use when wiring `BodyComponent`/`ColliderComponent`/`ConstraintComponent`/`WorldComponent`, building ragdolls, vehicles, breakables, or draggable props, debugging tunneling/constraints, or using `Physics.ForceMode`/`createGlobalProbe`/`addPointConstraint`/`WorldSettingsAsset`/`Matter`/`Filter`. Fires on `.esproj` with `Physics.*` or code like `body.addForce`/`probe.rayCast`. SKIP for other engines (Unity, Unrea

How it works

  1. 1. World
  2. 2. Body and Collider
  3. 3. Constraints
  4. Hard limits
  5. Behavior helper vs script
  6. Adjacent features (NOT this skill)
  7. When to dig deeper
Original SKILL.md headings · 69 lines, 989 words
SKILL.md preview
---
name: physics
description: Build or debug Lens Studio physics — gravity, collisions, joints, raycast input, trigger zones, force-driven motion, and physics-driven AR (objects colliding with face/hand/world mesh). Use when wiring `BodyComponent`/`ColliderComponent`/`ConstraintComponent`/`WorldComponent`, building ragdolls, vehicles, breakables, or draggable props, debugging tunneling/constraints, or using `Physics.ForceMode`/`createGlobalProbe`/`addPointConstraint`/`WorldSettingsAsset`/`Matter`/`Filter`. Fires on `.esproj` with `Physics.*` or code like `body.addForce`/`probe.rayCast`. SKIP for other engines (Unity, Unreal, three.js, matter.js, Cannon, Rapier, Godot), non-physics LS work (visual-only face mesh, materials, TouchEvent with no body), and Hair/Cloth sim.
---
<!--
Copyright 2026 Specs Inc.
SPDX-License-Identifier: Apache-2.0
-->

# Lens Studio Physics

Three-layer model — skipping a layer is where most bugs come from.

## 1. World

- Gravity, sim rate, slow-mo, speed limits, layer matrix — all live on a `WorldSettingsAsset`.
- **The root world's default settings are uneditable.** `Physics.getRootWorldSettings()` returns `null` until you create your own `WorldSettingsAsset` and assign it on the Scene asset's `physicsRootSettings` field. Writes to the implicit default silently no-op.
- **Ground Is Zero** — invisible infinite floor at `y = 0`, enabled by default on the root world. Disable it (Scene > Physics) when you need custom floor geometry or want to drop below `y = 0`. Custom `WorldComponent` worlds do not inherit it.
- For parallel simulations (slow-mo overlay, inverted-gravity zone, isolated UI), add a `Physics.WorldComponent`. **Character Controller projects are limited to a single `WorldComponent`.**

## 2. Body and Collider

- `Physics.ColliderComponent` = static / trigger. `Physics.BodyComponent` extends Collider with a `dynamic` flag plus mass/density/damping. **`Body { dynamic: false }` ≡ a Collider** — prefer `ColliderComponent` for static intent; it reads cleaner and skips the mass/damping fields.
- **One body OR collider per SceneObject.** Multi-shape silhouettes use the **compound pattern**: parent owns `BodyComponent`; each child SceneObject owns a `ColliderComponent` with its own shape. The whole assembly tumbles as one rigid body. `forceCompound: bool` on a child controls whether raycasts return the leaf or the parent.
- Three build modes:
  - **A — fresh primitive**: use `*PhysicsObjectPreset` (Box / Sphere / Capsule / Cone / Cylinder). Comes wired with mesh + body + matching shape. For purely static visuals, use the non-physics counterparts (`BoxMeshObjectPreset` …) and add a `ColliderComponent` — clearer intent than dropping a physics preset and flipping `dynamic = false`.
  - **B — attach to existing imported mesh**: add `BodyComponent` / `ColliderComponent`, pick a shape, size to match. **Off-center pivots need a pivot-wrapper** — a body rotates around the SceneObject pivot, not the mesh center. Pin authored with pivot-at-base spins sideways instead of toppling. See `references/api-surface.md` § Fitting.
  - **C — skinned / deforming mesh (face / hand / body / world mesh)**: `ColliderComponent` only (dynamic skinned bodies are unsupported). Set both `shape.mesh` and `shape.skin` — without `skin` the collider freezes at the bind pose. Hollow + no CCD → fast bodies tunnel; raise `simulationRate` or use a primitive on the dynamic side.
- **Always turn on `debugDrawEnabled = true` while authoring.** The cyan wireframe is the only way to see whether a collider matches the visual.

## 3. Constraints

- `Physics.ConstraintComponent` on a **child** of a body. Types: `Fixed` / `Point` / `Hinge`. `target` = another body/collider, or `null` to anchor to world.
- The component's world transform when added becomes the anchor — **immutable after**. Move the `target` to move the joint.
- **Hinge axis = local Y of the constraint child.** See `references/gotchas.md` § *Hinge axis defaults to local Y* for the rotation recipe and code example.
- **Persistent** (editor-authored child) vs **ad-hoc** (`body.addPointConstraint / addFixedConstraint / addHingeConstraint`, paired with `removeConstraint`) — pick by lifetime. Ad-hoc is the canonical form for grab/throw/break interactions.

## Hard limits

- **Collider sweet spot: 10 cm – 5 m** under default gravity. Lens Studio has no continuous collision detection — below 10 cm, fast bodies tunnel through static colliders.
- **Mitigations for fast scenes**: raise `worldSettings.simulationRate` (default 60, valid 30–240 step 30) to 120/240, or set `absoluteSpeedLimit` / `relativeSpeedLimit`.
- **Units are centimeters.** Default gravity `(0, -980, 0)` cm/s². **Right-handed**: +X right, +Y up, **−Z forward**.
- **Object budget**: ~200 dynamic bodies on mobile, ~100 on Spectacles 2021.
- **Mesh shapes**: `shape.convex = true` is **required** on dynamic bodies (engine bakes a convex hull; concavity collapses). For concave dynamic geometry, use a compound of primitives. Mesh-vs-mesh is the most expensive contact pair.
- **`fitVisual` only works on Box and Sphere** — Capsule/Cylinder/Cone/Mesh silently ignore it. `Plane.mesh` has 0 thickness on Y, so `fitVisual` on a flat floor produces a zero-thickness slab that bodies fall through. Static floors/walls need ≥ 20 cm explicit thickness on the contact axis.
- **Matter combines multiplicatively** between the two contact surfaces — a bouncy ball that "won't bounce" is almost always a wall with no `matter` assigned.
- **Filter `includeIntangible` defaults to false** — triggers don't detect other triggers unless explicitly opted in.

## Behavior helper vs script

| Behavior helper | Script |
|---|---|
| Trigger is a `Physics Collider Event`, response is a stock action (Play Sound, Set Color, Spawn Prefab, Apply Force, Send Custom Trigger) | Need raycasts, dynamic spawning, math on contact normals, conditional logic on impulse |
| Purely declarative (event → action) | Read/write `velocity` / `angularVelocity`, apply mass-aware impulses, per-frame `UpdateEvent` loop |

Bridge: `global.behaviorSystem.sendCustomTrigger('name')` ↔ `addCustomTriggerResponse('name', cb)`.

`Physics Collider Event` has its own Static / Dynamic / Intangible filter checkboxes — set them on the trigger, not on the body.

## Adjacent features (NOT this skill)

- **Hair / Cloth Simulation** — separate runtimes with their own components. World-physics bodies do not interact with them. Cloth only accepts primitive Physics colliders. **LevelSet shapes belong here**, not on rigid bodies — `Physics.ColliderComponent` will accept a LevelSet shape but rigid bodies won't collide with it.
- **Character Controller** — separate movement system that talks to physics but isn't a body. Limits the project to a single `WorldComponent`.

## When to dig deeper

- **Full API surface** (force modes, event payloads, Probe / raycast / shapeCast, constraint types, matter/filter, shape.skin, compound, persistent vs ad-hoc): `references/api-surface.md`.
- **Fitting colliders to imported meshes** (bbox-vs-pivot check, shape picker, wrapper recipe, sizing math, `Editor.Shape.create*Shape(scene)` patterns): `references/api-surface.md` § Fitting.
- **Gotchas list** — read before debugging anything that "doesn't work": `references/gotchas.md`.
- **Patterns library** (static obstacle, dynamic-on-tap, hinge/point/fixed joints, trigger zone, continuous-force field, articulated chain, compound, skinned-mesh, multi-world, drag-to-move): `references/patterns.md`.
- **Drag-to-Move** — the most reusable physics input pattern: `references/draggable-pattern.md`.
- **MCP workflow specifics** (scene-graphql / asset-graphql shapes for physics components, dispatching shape construction to `editor-api-specialist`): `references/mcp-workflow.md`.
Files in this package (6)
  • SKILL.md 8 KB
  • references/api-surface.md 21 KB
  • references/draggable-pattern.md 11 KB
  • references/gotchas.md 13 KB
  • references/mcp-workflow.md 8 KB
  • references/patterns.md 19 KB

Versions

RepositoryScoreLicence
This page · lens-studio-devs/ls-extensions100Apache-2.0
skymanbp/sci-paper100MIT
leex852/skills100MIT

Database snapshot: 13.11.2026 · package version 5e81bd3e5155 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100unity-2d-physics
    Unity 2D physics — Rigidbody2D body types, Collider2D shapes, joints, effectors, layer collision matrix, contact filters, IEEE physics gotchas in 2D, raycast/overlap APIs. USE WHEN: tuning Rigidbody2D movement, joint setups (hinge/spring/distance/ slider), one-way platforms,…
  • 100r3f-physics
    3D physics in React Three Fiber with @react-three/rapier — RigidBody, colliders (cuboid, ball, hull, trimesh), joints (revolute, fixed, spherical), kinematic vs dynamic vs fixed, raycast/character controller, drag with springs, gestures, debug visualizer. Use when adding rigid…
  • 85raycast
    Raycast extension development. Use when working with @raycast/api imports, Raycast commands/tools, or building extensions.
  • 100physics-arcade
    Use this skill when using Arcade Physics in Phaser 4. Covers enabling physics, velocity, acceleration, gravity, collisions, overlap, world bounds, physics groups, static bodies, and collision categories. Triggers on: physics, arcade, velocity, gravity, collide, overlap, bounce, physics body.
  • 95melonjs-physics
    Use this skill for collision, physics bodies, movement, and spatial queries in melonJS — the built-in SAT world and the planck/matter adapters. Covers bodyDef vs Body, collision types and masks, the collision callback family and their firing rules, raycast/queryAABB/querySphere,…
  • 100unity-physics
    Set up 3D physics in Unity 6.3 LTS: Rigidbody movement and forces, colliders, triggers vs collisions, layer-based collision, raycasts, and joints. Use when adding a Rigidbody, handling OnCollisionEnter/OnTriggerEnter, tuning collision layers, casting rays, or when the user…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.