Scene API
The scene API provides a way to modify the scene from another webpage, on run time. This gives you the same flexibility than you have in the editor, as you can change the value of any parameter.
You would typically use it when you want to add custom controls to modify your scene. For instance, you may want:
- a button to change the color of a material.
- a checkbox to control the visibility of an object.
- a slider to change the size of an object.
- update the url of an API you are fetching data from.
- start an animation based on some event.
This can be particularly useful when creating a configurator like this one:
Try the Car Configurator Live or view the simpler examples below to get started:
Examples





More Examples coming soon:
- Get events from user click
- Add html elements in 3D space
- React on keystrokes
- Add a custom loader on long scene updates
- Control a custom shader
- Add a voxel on user input
- Upload a new texture
- Add annotations
- animation unfolding on scroll
Overview
Here is what you would typically do to interact with a Polygonjs scene at run time:
In your html, first load your scene iframe.
To find the iframe html for you scene, from the editor, go to File->Embed, and toggle on 'Embed Active'. The html will display then.
<iframe frameborder='0' height='100%' src='https://embed.polygonjs.com/scenes/5663bd4e-5ead-439b-bdb7-f7b2ed882710?timestamp=1563316376' width='100%' id='polygonjs-embed-iframe'></iframe>
Then attach events to buttons, sliders or any other element you want:
<input type='button' onclick='increase_scale'/>
Load Polygonjs Embed library:
<script src="https://unpkg.com/polygonjs-embed@1.0.7/dist/polygonjs-embed.min.js"></script>
If you are using npm or yarn, you can also install the module:
yarn add polygonjs-embed
And in your javascript, all you have to do is:
- wait for the scene to load, with
embed.on('scene_load', your_callback)
- update a node's parameter in the
increase_scale
function
// create the Poly.embed object
var embed = POLY.Embed('myiframeid')
var scale_node;
// wait for the scene to load
embed.on('scene_load', ()=>{
// once loaded, find the node you want to update
scale_node = embed.node('/geo1')
})
function increase_scale(){
// update the scale parameter of the node /geo1
scale_node.param('scale').set(2)
}
And that's it!
With this simple functionalities in mind, you can edit any node in your scene, with the same flexibility as when in the editor. This allows you to create truly powerful applications, such as:
- configurators
- data vizualiser
- art projects
- games
Classes
POLY.Embed
The Poly.Embed
object is the main starting point, which will allow you to get the scene, nodes and parameters.
Give it either the id of your iframe, or the iframe itself.
var embed = POLY.Embed('myiframeid')
or
var iframe_element = document.getElementById('myiframeid')
var embed = POLY.embed( iframe_element )
get the scene
var scene = embed.scene()
get a node
var geo1 = embed.node('/geo1')
listen to events
You would typically wait for the scene to be loaded before interacting with it.
function onload_listener(){ console.log('the scene has loaded') }
embed.on('scene_load', onload_listener)
With the same on
method, you will be able to attach custom events.
Scene
play
scene.play()
pause
scene.pause()
set frame
scene.set_frame(12)
get frame
This method returns you a promise.
scene.frame(12).then((frame)=>{console.log(frame)})
Node
get a parameter
var scene_param = node.param('scale') // pass it the name of the parameter
force cook
node.force_cook() // if you need to force a refresh
set the display flag
node.set_display_flag(true) // set the flag true or false
set the bypass flag
node.set_bypass_flag(true) // set the flag true or false
Param
set a new value
param.set(2) // pass it the new value
set an expression
param.set_expression('sin($F)') // pass it a string
get the value
param.eval().then((value)=>{console.log(value)})
← API Custom Node API →