Scene Composition

Structure

Unless you are creating a 2D game on the Overlay Canvas, you will most likely use the 3D Scene. A basic 3D Scene comprises of a Skybox, a Camera and a few Objects. There are extra components to help you further customize the look of your scene.

Scene Components

Components that make up the overall look of your scene:

Sky Color

Scene background color. Can be a solid color or a 3-tier gradient.

GAME.SCENE.setSkyColor(
    "#fff" # str color
);

Sky Dome

Scene background dome with gradient and optional texture.

GAME.SCENE.setSkyDome(
    "#fff", # str color1
    "#fff", # str color2
    "#fff", # str color3
    data    # obj additional data
);

# all fields are optional
obj additional = {
    texture: "assetID",
    emissive: "#ff0000",
    emissiveTexture: "assetID",
    textureMoveAxis: 0,      # 0 = x, 1 = y
    textureMoveSpeed: 5      # -20 to 20
};

# removing skydome
GAME.SCENE.removeSkyDome();

Sky Light

Directional light that casts shadows (sun).

GAME.SCENE.setSkyLight(
    "#fff", # str color
    2,      # num light intensity (0 - 3)
    45,     # num sun angle x (0 - 360)
    45,     # num sun angle y (0 - 360)
    100     # num light distance (10 - 15000)
);

Ambient Light

Indirect scene lighting.

GAME.SCENE.setAmbientLight(
    "#fff", # str color
    2       # num light intensity (0 - 3)
);

Fog

Fades objects to a color at a distance (client-side only).

GAME.SCENE.setFog(
    "#fff", # str color
    100     # num fog distance
);

Environments

A scene can feature several environments. Each environment is made up of:

To have multiple environments in your scene, use an Environment Zone. The active environment depends on which zone the camera is currently in.

# get active environment zone index
num activeZone = (num) GAME.CAMERA.envZone; # index or -1 if in default

Lights

Light objects add ambience to your scene. Use them sparingly as they can cause performance issues.

Point Light

Emits light equally in all directions from a point (bulb, candle, flame).

# client-side only
obj lamp = GAME.SCENE.addPointLight(
    "#fff", # str color
    0,      # num x position
    0,      # num y position
    0,      # num z position
    50,     # num range
    0.1,    # num falloff
    false   # bool castShadow
);

Directional Light

Emits light in a specific direction in world space (sun).

# client-side only
obj sun = GAME.SCENE.addDirLight(
    "#fff", # str color
    0,      # num x direction
    0,      # num y direction
    0,      # num z direction
    false   # bool castShadow
);

Spot Light

Emits light in a specific direction from a point (flashlight, projector).

# client-side only
obj flashlight = GAME.SCENE.addSpotLight(
    "#fff", # str color
    0,      # num x position
    20,     # num y position
    0,      # num z position
    0,      # num x target pos
    0,      # num y target pos
    0,      # num z target pos
    50,     # num range
    0.1,    # num decay
    1,      # num intensity
    0,      # num angle (degrees)
    0,      # num penumbra
    false   # bool castShadow
);

Rect Area Light

Emits light from a rectangular area (windows, screens).

# client-side only
obj window = GAME.SCENE.addRectLight(
    "#fff", # str color
    0,      # num x position
    0,      # num y position
    0,      # num z position
    1,      # num width
    1,      # num height
    1       # num length
);

Performance Alternatives

For better performance, use image-based light objects instead of real-time lights:

Light Cone - gradient cone object with emissive texture:

obj lightCone = GAME.SCENE.addLightCone(
    "#fff", # str color
    0,      # num x position
    0,      # num y position
    0,      # num z position
    10,     # num width
    10,     # num length
    20,     # num height
    data    # obj additional data
);

Light Bar - gradient plane object with emissive texture:

obj lightBar = GAME.SCENE.addLightBar(
    "#fff", # str color
    0,      # num x position
    0,      # num y position
    0,      # num z position
    10,     # num width
    10,     # num length
    data    # obj additional data
);

You may also choose to bake your lighting in external software and import the finished scene as an asset.

Object Additional Data

When adding an object to your scene, you can include additional data to customize it:

# all fields are optional
obj additional = {

    # Works on all object types:
    opacity: 0.5,
    emissive: "#ff0000",
    forceTransparency: true,
    side: 0,                   # 0 to 2
    doubleSided: false,
    textureStretching: false,
    textureScale: 1.0,         # 0.00 to 10.00
    textureMoveAxis: 0,        # 0 = x, 1 = y
    textureMoveSpeed: 0,       # -20 to 20
    textureOffsetX: 0.0,       # 0.00 to 1.00
    textureOffsetY: 0.0,       # 0.00 to 1.00
    textureRotation: 0,        # 0 to 360

    # Asset Only:
    textureSmoothing: false,
    spinSpeed: 0,              # -20 to 20
    spinAxis: 0,               # 0 = x, 1 = y
    animSpeed: 1.0,            # 0.01 to 10.00
    animStart: "Idle",         # starting clip name
    alwaysRender: false,
    alphaTest: 0.5             # 0.00 to 1.00
};

# additional data is passed into addCube, addAsset etc.

Moving, Rotating & Scaling Objects

Any 3D object can be moved, rotated or scaled (client-side):

# create cube object
obj cube = GAME.SCENE.addCube(
    "",     # no texture
    "#fff", # white color
    0, 0, 0,      # position x, y, z
    10, 10, 10    # width, height, length
);

# moving objects
cube.move(0, 0, 0);                  # set cube position
(num) cube.position.x += 1;          # move cube on x-axis
GAME.SCENE.movObj(cube, 0, 1, 0);    # move cube via action
cube.position.x = 10;                # set object x position

# scale objects
cube.scale.x = 5;                    # scale cube on x-axis
GAME.SCENE.scaleObj(cube, 5, 1, 1);  # scale cube via action

# rotate objects
cube.rotate(0, 0, Math.PI);
cube.rotation.x = Math.PI;               # rotate on x-axis
GAME.SCENE.rotObj(cube, 0, 0, Math.PI);  # rotate via action

# look at point
cube.lookAt(0, 0, 0);

Removing Objects

# remove specific object from scene
cube.delete();

# clear entire scene
GAME.SCENE.clear(); # removes all objects in scene

Attaching Objects

You can attach objects to other 3D objects (client-side):

# attach cube to camera
cube.attachTo(GAME.CAMERA.getObj(), 0, 0, 0);

# attach cube to other object
cube.attachTo(otherObj, 0, 0, 10);

# attach cube to a player
cube.attachTo(player, 0, 0, 0);

# attach at current location (at origin)
cube.attachTo(player, 0, 0, 0, true);

# detach
cube.detach();

Coordinate System

Coordinates in 3D space:

# X: left-right
# Y: up-down
# Z: backward-forward

You can convert 3D coordinates into 2D screen-space:

# get screen-space coords
obj coords2D = GAME.SCENE.posToScreen(0, 10, 0);
(num) coords2D.x;
(num) coords2D.y;
(bool) coords2D.onScreen; # true/false

This is useful for adding 2D overlays to objects such as healthbars, text tags, etc.

Object Visibility

Any 3D object can be hidden:

obj cube = GAME.SCENE.addCube("", "#fff", 0, 0, 0, 10, 10, 10);
cube.visible = false; # hide cube