OptionalalphaOpacity multiplied into the texture's alpha
OptionalalphaAlpha below which 'mask' mode cuts a pixel away
OptionalalphaHow the texture's alpha is used
'blend' draws the sprite in the transparent pass, which sorts back to front every frame: the
right default for soft edges. 'mask' cuts away pixels below
alphaCutoff in the opaque pass, with depth writes and no
sorting, so it batches better than 'blend'; it's the usual pick for foliage. 'opaque' draws
the whole quad solid.
OptionalanchorWhich point of the image sits on the node's origin, as a fraction of its size, with y
measured down from the top edge
A single number sets both axes. 0.5 centres the image, and { x: 0.5, y: 1 } stands it on
the origin. Left out, the texture's defaultAnchor applies, as on pixi's 2D Sprite; without
one it's centred, unlike the 2D Sprite's (0, 0). The Sprite3D class notes cover how
it behaves in each billboard mode.
OptionalangleLocal rotation as Euler angles in degrees: turns around Z, then Y, then X, each about the parent's axes
OptionalbillboardHow the quad turns to face the camera; see BillboardMode
Sprites with different modes don't share a draw; the Sprite3D class notes say when that costs draw calls.
OptionalboundsFixed local-space box used in place of this node's subtree when measuring bounds; see Container3D.boundsVolume
OptionalcastWhether the sprite casts shadows
Off by default because a billboarded sprite casts the shadow of its unturned quad, which
doesn't turn with the camera and can thin to a sliver. In 'none' mode a sprite casts once it's
'opaque' or 'mask' and its front faces the light, though a masked one's shadow doesn't show
its holes yet. A blended one, the default, casts nothing.
OptionalchildrenChildren to add, in order
OptionalcursorCSS cursor shown while this node is the pointer's target
Only the target's own cursor counts, as in 2D: a hit on a 'passive' child shows its
interactive ancestor's cursor, so set it on the node with the listeners. null shows the
View3D's own cursor. Any CSS cursor value works, url(...) included.
button.cursor = 'pointer';
handle.cursor = 'grab';
blade.cursor = 'url("crosshair.png") 8 8, crosshair'; // custom, with a hotspot
https://developer.mozilla.org/en-US/docs/Web/CSS/cursor MDN Cursor Documentation
OptionaldepthTarget depth along z; sets scale.z from the local bounds of the node and its children
OptionaleventHow this node takes part in pointer events, as on a pixi.js Container
'none': never picked, and neither is anything below it. The subtree costs nothing per
pointer event.'passive' (default): fires no listeners and is never the target. Under an interactive
ancestor it is still picked, and the hit goes to that ancestor with this node's surface
data. So one 'static' group makes its whole subtree clickable, with the group as target.'auto': as 'passive', but ray-tested even with no interactive ancestor, which costs time
and finds no target. Prefer 'passive'.'static': picked against its hitVolume, and fires
listeners.'dynamic': as 'static', and the View3D also picks again while a mouse or pen is
still, so a node that moves under it gets its enter and leave events.The renderer's eventMode option only sets the default for 2D containers, and the View warns
once when it isn't 'passive'. Picking costs time for each node that takes part, so set the
mode on the nodes and groups that need it.
OptionalheightThe sprite's height in world units, in place of
pixelSize on this axis; see
Sprite3DOptions.width for how it combines with width
OptionalhitShape the pointer ray is tested against when picking this node, like hitArea in 2D
Setting it doesn't make the node interactive; eventMode
does that. Left null, a Mesh3D uses its geometry's bounding box and a plain
Container3D has no shape, so it only hears events from its children.
A shape you set also clips the node's descendants, as hitArea does in 2D: a descendant only
hits where the hit point is inside every such shape above it, whatever those nodes'
eventMode. A clipped hit doesn't block what is behind it. A Geometry3D clips by its bounding
box, an IHitVolume3D only through its optional containsPoint, and the default
bounding box never clips. A ray that misses a Box or Sphere shape, or a Geometry3D's
bounding box, skips the exact test of every descendant under it.
mesh.interactive = true; // picked by its bounding box
mesh.hitVolume = 'geometry'; // picked per triangle
mesh.hitVolume = new Sphere(center, 0.4); // a cheaper or tighter shape
mesh.hitVolume = null; // back to the bounding box
// Children of the porthole only pick inside its sphere
porthole.hitVolume = new Sphere(new Vector3(), 1);
HitVolume3DInput For what each accepted value resolves to.
OptionalinteractiveShorthand for eventMode, as on a pixi.js Container
true sets 'static' and false sets 'passive'. It reads true for 'static' and
'dynamic'. false doesn't stop picking: under an interactive ancestor, a 'passive' node is
still picked on that ancestor's behalf. Set eventMode = 'none' to take a node and its
subtree out of picking.
OptionalinteractiveWhether this node's descendants can be picked, as on a pixi.js Container
false takes the whole subtree out of picking: descendants neither hit nor block what is
behind them, and cost nothing per pointer event. The node itself still picks by its own
eventMode and volume, so it can answer for the subtree.
menu.interactiveChildren = false; // nothing in the menu can be picked
menu.interactiveChildren = true; // every button picks again, eventMode intact
// One sphere answers for the whole robot: one ray test instead of one per mesh
robot.eventMode = 'static';
robot.hitVolume = new Sphere(new Vector3(), 2);
robot.interactiveChildren = false;
OptionallabelName to find the node by; see Container3D#label
OptionalmaterialThe material to draw the quad with; it needs a baseColor texture slot
It can be shared between sprites. Left out, the sprite makes an unlit, double-sided FlatMaterial of its own and frees it on destroy.
OptionalonclickProperty-based handler for the click event
Fired when a mouse click on this node completes, with any button but the right one.
mesh.eventMode = 'static';
mesh.onclick = (e) => {
if (e.hit3D) marker.position.copyFrom(e.hit3D.point);
};
IFederatedContainer3D#onpointertap For the equivalent for every pointer type.
OptionaloncontextmenuProperty-based handler for the contextmenu event
Fired when the browser is about to open its context menu over this node; call
preventDefault() to keep it closed.
OptionalonglobalmousemoveProperty-based handler for the globalmousemove event
Fired on every mouse move, wherever the pointer is on the page.
IFederatedContainer3D#onglobalpointermove For the equivalent for every pointer type.
OptionalonglobalpointermoveProperty-based handler for the globalpointermove event
Fired on every pointer move on the page, whether or not the pointer is over this node. The
node still needs eventMode 'static' or 'dynamic' to hear it.
OptionalonglobaltouchmoveProperty-based handler for the globaltouchmove event
Fired on every touch move, wherever the touch is on the page.
IFederatedContainer3D#onglobalpointermove For the equivalent for every pointer type.
OptionalonmousedownProperty-based handler for the mousedown event
Fired when a mouse button other than the right one goes down over this node.
IFederatedContainer3D#onpointerdown For the equivalent for every pointer type.
OptionalonmouseenterProperty-based handler for the mouseenter event
Fired when the mouse enters this node. Doesn't bubble.
IFederatedContainer3D#onpointerenter For the equivalent for every pointer type.
OptionalonmouseleaveProperty-based handler for the mouseleave event
Fired when the mouse leaves this node. Doesn't bubble.
IFederatedContainer3D#onpointerleave For the equivalent for every pointer type.
OptionalonmousemoveProperty-based handler for the mousemove event
Fired while the mouse moves across this node.
IFederatedContainer3D#onpointermove For the equivalent for every pointer type.
OptionalonmouseoutProperty-based handler for the mouseout event
Fired when the mouse moves off this node. Bubbles, unlike mouseleave.
IFederatedContainer3D#onpointerout For the equivalent for every pointer type.
OptionalonmouseoverProperty-based handler for the mouseover event
Fired when the mouse moves onto this node. Bubbles, unlike mouseenter.
// One handler on the shelf hears every item on it
shelf.onmouseover = (e) => highlight(e.target3D);
IFederatedContainer3D#onpointerover For the equivalent for every pointer type.
OptionalonmouseupProperty-based handler for the mouseup event
Fired when a mouse button other than the right one is released over this node.
IFederatedContainer3D#onpointerup For the equivalent for every pointer type.
OptionalonmouseupoutsideProperty-based handler for the mouseupoutside event
Fired when a mouse button that went down on this node is released anywhere else.
IFederatedContainer3D#onpointerupoutside For the equivalent for every pointer type.
OptionalonpointercancelProperty-based handler for the pointercancel event
Never called: pixi delivers no pointer cancellation, in 2D either.
OptionalonpointerdownProperty-based handler for the pointerdown event
Fired when a pointer goes down on this node: mouse, touch or pen alike.
OptionalonpointerenterProperty-based handler for the pointerenter event
Fired when a pointer enters this node. Doesn't bubble, so an ancestor hears it only when the pointer enters the ancestor itself.
OptionalonpointerleaveProperty-based handler for the pointerleave event
Fired when a pointer leaves this node. Doesn't bubble.
OptionalonpointermoveProperty-based handler for the pointermove event
Fired while a pointer moves across this node.
OptionalonpointeroutProperty-based handler for the pointerout event
Fired when a pointer moves off this node. Bubbles, unlike pointerleave.
OptionalonpointeroverProperty-based handler for the pointerover event
Fired when a pointer moves onto this node. Bubbles, unlike pointerenter.
OptionalonpointertapProperty-based handler for the pointertap event
Fired when a pointer completes a tap on this node, for any pointer type and any button, right clicks included.
OptionalonpointerupProperty-based handler for the pointerup event
Fired when a pointer is released over this node.
OptionalonpointerupoutsideProperty-based handler for the pointerupoutside event
Fired when a pointer that went down on this node is released anywhere else. The event's
target3D is the node that was pressed, and hit3D is what the pointer was released over.
OptionalonrightclickProperty-based handler for the rightclick event
Fired when a right click completes on this node.
OptionalonrightdownProperty-based handler for the rightdown event
Fired when the right mouse button goes down over this node.
OptionalonrightupProperty-based handler for the rightup event
Fired when the right mouse button is released over this node.
OptionalonrightupoutsideProperty-based handler for the rightupoutside event
Fired when the right mouse button that went down on this node is released anywhere else.
OptionalontapProperty-based handler for the tap event
Fired when a touch completes a tap on this node. Chrome gives each touch a new pointerId, and
detail only counts repeat taps by the same one, so it stays 1 there; time a double tap yourself.
let lastTap = 0;
mesh.ontap = (e) => {
if (e.timeStamp - lastTap < 300) focusOn(mesh); // double tap
lastTap = e.timeStamp;
};
IFederatedContainer3D#onpointertap For the equivalent for every pointer type.
OptionalontouchcancelProperty-based handler for the touchcancel event
Never called: pixi delivers no touch cancellation, in 2D either.
OptionalontouchendProperty-based handler for the touchend event
Fired when a touch lifts off this node.
IFederatedContainer3D#onpointerup For the equivalent for every pointer type.
OptionalontouchendoutsideProperty-based handler for the touchendoutside event
Fired when a touch that started on this node lifts off anywhere else.
IFederatedContainer3D#onpointerupoutside For the equivalent for every pointer type.
OptionalontouchmoveProperty-based handler for the touchmove event
Fired while a touch moves across this node.
canvasMesh.hitVolume = 'geometry'; // per triangle, so hits carry a uv
canvasMesh.ontouchmove = (e) => {
if (e.hit3D) paintAt(e.hit3D.uv);
};
IFederatedContainer3D#onpointermove For the equivalent for every pointer type.
OptionalontouchstartProperty-based handler for the touchstart event
Fired when a touch lands on this node.
IFederatedContainer3D#onpointerdown For the equivalent for every pointer type.
OptionalonwheelProperty-based handler for the wheel event
Fired when the wheel turns while the pointer is over this node.
OptionaloriginPoint in local space that rotation and scale happen around; see Container3D#origin
OptionalparentParent to add this node to, once everything else is applied
OptionalpixelWorld units per texture pixel, which sets the sprite's size
At the default 0.01 a 512 px texture is 5.12 units across, which suits a scene measured in metres.
OptionalpositionLocal position
OptionalquaternionLocal rotation as a unit quaternion
OptionalreceiveWhether the sprite is shadowed
Only a lit material takes shadows, so it does nothing with the default FlatMaterial.
OptionalrotationLocal rotation as Euler angles in radians: turns around Z, then Y, then X, each about the parent's axes
OptionalscaleLocal scale; a number scales all three axes
OptionaltextureThe image on the quad
Its untrimmed pixel size times pixelSize sets the sprite's world size.
OptionaltintColour multiplied into the texture, any ColorSource, as with Container.tint
OptionalvisibleWhether this node and its descendants draw
OptionalwidthThe sprite's width in world units, in place of pixelSize on this axis
Pass only width or only height and the other follows the texture's aspect ratio:
{ height: 4 } on a 128×200 texture gives 2.56 × 4. Pass both to stretch the image to that
box. It ends up in scale, as on pixi's 2D Sprite, but unlike there a lone width or
height keeps the aspect ratio; the Sprite3D#width and Sprite3D#height
accessors set one axis each.
It's measured against the texture once, at construction. A texture still loading has no size, so the value is dropped with a warning; size the sprite once it loads.
OptionalxLocal position on x; the same as position.x
OptionalyLocal position on y; the same as position.y
OptionalzLocal position on z; the same as position.z
Constructor options for Sprite3D
texture,tint,alpha,alphaModeandalphaCutoffshape the sprite's material. Withoutmaterialthey build the unlit FlatMaterial the sprite makes; with one, those you set are written into it,textureinto itsbaseColorslot. The other Mesh3DOptions apply too, andlabeldefaults to'Sprite3D'.Example