Pins a node to a fixed spot on the screen, ignoring camera motion — the way to make HUD markers, screen-space labels, and UI overlays inside a 3D scene.
Declarative element:
<sk-viewport-position-constraint>
Not on the sk.* global — construct via the declarative element or a module import.
This is the screen-space member of the Constraint family, and the odd one
out: instead of reading another scene object, it reads the viewport. Like every
constraint it drives its constrained
target by recomputing each frame — here it converts a screen position into world
space against the current camera, so the target stays glued to that screen spot
however the camera pans, orbits, or zooms.
Key attributes. mode chooses how the screen position is expressed: px
(absolute CSS pixels, the default), percent (0–100 of viewport width/height, so
it survives resizing), or anchor (offsets from a named corner/edge). In anchor
mode, anchor names the reference point (e.g. top-left, bottom-right). x
and y give the position or offset in the chosen mode's units, and z is the
normalized-device depth (0 = near plane, 1 = far plane) that controls what the
pinned node draws in front of or behind.
Related. It commonly pins annotation nodes (sk-live-annotation,
sk-overlay-annotation). Unlike the other members of the
Constraint family — sk-align-to-spline-constraint,
sk-orbit-constraint, sk-target-at-constraint — it constrains to
the screen rather than to another node; the GPU-parallel PointConstraint
applies per-clone effects across a Cloner.
constructor(config?: { camera?: AbstractCamera | string; provider?: ViewportPositionProvider; mode?: ViewportPositionMode; anchor?: AnchorAlignment; x?: number; y?: number; z?: number; id?: string })Inherited from: Constraint, SkenraAnimatable
— see those pages for inherited members.
| Property | Type | Default | Description | Declared by |
|---|---|---|---|---|
camera |
AbstractCamera | string |
— | Gets the camera used for coordinate conversion. | ViewportPositionConstraint |
providerconfig-only |
ViewportPositionProvider |
— | An external position provider that dynamically computes the | ViewportPositionConstraintConfig |
modeanimatable |
ViewportPositionMode |
— | Gets the positioning mode. | ViewportPositionConstraint |
anchor |
AnchorAlignment |
— | Gets the viewport anchor (only meaningful in 'anchor' mode). |
ViewportPositionConstraint |
x |
number |
— | Attribute alias for viewportCssX (metadata x). |
ViewportPositionConstraint |
y |
number |
— | Attribute alias for viewportCssY (metadata y). |
ViewportPositionConstraint |
z |
number |
— | Attribute alias for viewportZ (metadata z). |
ViewportPositionConstraint |
idconfig-only |
string |
— | Optional unique identifier for the constraint. | ViewportPositionConstraintConfig |
| Property | Type | Default | Description | Declared by |
|---|---|---|---|---|
targetNoderead-only |
SceneNode |
— | The node this constraint pins to a viewport position. | ViewportPositionConstraint |
viewportCssX |
number |
— | Gets the X coordinate in viewport space (CSS pixels). | ViewportPositionConstraint |
viewportCssY |
number |
— | Gets the Y coordinate in viewport space (CSS pixels). | ViewportPositionConstraint |
viewportZ |
number |
— | Gets the Z depth in NDC space. | ViewportPositionConstraint |
targetread-only |
SkenraAnimatable | null |
— | The node this constraint modifies. | Constraint |
priority |
number |
— | Gets the priority for this modifier in the effect stack. | Constraint |
sceneread-only |
any |
— | Gets the Scene this animatable belongs to, if any. | SkenraAnimatable |
animationsread-only |
SkenraAnimation[] |
— | Public getter for the animations affecting this target. | SkenraAnimatable |
| Method | Description | Declared by |
|---|---|---|
animate(firstArg: TypedKeyframe<this>[] | TypedPropertyIndexedKeyframes<this> | Record<string, any> | globalThis.Keyframe[] | globalThis.PropertyIndexedKeyframes | null, secondArg?: number | KeyframeAnimationOptions | globalThis.KeyframeAnimationOptions): SkenraAnimation & Animation |
Creates a new SkenraAnimation for this target per Web Animations API. | SkenraAnimatable |
removeAnimation(animation: SkenraAnimation): boolean |
Removes a specific animation from this object. | SkenraAnimatable |
constrain(type: K, config: ConstraintConfigMap[K]): ConstraintReturnMap[K] |
Creates a constraint on this Animatable using a fluent API. | SkenraAnimatable |
// Pin a label 20px in from the top-left corner of the viewport.
const vp = new ViewportPositionConstraint({ camera, mode: 'anchor',
anchor: 'top-left', x: 20, y: 20, z: 0.5 });
vp.setTarget(label);