Polygonjs

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

Play/Pause
Learn How to pause and play the scene
Change Instances Count
Learn How to update instances
Switch Materials
Learn How to assign different materials
Table Configurator
A small example showing how to create geometry on the fly
Car Configurator
A more complex setup to show how to setup a car in its enviroment

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)})

← Custom Node API →