3D Models
Studio provides support for incorporating 3D objects into your projects using the Mesh
component,
allowing you to create immersive and interactive experiences. 3D models today cover
Primitives/Geometries that come included as options in Studio, or GLB/GLTF models that can be
created externally and imported into Studio. To learn more about using and optimizing 3D Models in
GLB/GLTF format please see Your 3D Models on the Web.
When you click on a 3D model in the left menu, it will open into the 3D Model viewer. This viewer is
a great tool for checking if your model is set up correctly.
A 3D Model can be added to the entity via the Studio interface via the Mesh
component, or in code.
Adding them in Studio is done via the (+) button on the Hierarchy or adding a "New Component" via the
Inspector for a selected entity. The Mesh component features various Geometry, Materials, and GLTF
Animations settings.
Primitives
The following geometries (aka Primitives) are supported. For custom objects, GLTF models are a good option. Otherwise it’s technically possible to use raw THREE.js code to do things like custom geometries if you really need to.
They can all be configured the same as any other component, for example:
ecs.SphereGeometry.set(world, eid, {radius: 5})
Geometry | Attributes |
---|---|
SphereGeometry | radius |
BoxGeometry | width, height, depth |
PlaneGeometry | width, height |
CapsuleGeometry | radius, height |
ConeGeometry | radius, height |
CylinderGeometry | radius, height |
TetrahedronGeometry | radius |
CircleGeometry | radius |
RingGeometry | innerRadius, outerRadius |
GLTF & GLB Models
Studio supports GLTF and GLB files types.
Set a model source
ecs.GltfModel.set(world, eid, {url: 'https://some.example/my-model.gltf'})
Setting model properties
ecs.GltfModel.set(world, eid, {
url: 'https://some.example/my-model.gltf',
animationClip: 'clip1',
loop: true,
paused: false,
time: 0,
timeScale: 1,
})
Notes:
- DRACO compression is supported
- As with other supported components, model assets in the project can be used (for more, see Assets)
Model properties
Property | Data | Required | Description |
---|---|---|---|
url | string | true | The source url. |
animationClip | string | false | The name of the animationClip attached to the model to play |
loop | Boolean | false | Whether the animation clip restarts after it finishes playing or not |
paused | Boolean | false | Whether the animation clip is paused |
time | number | false | Time in seconds of animationClip to jump to |
timeScale | number | false | Scaling factor for the time. 0 causes the animation to pause. Negative values cause the animation to play backwards. |
reverse | Boolean | false | If set, the animation will play in reverse when it finishes playing forward (together counts as one loop iteration) |
repetitions | Number | false | If set along with loop , the number of times the loop will be repeated (-1 means loop forever). |
crossFadeDuration | Number | false | The time in seconds that will be spent blending between animations when a new animation is started (and an existing animation is playing) |
FBX to GLB conversion
Studio supports native FBX to GLB conversion via Facebook-developed FBX2glTF CLI conversion tool. However, Studio does not support FBX conversion with separate texture sources. In your modeling tool's FBX export settings, be sure to embed textures before converting to GLB in Niantic Studio.
Materials
Materials can be configured either in code or as part of the Mesh component in the editor:
The following material types are supported:
- Material (the standard type)
- ShadowMaterial
- UnlitMaterial*
- HiderMaterial*
* Unlit and Hider Materials can only be applied to Primitives.
The standard material supports a wide variety of configurations (roughness, metalness, and emissive textures for example). The shadow material makes transparent objects that can still have visible shadows projected on them (if set to receive them). This is useful for AR situations where we want objects to appear to have shadows in the real world. The HiderMaterial (for Primitives) lets you easily obscure or "hide" objects within a scene, within or behind the material. The UnlitMaterial ensures that certain objects remain clear and readable, unaffected by light sources, shadows, or shading effects.
Materials can be set in code:
// Setting the standard material
ecs.Material.set(world, eid, {r: 255, g: 0, b: 100, roughness: 1})
// Setting the shadow material
ecs.ShadowMaterial.set(world, eid, {r: 255, g: 0, b: 100})
You can also set a texture, and unless you want it to be tinted, make sure the r/g/b are set to 255:
ecs.Material.set(world, eid, {
r: 255,
g: 255,
b: 255,
textureSrc: 'https://placehold.co/800?text=Hello+World&font=roboto'
})
Material properties
Displayed Property | ECS Propertyies | Data | Component | Description |
---|---|---|---|---|
Color | r, g, b Number (uint8), [0...255] | All | Color of the material | |
Texture | textureSrc | String (URL) | Material | The color map, modulated by color (if set) |
Roughness | roughness | Number (float) [0...1] | Material | How rough the material appears |
Roughness Texture | roughnessMap | String (URL) | Material | Green channel of this texture maps the roughness, multiplied by the roughness number. |
Metalness | metalness | Number (float), [0...1] | Material | How metallic the material appears |
Metalness Texture | metalnessMap | String (URL) | Material | Blue channel of this texture affects how metal the material appears. |
Normal | normalScale | Number (float) [0...1] | Material | How much the normal map (if set) affects the material. |
Normal Texture | normalMap | String (URL) | Material | Normal map of the texture. |
Opacity | opacity | Number (float) [0...1] | All | Overall alpha/transparency of the material. |
Opacity Texture | opacityMap | String (URL) | Material | Alpha/transparency mapped via a texture. |
Emissive | emissiveIntensity | Number (float) [0...1] | Material | Overall intensity of the emissive map. |
Emissive Texture | emissiveMap | String (URL) | Material | Emissiveness mapped as a texture. Modulated by emissive color and intensity. |
Emissive Color | emissiveR, emissiveG, emissiveB | Number (uint8) [0...255] | Material | Overall emissive color of the material. |
Side | side | String (“front”, “back”, “double”) | All | Which sides of faces will be rendered. |
Blending | blending | String (“no”, “normal”, “additive”, “subtractive”, “multiply”) | Material | Blending to use when displaying objects with this material. |
Repeat (X, Y) | repeatX, repeatY | Number (float) | Material | How many times a texture is repeated across a material. |
Offset (X, Y) | offsetX, offsetY | Number (float) | Material | How much a texture is offset across a material. |
Depth Test | depthTest | Boolean | All | Whether to test depth when rendering this material (true by default) |
Depth Write | depthWrite | Boolean | All | Whether rendering this material impacts the depth buffer (true by default) |
Wireframe | wireframe | Boolean | Material | Render geometry as wireframe. |