API Reference - samrun0/ion-3D-Engine GitHub Wiki
ion's API is consistent with the Three.js API
💢 Core
ion Engine is based on entity-component-system (ECS) architecture which is a popular and powerful pattern to develop 3D applications. The building blocks of this model are:
-
Components: they are encapsulated data holders and decoupled from the application logic. Components can be attached to entities to describe their attributes and how to be treated by systems.
-
Entities: each entity represents a different conceptual object with the desired components in the 3D scene. For example, an entity with a GUI component can be rendered as a 3D user interface.
-
Systems: a system is a process which acts on the entities. For example, a GUI system queries the entities with a GUI Component and handles the GUI related operations and renders them into the 3D scene.
💠 Components
Components are encapsulated data holders and decoupled from the application logic. Components can be attached to entities to describe their attributes and how to be treated by systems.
GUIComponent
A GUIComponent stores data and attributes related to an HTML DOM tree and it can be used to render HTML in a 3D scene. This also requires a GUISystem to be added to the engine.
🔹 Examples
🔹 Constructor
GUIComponent({
rootElement: HTMLElement,
pixelRatio: number,
material: THREE.Material,
transparent: boolean,
renderTimeout: number,
htmlFilter: () => boolean,
textureConstants: object,
})
rootElement[required] - any valid HTML Element to be rendered in 3D along side all of its descendants.
pixelRatio[optional] - size ratio set to convert rootElement's dimensions (width and height in pixels) to world units. e.g. if set to 100 then every 100 pixels of rootElement equals to ThreeJS world unit when rendered in the scene; Defaults to 100.
material[optional] - custom material of the plane mesh displaying the HTML content; Defaults to THREE.MeshBasicMaterial.
transparent[optional] - defines whether the GUIComponent is transparent when rendering the HTML content; Defaults to true.
renderTimeout[optional] - an interval of time (milliseconds) elapsed from the last user interaction with the component or any HTML DOM events/updates to dynamically render rootElement. This is can be used for static HTML content and optimization; Defaults to 2000ms.
htmlFilter[optional] - a callback function to filter the DOM trees by returning false for the HTML elements that are not needed to be rendered.
textureConstants[optional] - to set and override any ThreeJS texture constants; Defaults to ThreeJS original texture constants.
🔹 Properties
rootElement: HTMLElement
pixelRatio: number
material: THREE.Material
transparent: boolean
renderTimeout: number
htmlFilter: () => boolean
textureConstants: object
🔹 Methods
No methods.
🔹 Source
🛠 Systems
A system is a process which acts on the entities. For example, a GUI system queries the entities with a GUI Component and handles the GUI related operations and renders them into the 3D scene.
GUISystem
🔹 Examples
🔹 Constructor
GUISystem()
🔹 Properties
No properties.
🔹 Methods
No methods.
🔹 Source
📥 Entity
🔹 Examples
🔹 Constructor
Entity({
name: string;
})
name[optional] - name of the entity; Defaults to empty string.
🔹 Properties
id: string
UUID of this instance. This gets automatically generated and shouldn't be edited.
name: string
Optional name for this entity. Default is an empty string.
components: object
An object map holding components added to this entity.
🔹 Methods
addComponent (component: Component): void
Attaches a component to this entity.
getComponent (compType: string): Component
Returns the component of a given type.
🔹 Source
📘 Constants
Control Constants
These are assigned to control when creating an engine instance. This is how to choose between various available control modes that are used for user interaction and navigating the 3D scene.
ION.SpaceControl
ION.FirstPersonControl
ION.ArcBallControl
ION.FlyControl
Other Constants
ION.zIndex
This is the zIndex constant value used to assign the HTLM canvas element and display other necessary HTML elements on top of the canvas.
⚙️ Engine
🔹 Examples
🔹 Constructor
constructor({
canvas: HTMLCanvasElement,
scene: THREE.Scene,
control: string,
controlOptions = {
vrTeleportEnabled: boolean,
vrTeleportList: Array,
framebufferScaleFactor: number
},
vrEnabled = boolean,
graphicsOptions = object,
fullScreen = boolean,
stats = boolean,
camera = THREE.Camera,
})
canvas[required] - the primary canvas element that engine draws its output.
scene[optional] - a custom ThreeJS scene to override the default scene; Defaults to the ion template scene.
control[optional] - can be set to any of control constants to define the control mode: Defaults to ION.SpaceControl.
controlOptions[optional] - an object map of control parameters. See the engine properties section for the list of options.
vrEnabled[optional] - set to true to enable the WebXR functionalities and to be able to transition into VR mode; Defaults to false.
graphicsOptions[optional] - an object map of graphics parameters to adjust ThreeJS renderer's properties. See the engine properties section for the list of options; Defaults to original ThreeJS values.
fullScreen[optional] - if set to true, the engine seamlessly expands the canvas element and assigns the necessary values to display the scene in fullscreen; Defaults to true.
stats[optional] - if set to true, stats is initialized and made visible; Defaults to false.
camera[optional] - a custom camera to pass and override the default camera; Defaults to a sample THREE.PerspectiveCamera.
🔹 Properties
canvas: HTMLCanvasElement
the primary canvas element that engine draws its output.
renderer: THREE.Renderer
Renderer that is initialized with graphicsOptions and it is used to render the 3D scene on the canvas.
camera: THREE.Camera
The camera object that is passed to the renderer and control. Whether the default camera or a custom camera provided.
scene: THREE.Scene
The main scene that is rendered by the engine. A default scene is generated if not provided from the constructor. You can directly add any valid ThreeJS meshes or lights to the scene to customize the experience.
controlOptions: object
Available control options and their default values are:
controlOptions = {
vrTeleportEnabled: false,
vrTeleportList: [],
framebufferScaleFactor: 2.0
}
To enable VR teleportation functionality set vrTeleportEnabled to true. This way a pointer shows up once user points at any valid meshes that are listed in vrTeleportList using the VR controller in order to move through the 3D scene. List any meshes that you wish to be able to teleport to in vrTeleportList. Meshes of type GUIComponents are excluded and are not selectable by default.
framebufferScaleFactor Specifies the scaling factor to use when determining the size of the framebuffer when rendering to a XR device. The value is relative to the default XR device display resolution. The default is 2.0 which is considered very high quality. You can lower this value ff you wish to have a better performance and FPS when in VR mode . Visit WebXRManager for more info.
vrEnabled: boolean
A boolean that inedcates if WebXR functionalities are enabled or not.
graphicsOptions: object
Options to set the renderer's properties and their default values:
graphicsOptions: {
shadowMapEnabled: false,
shadowMapType: THREE.PCFShadowMap,
outputEncoding: THREE.LinearEncoding,
toneMapping: THREE.LinearToneMapping,
physicallyCorrectLights: false,
},
Reminder: enabling shadow map and physicallyCorrectLights lowers the performance and FPS specially in VR mode.
stats: any
If set to true, stats is initialized and made visible; Defaults to false.
🔹 Methods
addEntity(entity: Entity): void
Processes the given entity and its components and adds it to the entity registry.
addSystem(system: System): void
Adds a system to engine to be executed at runtime.
start(): void
Starts the animation loop and rendering process.
setRuntimeCallback(cb: Function): void
Setting runtime callbacks gives you the ability to execute your own update functions in the animation loop at each frame:
engine.setRuntimeCallback(() => {
console.log('Running at each frame...');
});
See the live demo and full source code of such integration.
setVRTeleportList(vrTeleportList: THREE.Mesh[]): void
Assigns a new array of meshes to the vrTeleportList property. This method can be used during runtime. vrTeleportList can be also assigned from the constructor. Meshes in vrTeleportList are used for teleportation in VR mode. Meshes of type GUIComponents are excluded and are not selectable by default.
🔹 Source
🕹 Controls
Controls are used for user interaction and navigating the 3D scene. See Control Constants to choose between different types of controls.
SpaceControls
🔹 Examples
🔹 Constructor
SpaceControls(camera: THREE.Camera, renderer: THREE.Renderer)
camera[required] - camera that is used to interact with the scene.
renderer[required] - renderer that is used to render the 3D scene.
🔹 Properties
No props.
🔹 Methods
updateControl(delta: number): void
Method to call in the animation loop to update the control.
🔹 Source
FirstPersonControls
🔹 Examples
🔹 Constructor
FirstPersonControls(camera: THREE.Camera, renderer: THREE.Renderer)
camera[required] - camera that is used to interact with the scene.
renderer[required] - renderer that is used to render the 3D scene.
🔹 Properties
No props.
🔹 Methods
updateControl(delta: number): void
Method to call in the animation loop to update the control.
🔹 Source
ArcBallControls
🔹 Examples
🔹 Constructor
ArcBallControls(camera: THREE.Camera, renderer: THREE.Renderer)
camera[required] - camera that is used to interact with the scene.
renderer[required] - renderer that is used to render the 3D scene.
🔹 Properties
No props.
🔹 Methods
updateControl(delta: number): void
Method to call in the animation loop to update the control.
🔹 Source
FlyieControls
🔹 Examples
🔹 Constructor
FlyieControls(camera: THREE.Camera, renderer: THREE.Renderer)
camera[required] - camera that is used to interact with the scene.
renderer[required] - renderer that is used to render the 3D scene.
🔹 Properties
No props.
🔹 Methods
updateControl(delta: number): void
Method to call in the animation loop to update the control.
🔹 Source