To create a 3D Website, you will need to understand how to specify positions and orientations in 3D space in a 3D Web World. This will be easier if you have some familiarity with 3D concepts from elsewhere, for example use of DirectX or OpenGl, game scripting, or scripting in Second Life; basic 3D maths is beyond the scope of this document.
The 3D Web browser Core API contains various 3D types for representing 3D positions, vectors, orientations, transforms and geometric shapes. These types are located in the Core.Math and Core.Math.Geom namespaces.
For example, the 'Vector3' type represents a vector in 3D space.
A new Vector3 can be created using code like:
local v = Core.Math.Vector3.New(x, y, z)
There are aliases for all the Math and Math.Geom New functions in the global namespace, so the above code can also be written:
local v = Vector3(x, y, z)
This simplifies use of these types considerably.
The x, y, z values passed in to the New function specify the three coordinate values.
See the full documentation for a list of all the kinds of parameters that the New function can take.
Leave them out to get a zero vector.
Once a Math value has been created, it can be used in normal ways:
local v1 = Vector3()
local v2 = Vector3(1, 2, 3)
assert(v2 > v1)
local r = v1 + v2
assert(r:GetX() == 1)
assert(Core.Math.Dot(r, v2) == 14)
And so on.
There are some standard Vector3 values defined in the Core API:
Core.xAxis = Vector3(1, 0, 0)
Core.yAxis = Vector3(0, 1, 0)
Core.zAxis = Vector3(0, 0, 1)
The 3D Web browser provides the following vector types: Vector2, Vector3 and Vector4. A Vector2 is used for 2D coordinates, for example specifying a location on a texture or 2D browser. Vector3 is the standard type for 3D coordinates. Vector4 provides a fourth coordinate and can be used for homogenous operations (useful for some advanced 3D applications).
Each 3D Website has its own 3D space, known as World Space.
In order to allow 3D Websites to be large, a special type is used to represent a position in World Space, the 'WorldPos' type.
local wp = WorldPos(1, 2, 3)
This type uses a special representation that provides enough range to cover the whole solar system with a precision of approximately 1 micrometer (one thousandth of a millimeter) across the entire range.
Whenever a position in World coordinates is needed, this type must be used.
For example, the position of a 3D model or a light must be specified using a WorldPos value.
Adding a Vector3 to a WorldPos results in a new WorldPos.
This way, a World position can be updated and changed using a Vector3.
The 3D Web browser uses Quaternions to represent rotation and orientation.
A Matrix type is available, but it is not well supported and its use is deprecated.
Quaternions provide a much more concise, robust representation of rotations.
There are various functions for creating Quaternions, including:
local q = Core.Math.Yaw(math.rad(90))
local q = Core.Math.Pitch(math.rad(90))
local q = Core.Math.Roll(math.rad(90))
The Yaw, Pitch and Roll functions each take an angle in radians and return a quaternion rotation about the Y, X and Z axes respectively.
Other functions for creating Quaternions include AxisAngle, LookAt and BetweenVectors.
There are standard math functions in the Core.Math namespace that operate on the math types.
AxisAngle is one example; others include:
v = Core.Math.Cross(v1, v2) Calculates the cross product of two vectors.
l = Core.Math.Length(v) Calculates the length of a vector.
v = Core.Math.Lerp(v1, v2, l) Linearly interpolate between two values.
q = Core.Math.Invert(q) Calculates the inverse of a quaternion.
For full details and a complete list, see the full documentation for any Package.
The 3D Web browser has an 'Xform' type (short for transform) that is used to represent a full 3D transform, including a uniform scale, a rotation and a translation. There are two variants: XformW and XformL.
XformW is a World transform; the translation is in World coordinates using a WorldPos value. An XformW can be used to specify the full location, orientation and size of an entity in the world. It is often used when constructing a new object such as a 3D model or WorldPortal, in order to place it at a given location in the World.
XformL is a local transform with a translation specified using a Vector3. XformLs are used to transform from one local space to another. Their use by 3D Web application code is less common.
There are functions for the combination and application of Xforms in the Core.Math.Geom namespace; see the full documentation for details.
The Core.Math.Color type defines a 4 component color value with red, green, blue and alpha (opacity) values. Colors are used whenever a color is needed; for example for a material color or a light color. There is also an 'Hsl' type which represents a color in a Hue-Saturation-Luminance format that may be easier to work with in some cases.
The 3D Web browser defines a set of Geometric types in the Core.Math.Geom namespace. These include Points, Lines, Spheres, Boxes, Axis-Aligned Boxes (AaBoxes) and Frusta. All geometric types come in 'W' and 'L' variants, using either WorldPos positions or Vector3 positions respectively. These types are rarely used for normal 3D Websites, although advanced applications may need them.