Getting Started — Vanilla JavaScript — Five SDK

Info

This tutorial does not depend on any frontend framework. Complete source examples: JavaScript | TypeScript.

What you will learn in this chapter

Setting up your development environment.
How to import the Five SDK.
Rendering a 3D space on screen.

Preparation

Development environment

You need a modern browser.

Info

Five SDK supports the following browsers. Choose whichever one you are comfortable with:

Safari	Safari on iOS	Chrome	Chrome for Android	Edge	Firefox
>= 9	>= 9	>= 49	>= 93	>= 13	>= 45

Install Node.js ^20.19.0 or >=22.12.0, matching the Vite 8 engine requirement used by this guide.

Using a build tool

This example initializes the development environment with Vite. You can initialize it yourself with the code below.

	# npm 6.x
	npm create vite@9.1.1 my-vue-app --template vanilla

	# npm 7+, extra double-dash is needed:
	npm create vite@9.1.1 my-vue-app -- --template vanilla

	# npm 6.x
	npm create vite@9.1.1 my-vue-app --template vanilla-ts

	# npm 7+, extra double-dash is needed:
	npm create vite@9.1.1 my-vue-app -- --template vanilla-ts

Under src, create the directory for this tutorial: src/0.getting-started.

Each tutorial creates a new directory as a record, making it easier to summarize and look things up. By the time you finish the course, you will end up with a directory structure like this:

src
├── 0.getting-started
├── 1.displaying-work
├── 2.knowing-state
...

The complete code samples use the same directory structure, so you can refer to them at any time.

Tip

If you are familiar with other build tools such as Webpack | Snowpack | parcel, you are free to use them instead.

Creating the HTML file

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" href="data:;base64,iVBORw0KGgo=" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Getting started</title>
    <!-- highlight-start -->
    <style>
      * {
        margin: 0;
        padding: 0;
      }
      html,
      body,
      #app {
        width: 100%;
        height: 100%;
        overflow: hidden;
      }
    </style>
    <!-- highlight-end -->
  </head>
  <body>
    <!-- highlight-start -->
    <div id="app"></div>
    <script type="module" src="./index"></script>
    <!-- highlight-end -->
  </body>
</html>

Info

Importing directly with <script type="module" src="./index"></script> is a Vite feature. If you use another build tool, handle the imports and entry file yourself — for example, by using HtmlWebpackPlugin with Webpack.

Writing the test logic

Let's first create a simple Hello World to make sure the whole setup runs end to end.

  const app = document.querySelector("#app");
  // highlight-start
  app.innerHTML = "Hello World.";
  // highlight-end
  export {};

  const app = document.querySelector("#app")!;
  // highlight-start
  app.innerHTML = "Hello World.";
  // highlight-end
  export {};

The trailing export {}; is required because Vite imports files with type="module", so every file must be a module and therefore needs an export. If you use another build tool, write it according to that tool's requirements.

Start the dev server with npm run dev and navigate to the current page at " http://localhost:3000/src/0.getting-started/index.html ".

Info

Check your console — the port number may change depending on your configuration and which ports are currently in use, so rely on the console output. If you use another build tool, start the server according to that tool's requirements.

Then you will see the following output on the page:

Hello World.

If you see this, your build tool setup is complete.

The following chapters will not describe the steps above in detail again, so make sure you complete them.

Installing the dependency packages from npm

Install the dependencies in your project directory:

npm install @realsee/five@6.8.9 three@0.117.1

Info

@realsee/five — the Five SDK rendering engine.
three — Three.js is the graphics/math library that Five SDK depends on. Use the exact 0.117.1 version.

Rendering a 3D space

It's time to render a VR scene and take a look.

Loading a 3D space

Delete your previous Hello World code. We'll rewrite it from scratch. You don't need to understand what the following code means yet — you'll learn that in the next chapter.

  import { Five, parseWork } from "@realsee/five";

  const workURL =
    "https://vr-public.realsee-cdn.cn/release/static/image/release/five/work-sample/07bdc58f413bc5494f05c7cbb5cbdce4/work.json";

  const five = new Five();

  five.appendTo(document.querySelector("#app"));

  fetch(workURL)
    .then((res) => res.json())
    .then((json) => {
      const work = parseWork(json);
      five.load(work);
    });

  export {};

  import { Five, parseWork } from "@realsee/five";

  const workURL =
    "https://vr-public.realsee-cdn.cn/release/static/image/release/five/work-sample/07bdc58f413bc5494f05c7cbb5cbdce4/work.json";

  const five = new Five();

  five.appendTo(document.querySelector("#app")!);

  fetch(workURL)
    .then((res) => res.json())
    .then((json) => {
      const work = parseWork(json);
      five.load(work);
    });

  export {};

Go back to your browser and see whether a 3D space is now displayed. You can control the view with your mouse or touch gestures — the basic navigation features are already included.

Making the view fit the screen

Try resizing the browser window. You'll notice the view does not change with the window size, which is not what we want. Let's add this capability:

  import { Five, parseWork } from "@realsee/five";

  const workURL =
    "https://vr-public.realsee-cdn.cn/release/static/image/release/five/work-sample/07bdc58f413bc5494f05c7cbb5cbdce4/work.json";

  const five = new Five();

  five.appendTo(document.querySelector("#app"));

  fetch(workURL)
    .then((res) => res.json())
    .then((json) => {
      const work = parseWork(json);
      five.load(work);
    });

  // highlight-start
  window.addEventListener("resize", () => five.refresh(), false);
  // highlight-end

  export {};

  import { Five, parseWork } from "@realsee/five";

  const workURL =
    "https://vr-public.realsee-cdn.cn/release/static/image/release/five/work-sample/07bdc58f413bc5494f05c7cbb5cbdce4/work.json";

  const five = new Five();

  five.appendTo(document.querySelector("#app")!);

  fetch(workURL)
    .then((res) => res.json())
    .then((json) => {
      const work = parseWork(json);
      five.load(work);
    });

  // highlight-start
  window.addEventListener("resize", () => five.refresh(), false);
  // highlight-end

  export {};

Go back to your browser and check whether it behaves as expected.

Great job 🥳!

What you will learn in the next chapter

Understanding what a Work is.
Understanding how the code you just wrote works, such as parseWork(json) and five.load(work).