Installation

TIP

WebGPU is a low-level access API. To prevent MITM attackers, most browsers restrict WebGPU usage only in Secure contexts. When deploying a web application built with WebGPU or Orillusion, users need to deploy it on an https based secure doamin or access it via a localhost domain, such as http://127.0.0.1, http://localhost or http://*.localhost for custom domains.

Install by NPM

We recommend using frontend build tools based on Node.js to develop Web3D applications. For example, you can use frontend frameworks such as Vite or Webpack to build complex frontend projects. You can also use TypeScript for more convenient development.

1. Installing dependencies Use the npm command in the command prompt to install engine dependencies:

npm install @orillusion/core --save

2. Import modules

Import certain modules:

import { Engine3D, Camera3D } from '@orillusion/core'

Or you can import the entire module:

import * as Orillusion from '@orillusion/core'

Note: The Orillusion engine requires a browser that supports the latest WebGPU standard, such as Chrome >= 114. Therefore, there is no need to maintain compatibility with older JavaScript syntax. The default production release is targetting ESNext syntax. If you are using build tools like Vite or Webpack to deploy your project, it is recommended to set the build target to ES2021 or later to ensure all APIs operate in their optimal state.

Import Via CDN Links

We support quick access to the orillusion engine directly through a CDN link with the <script> tag. Here is an example of using @orillusion/core link.

Users can use third-party NPM distribution services to load various versions of orillusion files, such as unpkg or jsdelivr. For local development, users can download the corresponding version of js file.

1. Using Global Build

<!- Use the latest published version through unpkg->
<script src="https://unpkg.com/@orillusion/core/dist/orillusion.umd.js"></script>
<!- Or use the specified version ->
<script src="https://unpkg.com/@orillusion/core@0.8.x/dist/orillusion.umd.js"></script>

The page globally loads <script>, and a global variable (named Orillusion) is declared in the window object, which can be used directly as follows:

<script>
  const { Engine3D, Camera3D } = Orillusion
</script>

2. Using the ESModule Build

We recommend using ESModule for development. Most browsers already support the native ES module, and users can directly import the orillusion.es.js build that complies with ESNext for rapid development.

<script type="module">
    // Use the latest published version through unpkg.com 
    import { Engine3D, Camera3D } from "https://unpkg.com/@orillusion/core/dist/orillusion.es.js"
    // Or use the specified version
    import { Engine3D, Camera3D } from "https://unpkg.com/@orillusion/core@0.8.x/dist/orillusion.es.js" 
</script>

Note that we use the <script type="module"> label, which allows us to use modular syntax like import and export directly in the browser. And with the vite or other front-end build tools, we can import CDN links directly into our project for development.

3. Using importmap

To standardize the management of dependencies with its address, we recommend using Import Maps to manage how the browser locates dependent packages:

<!-- Define the names and corresponding addresses of the ES module -->
<script type="importmap">
{
  "imports": {
    "@orillusion/core": "https://unpkg.com/@orillusion/core/dist/orillusion.es.js",
    "@orillusion/stats": "https://unpkg.com/@orillusion/stats/dist/stats.es.js"
  }
}
</script>
<!-- Use custom names to import -->
<script type="module">
    import { Engine3D, Camera3D } from "@orillusion/core"
    import { Stats } from "@orillusion/stats"
</script>