Using oasis to develop a hop by hop (I) -- Scene Building

《 Take a jump 》 It is the first well-made wechat game , It is also a very popular game . Here we jump one by one MVP（ Simplest feasible version ） Version as an example , Let us know 『 How to use Oasis Develop a Web 3D game 』 This process . The end result is as follows ：

You can ： https://stackblitz.com/edit/oasis-jump-aeuowy?file=src/index.ts Experience and try to modify the code .（BTW： If access is not available or too slow , You can go there by yourself https://github.com/gz65555/jump-game/tree/feat/game Clone the project to local startup .）

We divide the core part into three parts , scene 、 role and The game logic , The following tutorial will focus on these three parts , Implement a hop by hop minimum available version （ Not a complete game ）. The following figure shows the analysis of the core modules ：

In the first phase, we are going to make the most basic scenes , Finish lighting , The camera , Placement of basic base .

Before specifically entering development , We need to build the whole project first .

Project construction

So let's use create-oasis-app Create project .

The first step in using the command is to install Node.js. If installed Node.js(version >= 12.0.0) You can execute the command to create oasis Templates ：

npm init @oasis-engine/oasis-app

Because we don't need to develop the front-end part , So use it directly Vanilla Template can be . The following is the procedure of invoking the command .

When execution is complete , We went into the project terminal in , perform ：

npm install

Use after installing the dependency ：

npm run dev

start-up dev The server , The process is shown in the figure below ：

And on again http://localhost:3000 You can see ：

It indicates that the construction of the project has been completed . At this point, the project directory is as follows ：

|-jump-game
  |-index.html   // HTML  file 
  |-main.js    //  entrance  js  file 
  |-package.json  //  Project description file 
  |-src
  |  |-index.ts   // oasis  Part of the code 

Basic scenario construction

Engine and scene initialization

We use it IDE Open the project , find /src/index.ts

As shown in the following code ：

import { Camera, Vector3, WebGLEngine, DirectLight } from "oasis-engine";

//  Initialize engine 
const engine = new WebGLEngine("canvas");
//  According to the page setup  canvas  size 
engine.canvas.resizeByClientSize();

const zeroVector = new Vector3(0, 0, 0);

//  Set background color 
const scene = engine.sceneManager.activeScene;
scene.background.solidColor.setValue(208 / 255, 210 / 255, 211 / 255, 1);
scene.ambientLight.diffuseSolidColor.setValue(0.5, 0.5, 0.5, 1);

//  Create a root node 
const rootEntity = scene.createRootEntity();
const cameraEntity = rootEntity.createChild("camera");
cameraEntity.transform.setPosition(-100, 100, 100);
const camera = cameraEntity.addComponent(Camera);

//  Initialize camera 
camera.isOrthographic = true;
cameraEntity.transform.lookAt(zeroVector);

//  Initialize lights 
const directLightEntity = rootEntity.createChild("directLight");
const directLight = directLightEntity.addComponent(DirectLight);
directLight.intensity = 0.5;
directLightEntity.transform.setPosition(10, 30, 20);
directLightEntity.transform.lookAt(zeroVector);

engine.run();

This code creates the engine , scene , And the camera is initialized , The light . The camera uses an orthographic camera , Towards origin . The direct light is also set to face the origin .

After completing the above steps, the scene is still gray , Let's add the logic of base generation and camera movement to the scene .

Scene base initialization

Let's create a SceneScript.ts To manage the whole scene , And in rootEntity Add SceneScript：

const sceneScript = rootEntity.addComponent(SceneScript);

The script is Oasis Engine Very core concept , Is a special component , Components are attached to entities （Entity） Upper , To provide the engine with the ability to expand . For more information on entity and component concepts, see ：《 Entities and components 》 file .

Next , stay SceneScript Of onAwake Create a in the lifecycle ground Entity , It is used to place the base for jumping .onAwake The lifecycle function is called when the mounted entity is activated , It is generally used to place the initialization code . There are also many life cycle hook functions in the engine to help developers write business logic , More script lifecycles can be viewed ：《 Script 》.

Create at the same time TableManager Object to control the base generation .

onAwake() {
  this.ground = this.entity.createChild("ground");
  this.tableManager = new TableManager(this._engine, this.ground);
}

We are TableManager Create reusable materials in （Material） And grid （Mesh）. Create a 3D Rendering of objects , Need to use MeshRenderer Mesh renderer component , Set the material and mesh .

the reason being that MVP edition , I only use a red cube here Table As a sign ：

import {
  BlinnPhongMaterial,
  Engine,
  Entity,
  MeshRenderer,
  ModelMesh,
  PrimitiveMesh,
} from "oasis-engine";
import { Config } from "./Config";

export class TableManager {
  //  Base  Mesh
  private cuboidMesh: ModelMesh;
  //  The material of the base 
  private cuboidMaterial: BlinnPhongMaterial;

  constructor(engine: Engine, private sceneEntity: Entity) {
    //  Create basic mesh 
    this.cuboidMesh = PrimitiveMesh.createCuboid(
      engine,
      Config.tableSize,
      Config.tableHeight,
      Config.tableSize
    );
    //  Create basic materials 
    this.cuboidMaterial = new BlinnPhongMaterial(engine);
    //  Set material color 
    this.cuboidMaterial.baseColor.setValue(1, 0, 0, 1);
  }
  
  //  Create a square base 
  createCuboid(x: number, y: number, z: number) {
    //  Create render entities 
    const cuboid = this.sceneEntity.createChild("cuboid");
    const renderEntity = cuboid.createChild("render");
    //  Set coordinates 
    renderEntity.transform.setPosition(0, Config.tableHeight / 2, 0);
    cuboid.transform.setPosition(x, y, z);
    //  establish  MeshRenderer  Components 
    const renderer = renderEntity.addComponent(MeshRenderer);
    //  set grid 
    renderer.mesh = this.cuboidMesh;
    //  Settings settings materials 
    renderer.setMaterial(this.cuboidMaterial);
    return { entity: cuboid, size: Config.tableSize };
  }

  //  Remove all bases 
  clearAll() {
    this.sceneEntity.clearChildren();
  }
}

We can see the above tableSize and tableHeight It's all in GameConfig The definition of , We also need to create a Config.ts To set the game configuration ：

export module Config {
  export const tableHeight = 5 / 3;
  export const tableSize = 8 / 3;
}

By converging the configuration to a unified file , Easy configuration modification .

Let's get to SceneScript Add reset Method ：

reset() {
  //  Remove all bases 
  this.ground.clearChildren();
  //  The first sled initialized 
  this.tableManager.createCuboid(-2.5, 0, 0);
  //  Initialize the second sled 
  this.tableManager.createCuboid(4.2, 0, 0);
}

reset Method is the method that needs to be called every time the game starts and ends . The above values are the results of debugging in the actual development , It is relatively close to the real game .

We are index.ts call sceneScript.reset() You can see the effect ：

summary

This article talks about the simple scene construction of jump by jump , The knowledge involved is ：

• Oasis Project construction

• Component system architecture

• Script life cycle

• 3D Setting up the scene

• • The camera
  • The light
  • Mesh renderers

The next installment will bring the logical part of the scenario ： Base generation and camera moving parts .

This tutorial code can refer to feat/init Branch .