|
|
|
|
@ -684,7 +684,7 @@ wherever a texture can: composited over the overlay with
|
|
|
|
|
the same options page works flat on the screen and on the monitor of a
|
|
|
|
|
modeled arcade cabinet. A GUI needs the GPU device the 3D scene uses, so it
|
|
|
|
|
is unavailable on a machine without one (see <<sceneperformance,Performance
|
|
|
|
|
and Requirements>>); `guiNew` raises an error rather than answering false, so
|
|
|
|
|
and Requirements>>); `guiNew` ends the script rather than answering false, so
|
|
|
|
|
ask <<singehasgpu,singeHasGpu>> first if your game can do without. The bundled
|
|
|
|
|
menu does exactly that, and draws itself into the overlay instead when the
|
|
|
|
|
answer is no (see xref:Manual.adoc#menurenderers[The two renderers]). Every call named here has an entry in the
|
|
|
|
|
@ -2776,7 +2776,7 @@ morph target weights are all driven. See the Animation part of
|
|
|
|
|
seconds = animationGetTime(node)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
The current time into the base layer's clip, playing or paused, in the clip's own seconds (a `speed` of `2` moves it twice as fast). A looping clip wraps back to `0` at its end; a non-looping one stops at its length. Nothing played yet gives `0`. Clips on the upper layers are not reported. A node that is not an instance root raises an error.
|
|
|
|
|
The current time into the base layer's clip, playing or paused, in the clip's own seconds (a `speed` of `2` moves it twice as fast). A looping clip wraps back to `0` at its end; a non-looping one stops at its length. Nothing played yet gives `0`. Clips on the upper layers are not reported. A node that is not an instance root ends the script.
|
|
|
|
|
|
|
|
|
|
*Returns:* Seconds as a number.
|
|
|
|
|
|
|
|
|
|
@ -2805,7 +2805,7 @@ end
|
|
|
|
|
playing = animationIsPlaying(node)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Whether the base layer's clip is advancing on this instance. A non-looping clip stops playing when it reaches its end, and `animationPause` and `animationStop` both make this `false`; a looping clip stays `true` until stopped. Unlike the other calls here, a node that is not an instance root does not raise an error but answers `false`.
|
|
|
|
|
Whether the base layer's clip is advancing on this instance. A non-looping clip stops playing when it reaches its end, and `animationPause` and `animationStop` both make this `false`; a looping clip stays `true` until stopped. Unlike the other calls here, a node that is not an instance root does not end the script but answers `false`.
|
|
|
|
|
|
|
|
|
|
*Returns:* Boolean.
|
|
|
|
|
|
|
|
|
|
@ -2833,7 +2833,7 @@ end
|
|
|
|
|
animationPause(node)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Freezes the base layer's clip at its current time; the nodes hold that pose until `animationResume` continues it or another clip is played. Clips on the upper layers keep running. Pausing an instance that has nothing playing is harmless. A node that is not an instance root raises an error.
|
|
|
|
|
Freezes the base layer's clip at its current time; the nodes hold that pose until `animationResume` continues it or another clip is played. Clips on the upper layers keep running. Pausing an instance that has nothing playing is harmless. A node that is not an instance root ends the script.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<animationresume,animationResume>>, <<animationsettime,animationSetTime>>
|
|
|
|
|
@ -2861,7 +2861,7 @@ animationPlay(node, nameOrIndex, loop, speed)
|
|
|
|
|
animationPlay(node, nameOrIndex, loop, speed, fade)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Starts one of the model's clips from its beginning on the base layer of this instance, replacing whatever was playing there; the pose updates at once. With a `fade` the old clip keeps running while it fades out over that many seconds, and when nothing was playing the fade starts from the pose the nodes are in now (a ragdoll that was just switched off, a scripted pose), with nodes the new clip does not animate easing back to the model's rest pose. A node that is not an instance root, a name the model does not have, or a number outside `1` to the clip count raises an error.
|
|
|
|
|
Starts one of the model's clips from its beginning on the base layer of this instance, replacing whatever was playing there; the pose updates at once. With a `fade` the old clip keeps running while it fades out over that many seconds, and when nothing was playing the fade starts from the pose the nodes are in now (a ragdoll that was just switched off, a scripted pose), with nodes the new clip does not animate easing back to the model's rest pose. A node that is not an instance root, a name the model does not have, or a number outside `1` to the clip count ends the script.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -2898,7 +2898,7 @@ animationPlayLayer(node, layer, nameOrIndex, loop, speed)
|
|
|
|
|
animationPlayLayer(node, layer, nameOrIndex, loop, speed, fade)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Plays a clip on one of the four layers above the base, blended over whatever is beneath it by the layer's weight (`animationSetLayerWeight`, default `1`) and limited to part of the skeleton when a mask is set (`animationSetLayerMask`). Higher layers blend over lower ones; each layer runs its own clip, time and loop independently of the base. `nameOrIndex`, `loop`, `speed` and `fade` mean what they do in `animationPlay`, with one difference: a `fade` on a layer that was empty ramps the layer's weight in from `0` instead of crossfading from a pose. A layer outside `1` to `4`, a node that is not an instance root, or a clip the model does not have raises an error.
|
|
|
|
|
Plays a clip on one of the four layers above the base, blended over whatever is beneath it by the layer's weight (`animationSetLayerWeight`, default `1`) and limited to part of the skeleton when a mask is set (`animationSetLayerMask`). Higher layers blend over lower ones; each layer runs its own clip, time and loop independently of the base. `nameOrIndex`, `loop`, `speed` and `fade` mean what they do in `animationPlay`, with one difference: a `fade` on a layer that was empty ramps the layer's weight in from `0` instead of crossfading from a pose. A layer outside `1` to `4`, a node that is not an instance root, or a clip the model does not have ends the script.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -2934,7 +2934,7 @@ end
|
|
|
|
|
animationResume(node)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Continues the base layer's clip from where `animationPause` froze it, or from wherever `animationSetTime` moved it meanwhile. Resuming a clip that is already playing changes nothing. An instance with no clip on its base layer (never played, or stopped) raises an error, as does a node that is not an instance root.
|
|
|
|
|
Continues the base layer's clip from where `animationPause` froze it, or from wherever `animationSetTime` moved it meanwhile. Resuming a clip that is already playing changes nothing. An instance with no clip on its base layer (never played, or stopped) ends the script, as does a node that is not an instance root.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<animationpause,animationPause>>, <<animationsettime,animationSetTime>>
|
|
|
|
|
@ -2959,7 +2959,7 @@ animationSetLayerMask(node, layer, maskNode)
|
|
|
|
|
animationSetLayerMask(node, layer)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Limits a layer to `maskNode` and everything under it, so the clip on that layer moves only that part of the model and the rest keeps following the layers beneath. `maskNode` must be one of the instance's own nodes, found with `nodeFind(name, node)`; the instance root itself does not count. Leaving `maskNode` out, or passing `nil`, lifts the limit. The mask stays on the layer across later `animationPlayLayer` calls. A layer outside `1` to `4` raises an error, and so does a node that is not an instance root or a `maskNode` that is not part of that instance.
|
|
|
|
|
Limits a layer to `maskNode` and everything under it, so the clip on that layer moves only that part of the model and the rest keeps following the layers beneath. `maskNode` must be one of the instance's own nodes, found with `nodeFind(name, node)`; the instance root itself does not count. Leaving `maskNode` out, or passing `nil`, lifts the limit. The mask stays on the layer across later `animationPlayLayer` calls. A layer outside `1` to `4` ends the script, and so does a node that is not an instance root or a `maskNode` that is not part of that instance.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -2992,7 +2992,7 @@ end
|
|
|
|
|
animationSetLayerWeight(node, layer, weight)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
How much a layer's clip shows over what is beneath it, `0` (not at all) to `1` (fully, the default); values outside that range are clamped. The weight belongs to the layer, not the clip, so it survives `animationPlayLayer` and `animationStop` on that layer. Change it a little every frame to fade a layer in or out by hand, or let a `fade` on `animationPlayLayer` do it once. A layer outside `1` to `4` or a node that is not an instance root raises an error.
|
|
|
|
|
How much a layer's clip shows over what is beneath it, `0` (not at all) to `1` (fully, the default); values outside that range are clamped. The weight belongs to the layer, not the clip, so it survives `animationPlayLayer` and `animationStop` on that layer. Change it a little every frame to fade a layer in or out by hand, or let a `fade` on `animationPlayLayer` do it once. A layer outside `1` to `4` or a node that is not an instance root ends the script.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<animationplaylayer,animationPlayLayer>>, <<animationsetlayermask,animationSetLayerMask>>
|
|
|
|
|
@ -3015,7 +3015,7 @@ end
|
|
|
|
|
animationSetTime(node, seconds)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Jumps the base layer's clip to a time in its own seconds; negative values become `0`. The pose updates at once whether or not the clip is playing, so a paused instance can be scrubbed to an exact frame, and a playing one continues from the new time. Any crossfade in progress on the base layer is cut short. An instance with no clip on its base layer raises an error, as does a node that is not an instance root.
|
|
|
|
|
Jumps the base layer's clip to a time in its own seconds; negative values become `0`. The pose updates at once whether or not the clip is playing, so a paused instance can be scrubbed to an exact frame, and a playing one continues from the new time. Any crossfade in progress on the base layer is cut short. An instance with no clip on its base layer ends the script, as does a node that is not an instance root.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<animationgettime,animationGetTime>>, <<animationpause,animationPause>>, <<animationresume,animationResume>>
|
|
|
|
|
@ -3041,7 +3041,7 @@ animationStop(node)
|
|
|
|
|
animationStop(node, layer)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Stops and forgets every clip on the instance, or only the clip on one layer above the base (`1` to `4`); the base layer alone cannot be stopped without the layers above it. The nodes keep their last pose, which a following `animationPlay` with a `fade` eases out of. After stopping everything, `animationResume` and `animationSetTime` raise an error until something is played again. Layer weights and masks are kept. A layer outside `1` to `4` or a node that is not an instance root raises an error.
|
|
|
|
|
Stops and forgets every clip on the instance, or only the clip on one layer above the base (`1` to `4`); the base layer alone cannot be stopped without the layers above it. The nodes keep their last pose, which a following `animationPlay` with a `fade` eases out of. After stopping everything, `animationResume` and `animationSetTime` end the script until something is played again. Layer weights and masks are kept. A layer outside `1` to `4` or a node that is not an instance root ends the script.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<animationplay,animationPlay>>, <<animationplaylayer,animationPlayLayer>>, <<animationpause,animationPause>>
|
|
|
|
|
@ -3281,7 +3281,7 @@ argument aborts the script.
|
|
|
|
|
[#body]
|
|
|
|
|
=== Body
|
|
|
|
|
|
|
|
|
|
A body gives a scene node a place in the physics world. There is one body per node, addressed by the node handle: a static body stays where the node was when the body was made, a kinematic body follows its node each step and pushes without being pushed, and a dynamic body is moved by the simulation and drives its node. Sizes, positions and velocities are in world units (meters in a 3D scene, overlay pixels in a 2D world), masses in kilograms, and time in seconds. Every call here raises an error when the node has no body; a call that only makes sense for one kind of body (a force on a static body, say) is ignored on the others, except `bodySetMass`, which raises. See <<physics,Physics>> in Game Development for how bodies, nodes and the frame fit together.
|
|
|
|
|
A body gives a scene node a place in the physics world. There is one body per node, addressed by the node handle: a static body stays where the node was when the body was made, a kinematic body follows its node each step and pushes without being pushed, and a dynamic body is moved by the simulation and drives its node. Sizes, positions and velocities are in world units (meters in a 3D scene, overlay pixels in a 2D world), masses in kilograms, and time in seconds. Every call here ends the script when the node has no body; a call that only makes sense for one kind of body (a force on a static body, say) is ignored on the others, except `bodySetMass`, which raises. See <<physics,Physics>> in Game Development for how bodies, nodes and the frame fit together.
|
|
|
|
|
|
|
|
|
|
[#bodynew]
|
|
|
|
|
==== bodyNew
|
|
|
|
|
@ -3294,7 +3294,7 @@ bodyNew(node, type, shape, a, b)
|
|
|
|
|
bodyNew(node, type, shape, a, b, c)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Gives the node a body of the given type, placed where the node is in the world right now (its parents included), with a collision shape sized by `a`, `b` and `c` in world units and scaled by the node's world scale. A second call on the same node replaces the first, and a node that had a player loses it. A dynamic body's mass comes from its shape's volume at the density of water, so set `bodySetMass` on anything meant to feel light. Changing the node's scale later does not resize the body. Raises an error for an unknown type or shape, when physics is not available on this machine, when the world already holds `4096` bodies, or when the shape cannot be built (a dynamic `SHAPE_MESH`, or a hull with no mesh under the node).
|
|
|
|
|
Gives the node a body of the given type, placed where the node is in the world right now (its parents included), with a collision shape sized by `a`, `b` and `c` in world units and scaled by the node's world scale. A second call on the same node replaces the first, and a node that had a player loses it. A dynamic body's mass comes from its shape's volume at the density of water, so set `bodySetMass` on anything meant to feel light. Changing the node's scale later does not resize the body. Ends the script for an unknown type or shape, when physics is not available on this machine, when the world already holds `4096` bodies, or when the shape cannot be built (a dynamic `SHAPE_MESH`, or a hull with no mesh under the node).
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -3395,7 +3395,7 @@ end
|
|
|
|
|
bodyDelete(node)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Removes the body from the world; the node and its mesh stay where they are. Every joint attached to the body, and any vehicle built on it, goes with it. Deleting the node removes its body too, so this is only needed to keep a node without its body. Raises an error when the node has no body.
|
|
|
|
|
Removes the body from the world; the node and its mesh stay where they are. Every joint attached to the body, and any vehicle built on it, goes with it. Deleting the node removes its body too, so this is only needed to keep a node without its body. Ends the script when the node has no body.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<bodynew,bodyNew>>, <<bodysetenabled,bodySetEnabled>>, <<jointdelete,jointDelete>>
|
|
|
|
|
@ -3667,7 +3667,7 @@ bodySetFriction(pond, 0.02)
|
|
|
|
|
bodySetMass(node, kilograms)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Rescales a dynamic body's mass and, with it, its inertia. Do this for anything meant to feel light or heavy: the default is the shape's volume at the density of water, so a door-sized box weighs about 140 kilograms and a nudge will not move it. Forces and impulses scale with mass, so set the mass before tuning them. Raises an error when the body is not dynamic or the mass is not positive.
|
|
|
|
|
Rescales a dynamic body's mass and, with it, its inertia. Do this for anything meant to feel light or heavy: the default is the shape's volume at the density of water, so a door-sized box weighs about 140 kilograms and a nudge will not move it. Forces and impulses scale with mass, so set the mass before tuning them. Ends the script when the body is not dynamic or the mass is not positive.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<bodynew,bodyNew>>, <<bodyapplyimpulse,bodyApplyImpulse>>, <<playersetpush,playerSetPush>>
|
|
|
|
|
@ -3749,7 +3749,7 @@ bodySetWater(node, density, linearDrag)
|
|
|
|
|
bodySetWater(node, density, linearDrag, angularDrag)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Fills a static body with water and makes it a trigger: the top of its shape is the surface, and every dynamic body inside floats, sinks or rolls by buoyancy against that surface (the submerged part of the shape counts, so a tilted crate rights itself), slowed by the drags. A player whose middle is below the surface swims. Because the volume is a trigger, `onTrigger` fires on the way in and out. The water is not drawn: give the node a blended material, or none. Raises an error when the body is not static.
|
|
|
|
|
Fills a static body with water and makes it a trigger: the top of its shape is the surface, and every dynamic body inside floats, sinks or rolls by buoyancy against that surface (the submerged part of the shape counts, so a tilted crate rights itself), slowed by the drags. A player whose middle is below the surface swims. Because the volume is a trigger, `onTrigger` fires on the way in and out. The water is not drawn: give the node a blended material, or none. Ends the script when the body is not static.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -3793,7 +3793,7 @@ cameraSet(node)
|
|
|
|
|
cameraSet(-1)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Makes a node the camera: the scene is drawn from its world position looking down its own -Z, so its parents' movement and rotation count. Any node will do, including one that also carries a mesh or a light, and switching cameras is one call. `-1` restores the default view from `(0, 0, 5)` looking at the origin. Deleting the camera node also falls back to the default view. Raises an error for a node handle that is not valid.
|
|
|
|
|
Makes a node the camera: the scene is drawn from its world position looking down its own -Z, so its parents' movement and rotation count. Any node will do, including one that also carries a mesh or a light, and switching cameras is one call. `-1` restores the default view from `(0, 0, 5)` looking at the origin. Deleting the camera node also falls back to the default view. Ends the script for a node handle that is not valid.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<nodelookat,nodeLookAt>>, <<camerasetperspective,cameraSetPerspective>>, <<viewsetcamera,viewSetCamera>>, <<nodenew,nodeNew>>
|
|
|
|
|
@ -5344,7 +5344,7 @@ emitter = emitterNew()
|
|
|
|
|
emitter = emitterNew(node)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Makes an emitter. With no argument it is a 2D one at overlay position `(0, 0)`, moved with `emitterSetPosition`; with a node it is a 3D one whose particles are born at that node's world position, and it needs the 3D scene, so on a machine without one the call raises an error (2D emitters work everywhere). A new emitter is not streaming; call `emitterStart` or `emitterBurst`. Deleting the node deletes its emitters. Defaults: 50 particles a second, living one to two seconds, 30 degree spread, white fading to transparent, normal blending, no gravity, drag, spin, radius, texture, trail or collision, a pool of 1000; a 2D emitter starts them up the screen at 50 to 100 overlay units a second shrinking from 16 to 4, a 3D one up the Y axis at 1 to 2 world units a second shrinking from 0.2 to 0.05.
|
|
|
|
|
Makes an emitter. With no argument it is a 2D one at overlay position `(0, 0)`, moved with `emitterSetPosition`; with a node it is a 3D one whose particles are born at that node's world position, and it needs the 3D scene, so on a machine without one the call ends the script (2D emitters work everywhere). A new emitter is not streaming; call `emitterStart` or `emitterBurst`. Deleting the node deletes its emitters. Defaults: 50 particles a second, living one to two seconds, 30 degree spread, white fading to transparent, normal blending, no gravity, drag, spin, radius, texture, trail or collision, a pool of 1000; a 2D emitter starts them up the screen at 50 to 100 overlay units a second shrinking from 16 to 4, a 3D one up the Y axis at 1 to 2 world units a second shrinking from 0.2 to 0.05.
|
|
|
|
|
|
|
|
|
|
*Returns:* The emitter handle.
|
|
|
|
|
|
|
|
|
|
@ -5374,7 +5374,7 @@ emitterStart(exhaust)
|
|
|
|
|
emitterDelete(emitter)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Removes the emitter, its live particles and its copy of the texture at once; nothing fades out. Use `emitterStop` instead to let the last particles finish. A 3D emitter is also removed on its own when its node is deleted. A handle that is not a live emitter raises an error, so clear the variable afterward.
|
|
|
|
|
Removes the emitter, its live particles and its copy of the texture at once; nothing fades out. Use `emitterStop` instead to let the last particles finish. A 3D emitter is also removed on its own when its node is deleted. A handle that is not a live emitter ends the script, so clear the variable afterward.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<emitternew,emitterNew>>, <<emitterstop,emitterStop>>, <<emitterisactive,emitterIsActive>>
|
|
|
|
|
@ -5452,7 +5452,7 @@ emitterSetFrames(debris, 4, 7)
|
|
|
|
|
emitterSetBlend(emitter, mode)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
How particles combine with what is behind them. `PARTICLE_ALPHA` (default) blends normally, for smoke, dust, rain and debris; `PARTICLE_ADD` adds light, for fire, sparks, glows and magic, and never darkens. Takes effect on the live particles at once. Anything other than those two constants raises an error.
|
|
|
|
|
How particles combine with what is behind them. `PARTICLE_ALPHA` (default) blends normally, for smoke, dust, rain and debris; `PARTICLE_ADD` adds light, for fire, sparks, glows and magic, and never darkens. Takes effect on the live particles at once. Anything other than those two constants ends the script.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<emittersetcolor,emitterSetColor>>, <<emittersettexture,emitterSetTexture>>
|
|
|
|
|
@ -5475,7 +5475,7 @@ emitterSetColor(smoke, 160, 160, 170, 120, 120, 120, 130, 0)
|
|
|
|
|
emitterSetLayer(emitter, layer)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
2D only: where `emitterDraw` puts the particles. `PARTICLE_OVER` (default) draws above everything on the overlay; `PARTICLE_UNDER` draws beneath the overlay and above the video and the 3D scene, for smoke behind the score. On a 3D emitter the setting is accepted and ignored. Anything other than those two constants raises an error.
|
|
|
|
|
2D only: where `emitterDraw` puts the particles. `PARTICLE_OVER` (default) draws above everything on the overlay; `PARTICLE_UNDER` draws beneath the overlay and above the video and the 3D scene, for smoke behind the score. On a 3D emitter the setting is accepted and ignored. Anything other than those two constants ends the script.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<emitterdraw,emitterDraw>>, <<emittersetposition,emitterSetPosition>>
|
|
|
|
|
@ -5731,7 +5731,7 @@ emitterSetCollide(emitter, mode, bounce, friction)
|
|
|
|
|
emitterSetCollide(emitter, mode, bounce, friction, floor)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
What particles bounce off. `COLLIDE_NONE` (default) is nothing; `COLLIDE_FLOOR` is a horizontal plane at height `floor`, below which (larger Y in 2D, smaller Y in 3D) a particle is put back on the plane and reflected; `COLLIDE_SCENE` is the physics world, for 3D emitters only, by a ray cast per particle along its motion each frame, capped at `200` casts per emitter per frame and resumed where they left off, so a big emitter spreads the cost over a few frames. On a 2D emitter `COLLIDE_SCENE` is accepted and does nothing. A mode other than those three raises an error.
|
|
|
|
|
What particles bounce off. `COLLIDE_NONE` (default) is nothing; `COLLIDE_FLOOR` is a horizontal plane at height `floor`, below which (larger Y in 2D, smaller Y in 3D) a particle is put back on the plane and reflected; `COLLIDE_SCENE` is the physics world, for 3D emitters only, by a ray cast per particle along its motion each frame, capped at `200` casts per emitter per frame and resumed where they left off, so a big emitter spreads the cost over a few frames. On a 2D emitter `COLLIDE_SCENE` is accepted and does nothing. A mode other than those three ends the script.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -5890,7 +5890,7 @@ emitterStart(aura)
|
|
|
|
|
emitterSetMax(emitter, count)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
The pool: how many particles may be alive at once, default `1000`. A full pool makes no more, from the stream or a burst, until some die. Changing the count rebuilds the pool and kills every live particle, so set it before starting. Size the pool to rate times longest life, plus the biggest burst. A count below `1` raises an error.
|
|
|
|
|
The pool: how many particles may be alive at once, default `1000`. A full pool makes no more, from the stream or a burst, until some die. Changing the count rebuilds the pool and kills every live particle, so set it before starting. Size the pool to rate times longest life, plus the biggest burst. A count below `1` ends the script.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<emittersetrate,emitterSetRate>>, <<emitterburst,emitterBurst>>, <<emittergetcount,emitterGetCount>>
|
|
|
|
|
@ -5914,7 +5914,7 @@ emitterStart(fountain)
|
|
|
|
|
emitterSetPosition(emitter, x, y)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
2D only: where new particles are born, in overlay coordinates; default `(0, 0)`. Set it every frame to follow a sprite or a 2D physics body. Live particles stay where they are unless `emitterSetLocal` is on. A 3D emitter follows its node and raises an error here; move the node instead.
|
|
|
|
|
2D only: where new particles are born, in overlay coordinates; default `(0, 0)`. Set it every frame to follow a sprite or a 2D physics body. Live particles stay where they are unless `emitterSetLocal` is on. A 3D emitter follows its node and ends the script here; move the node instead.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<emitterdraw,emitterDraw>>, <<emittersetlocal,emitterSetLocal>>, <<emittersetradius,emitterSetRadius>>
|
|
|
|
|
@ -6071,7 +6071,7 @@ end
|
|
|
|
|
emitterDraw(emitter)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
2D only, from `onOverlayUpdate`: queues the emitter's particles to be drawn this frame, above or beneath the overlay per `emitterSetLayer`, in overlay coordinates mapped onto the window. Emitters on the same layer draw in the order they were queued. The queue empties every frame, so the call belongs in every frame the particles should show; not drawing an emitter does not stop it. Up to `64` emitters per layer draw in a frame. A 3D emitter draws itself in the scene and raises an error here.
|
|
|
|
|
2D only, from `onOverlayUpdate`: queues the emitter's particles to be drawn this frame, above or beneath the overlay per `emitterSetLayer`, in overlay coordinates mapped onto the window. Emitters on the same layer draw in the order they were queued. The queue empties every frame, so the call belongs in every frame the particles should show; not drawing an emitter does not stop it. Up to `64` emitters per layer draw in a frame. A 3D emitter draws itself in the scene and ends the script here.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<emittersetlayer,emitterSetLayer>>, <<emittersetposition,emitterSetPosition>>, <<onoverlayupdate,onOverlayUpdate>>
|
|
|
|
|
@ -6336,7 +6336,7 @@ end
|
|
|
|
|
[#guiref]
|
|
|
|
|
=== Gui
|
|
|
|
|
|
|
|
|
|
A GUI is an RmlUi document tree of a fixed size rendered into its own texture every frame: `guiNew` makes one and returns an integer handle, `guiLoad` puts an RML document in it and returns a document handle, `guiDraw` composites it over the overlay and `materialSetGui` shows it on a material in the scene. Documents are HTML-like RML styled by CSS-like RCSS, loaded through the virtual file system like sprites; `Singe/gui.rcss` is the shipped theme and `Singe/FreeSansBold.ttf` the fallback face. The by-id helpers `guiGetValue`, `guiSetValue` and `guiSetHandler` reach elements without the object model; everything else is RmlUi's Lua API on the `rmlui` global, where a GUI is the context named `gui` followed by its handle. Up to sixteen GUIs exist at once, each with thirty-two documents. A GUI needs the GPU device, so `guiNew` raises an error on a machine without one; a bad GUI handle raises `No GUI N`, and a bad document handle `No document N in GUI G`. See <<gui,GUI>> in Game Development.
|
|
|
|
|
A GUI is an RmlUi document tree of a fixed size rendered into its own texture every frame: `guiNew` makes one and returns an integer handle, `guiLoad` puts an RML document in it and returns a document handle, `guiDraw` composites it over the overlay and `materialSetGui` shows it on a material in the scene. Documents are HTML-like RML styled by CSS-like RCSS, loaded through the virtual file system like sprites; `Singe/gui.rcss` is the shipped theme and `Singe/FreeSansBold.ttf` the fallback face. The by-id helpers `guiGetValue`, `guiSetValue` and `guiSetHandler` reach elements without the object model; everything else is RmlUi's Lua API on the `rmlui` global, where a GUI is the context named `gui` followed by its handle. Up to sixteen GUIs exist at once, each with thirty-two documents. A GUI needs the GPU device, so `guiNew` ends the script on a machine without one; a bad GUI handle raises `No GUI N`, and a bad document handle `No document N in GUI G`. See <<gui,GUI>> in Game Development.
|
|
|
|
|
|
|
|
|
|
[#guiclose]
|
|
|
|
|
==== guiClose
|
|
|
|
|
@ -6370,7 +6370,7 @@ end)
|
|
|
|
|
guiDelete(gui)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Frees the GUI, every document in it and its texture, and stops the per-frame update and render it cost. Materials showing it through `materialSetGui` go back to their own texture. The handle is invalid afterwards and raises an error if used again; since a GUI keeps rendering whether or not it is drawn, delete the ones a game is finished with rather than hiding them.
|
|
|
|
|
Frees the GUI, every document in it and its texture, and stops the per-frame update and render it cost. Materials showing it through `materialSetGui` go back to their own texture. The handle is invalid afterwards and ends the script if used again; since a GUI keeps rendering whether or not it is drawn, delete the ones a game is finished with rather than hiding them.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<guinew,guiNew>>, <<guiclose,guiClose>>, <<materialsetgui,materialSetGui>>
|
|
|
|
|
@ -6462,7 +6462,7 @@ end
|
|
|
|
|
height = guiGetHeight(gui)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
The GUI's height in its own pixels, as given to `guiNew`. Raises an error for a handle that is not valid.
|
|
|
|
|
The GUI's height in its own pixels, as given to `guiNew`. Ends the script for a handle that is not valid.
|
|
|
|
|
|
|
|
|
|
*Returns:* An integer.
|
|
|
|
|
|
|
|
|
|
@ -6509,7 +6509,7 @@ debugPrint(string.format("gui draws %d layers %d filters %d passes %d, %d KB of
|
|
|
|
|
value = guiGetValue(gui, document, id)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
The value of the element with that `id` in the document, as a string: a form control's value (a text field's text, a `select` option's `value`, a range in RmlUi's own formatting such as `"85.000000"`, a checkbox's or radio button's `value` attribute, `"on"` when it has none, whether or not it is checked; its state is its `checked` attribute, read through RmlUi's API), or, for any other element, its inner RML. Returns `nil` when no element has that id, so a page can be probed without an error; a bad GUI or document handle raises one. Values longer than 4095 characters are cut.
|
|
|
|
|
The value of the element with that `id` in the document, as a string: a form control's value (a text field's text, a `select` option's `value`, a range in RmlUi's own formatting such as `"85.000000"`, a checkbox's or radio button's `value` attribute, `"on"` when it has none, whether or not it is checked; its state is its `checked` attribute, read through RmlUi's API), or, for any other element, its inner RML. Returns `nil` when no element has that id, so a page can be probed without ending the script; a bad GUI or document handle ends it. Values longer than 4095 characters are cut.
|
|
|
|
|
|
|
|
|
|
*Returns:* A string, or `nil`.
|
|
|
|
|
|
|
|
|
|
@ -6535,7 +6535,7 @@ end)
|
|
|
|
|
width = guiGetWidth(gui)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
The GUI's width in its own pixels, as given to `guiNew`. Raises an error for a handle that is not valid.
|
|
|
|
|
The GUI's width in its own pixels, as given to `guiNew`. Ends the script for a handle that is not valid.
|
|
|
|
|
|
|
|
|
|
*Returns:* An integer.
|
|
|
|
|
|
|
|
|
|
@ -6671,7 +6671,7 @@ end
|
|
|
|
|
guiRefresh(gui)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Draws the GUI again on the next frame even if nothing about it seems to have changed. A GUI is only redrawn when its picture changes: when a frame's document draws exactly what the last frame drew, and nothing new was made in between, the texture already holds that picture and is kept, which saves the GPU most of a GUI's cost on the frames a HUD or a menu stands still. Changes made through RML, RCSS, the RmlUi Lua interface or the `gui*` calls are all seen. This call is the way out should one ever be missed -- a GUI that stops updating when it should -- and a game should not need it; if it does, that is worth reporting. A GUI that does not exist raises an error.
|
|
|
|
|
Draws the GUI again on the next frame even if nothing about it seems to have changed. A GUI is only redrawn when its picture changes: when a frame's document draws exactly what the last frame drew, and nothing new was made in between, the texture already holds that picture and is kept, which saves the GPU most of a GUI's cost on the frames a HUD or a menu stands still. Changes made through RML, RCSS, the RmlUi Lua interface or the `gui*` calls are all seen. This call is the way out should one ever be missed -- a GUI that stops updating when it should -- and a game should not need it; if it does, that is worth reporting. A GUI that does not exist ends the script.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<guidraw,guiDraw>>, <<guigetstats,guiGetStats>>
|
|
|
|
|
@ -6728,7 +6728,7 @@ end)
|
|
|
|
|
guiSetInput(gui, enabled)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Whether the mouse and light gun, keys, typed text and the framework switches from a pad or mouse reach the GUI. A new GUI only displays, which suits a HUD or a sign; turn input on for a menu or a form. While it is on, the pointer reaches the GUI wherever it is drawn flat (the last drawn on top) or shown on a surface in the scene, every key goes to it except `Tab`, which the GUI is given only while a text field is being typed in (RmlUi uses it to move focus and never hands it back, and a game whose keys include `Tab` would otherwise lose it), a text field with focus turns on SDL's text input, and the pad's directions arrive as arrow keys with `ACTION_1` as Return and `ACTION_2` as Escape. What an element uses never reaches `onInputPressed`, `onKeyPressed` or the mouse callbacks; what nothing used falls through to them as usual. Raises an error for a handle that is not valid.
|
|
|
|
|
Whether the mouse and light gun, keys, typed text and the framework switches from a pad or mouse reach the GUI. A new GUI only displays, which suits a HUD or a sign; turn input on for a menu or a form. While it is on, the pointer reaches the GUI wherever it is drawn flat (the last drawn on top) or shown on a surface in the scene, every key goes to it except `Tab`, which the GUI is given only while a text field is being typed in (RmlUi uses it to move focus and never hands it back, and a game whose keys include `Tab` would otherwise lose it), a text field with focus turns on SDL's text input, and the pad's directions arrive as arrow keys with `ACTION_1` as Return and `ACTION_2` as Escape. What an element uses never reaches `onInputPressed`, `onKeyPressed` or the mouse callbacks; what nothing used falls through to them as usual. Ends the script for a handle that is not valid.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<guisethandler,guiSetHandler>>, <<guidraw,guiDraw>>, <<sceneprobegui,sceneProbeGui>>
|
|
|
|
|
@ -6805,7 +6805,7 @@ end
|
|
|
|
|
[#joint]
|
|
|
|
|
=== Joint
|
|
|
|
|
|
|
|
|
|
Joints connect two bodies, or a body and the world when the second node is `-1`, and hand back an integer joint handle that the other calls take. Anchors and axes are given in world space at the moment the joint is made, with the bodies where they are then, so place the nodes and give them bodies before jointing them. Distances are in world units and hinge angles in degrees. Deleting either body, or its node, deletes the joint; a handle that has been deleted raises an error. See <<physics,Physics>> in Game Development, Joints.
|
|
|
|
|
Joints connect two bodies, or a body and the world when the second node is `-1`, and hand back an integer joint handle that the other calls take. Anchors and axes are given in world space at the moment the joint is made, with the bodies where they are then, so place the nodes and give them bodies before jointing them. Distances are in world units and hinge angles in degrees. Deleting either body, or its node, deletes the joint; a handle that has been deleted ends the script. See <<physics,Physics>> in Game Development, Joints.
|
|
|
|
|
|
|
|
|
|
[#jointhinge]
|
|
|
|
|
==== jointHinge
|
|
|
|
|
@ -6815,7 +6815,7 @@ Joints connect two bodies, or a body and the world when the second node is `-1`,
|
|
|
|
|
joint = jointHinge(nodeA, nodeB, ax, ay, az, dx, dy, dz)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Makes a hinge between the two bodies through the world point `(ax, ay, az)` along the axis `(dx, dy, dz)`: a door, a wheel, a lever, a seesaw. The bodies keep that point and axis in common and may only turn about it. The axis is normalized, so its length does not matter; a zero axis becomes `(0, 1, 0)`. Both nodes must carry a body, or `nodeB` may be `-1` to hinge `nodeA` to the world. Raises an error when a node has no body or the joint cannot be made.
|
|
|
|
|
Makes a hinge between the two bodies through the world point `(ax, ay, az)` along the axis `(dx, dy, dz)`: a door, a wheel, a lever, a seesaw. The bodies keep that point and axis in common and may only turn about it. The axis is normalized, so its length does not matter; a zero axis becomes `(0, 1, 0)`. Both nodes must carry a body, or `nodeB` may be `-1` to hinge `nodeA` to the world. Ends the script when a node has no body or the joint cannot be made.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -6852,7 +6852,7 @@ bodyApplyImpulse(door, 0, 0, -60, 0.5, -0.62, 1.45)
|
|
|
|
|
joint = jointBall(nodeA, nodeB, ax, ay, az)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Makes a ball-and-socket joint at the world point `(ax, ay, az)`: the bodies may turn any way about it but cannot separate. A pendulum, a chain link, a hanging sign, a ragdoll shoulder. Both nodes must carry a body, or `nodeB` may be `-1` to hang `nodeA` from a fixed point in the world. A ball joint has no limits, so `jointSetLimits` refuses it. Raises an error when a node has no body or the joint cannot be made.
|
|
|
|
|
Makes a ball-and-socket joint at the world point `(ax, ay, az)`: the bodies may turn any way about it but cannot separate. A pendulum, a chain link, a hanging sign, a ragdoll shoulder. Both nodes must carry a body, or `nodeB` may be `-1` to hang `nodeA` from a fixed point in the world. A ball joint has no limits, so `jointSetLimits` refuses it. Ends the script when a node has no body or the joint cannot be made.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -6889,7 +6889,7 @@ end
|
|
|
|
|
joint = jointSlider(nodeA, nodeB, ax, ay, az, dx, dy, dz)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Lets the bodies slide relative to each other only along the axis `(dx, dy, dz)` through the anchor `(ax, ay, az)`, keeping their orientation: a drawer, a piston, a lift, a sliding door. The axis is normalized, so its length does not matter; a zero axis becomes `(0, 1, 0)`. Both nodes must carry a body, or `nodeB` may be `-1` to run `nodeA` along a rail fixed in the world. Raises an error when a node has no body or the joint cannot be made.
|
|
|
|
|
Lets the bodies slide relative to each other only along the axis `(dx, dy, dz)` through the anchor `(ax, ay, az)`, keeping their orientation: a drawer, a piston, a lift, a sliding door. The axis is normalized, so its length does not matter; a zero axis becomes `(0, 1, 0)`. Both nodes must carry a body, or `nodeB` may be `-1` to run `nodeA` along a rail fixed in the world. Ends the script when a node has no body or the joint cannot be made.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -6924,7 +6924,7 @@ bodySetVelocity(crate, 3, 0, 0)
|
|
|
|
|
jointSetLimits(joint, low, high)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Bounds a hinge's angle in degrees, or a slider's travel in world units, either side of where the joint started. A positive hinge angle is a right-hand turn of `nodeA` about the axis; a positive slider distance is along the axis. `low` is clamped to at most `0` and `high` to at least `0`, so the starting pose is always inside the range. Call it again to change the range at any time. Raises an error for a ball joint or a handle that no longer exists.
|
|
|
|
|
Bounds a hinge's angle in degrees, or a slider's travel in world units, either side of where the joint started. A positive hinge angle is a right-hand turn of `nodeA` about the axis; a positive slider distance is along the axis. `low` is clamped to at most `0` and `high` to at least `0`, so the starting pose is always inside the range. Call it again to change the range at any time. Ends the script for a ball joint or a handle that no longer exists.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -6961,7 +6961,7 @@ end
|
|
|
|
|
jointDelete(joint)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Removes the joint; the bodies are free of each other again and keep whatever velocity they had. Joints also go away with either of their bodies, so this is only needed to free two bodies that both stay. Raises an error for a handle that does not exist or was already deleted.
|
|
|
|
|
Removes the joint; the bodies are free of each other again and keep whatever velocity they had. Joints also go away with either of their bodies, so this is only needed to free two bodies that both stay. Ends the script for a handle that does not exist or was already deleted.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<jointhinge,jointHinge>>, <<jointball,jointBall>>, <<bodydelete,bodyDelete>>
|
|
|
|
|
@ -7264,7 +7264,7 @@ end
|
|
|
|
|
[#light]
|
|
|
|
|
=== Light
|
|
|
|
|
|
|
|
|
|
Lights are nodes carrying a light, made by `lightNew` and moved, parented and animated with the node calls. Up to eight visible lights shine in a frame, in node order; `sceneSetAmbient` and a sky from `sceneSetSky` add light from everywhere. Directional and spot lights shine down the node's -Z, so aim them with `nodeLookAt` or `nodeSetRotation`; point lights only need a position. Colors are integers from `0` to `255`, intensities are multipliers in the scene's linear light, angles are degrees, and distances are world units. Every `lightSet*` call raises an error for a node that does not carry a light. See <<scenes3d,3D Scenes>> for lighting, exposure and shadows.
|
|
|
|
|
Lights are nodes carrying a light, made by `lightNew` and moved, parented and animated with the node calls. Up to eight visible lights shine in a frame, in node order; `sceneSetAmbient` and a sky from `sceneSetSky` add light from everywhere. Directional and spot lights shine down the node's -Z, so aim them with `nodeLookAt` or `nodeSetRotation`; point lights only need a position. Colors are integers from `0` to `255`, intensities are multipliers in the scene's linear light, angles are degrees, and distances are world units. Every `lightSet*` call ends the script for a node that does not carry a light. See <<scenes3d,3D Scenes>> for lighting, exposure and shadows.
|
|
|
|
|
|
|
|
|
|
[#lightnew]
|
|
|
|
|
==== lightNew
|
|
|
|
|
@ -7275,7 +7275,7 @@ node = lightNew(type)
|
|
|
|
|
node = lightNew(type, parent)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Makes a new node carrying a light and returns the node handle. The light starts white at intensity `1`, with no range limit and, for a spot, a cone of `20` to `30` degrees. Place and aim it with the node calls: `nodeSetPosition` for a point or spot light, `nodeLookAt` for a directional or spot light. A light parented to a moving node moves with it, so a headlight on a car or a torch in a hand is one call. Raises an error for an unknown type or when no node can be made.
|
|
|
|
|
Makes a new node carrying a light and returns the node handle. The light starts white at intensity `1`, with no range limit and, for a spot, a cone of `20` to `30` degrees. Place and aim it with the node calls: `nodeSetPosition` for a point or spot light, `nodeLookAt` for a directional or spot light. A light parented to a moving node moves with it, so a headlight on a car or a torch in a hand is one call. Ends the script for an unknown type or when no node can be made.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -7317,7 +7317,7 @@ lightSetIntensity(headlight, 30)
|
|
|
|
|
lightSetColor(node, r, g, b)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
The light's color, `0` to `255` per channel (out-of-range values are clamped), treated as sRGB; white by default. Brightness belongs in `lightSetIntensity`, so keep the color for the hue (a warm `255, 230, 190` bulb, a cool `150, 190, 255` moon) and leave at least one channel near `255`. Raises an error when the node carries no light.
|
|
|
|
|
The light's color, `0` to `255` per channel (out-of-range values are clamped), treated as sRGB; white by default. Brightness belongs in `lightSetIntensity`, so keep the color for the hue (a warm `255, 230, 190` bulb, a cool `150, 190, 255` moon) and leave at least one channel near `255`. Ends the script when the node carries no light.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<lightsetintensity,lightSetIntensity>>, <<lightnew,lightNew>>
|
|
|
|
|
@ -7347,7 +7347,7 @@ end
|
|
|
|
|
lightSetCone(node, innerDegrees, outerDegrees)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
The shape of a spot light's cone, both angles measured from the axis (the node's -Z): full brightness within `innerDegrees`, fading smoothly to nothing at `outerDegrees`. The defaults are `20` and `30`. A narrow gap between the two gives a hard-edged theater spot, a wide one a soft pool. The values are stored for every light but only a `LIGHT_SPOT` uses them. Raises an error when the node carries no light.
|
|
|
|
|
The shape of a spot light's cone, both angles measured from the axis (the node's -Z): full brightness within `innerDegrees`, fading smoothly to nothing at `outerDegrees`. The defaults are `20` and `30`. A narrow gap between the two gives a hard-edged theater spot, a wide one a soft pool. The values are stored for every light but only a `LIGHT_SPOT` uses them. Ends the script when the node carries no light.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -7379,7 +7379,7 @@ lightSetShadow(spot, true)
|
|
|
|
|
lightSetIntensity(node, intensity)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
The light's brightness multiplier in the scene's linear light, default `1`. A directional light of intensity `1` lights a white surface facing it to white. A point or spot light fades with distance as `1 / (1 + d^2)`, so its intensity is the brightness at the light itself, half of it one unit away and a hundredth ten units away; bulbs usually want values well above `1`, `10` to `50` for a room, and `sceneSetExposure` brings the whole scene back into range. Raises an error when the node carries no light.
|
|
|
|
|
The light's brightness multiplier in the scene's linear light, default `1`. A directional light of intensity `1` lights a white surface facing it to white. A point or spot light fades with distance as `1 / (1 + d^2)`, so its intensity is the brightness at the light itself, half of it one unit away and a hundredth ten units away; bulbs usually want values well above `1`, `10` to `50` for a room, and `sceneSetExposure` brings the whole scene back into range. Ends the script when the node carries no light.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<lightsetrange,lightSetRange>>, <<scenesetexposure,sceneSetExposure>>, <<lightsetcolor,lightSetColor>>
|
|
|
|
|
@ -7407,7 +7407,7 @@ end
|
|
|
|
|
lightSetRange(node, range)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
How far a point or spot light reaches, in world units; `0` (the default) means no limit. The light fades to exactly nothing at the range, on top of its distance falloff, so lights do not pop as objects cross it. A range also bounds how far a shadow-casting light's shadow map has to reach, which keeps its shadows sharp. Directional lights ignore it. Raises an error when the node carries no light.
|
|
|
|
|
How far a point or spot light reaches, in world units; `0` (the default) means no limit. The light fades to exactly nothing at the range, on top of its distance falloff, so lights do not pop as objects cross it. A range also bounds how far a shadow-casting light's shadow map has to reach, which keeps its shadows sharp. Directional lights ignore it. Ends the script when the node carries no light.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<lightsetintensity,lightSetIntensity>>, <<lightsetshadow,lightSetShadow>>
|
|
|
|
|
@ -7433,7 +7433,7 @@ end
|
|
|
|
|
lightSetShadow(node, shadow)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Makes the light cast shadows from everything opaque in the scene, or stops it; off by default. Any of the eight lights may cast, in any mix. A spot light gets one shadow map; a directional light gets one map per cascade (`sceneSetShadowCascades`); a point light gets a cube map of six views, which covers every direction (a bulb inside a room) at six times the cost. `nodeSetShadow` excuses a mesh from casting. Raises an error when the node carries no light.
|
|
|
|
|
Makes the light cast shadows from everything opaque in the scene, or stops it; off by default. Any of the eight lights may cast, in any mix. A spot light gets one shadow map; a directional light gets one map per cascade (`sceneSetShadowCascades`); a point light gets a cube map of six views, which covers every direction (a bulb inside a room) at six times the cost. `nodeSetShadow` excuses a mesh from casting. Ends the script when the node carries no light.
|
|
|
|
|
|
|
|
|
|
*Notes:* Each shadow map costs one extra pass over the scene per frame, a cube map six, and a cascaded sun as many as it has cascades; the maps' size is set by `sceneSetShadowSize`. A modern integrated GPU manages eight casters comfortably; a Raspberry Pi wants one or two at `512`.
|
|
|
|
|
|
|
|
|
|
@ -7460,7 +7460,7 @@ nodeSetShadow(bulbGlass, false)
|
|
|
|
|
[#material]
|
|
|
|
|
=== Material
|
|
|
|
|
|
|
|
|
|
A material is how a mesh looks: a base color with alpha, an optional base texture from a sprite, a KTX2 file, a video or a rendered view, and the glTF metallic-roughness parameters with four optional maps. `materialNew` returns an integer handle; pass it to `nodeSetMesh` or `nodeSetMaterial`, and to every `materialSet*` call. Materials are shared, so changing one changes every mesh drawn with it, and a node without one draws white and half rough. Colors are integers from `0` to `255` per channel and are treated as sRGB; factors such as roughness run from `0` to `1`. A bad handle raises an error. See <<scenes3d,3D Scenes>> for how materials are lit.
|
|
|
|
|
A material is how a mesh looks: a base color with alpha, an optional base texture from a sprite, a KTX2 file, a video or a rendered view, and the glTF metallic-roughness parameters with four optional maps. `materialNew` returns an integer handle; pass it to `nodeSetMesh` or `nodeSetMaterial`, and to every `materialSet*` call. Materials are shared, so changing one changes every mesh drawn with it, and a node without one draws white and half rough. Colors are integers from `0` to `255` per channel and are treated as sRGB; factors such as roughness run from `0` to `1`. A bad handle ends the script. See <<scenes3d,3D Scenes>> for how materials are lit.
|
|
|
|
|
|
|
|
|
|
[#materialnew]
|
|
|
|
|
==== materialNew
|
|
|
|
|
@ -7470,7 +7470,7 @@ A material is how a mesh looks: a base color with alpha, an optional base textur
|
|
|
|
|
material = materialNew()
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Allocates a new material and returns its handle. It starts white and opaque (color `255, 255, 255, 255`), with roughness `0.5`, metallic `0`, no emissive color, tiling `1, 1`, linear filtering, single sided, lit, and no texture or maps. Set what differs from that and hand the handle to `nodeSetMesh`. Loaded models bring their own materials, so this is for meshes built from script. Raises an error on a machine with no usable GPU.
|
|
|
|
|
Allocates a new material and returns its handle. It starts white and opaque (color `255, 255, 255, 255`), with roughness `0.5`, metallic `0`, no emissive color, tiling `1, 1`, linear filtering, single sided, lit, and no texture or maps. Set what differs from that and hand the handle to `nodeSetMesh`. Loaded models bring their own materials, so this is for meshes built from script. Ends the script on a machine with no usable GPU.
|
|
|
|
|
|
|
|
|
|
*Returns:* The material handle, an integer.
|
|
|
|
|
|
|
|
|
|
@ -7503,7 +7503,7 @@ nodeSetMesh(trophy, meshCone(0.3, 0.8, 24), gold)
|
|
|
|
|
materialDelete(material)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Frees the material and any texture it uploaded. Every node that was drawn with it falls back to the default look (white, half rough), so reassign those nodes with `nodeSetMaterial` first if they should keep a look. The handle is invalid afterwards and raises an error if used again. The private material a node makes for itself under `nodeSetSprite` or `nodeSetText` belongs to the node and cannot be deleted; the call raises an error, and clearing the sprite or text frees it. Materials are cheap; deleting them matters mostly for ones that carried large textures.
|
|
|
|
|
Frees the material and any texture it uploaded. Every node that was drawn with it falls back to the default look (white, half rough), so reassign those nodes with `nodeSetMaterial` first if they should keep a look. The handle is invalid afterwards and ends the script if used again. The private material a node makes for itself under `nodeSetSprite` or `nodeSetText` belongs to the node and cannot be deleted; the call ends the script, and clearing the sprite or text frees it. Materials are cheap; deleting them matters mostly for ones that carried large textures.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<materialnew,materialNew>>, <<nodesetmaterial,nodeSetMaterial>>
|
|
|
|
|
@ -7659,7 +7659,7 @@ materialSetEmissiveMap(material, nil)
|
|
|
|
|
materialSetEmissiveMap(material)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
A texture saying which parts of the surface glow. Its color is multiplied by the color from `materialSetEmissive`, so set that too: white to use the map's own colors, or a tint. The image comes from a loaded sprite (a copy is uploaded, so the sprite may be unloaded afterwards) or from a `.ktx2` file by name, kept compressed on the GPU. With `nil` or no second argument the map is removed. Raises an error when the texture cannot be uploaded or the file is not a KTX2 texture.
|
|
|
|
|
A texture saying which parts of the surface glow. Its color is multiplied by the color from `materialSetEmissive`, so set that too: white to use the map's own colors, or a tint. The image comes from a loaded sprite (a copy is uploaded, so the sprite may be unloaded afterwards) or from a `.ktx2` file by name, kept compressed on the GPU. With `nil` or no second argument the map is removed. Ends the script when the texture cannot be uploaded or the file is not a KTX2 texture.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<materialsetemissive,materialSetEmissive>>, <<materialsettexture,materialSetTexture>>, <<materialsettiling,materialSetTiling>>
|
|
|
|
|
@ -7688,7 +7688,7 @@ end
|
|
|
|
|
materialSetFilter(material, filter)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
How the material's textures are sampled. `FILTER_LINEAR` (the default) blends between texels and between mipmap levels, with anisotropic filtering on surfaces seen at a grazing angle. `FILTER_NEAREST` picks the closest texel and the closest mipmap level, so pixel art stays crisp on a quad. Every texture carries a full mipmap chain, so a texture seen small never sparkles either way. Any other value raises an error.
|
|
|
|
|
How the material's textures are sampled. `FILTER_LINEAR` (the default) blends between texels and between mipmap levels, with anisotropic filtering on surfaces seen at a grazing angle. `FILTER_NEAREST` picks the closest texel and the closest mipmap level, so pixel art stays crisp on a quad. Every texture carries a full mipmap chain, so a texture seen small never sparkles either way. Any other value ends the script.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<materialsettexture,materialSetTexture>>, <<materialsetunlit,materialSetUnlit>>
|
|
|
|
|
@ -7715,7 +7715,7 @@ materialSetGui(material, nil)
|
|
|
|
|
materialSetGui(material)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Shows a GUI from `guiNew` as the material's base color texture, updated every frame: a monitor, a cockpit panel, a sign, with the same document a `guiDraw` would show flat. Usually paired with `materialSetUnlit` so the page is not shaded by the lights, and tinted by the base color like any texture. With `nil` or no second argument the material goes back to its own texture, which is kept underneath; deleting the GUI does the same. Setting a GUI drops any video or view the material was showing. While the GUI takes input, the mouse or a light gun pointing at a surface drawn with the material reaches it through the same probe as `sceneProbeGui`. Raises an error for a GUI handle that is not valid.
|
|
|
|
|
Shows a GUI from `guiNew` as the material's base color texture, updated every frame: a monitor, a cockpit panel, a sign, with the same document a `guiDraw` would show flat. Usually paired with `materialSetUnlit` so the page is not shaded by the lights, and tinted by the base color like any texture. With `nil` or no second argument the material goes back to its own texture, which is kept underneath; deleting the GUI does the same. Setting a GUI drops any video or view the material was showing. While the GUI takes input, the mouse or a light gun pointing at a surface drawn with the material reaches it through the same probe as `sceneProbeGui`. Ends the script for a GUI handle that is not valid.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<guinew,guiNew>>, <<guidraw,guiDraw>>, <<sceneprobegui,sceneProbeGui>>, <<materialsetview,materialSetView>>, <<materialsetvideo,materialSetVideo>>, <<materialsetunlit,materialSetUnlit>>
|
|
|
|
|
@ -7773,7 +7773,7 @@ materialSetMetallicRoughnessMap(material, nil)
|
|
|
|
|
materialSetMetallicRoughnessMap(material)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
A texture varying the finish across the surface: its green channel multiplies the roughness from `materialSetRoughness` and its blue channel the metallic value from `materialSetMetallic`, the way glTF packs them, so a map from a glTF tool works as is. Set both factors to `1` to use the map's values alone. The image comes from a sprite or a `.ktx2` file by name; `nil` or no second argument removes the map. Raises an error when the texture cannot be uploaded.
|
|
|
|
|
A texture varying the finish across the surface: its green channel multiplies the roughness from `materialSetRoughness` and its blue channel the metallic value from `materialSetMetallic`, the way glTF packs them, so a map from a glTF tool works as is. Set both factors to `1` to use the map's values alone. The image comes from a sprite or a `.ktx2` file by name; `nil` or no second argument removes the map. Ends the script when the texture cannot be uploaded.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<materialsetmetallic,materialSetMetallic>>, <<materialsetroughness,materialSetRoughness>>, <<materialsettexture,materialSetTexture>>
|
|
|
|
|
@ -7804,7 +7804,7 @@ materialSetNormalMap(material, nil)
|
|
|
|
|
materialSetNormalMap(material)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
A tangent-space normal map (the usual bluish kind, flat at `128, 128, 255`) that tilts the lighting per texel so bricks, grooves and rivets catch the light without extra geometry. Every mesh has tangents for it: a model's own when the file carries them, otherwise computed from the UVs. The image comes from a sprite or a `.ktx2` file by name; `nil` or no second argument removes the map. Raises an error when the texture cannot be uploaded.
|
|
|
|
|
A tangent-space normal map (the usual bluish kind, flat at `128, 128, 255`) that tilts the lighting per texel so bricks, grooves and rivets catch the light without extra geometry. Every mesh has tangents for it: a model's own when the file carries them, otherwise computed from the UVs. The image comes from a sprite or a `.ktx2` file by name; `nil` or no second argument removes the map. Ends the script when the texture cannot be uploaded.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -7874,7 +7874,7 @@ materialSetOcclusionMap(material, nil)
|
|
|
|
|
materialSetOcclusionMap(material)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
An ambient occlusion map, occlusion in the red channel (white for open, dark for crevices), that darkens the ambient and sky light in corners and folds. Direct light from light nodes is not affected, as in glTF. The image comes from a sprite or a `.ktx2` file by name; `nil` or no second argument removes the map. Raises an error when the texture cannot be uploaded.
|
|
|
|
|
An ambient occlusion map, occlusion in the red channel (white for open, dark for crevices), that darkens the ambient and sky light in corners and folds. Direct light from light nodes is not affected, as in glTF. The image comes from a sprite or a `.ktx2` file by name; `nil` or no second argument removes the map. Ends the script when the texture cannot be uploaded.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -7939,7 +7939,7 @@ materialSetTexture(material, nil)
|
|
|
|
|
materialSetTexture(material)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Uses a sprite's image as the base color texture (a copy is uploaded, so the sprite may be unloaded afterwards), or a KTX2 file by name, kept compressed on the GPU in the block format the machine has (see Compressed textures in <<scenes3d,3D Scenes>>). With `nil` or no second argument the texture is removed and the material shows its base color alone. Setting a texture also drops any video or view the material was showing. Texture coordinates come from the mesh; the primitives map an image once across each face, and `materialSetTiling` repeats it. A name that is not a KTX2 file raises an error (load other pictures with `spriteLoad`), as does a failed upload.
|
|
|
|
|
Uses a sprite's image as the base color texture (a copy is uploaded, so the sprite may be unloaded afterwards), or a KTX2 file by name, kept compressed on the GPU in the block format the machine has (see Compressed textures in <<scenes3d,3D Scenes>>). With `nil` or no second argument the texture is removed and the material shows its base color alone. Setting a texture also drops any video or view the material was showing. Texture coordinates come from the mesh; the primitives map an image once across each face, and `materialSetTiling` repeats it. A name that is not a KTX2 file ends the script (load other pictures with `spriteLoad`), as does a failed upload.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<spriteload,spriteLoad>>, <<materialsettiling,materialSetTiling>>, <<materialsetvideo,materialSetVideo>>, <<materialsetview,materialSetView>>
|
|
|
|
|
@ -8027,7 +8027,7 @@ materialSetView(material, nil)
|
|
|
|
|
materialSetView(material)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Shows a rendered view from `viewNew` as the material's base color texture, updated every frame: a security monitor, a rear-view mirror, a portal. Usually paired with `materialSetUnlit` so the picture is not shaded by the lights, and tinted by the base color like any texture. With `nil` or no second argument the material goes back to its own texture, which is kept underneath. Setting a view drops any video the material was showing. Raises an error for a view handle that is not valid.
|
|
|
|
|
Shows a rendered view from `viewNew` as the material's base color texture, updated every frame: a security monitor, a rear-view mirror, a portal. Usually paired with `materialSetUnlit` so the picture is not shaded by the lights, and tinted by the base color like any texture. With `nil` or no second argument the material goes back to its own texture, which is kept underneath. Setting a view drops any video the material was showing. Ends the script for a view handle that is not valid.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<viewnew,viewNew>>, <<viewsetcamera,viewSetCamera>>, <<materialsetvideo,materialSetVideo>>, <<materialsetunlit,materialSetUnlit>>
|
|
|
|
|
@ -8058,7 +8058,7 @@ materialSetVideo(material, video)
|
|
|
|
|
|
|
|
|
|
Uses the laserdisc (no `video`) or a video loaded with `videoLoad` as the base color texture, updated every frame while it plays. Usually paired with `materialSetUnlit` so the picture is not tinted by the lights. The video keeps playing whether or not it is also drawn on the overlay, and several materials may show the same one. Setting a video drops any texture or view the material had; `materialSetTexture` takes it off again.
|
|
|
|
|
|
|
|
|
|
*Notes:* The disc form raises an error in a game without a disc; a bad video handle raises one too.
|
|
|
|
|
*Notes:* The disc form ends the script in a game without a disc, and so does a bad video handle.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<videoload,videoLoad>>, <<materialsetunlit,materialSetUnlit>>, <<materialsettexture,materialSetTexture>>
|
|
|
|
|
@ -9162,7 +9162,7 @@ end
|
|
|
|
|
modelDelete(model)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Frees the model's meshes, materials and parsed data. Every instance made from it is forgotten at the same time: its nodes stay in the scene (position, parent and children intact) but draw nothing, its animations stop where they are, and a later `animation*` call on its root raises an error because the node is no longer a model instance. Delete the instance roots with `nodeDelete` when the nodes are not wanted either. A handle that is not a loaded model raises an error.
|
|
|
|
|
Frees the model's meshes, materials and parsed data. Every instance made from it is forgotten at the same time: its nodes stay in the scene (position, parent and children intact) but draw nothing, its animations stop where they are, and a later `animation*` call on its root ends the script because the node is no longer a model instance. Delete the instance roots with `nodeDelete` when the nodes are not wanted either. A handle that is not a loaded model ends the script.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<modelload,modelLoad>>, <<modelinstance,modelInstance>>, <<nodedelete,nodeDelete>>
|
|
|
|
|
@ -9189,7 +9189,7 @@ end
|
|
|
|
|
names = modelGetAnimations(model)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Lists the model's animation clips in file order as a table of strings, so `names[3]` is the clip that `animationPlay(node, 3)` plays. A clip the exporter left unnamed gives an empty string; it can still be played by number. A model with no animations gives an empty table. A handle that is not a loaded model raises an error.
|
|
|
|
|
Lists the model's animation clips in file order as a table of strings, so `names[3]` is the clip that `animationPlay(node, 3)` plays. A clip the exporter left unnamed gives an empty string; it can still be played by number. A model with no animations gives an empty table. A handle that is not a loaded model ends the script.
|
|
|
|
|
|
|
|
|
|
*Returns:* A table of strings indexed from `1`.
|
|
|
|
|
|
|
|
|
|
@ -9219,7 +9219,7 @@ node = modelInstance(model)
|
|
|
|
|
node = modelInstance(model, parent)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Builds the model's node tree under a new root node, itself under `parent` or the scene root. The root is a plain node: position, rotate, scale or parent it like any other, and delete it with `nodeDelete` to remove the whole instance. The model's own nodes take their glTF names (or their mesh's name when the node is unnamed) so `nodeFind(name, node)` reaches them; a mesh with several materials becomes one child node per part; lights in the file become scene lights with the file's color, intensity, range and cone; skins are attached and morph weights set. The nodes stand in the file's pose until an animation plays. A handle that is not a loaded model or a `parent` that is not a node raises an error, as does running out of nodes.
|
|
|
|
|
Builds the model's node tree under a new root node, itself under `parent` or the scene root. The root is a plain node: position, rotate, scale or parent it like any other, and delete it with `nodeDelete` to remove the whole instance. The model's own nodes take their glTF names (or their mesh's name when the node is unnamed) so `nodeFind(name, node)` reaches them; a mesh with several materials becomes one child node per part; lights in the file become scene lights with the file's color, intensity, range and cone; skins are attached and morph weights set. The nodes stand in the file's pose until an animation plays. A handle that is not a loaded model or a `parent` that is not a node ends the script, as does running out of nodes.
|
|
|
|
|
|
|
|
|
|
*Returns:* The instance's root node handle.
|
|
|
|
|
|
|
|
|
|
@ -9761,7 +9761,7 @@ musicUnload(theme)
|
|
|
|
|
[#nav]
|
|
|
|
|
=== Nav
|
|
|
|
|
|
|
|
|
|
Navigation meshes baked from scene geometry, and the crowd agents that walk them (see <<scenes3d,3D Scenes>>, Navigation). `navNew` and `navLoad` return a mesh handle and `navAgentNew` an agent handle; both are integers, checked on every call, and an invalid one terminates the script. Positions are world units, speeds units a second and slopes degrees. Up to eight meshes at once, 128 agents on each and 256 in all. The queries and the agents need a mesh that `navBuild` has baked or `navLoad` has read; before that the queries return `nil`, `navDraw` draws nothing and `navAgentNew` raises an error.
|
|
|
|
|
Navigation meshes baked from scene geometry, and the crowd agents that walk them (see <<scenes3d,3D Scenes>>, Navigation). `navNew` and `navLoad` return a mesh handle and `navAgentNew` an agent handle; both are integers, checked on every call, and an invalid one terminates the script. Positions are world units, speeds units a second and slopes degrees. Up to eight meshes at once, 128 agents on each and 256 in all. The queries and the agents need a mesh that `navBuild` has baked or `navLoad` has read; before that the queries return `nil`, `navDraw` draws nothing and `navAgentNew` ends the script.
|
|
|
|
|
|
|
|
|
|
[#navaddnode]
|
|
|
|
|
==== navAddNode
|
|
|
|
|
@ -9771,7 +9771,7 @@ Navigation meshes baked from scene geometry, and the crowd agents that walk them
|
|
|
|
|
navAddNode(nav, node)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Adds the node's mesh, and the mesh of every node under it, to the geometry the navigation mesh will be baked from, as they stand in the world right now, so place them first. A model instance's root node adds the whole model, and a level built from primitives can be added node by node. Only mesh geometry counts: bodies, sprites and text add nothing. Raises an error once the mesh has been built.
|
|
|
|
|
Adds the node's mesh, and the mesh of every node under it, to the geometry the navigation mesh will be baked from, as they stand in the world right now, so place them first. A model instance's root node adds the whole model, and a level built from primitives can be added node by node. Only mesh geometry counts: bodies, sprites and text add nothing. Ends the script once the mesh has been built.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<navnew,navNew>>, <<navbuild,navBuild>>, <<modelinstance,modelInstance>>
|
|
|
|
|
@ -9922,7 +9922,7 @@ end
|
|
|
|
|
agent = navAgentNew(nav, node, radius, height, speed)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Puts an agent of that size on the mesh at the point nearest the node's world position (the raw position when nothing is within 2 units sideways and 4 up or down), walking at `speed` units a second and accelerating at 8 units a second squared. The radius and height are kept at `0.01` or more, as `navNew` keeps its own. From then on the engine moves the node along the mesh every frame, in its parent's frame, and turns it about Y to face the way it is going whenever it moves faster than `0.05` units a second; nodes look down -Z, as models do. The crowd steers agents round each other, anticipates turns and keeps them apart. To drive a player controller on the node instead of placing the node, see `navAgentSetPlayer`. Raises an error when the mesh is not built or 128 agents are already on it.
|
|
|
|
|
Puts an agent of that size on the mesh at the point nearest the node's world position (the raw position when nothing is within 2 units sideways and 4 up or down), walking at `speed` units a second and accelerating at 8 units a second squared. The radius and height are kept at `0.01` or more, as `navNew` keeps its own. From then on the engine moves the node along the mesh every frame, in its parent's frame, and turns it about Y to face the way it is going whenever it moves faster than `0.05` units a second; nodes look down -Z, as models do. The crowd steers agents round each other, anticipates turns and keeps them apart. To drive a player controller on the node instead of placing the node, see `navAgentSetPlayer`. Ends the script when the mesh is not built or 128 agents are already on it.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -10016,7 +10016,7 @@ end
|
|
|
|
|
navBuild(nav)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Bakes the walkable mesh from everything `navAddNode` added: floors and slopes up to the mesh's angle, steps up to its height, with the agent's radius trimmed off round every wall and drop, and anything with less than the agent's height above it left out. The bake works on cells a third of the agent's radius across and covers at most 4096 by 4096 of them, so a small radius over a big level is slow and can fail; a tenth of a second for Sponza on a desktop, a few seconds on a Raspberry Pi. The geometry that was added is freed afterward, and nothing more can be added; bake another mesh instead. `navSave` keeps the result. Raises an error when nothing was added, the mesh is already built, or the bake fails.
|
|
|
|
|
Bakes the walkable mesh from everything `navAddNode` added: floors and slopes up to the mesh's angle, steps up to its height, with the agent's radius trimmed off round every wall and drop, and anything with less than the agent's height above it left out. The bake works on cells a third of the agent's radius across and covers at most 4096 by 4096 of them, so a small radius over a big level is slow and can fail; a tenth of a second for Sponza on a desktop, a few seconds on a Raspberry Pi. The geometry that was added is freed afterward, and nothing more can be added; bake another mesh instead. `navSave` keeps the result. Ends the script when nothing was added, the mesh is already built, or the bake fails.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<navnew,navNew>>, <<navaddnode,navAddNode>>, <<navsave,navSave>>, <<navdraw,navDraw>>
|
|
|
|
|
@ -10107,7 +10107,7 @@ end
|
|
|
|
|
nav = navLoad(name, agentRadius, agentHeight)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Loads a mesh `navSave` wrote, looked for among the game's files first (so a baked mesh can ship with the game, packed or not) and then in the game's data folder. The mesh comes back built, ready for agents and queries, and takes no more `navAddNode`. The slope and step it was baked with are in the file; the agent radius and height are what the crowd steers with, so give the values it was baked for. Raises an error when the file cannot be read, is not a navigation mesh, is shorter than the mesh its header describes (truncated, or edited by hand), or no mesh slot is free.
|
|
|
|
|
Loads a mesh `navSave` wrote, looked for among the game's files first (so a baked mesh can ship with the game, packed or not) and then in the game's data folder. The mesh comes back built, ready for agents and queries, and takes no more `navAddNode`. The slope and step it was baked with are in the file; the agent radius and height are what the crowd steers with, so give the values it was baked for. Ends the script when the file cannot be read, is not a navigation mesh, is shorter than the mesh its header describes (truncated, or edited by hand), or no mesh slot is free.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -10175,7 +10175,7 @@ end
|
|
|
|
|
nav = navNew(agentRadius, agentHeight, maxSlope, maxStep)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Starts a navigation mesh for agents of that radius and height that can climb steps up to `maxStep` units and slopes up to `maxSlope` degrees. The radius and height are kept at `0.01` or more, the slope between `0` and `89` and the step at `0` or more. The radius also sets the bake's resolution, a cell being a third of it, so it decides how long `navBuild` takes and how big a level it can cover. Add geometry with `navAddNode`, then `navBuild`. Raises an error when eight meshes already exist.
|
|
|
|
|
Starts a navigation mesh for agents of that radius and height that can climb steps up to `maxStep` units and slopes up to `maxSlope` degrees. The radius and height are kept at `0.01` or more, the slope between `0` and `89` and the step at `0` or more. The radius also sets the bake's resolution, a cell being a third of it, so it decides how long `navBuild` takes and how big a level it can cover. Add geometry with `navAddNode`, then `navBuild`. Ends the script when eight meshes already exist.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -10306,7 +10306,7 @@ end
|
|
|
|
|
navSave(nav, name)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Writes the baked mesh to the game's data folder under `name`, for `navLoad` next time, or to copy into the game directory to ship. The mesh must be built. Raises an error when it is not, or when the file cannot be written.
|
|
|
|
|
Writes the baked mesh to the game's data folder under `name`, for `navLoad` next time, or to copy into the game directory to ship. The mesh must be built. Ends the script when it is not, or when the file cannot be written.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<navload,navLoad>>, <<navbuild,navBuild>>
|
|
|
|
|
@ -12109,7 +12109,7 @@ end
|
|
|
|
|
[#player]
|
|
|
|
|
=== Player
|
|
|
|
|
|
|
|
|
|
A player is a character controller on a node: where a body goes where forces send it, a player goes where the script says, walking floors, climbing steps, sliding along walls, riding platforms and shoving light bodies aside. Players are addressed by their node, and a node carries a body or a player, not both. Sizes and speeds are in world units (meters in a 3D scene, overlay pixels in a 2D world) and the controller's tolerances scale with the shape, so a 30 pixel capsule behaves like a 0.3 meter one. The player drives its node's position each step and leaves the rotation to the script. Every call here raises an error when the node has no player. See <<physics,Physics>> in Game Development, Players.
|
|
|
|
|
A player is a character controller on a node: where a body goes where forces send it, a player goes where the script says, walking floors, climbing steps, sliding along walls, riding platforms and shoving light bodies aside. Players are addressed by their node, and a node carries a body or a player, not both. Sizes and speeds are in world units (meters in a 3D scene, overlay pixels in a 2D world) and the controller's tolerances scale with the shape, so a 30 pixel capsule behaves like a 0.3 meter one. The player drives its node's position each step and leaves the rotation to the script. Every call here ends the script when the node has no player. See <<physics,Physics>> in Game Development, Players.
|
|
|
|
|
|
|
|
|
|
[#playernew]
|
|
|
|
|
==== playerNew
|
|
|
|
|
@ -12124,7 +12124,7 @@ playerNew(node, SHAPE_BOX, width, height, depth)
|
|
|
|
|
playerNew(node, SHAPE_HULL)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Puts a player on the node, where the node is in the world right now: a capsule of that radius and total height, or any convex `bodyNew` shape with its sizes, scaled by the node's world scale. The shape stands on the node's origin, so the node is the feet. It starts with a mass of `70` kilograms, a push of `300` newtons, a slope limit of `45` degrees, a step height of `0.3` scaled by the shape, gravity scale `1` and the default swimming rates. Replaces any body or player the node had. Raises an error for `SHAPE_MESH` (a player needs a convex shape; use `SHAPE_HULL`), when physics is not available on this machine, or when the player cannot be made (a hull with too little mesh, or sixteen players already).
|
|
|
|
|
Puts a player on the node, where the node is in the world right now: a capsule of that radius and total height, or any convex `bodyNew` shape with its sizes, scaled by the node's world scale. The shape stands on the node's origin, so the node is the feet. It starts with a mass of `70` kilograms, a push of `300` newtons, a slope limit of `45` degrees, a step height of `0.3` scaled by the shape, gravity scale `1` and the default swimming rates. Replaces any body or player the node had. Ends the script for `SHAPE_MESH` (a player needs a convex shape; use `SHAPE_HULL`), when physics is not available on this machine, or when the player cannot be made (a hull with too little mesh, or sixteen players already).
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -12161,7 +12161,7 @@ playerNew(robot, SHAPE_BOX, 0.8, 1.6, 0.6)
|
|
|
|
|
playerDelete(node)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Removes the player; the node and whatever hangs under it stay where they are. Deleting the node removes its player too, and so does giving the node a body with `bodyNew`. Raises an error when the node has no player.
|
|
|
|
|
Removes the player; the node and whatever hangs under it stay where they are. Deleting the node removes its player too, and so does giving the node a body with `bodyNew`. Ends the script when the node has no player.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<playernew,playerNew>>, <<playersetenabled,playerSetEnabled>>
|
|
|
|
|
@ -12619,7 +12619,7 @@ A skinned model's skeleton handed to physics (see <<physics,Physics>>, Ragdolls)
|
|
|
|
|
ragdollNew(node)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Looks at the node and under it for the first skinned mesh and builds a ragdoll recipe from its skeleton: every joint that has a child joint becomes a bone, a capsule running from the joint toward its children, jointed to the nearest bone above it by a swing-twist joint limited to 45 degrees of swing and 30 of twist. Joints with no child joint, such as fingertips and the tip of a tail, ride along with their parent bone and cannot be named in the other calls. Nothing is simulated yet: the model keeps animating until `ragdollActivate`. Calling it again on the same node discards the old ragdoll first. Raises an error when physics is unavailable, when no skinned mesh with bones is under the node, or when eight ragdolls already exist.
|
|
|
|
|
Looks at the node and under it for the first skinned mesh and builds a ragdoll recipe from its skeleton: every joint that has a child joint becomes a bone, a capsule running from the joint toward its children, jointed to the nearest bone above it by a swing-twist joint limited to 45 degrees of swing and 30 of twist. Joints with no child joint, such as fingertips and the tip of a tail, ride along with their parent bone and cannot be named in the other calls. Nothing is simulated yet: the model keeps animating until `ragdollActivate`. Calling it again on the same node discards the old ragdoll first. Ends the script when physics is unavailable, when no skinned mesh with bones is under the node, or when eight ragdolls already exist.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<ragdollactivate,ragdollActivate>>, <<ragdollsetjoint,ragdollSetJoint>>, <<modelinstance,modelInstance>>
|
|
|
|
|
@ -12677,7 +12677,7 @@ end
|
|
|
|
|
ragdollSetJoint(node, jointName, radius, swingDegrees, twistDegrees)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Tunes one bone's recipe. The values are read when the bodies are made, so call it before `ragdollActivate`; a ragdoll that is already active keeps its bodies until it is deactivated and activated again. The radius `0` asks for the automatic capsule, 0.22 of the bone's length and never thinner than `0.02` units. The swing is the half-angle of the cone the bone may move through relative to its parent, the twist how far it may turn about its own axis; both are clamped to `0` through `179`. Only bones can be named, not the leaf joints; the name is matched without regard to case, and a name with no bone raises an error.
|
|
|
|
|
Tunes one bone's recipe. The values are read when the bodies are made, so call it before `ragdollActivate`; a ragdoll that is already active keeps its bodies until it is deactivated and activated again. The radius `0` asks for the automatic capsule, 0.22 of the bone's length and never thinner than `0.02` units. The swing is the half-angle of the cone the bone may move through relative to its parent, the twist how far it may turn about its own axis; both are clamped to `0` through `179`. Only bones can be named, not the leaf joints; the name is matched without regard to case, and a name with no bone ends the script.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -12710,7 +12710,7 @@ ragdollActivate(fox)
|
|
|
|
|
ragdollActivate(node)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Hands the skeleton to physics from its current pose: every animation layer on the node stops, a dynamic capsule is made for each bone where its joint stands right now, the swing-twist joints are made between them, and from then on each physics step drives the joint nodes from the bodies, so the skinned mesh follows. The bones collide with the world and with each other, except each bone with its parent. The pose at this moment is what `ragdollSetStrength` pulls toward. A ragdoll that is already active is left as it is. Raises an error when a bone's body cannot be made.
|
|
|
|
|
Hands the skeleton to physics from its current pose: every animation layer on the node stops, a dynamic capsule is made for each bone where its joint stands right now, the swing-twist joints are made between them, and from then on each physics step drives the joint nodes from the bodies, so the skinned mesh follows. The bones collide with the world and with each other, except each bone with its parent. The pose at this moment is what `ragdollSetStrength` pulls toward. A ragdoll that is already active is left as it is. Ends the script when a bone's body cannot be made.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<ragdolldeactivate,ragdollDeactivate>>, <<ragdollapplyimpulse,ragdollApplyImpulse>>, <<ragdollsetstrength,ragdollSetStrength>>
|
|
|
|
|
@ -13103,7 +13103,7 @@ The scene is the 3D layer drawn between the disc video and the overlay; nodes pu
|
|
|
|
|
sceneEnable(enabled)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Turns the 3D layer on or off. Nodes, meshes and materials can be built before it is on and survive it being turned off; only drawing stops. Raises an error when turning it on with no usable GPU (see <<scenes3d,3D Scenes>>), so wrap the first call in `pcall` if the game has a 2D fallback. The display refreshes on the next frame either way.
|
|
|
|
|
Turns the 3D layer on or off. Nodes, meshes and materials can be built before it is on and survive it being turned off; only drawing stops. Ends the script when turning it on with no usable GPU (see <<scenes3d,3D Scenes>>), so a game with a 2D fallback asks `singeCapabilities().SCENE` first. The display refreshes on the next frame either way.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<scenesetbackground,sceneSetBackground>>, <<scenesetantialias,sceneSetAntialias>>
|
|
|
|
|
@ -13112,8 +13112,9 @@ Turns the 3D layer on or off. Nodes, meshes and materials can be built before it
|
|
|
|
|
[source,lua]
|
|
|
|
|
----
|
|
|
|
|
-- Fall back to the plain overlay when 3D is unavailable.
|
|
|
|
|
has3d = pcall(sceneEnable, true)
|
|
|
|
|
has3d = singeCapabilities().SCENE
|
|
|
|
|
if has3d then
|
|
|
|
|
sceneEnable(true)
|
|
|
|
|
buildArena()
|
|
|
|
|
else
|
|
|
|
|
debugPrint("No 3D here; using the 2D attract mode.")
|
|
|
|
|
@ -13499,7 +13500,7 @@ sceneSetFog(r, g, b, near, far)
|
|
|
|
|
sceneSetFog()
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Distance fog: clear up to `near` units from the camera, fully the fog color at `far` and beyond, on meshes (unlit ones too) and particles alike; additive particles fade out instead of going gray. With no arguments, or a `far` no greater than `near`, there is no fog. The sky is not fogged, so pick a color close to its horizon, or to the background when there is no sky. Any other number of arguments raises an error.
|
|
|
|
|
Distance fog: clear up to `near` units from the camera, fully the fog color at `far` and beyond, on meshes (unlit ones too) and particles alike; additive particles fade out instead of going gray. With no arguments, or a `far` no greater than `near`, there is no fog. The sky is not fogged, so pick a color close to its horizon, or to the background when there is no sky. Any other number of arguments ends the script.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -13610,7 +13611,7 @@ sceneSetSky(nil)
|
|
|
|
|
sceneSetSky()
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Wraps the scene in an equirectangular panorama: a Radiance `.hdr` (as HDRI sites ship, keeping its range), or a PNG, JPEG or other image SDL_image reads, decoded from sRGB. The name is game relative like `spriteLoad`. The sky is drawn behind everything in place of the background color (so the video no longer shows through) and lights the scene unless `sceneSetEnvironment(false)`. Its center faces -Z and its top is up. It is resampled into a cube of up to 1024 texels a face, so a 2048 by 1024 image is plenty and larger ones take a moment to prepare on a Raspberry Pi. With no argument, or `nil`, the sky is removed. Raises an error when the file cannot be read or 3D is unavailable.
|
|
|
|
|
Wraps the scene in an equirectangular panorama: a Radiance `.hdr` (as HDRI sites ship, keeping its range), or a PNG, JPEG or other image SDL_image reads, decoded from sRGB. The name is game relative like `spriteLoad`. The sky is drawn behind everything in place of the background color (so the video no longer shows through) and lights the scene unless `sceneSetEnvironment(false)`. Its center faces -Z and its top is up. It is resampled into a cube of up to 1024 texels a face, so a 2048 by 1024 image is plenty and larger ones take a moment to prepare on a Raspberry Pi. With no argument, or `nil`, the sky is removed. Ends the script when the file cannot be read or 3D is unavailable.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<scenesetskyintensity,sceneSetSkyIntensity>>, <<scenesetenvironment,sceneSetEnvironment>>, <<scenesetfog,sceneSetFog>>, <<scenesetbackground,sceneSetBackground>>
|
|
|
|
|
@ -13665,7 +13666,7 @@ end
|
|
|
|
|
sceneSetTonemap(curve)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
The curve that maps the scene's linear light to the screen, applied after exposure. `TONEMAP_NEUTRAL` (the default) keeps colors faithful and compresses only the brightest light; `TONEMAP_ACES` is the filmic curve with more contrast and a warmer roll-off; `TONEMAP_NONE` clips at white. Video materials, unlit surfaces and the sky pass through the same curve, so a game whose disc must look exactly as filmed wants `TONEMAP_NONE` with an exposure of `0`. Any other value raises an error.
|
|
|
|
|
The curve that maps the scene's linear light to the screen, applied after exposure. `TONEMAP_NEUTRAL` (the default) keeps colors faithful and compresses only the brightest light; `TONEMAP_ACES` is the filmic curve with more contrast and a warmer roll-off; `TONEMAP_NONE` clips at white. Video materials, unlit surfaces and the sky pass through the same curve, so a game whose disc must look exactly as filmed wants `TONEMAP_NONE` with an exposure of `0`. Any other value ends the script.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<scenesetexposure,sceneSetExposure>>, <<scenesetbloom,sceneSetBloom>>
|
|
|
|
|
@ -14813,7 +14814,7 @@ softNew(node, SOFT_BODY)
|
|
|
|
|
softNew(node, SOFT_ROPE, x, y, z, segments, radius)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
For `SOFT_CLOTH` and `SOFT_BODY` the node's mesh, of three vertices or more, becomes the particles: vertices at the same position (within `0.0001` units) are welded into one, placed where the node's transform puts them in the world, and the triangles give the stretch, shear and bend constraints. Cloth collides on both faces and is what an open sheet wants; a body is a closed mesh that `softSetPressure` can inflate. For `SOFT_ROPE` the node needs no mesh: `segments + 1` particles run in a line from the node's world position to the world point, the node is given a new six-sided tube mesh of that radius round them (keeping whatever material it had), and the particles collide as spheres of that radius, where cloth and body particles are spheres of radius `0.03`. Every kind starts with stretch `0.9`, bend `0.2`, mass `1` kilogram, damping `0.1` and pressure `0`. A soft body already on the node is removed before the new one is made, so a call that fails leaves the node with none; a rope's tube mesh goes with it, which is why a rope's node cannot become cloth or a body (the call fails for want of a mesh). Raises an error when physics is unavailable, the kind is unknown, the argument count does not fit the kind, the mesh is missing, a rope has no segments or no radius, or 16 soft bodies already exist.
|
|
|
|
|
For `SOFT_CLOTH` and `SOFT_BODY` the node's mesh, of three vertices or more, becomes the particles: vertices at the same position (within `0.0001` units) are welded into one, placed where the node's transform puts them in the world, and the triangles give the stretch, shear and bend constraints. Cloth collides on both faces and is what an open sheet wants; a body is a closed mesh that `softSetPressure` can inflate. For `SOFT_ROPE` the node needs no mesh: `segments + 1` particles run in a line from the node's world position to the world point, the node is given a new six-sided tube mesh of that radius round them (keeping whatever material it had), and the particles collide as spheres of that radius, where cloth and body particles are spheres of radius `0.03`. Every kind starts with stretch `0.9`, bend `0.2`, mass `1` kilogram, damping `0.1` and pressure `0`. A soft body already on the node is removed before the new one is made, so a call that fails leaves the node with none; a rope's tube mesh goes with it, which is why a rope's node cannot become cloth or a body (the call fails for want of a mesh). Ends the script when physics is unavailable, the kind is unknown, the argument count does not fit the kind, the mesh is missing, a rope has no segments or no radius, or 16 soft bodies already exist.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -16461,7 +16462,7 @@ spriteSetBlend(id, SPRITE_ALPHA | SPRITE_ADD | SPRITE_MULTIPLY)
|
|
|
|
|
|
|
|
|
|
How every draw of the sprite lays it over what is already on the overlay. `SPRITE_ALPHA`, the default, draws it over by its alpha. `SPRITE_ADD` adds its colour, scaled by its alpha, to what is there, so it can only brighten: glows, light, sparks, and the shadebobs of the old demos, where a ball drawn over itself again and again burns to white. `SPRITE_MULTIPLY` darkens what is there by its colour, for shadows and tinted glass.
|
|
|
|
|
|
|
|
|
|
Added and multiplied pixels keep the overlay's own alpha, so they show only where something is already drawn on the overlay: over a transparent overlay, above a video or the 3D scene, they change nothing. Draw something opaque first, or use `emitterSetBlend` with `PARTICLE_ADD`, which adds over everything. Anything other than the three constants raises an error.
|
|
|
|
|
Added and multiplied pixels keep the overlay's own alpha, so they show only where something is already drawn on the overlay: over a transparent overlay, above a video or the 3D scene, they change nothing. Draw something opaque first, or use `emitterSetBlend` with `PARTICLE_ADD`, which adds over everything. Anything other than the three constants ends the script.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -16982,7 +16983,7 @@ Heightmap ground made with `meshHeightmap`, which turns a grayscale image into a
|
|
|
|
|
height = terrainGetHeight(node, x, z)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
The world height of the heightmap mesh on `node` at world `x, z`, interpolated between the nearest four samples, or `nil` beyond its edges or when the node's mesh is not a heightmap. The node's world position and scale count; its rotation is ignored, since terrains lie flat. Use it for placing trees, spawning things on the ground, or a camera that follows the surface, without the cost of a ray cast. Raises an error for a node handle that is not valid.
|
|
|
|
|
The world height of the heightmap mesh on `node` at world `x, z`, interpolated between the nearest four samples, or `nil` beyond its edges or when the node's mesh is not a heightmap. The node's world position and scale count; its rotation is ignored, since terrains lie flat. Use it for placing trees, spawning things on the ground, or a camera that follows the surface, without the cost of a ray cast. Ends the script for a node handle that is not valid.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -17236,7 +17237,7 @@ Cars, motorcycles, tanks and boats built on a chassis body (see <<physics,Physic
|
|
|
|
|
vehicleNew(node, kind)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Turns the dynamic body on `node` into the chassis of a vehicle. A car, motorcycle or tank needs at least two wheels from `vehicleAddWheel` before the next physics step builds it; a boat has no wheels and is pushed by a propeller that only works under a surface made with `bodySetWater`. The new vehicle starts from the defaults: a 500 Nm engine peaking at 6000 rpm and idling at 1000, Jolt's five-speed automatic gearbox, 35 degrees of steering lock, 1500 Nm brakes and a 4000 Nm hand brake, 1.5 Hz suspension at 0.5 damping and no anti-roll bars. Calling it again on the same node discards the old vehicle and its wheels first. Raises an error for an unknown kind, a node whose body is not dynamic, a wheeled kind in a 2D world, or when 16 vehicles already exist.
|
|
|
|
|
Turns the dynamic body on `node` into the chassis of a vehicle. A car, motorcycle or tank needs at least two wheels from `vehicleAddWheel` before the next physics step builds it; a boat has no wheels and is pushed by a propeller that only works under a surface made with `bodySetWater`. The new vehicle starts from the defaults: a 500 Nm engine peaking at 6000 rpm and idling at 1000, Jolt's five-speed automatic gearbox, 35 degrees of steering lock, 1500 Nm brakes and a 4000 Nm hand brake, 1.5 Hz suspension at 0.5 damping and no anti-roll bars. Calling it again on the same node discards the old vehicle and its wheels first. Ends the script for an unknown kind, a node whose body is not dynamic, a wheeled kind in a 2D world, or when 16 vehicles already exist.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -17297,7 +17298,7 @@ end
|
|
|
|
|
index = vehicleAddWheel(node, wheelNode, radius, width, suspension)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Adds a wheel to the vehicle where `wheelNode` stands relative to the chassis when the vehicle is next built. The suspension hangs the wheel `suspension` units below that point when unloaded and compresses to half that. From then on the engine writes the wheel node's world transform after every step, with X as the axle and Y up, so the visible tire belongs on a child node: a `meshCylinder` turned 90 degrees about Z. Wheels ahead of the average wheel position along the nose count as front wheels: they steer by default and carry no hand brake. A tank sorts its wheels onto the left or right track by which side of the chassis they sit on and needs at least one on each side. Values below `0.001` are raised to it. Raises an error at the 17th wheel.
|
|
|
|
|
Adds a wheel to the vehicle where `wheelNode` stands relative to the chassis when the vehicle is next built. The suspension hangs the wheel `suspension` units below that point when unloaded and compresses to half that. From then on the engine writes the wheel node's world transform after every step, with X as the axle and Y up, so the visible tire belongs on a child node: a `meshCylinder` turned 90 degrees about Z. Wheels ahead of the average wheel position along the nose count as front wheels: they steer by default and carry no hand brake. A tank sorts its wheels onto the left or right track by which side of the chassis they sit on and needs at least one on each side. Values below `0.001` are raised to it. Ends the script at the 17th wheel.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -17370,7 +17371,7 @@ vehicleSetRudder(raft, 300)
|
|
|
|
|
vehicleSetWheel(node, index, steered, driven)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Says whether one wheel turns with the steering input and whether the engine drives it, replacing the defaults for that wheel: front wheels steer, and every wheel drives except a motorcycle's front one. Driven wheels pair up across the chassis into differentials, one per axle, and the engine's torque is shared equally between the axles; a driven wheel with no partner is an axle of its own. A tank ignores both flags, since its tracks drive every wheel and turn the hull. Takes effect at the next step's rebuild. Raises an error for an index the vehicle has no wheel for.
|
|
|
|
|
Says whether one wheel turns with the steering input and whether the engine drives it, replacing the defaults for that wheel: front wheels steer, and every wheel drives except a motorcycle's front one. Driven wheels pair up across the chassis into differentials, one per axle, and the engine's torque is shared equally between the axles; a driven wheel with no partner is an axle of its own. A tank ignores both flags, since its tracks drive every wheel and turn the hull. Takes effect at the next step's rebuild. Ends the script for an index the vehicle has no wheel for.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -17444,7 +17445,7 @@ vehicleSetGears(node, { ratio, ... }, reverseRatio)
|
|
|
|
|
vehicleSetGears(node, { ratio, ... }, reverseRatio, automatic)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Sets the gearbox: one to eight forward ratios, first gear first, the reverse ratio (default `2.9`, given as a positive number) and whether the box shifts by itself (default `true`). A vehicle that never gets this call runs Jolt's five-speed, `2.66`, `1.78`, `1.3`, `1.0` and `0.74`, with the same reverse. With `automatic` false the box no longer shifts on its own, and there is no call to shift it from script. A boat has no gearbox and ignores the call. Takes effect at the next step's rebuild. Raises an error when the table is empty or holds more than eight ratios.
|
|
|
|
|
Sets the gearbox: one to eight forward ratios, first gear first, the reverse ratio (default `2.9`, given as a positive number) and whether the box shifts by itself (default `true`). A vehicle that never gets this call runs Jolt's five-speed, `2.66`, `1.78`, `1.3`, `1.0` and `0.74`, with the same reverse. With `automatic` false the box no longer shifts on its own, and there is no call to shift it from script. A boat has no gearbox and ignores the call. Takes effect at the next step's rebuild. Ends the script when the table is empty or holds more than eight ratios.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -17812,7 +17813,7 @@ end
|
|
|
|
|
[#view]
|
|
|
|
|
=== View
|
|
|
|
|
|
|
|
|
|
A view is a second camera rendered to a texture every frame, for a monitor, a mirror or a portal in the scene: `viewNew` makes one and returns an integer handle, `viewSetCamera` points it at a node, and `materialSetView` shows it on a material. Up to four exist at once; each renders the whole scene again at its own size, in overlay-independent pixels, with the main camera's projection, the frame's shadows (a directional light's cascades included: each point takes the finest cascade that covers it) and no bloom, so keep them few and small. Every view turns billboards (`nodeSetBillboard`) to its own camera and sorts blended draws back to front from it, so a view whose camera looks from elsewhere still sees billboards face on and transparent objects in the right order. A bad handle raises an error. See <<scenes3d,3D Scenes>>.
|
|
|
|
|
A view is a second camera rendered to a texture every frame, for a monitor, a mirror or a portal in the scene: `viewNew` makes one and returns an integer handle, `viewSetCamera` points it at a node, and `materialSetView` shows it on a material. Up to four exist at once; each renders the whole scene again at its own size, in overlay-independent pixels, with the main camera's projection, the frame's shadows (a directional light's cascades included: each point takes the finest cascade that covers it) and no bloom, so keep them few and small. Every view turns billboards (`nodeSetBillboard`) to its own camera and sorts blended draws back to front from it, so a view whose camera looks from elsewhere still sees billboards face on and transparent objects in the right order. A bad handle ends the script. See <<scenes3d,3D Scenes>>.
|
|
|
|
|
|
|
|
|
|
[#viewdelete]
|
|
|
|
|
==== viewDelete
|
|
|
|
|
@ -17822,7 +17823,7 @@ A view is a second camera rendered to a texture every frame, for a monitor, a mi
|
|
|
|
|
viewDelete(view)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Frees the view and its textures, and stops the extra render pass it cost. Materials showing it go back to their own texture. The handle is invalid afterwards and raises an error if used again; since only four views exist at once, delete the ones a level no longer needs.
|
|
|
|
|
Frees the view and its textures, and stops the extra render pass it cost. Materials showing it go back to their own texture. The handle is invalid afterwards and ends the script if used again; since only four views exist at once, delete the ones a level no longer needs.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<viewnew,viewNew>>, <<materialsetview,materialSetView>>
|
|
|
|
|
@ -17851,7 +17852,7 @@ end
|
|
|
|
|
view = viewNew(width, height)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Makes a camera rendered to a `width` by `height` texture every frame (each clamped to `1` to `4096`), from the default view until `viewSetCamera` names a node, and returns the view handle for `materialSetView`. The view uses the projection from `cameraSetPerspective` or `cameraSetOrthographic` at its own aspect ratio. The scene renders once more per view, so `512` by `384` is plenty for a monitor and a Raspberry Pi wants smaller. Raises an error when 3D is unavailable or four views are already in use.
|
|
|
|
|
Makes a camera rendered to a `width` by `height` texture every frame (each clamped to `1` to `4096`), from the default view until `viewSetCamera` names a node, and returns the view handle for `materialSetView`. The view uses the projection from `cameraSetPerspective` or `cameraSetOrthographic` at its own aspect ratio. The scene renders once more per view, so `512` by `384` is plenty for a monitor and a Raspberry Pi wants smaller. Ends the script when 3D is unavailable or four views are already in use.
|
|
|
|
|
|
|
|
|
|
*Parameters:*
|
|
|
|
|
|
|
|
|
|
@ -17889,7 +17890,7 @@ viewSetCamera(view, nil)
|
|
|
|
|
viewSetCamera(view)
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
The node the view looks from, down its own -Z like the main camera, so its parents' movement counts. With `nil` or no second argument the view goes back to the default view from `(0, 0, 5)` looking at the origin. Parent the node to a car for a rear-view mirror, or reflect the main camera's position about a wall for a mirror in it. Raises an error for a node handle that is not valid.
|
|
|
|
|
The node the view looks from, down its own -Z like the main camera, so its parents' movement counts. With `nil` or no second argument the view goes back to the default view from `(0, 0, 5)` looking at the origin. Parent the node to a car for a rear-view mirror, or reflect the main camera's position about a wall for a mirror in it. Ends the script for a node handle that is not valid.
|
|
|
|
|
|
|
|
|
|
*Since:* 3.00.
|
|
|
|
|
*See also:* <<viewnew,viewNew>>, <<cameraset,cameraSet>>, <<nodelookat,nodeLookAt>>
|
|
|
|
|
|
Scott Duensing
