For a quick walkthrough of what can be done in a Three.V8 user script, see Features.
For details of the APIs that enable the features, see below.
Three.V8 User Script APIs
The user script APIs consist of
- Engine Classes: have properties and methods to communicate with engine objects.
- Global Functions: can be called directly from user script.
- Global Objects: are special engine objects which are preexisting in the context rather than created by the user script.
- Callback Functions: are used by user script to recieve the event calls from the host program.
Engine Classes (3D)
| Class Name | Description |
|---|---|
| Image | Represents an image that resides in CPU memory. |
| CubeImage | Represents a cubemap image that resides in CPU memory. |
| DDSImage | Represents a dds-image that resides in CPU memory. |
| HDRImage | Represents a HDR image that resides in CPU memory. |
| HDRCubeImage | Represents a HDR cubemap image that resides in CPU memory. |
| Object3D | Base class of all 3D objects visible to user script. |
| Camera | Base class for cameras. |
| PerspectiveCamera | Perspective camera |
| Reflector | Planar reflector. |
| Backround | Abstract class for all backgrounds |
| ColorBackground | A background that has a monotone color. |
| CubeBackground | A background using a CubeMap. |
| HemisphereBackground | A background that has a sky color and a ground color. |
| BackgroundScene | Use another scene as background. |
| Light | Abstract class for all direct lights. |
| DirectionalLight | A light that gets emitted in a specific direction. |
| IndirectLight | Abstract class for all indirect lights |
| EnvironmentMap | Image based indirect light |
| EnvironmentMapCreator | Cube-map filter that generates environmaps |
| AmbientLight | Uniform indirect light |
| HemisphereLight | Gradient indirect light |
| ProbeGrid | An uniform grid of light-probes |
| LODProbeGrid | A mixed resolution grid of light-probes |
| SimpleModel | A Model containing a single simple geometry |
| GLTFModel | A Model that has a GLTF style internal structure. |
| AnimationMixer | Utility for linear blending of animation clips. |
| Scene | 3D Object collection for rendering |
| Fog | Represents the particle substance in the air |
| GLRenderer | Manages rendering routines, including shaders |
| GLRenderTarget | An off-screen render target. |
| CubeRenderTarget | A cubemap render target. |
| BoundingVolumeHierarchy | Acceleration structure for ray-casting. |
| GamePlayer | Wrapper for the host GamePlayer object. |
| FileLoader | Provides a few interfaces to loading local files. |
| ImageLoader | Provides a few interfaces to load images. |
| DDSImageLoader | Provides a few interfaces to load dds-images. |
| HDRImageLoader | Provides a few interfaces to load HDR images. |
| GLTFLoader | Provides a few interfaces to load GLTF models. |
| ProbeGridLoader | Provides a few interfaces to load probe-grids. |
| LODProbeGridLoader | Provides a few interfaces to load lod-probe-grids. |
| Text | Provides a few interfaces for text conversion. |
Engine Classes (Network)
| Class Name | Description |
|---|---|
| HttpClient | Provides a few interfaces to make HTTP requests. |
| WSClient | Maintains a websocket connection at the client side. |
Engine Classes (GUI)
| Class Name | Description |
|---|---|
| UIManager | Manages UIArea objects. |
| UIArea | Manages UIElement objects and UI3DViewer objects. |
| UIElement | Abstract base class of all ui-elements. |
| UIBlock | Base class for all ui-elements containing other ui-elements. |
| UIPanel | A visible ui-block. |
| UIButton | A clickable ui-block. |
| UIScrollViewer | A scrollable ui-block. |
| UIImage | Image element in a UI. |
| UIText | Non-editable text element in a UI. |
| UITextBlock | Non-editable multi-lined text element in a UI. |
| UILineEdit | Editable text box in a UI. |
| UI3DViewer | Object for embedding a 3D view in a UI. |
| UIDraggable | A draggable ui-panel. |
Engine Classes (Multimedia)
| Class Name | Description |
|---|---|
| MMCamera | Represents an image source from a web-camera. |
| MMLazyVideo | Represents an image source from a video-file. |
| MMVideo | Represents a background video-file player. |
| MMAudio | Represents a background audio-file player. |
| OpusRecorder | Record from an audio device and encode as a raw opus stream. |
| OpusPlayer | Play back a raw opus stream. |
| AVCRecorder | Record from a video device and encode as a raw AVC stream. |
| AVCPlayer | Play back a raw AVC stream. |
Global Functions
These are functions that can be called directly in user script.
| Function Name | Description |
|---|---|
| print() | Print strings to stdout |
| setCallback() | Register a callback function. |
| now() | Current time in milliseconds. |
| getGLError() | Get the last OpenGL error code for debugging. |
| getListOfCameras() | Get a list of camera device names. |
| getListOfAudioPlaybackDevices() | Get a list of audio playback device names. |
print()
print(text1: String, text2: String, …): undefined
Print strings to stdout separated by spaces. Objects are not stringified automatically. To do that you need JSON.stringify().
setCallback()
setCallback(name: String, callback: Function): undefined
Register a callback function.
Parameters
name: one of the names listed in Callback Functions.
callback: function accessable from script, or lambda.
now()
now(): Number
Current time in milliseconds.
getGLError()
getGLError(): Number
Get the last OpenGL error code for debugging.
getListOfCameras()
getListOfCameras(): Array
Get a list of camera device names.
getListOfAudioPlaybackDevices()
getListOfAudioPlaybackDevices(): Array
Get a list of audio playback device names.
Global Objects
These are engine class singletons that can be used directly in user script.
| Object Name | Description |
|---|---|
| gamePlayer | Instance of GamePlayer. |
| fileLoader | Instance of FileLoader. |
| imageLoader | Instance of ImageLoader. |
| DDSImageLoader | Instance of DDSImageLoader. |
| HDRImageLoader | Instance of HDRImageLoader. |
| gltfLoader | Instance of GLTFLoader. |
| probeGridLoader | Instance of ProbeGridLoader. |
| LODProbeGridLoader | Instance of LODProbeGridLoader. |
| text | Instance of Text |
| http | Instance of HttpClient. |
| UIManager | Instance of UIManager. |
Callback Functions
User scripts are event driven programs. Callback functions need to be registered in the global scope by calling setCallback.
The host program calls these functions at specific events according to their names.
The following callback functions are called by the default “GamePlayer”.
Mouse callbacks are specific to desktop while touch callbacks are specific to mobile devices.
| Callback name | Description |
|---|---|
| init() | Called immediately after loading the script. |
| dispose() | Called before unloading the script. |
| render() | Called when rendering a video frame. |
| OnMouseDown() | Called when mouse button is pressed down. |
| OnMouseUp() | Called when mouse button is up. |
| OnMouseMove() | Called when mouse pointer is moved. |
| OnMouseWheel() | Called when mouse wheel is moved. |
| OnTouchDown() | Called when user touches screen. |
| OnTouchUp() | Called when user stops touching screen. |
| OnTouchMove() | Called when user moves on touch screen. |
init()
init(width: Number, height: Number): undefined
Called immediately after loading the script.
Parameters
width: width of the container window.
height: height of the container window.
dispose()
dispose(): undefined
Called before unloading the script.
render()
render(width: Number, height: Number, sizeChanged: Boolean): undefined
Called when rendering a video frame.
Parameters
width: width of the container window.
height: height of the container window.
sizeChanged: if size of windows has changed.
OnMouseDown()
OnMouseDown(e: Object): undefined
Called when mouse button is pressed down.
Parameters
e: has the following properties:
e.x: Number
x coordinate of mouse pointer
e.y: Number
y coordinate of mouse pointer
e.delta: Number
wheel delta
e.button: Number
0 = Left Button
1 = Middle Button
2 = Right Button
3 = XButton1
4 = XButton2
OnMouseUp()
OnMouseUp(e: Object): undefined
Called when mouse button is up.
The parameter e has the same structure as in OnMouseDown()
OnMouseMove()
OnMouseMove(e: Object): undefined
Called when mouse pointer is moved.
The parameter e has the same structure as in OnMouseDown()
OnMouseWheel()
OnMouseWheel(e: Object): undefined
Called when mouse wheel is moved.
The parameter e has the same structure as in OnMouseDown()
OnTouchDown()
OnTouchDown(e: Object): undefined
Called when user touches screen.
Parameters
e: has the following properties:
pointerId: Number
Identifier for distinguishing multiple touch points.
x: number
x coordinate of touch point.
y: number
y coordinate of touch point.
OnTouchUp()
OnTouchUp(e: Object): undefined
Called when user stops touching screen.
The parameter e has the same structure as in OnTouchDown()
OnTouchMove()
OnTouchMove(e: Object): undefined
Called when user moves on touch screen.
The parameter e has the same structure as in OnTouchDown()