Skip to content

Commit

Permalink
Merge pull request #228 from VCityTeam/dev-unstable
Browse files Browse the repository at this point in the history 
2.33.0
  • Loading branch information
@valentinMachado
valentinMachado authored Sep 20, 2021
2 parents 1541067 + 7792402 commit 923b121
Show file tree
Hide file tree
Showing 29 changed files with 638 additions and 156 deletions.
182 changes: 146 additions & 36 deletions Doc/Devel/LocalGameTutorial.md
View file
Original file line number Diff line number Diff line change
@@ -1,26 +1,25 @@
<!-- @format -->


# Local Game tutorial :lion:

Welcome in the first ud-viz game tutorial. We will proceed step by step, if you want to consult the complete project, you can find it in this [folder](../../examples). At the end of this tutorial you will fly with your zeppelin in the sky of Lyon, and collect some spheres!
Welcome in the first ud-viz game tutorial. We will proceed step by step, if you want to consult the complete project, you can find it in this [**folder**](../../examples). At the end of this tutorial you will fly with your zeppelin in the sky of Lyon, and collect some spheres!

![Zeppelin](./Pictures/zeppelin.gif)

# Create your game project :smile:

[Working environment](./LocalGameTutorial.md#working-environment)
[Initialize your project](./LocalGameTutorial.md#initialize-your-project)
[Importing ud-viz](./LocalGameTutorial.md#importing-ud-viz)
[Create your game](./LocalGameTutorial.md#create-your-game)
[Parameterize itowns layers](./LocalGameTutorial.md#parameterize-itowns-layers)
- [Working environment](./LocalGameTutorial.md#working-environment)
- [Initialize your project](./LocalGameTutorial.md#initialize-your-project)
- [Importing ud-viz](./LocalGameTutorial.md#importing-ud-viz)
- [Create your game](./LocalGameTutorial.md#create-your-game)
- [Parameterize itowns layers](./LocalGameTutorial.md#parameterize-itowns-layers)

## Working environment

Steps :

- Create an empty folder that you can call `My_UD-Viz_Game`.
- Create a html script in your folder that you call `index.html`.
- Create a html script in your folder that you call `index.html`([Check out the final version](../../examples/LocalGame.html)).

> Open the folder in visual studio code or your favorite IDE :computer:
Expand Down Expand Up @@ -70,21 +69,21 @@ You can visit your page at http://localhost:8000/ but nothing is displayed (yet)

## Importing ud-viz


* For this purpose, in your HTML file (`index.html`) add the following script tag in the **\<body\>**.
- For this purpose, in your HTML file ([`index.html`](../../examples/LocalGame.html)) add the following script tag in the **\<body\>**.

```html
<script src="./assets/js/udv.js"></script>
```
* Then copy this [file](../../examples/assets/js/udv.js) in a **My_UD-Viz_Game/assets/js/** directory, which contains all the ud-viz code in a single file.

- Then copy this [**file**](../../examples/assets/js/udv.js) in a **My_UD-Viz_Game/assets/js/** directory, which contains all the ud-viz code in a single file.

Still nothing displayed but the library is now globally accessible.
> To keep this tutorial simple ud-viz is imported this way, but a [npm package](https://www.npmjs.com/package/ud-viz) exists and it's recommended to use it since you can benefit of the update with it. You can visit this [repository](https://github.com/VCityTeam/UD-Viz-Template) to see an example of a npm project using ud-viz as a package.

> To keep this tutorial simple ud-viz is imported this way, but a [npm package](https://www.npmjs.com/package/ud-viz) exists and it's recommended to use it since you can benefit of the update with it. You can visit this [repository](https://github.com/VCityTeam/UD-Viz-Template) to see an example of a npm project using ud-viz as a package.
## Create your game

* Let's create a script tag in the `index.html` and add the following code to start a new local game (*Still in the **\<body\>***):
- Let's create a script tag in the [`index.html`](../../examples/LocalGame.html) and add the following code to start a new local game (\*Still in the **\<body\>\***):

```html
<script type="text/javascript">
Expand All @@ -105,7 +104,7 @@ First a new world called `My World` is created, you have to specify at which 3D

Then a [LocalGame](../../src/Templates/LocalGame/LocalGame.js) is instanciated, to start it you need to pass a world and the path to a config file.

* Create a new folder called `./assets/config/` and, in it, a new file called [`local_game_config.json`](../../examples/assets/config/local_game_config.json) composed of the following code:
- Create a new folder called `./assets/config/` and, in it, a new file called `local_game_config.json`([final version](../../examples/assets/config/local_game_config.json)) composed of the following code:

```json
{
Expand Down Expand Up @@ -134,7 +133,7 @@ Ok, at this point, your **browser** should display something like the following,

That's great, you don't know it yet but this is Lyon, ok let's make the city appeared !

- Let's add these lines in your `local_game_config.json` file
- Let's add these lines in your [`local_game_config.json`](../../examples/assets/config/local_game_config.json) file

```json
"background_image_layer": {
Expand All @@ -161,7 +160,7 @@ Here we are parameterized layers of the [itowns](http://www.itowns-project.org/i

![2](./Pictures/2.png)

- Okay we are close, add these lines in `local_game_config.json`:
- Okay we are close, add these lines in [`local_game_config.json`](../../examples/assets/config/local_game_config.json):

```json
"3DTilesLayer": {
Expand All @@ -172,7 +171,7 @@ Here we are parameterized layers of the [itowns](http://www.itowns-project.org/i
}
```

Here data (geometries of buildings) are not collected from a distant server but locally, you need to download the [`lod_flying_campus` folder](../../examples/assets/lod_flying_campus) in `./assets/`.
Here data (geometries of buildings) are not collected from a distant server but locally, you need to download the [`lod_flying_campus` folder](../../examples/assets/lod_flying_campus) in `./assets/`.

Here is what you shoudl see now

Expand All @@ -182,10 +181,9 @@ That's it Lyon is here! Now we are going to add our zeppelin.

## Create a worldscript


First we are going to attach a [`WorldScript`](../../src/Game/Shared/GameObject/Components/WorldScript.js) to our `GameManager` game object. A world script is used to customize the world simulation, you can put your code in different events called by the game engine.

* In `index.html`, complete the declaration of the `myWorld` object as the following:
- In [`index.html`](../../examples/LocalGame.html), complete the declaration of the `myWorld` object as the following:

```js
gameObject: {
Expand All @@ -203,7 +201,7 @@ gameObject: {

Now our `GameManager` game object is linked to a world script named `worldGameManager`. We need to import that script in our game.

- To do so add these lines to your `local_game_config.json` file.
- To do so add these lines to your [`local_game_config.json`](../../examples/assets/config/local_game_config.json) file.

```json
"assetsManager": {
Expand All @@ -215,9 +213,9 @@ Now our `GameManager` game object is linked to a world script named `worldGameMa
}
```

Now we need to create the `worldGameManager.js` world script in the new folder `./assets/worldScripts/`.
Now we need to create the `worldGameManager.js`([Check out the final version](../../examples/assets/worldScripts/worldGameManager.js)) world script in the new folder `./assets/worldScripts/`.

* Fill the script with the following skeleton:
- Fill the script with the following skeleton:

```js
let Shared;
Expand All @@ -239,7 +237,7 @@ module.exports = class WorldGameManager {

## Add the zeppelin gameobject

* Let's add the zeppelin, add these lines into `init` method.
- Let's add the zeppelin, add these lines into `init` method of [`worldGameManager.js`](../../examples/assets/worldScripts/worldGameManager.js).

```js
init() {
Expand All @@ -262,7 +260,7 @@ We create a new gameobject called zeppelin and a [Render](../../src/Game/Shared/

As always when we point to assets with an id, we need to import that asset (here a 3D model). We gonna to use this [one](../../examples/assets/models/Zeppelin_Labex_IMU.glb).

- Like the worldscript add these lines in your `local_game_config.json` file :
- Like the worldscript add these lines in your [`local_game_config.json`](../../examples/assets/config/local_game_config.json) file :

```json
"assetsManager": {
Expand Down Expand Up @@ -295,8 +293,7 @@ Yes a zeppelin appears on the middle of the scene ! trust me...

Ok let's add a [LocalScript](../../src/Game/Shared/GameObject/Components/LocalScript.js) now to focus this zeppelin with the camera. These scripts are used to customize client-side game.


* GameManager in `index.html` becomes:
- GameManager in [`index.html`](../../examples/LocalGame.html) becomes:

```js
gameObject: {
Expand All @@ -313,7 +310,7 @@ gameObject: {
}
```

- Import it the same way that the worldscript with these lines in your `local_game_config.json` file.
- Import it the same way that the worldscript with these lines in your [`local_game_config.json`](../../examples/assets/config/local_game_config.json) file.

```json
"localScripts": {
Expand Down Expand Up @@ -354,7 +351,7 @@ Ok here is what the game looks like now, you should also be able to zoom in/out

Ok in the next steps we are gonna to move the zeppelin above the city.

* Let's add a new `commands.js` local script. Complete the declaration of the GameManager game object in `index.html` like below:
- Let's add a new `commands.js` local script. Complete the declaration of the GameManager game object in [`index.html`](../../examples/LocalGame.html) like below:

```js
gameObject: {
Expand All @@ -371,7 +368,7 @@ gameObject: {
}
```

* Modify `local_game_config.json` to import it
- Modify [`local_game_config.json`](../../examples/assets/config/local_game_config.json) to import it

```json
"localScripts": {
Expand All @@ -384,11 +381,11 @@ gameObject: {
}
```

* Then copy this [commands.js](../../examples/assets/localScripts/commands.js) local scrip in the folder `./assets/localScripts`.
- Then copy this [commands.js](../../examples/assets/localScripts/commands.js) local scrip in the folder `./assets/localScripts`.

Now commands are send to world simulation but the world simulation don't know what to do with them.

- In the `worldGameManager.js` add these lines in the `tick` function
- In the [`worldGameManager.js`](../../examples/assets/worldScripts/worldGameManager.js) add these lines in the `tick` function

```js
tick() {
Expand Down Expand Up @@ -424,13 +421,13 @@ tick() {
}
```

* You can now pilot the zeppelin! Try it with the Z,Q,S,D or the arrows keys.
- You can now pilot the zeppelin! Try it with the Z,Q,S,D or the arrows keys.

## Add collisions

Now we are going to add some collectable spheres.

- In `worldGameManager.js` add the method `createCollectableSphere`
- In [`worldGameManager.js`](../../examples/assets/worldScripts/worldGameManager.js) add the method `createCollectableSphere`

```js
createCollectableSphere(x, y) {
Expand Down Expand Up @@ -488,7 +485,7 @@ for (let i = 0; i < 10; i++) {

ok that's nice, now let handle the collision with these objects.

- First add a [Collider](../../src/Game/Shared/GameObject/Components/Collider.js) component to these spheres in `worldGameManager.js`
- First add a [Collider](../../src/Game/Shared/GameObject/Components/Collider.js) component to these spheres in [`worldGameManager.js`](../../examples/assets/worldScripts/worldGameManager.js)

```js
createCollectableSphere(x, y) {
Expand Down Expand Up @@ -522,7 +519,8 @@ ok that's nice, now let handle the collision with these objects.
}
```

* Then add a [Collider](../../src/Game/Shared/GameObject/Components/Collider.js) component to the zeppelin in the `init` method inside `this.zeppelin` declaration:
- Then add a [Collider](../../src/Game/Shared/GameObject/Components/Collider.js) component to the zeppelin in the `init` method inside `this.zeppelin` declaration:

```js
this.zeppelin = new Shared.GameObject({
name: 'zeppelin',
Expand All @@ -545,10 +543,120 @@ Ok now let's add a worldscript to the zeppelin to handle collision.

Create a new worldscript import it with the config files and create it in the assets.

[zeppelin.js](../../examples/assets/worldScripts/zeppelin.js)
Check out [zeppelin.js](../../examples/assets/worldScripts/zeppelin.js)

When you touch spheres with the zeppelin they are disapearing !!

## Add some UI

We are going to display the count of spheres collected.

The collision with spheres is detected inside a **WorldScript**, and the rendering of game (where to add UI for example) is handle by the **LocalScript**. We need to transfer this data from [`zeppelin.js`](../../examples/assets/worldScripts/zeppelin.js) (worldScript) to a [`zeppelin.js`](../../examples/assets/localScripts/zeppelin.js) (localScript).

- First add the _localscript_ [`zeppelin.js`](../../examples/assets/localScripts/zeppelin.js) to your zeppelin gameobject in your [`worldGameManager.js`](../../examples/assets/worldScripts/worldGameManager.js).

```js
LocalScript: {
idScripts: ['zeppelin'],
conf: { sphereCount: 0 },
}
```

Here we are going to use the conf attribute of LocalScript.

- Inside [`zeppelin.js`](../../examples/assets/worldScripts/zeppelin.js) (_worldscript_) the `onEnterCollision()` becomes:

```js
onEnterCollision() {
const go = arguments[0];
const result = arguments[1];
const worldContext = arguments[2];

const goCollided = result.b.getGameObject();
worldContext.getWorld().removeGameObject(goCollided.getUUID());

const zeppelinLocalScript = go.fetchLocalScripts()['zeppelin'];
zeppelinLocalScript.conf.sphereCount++;
}
```

Here the conf of the _localscript_ is modified, this will trigger a update event on the _localscript_.

- The [`zeppelin.js`](../../examples/assets/localScripts/zeppelin.js) (_localscript_) looks like this:

```js
/** @format */

let udviz;

module.exports = class Zeppelin {
constructor(conf, udvizBundle) {
this.conf = conf;
udviz = udvizBundle;
this.labelSphereCount = null;
}

init() {
const localContext = arguments[1];

const l = document.createElement('div');
this.labelSphereCount = l;
localContext.getGameView().appendToUI(l);
this.updateUI();
}

updateUI() {
this.labelSphereCount.innerHTML = 'Sphere count: ' + this.conf.sphereCount;
}

update() {
this.updateUI();
}
};
```

Now when a sphere is collected the ui update the sphere count !

## Audio

Let's play a sound when a sphere is collected. First add this [wav file](../../examples/assets/sounds/ballon_pop.wav) in `./assets/sounds/`. Then import it with the assetsManager.

- Add these lines in [`local_game_config.json`](../../examples/assets/config/local_game_config.json) in the _assetsManager_ Object:

```json
"sounds": {
"ballon_pop": {
"path": "./assets/sounds/ballon_pop.wav"
}
}
```

- Then add an _Audio_ component in your zeppelin gameobject in [`worldGameManager`](../../examples/assets/worldScripts/worldGameManager.js).

```js
Audio: {
sounds: ['ballon_pop'],
}
```

Okay everything is setup to play a sound !

- In [`zeppelin.js`](../../examples/assets/localScripts/zeppelin.js) (_localscript_) the update function becomes:

```js
update() {
const go = arguments[0];
const s = go.getComponent(udviz.Game.Shared.Audio.TYPE).getSounds()[
'ballon_pop'
];
s.play();

this.updateUI();
}
```

That's it a sound will be played when the sphere is collected !

## Conclusion

Congrats you have finished this tutorial, you are now able to :
Expand All @@ -558,3 +666,5 @@ Congrats you have finished this tutorial, you are now able to :
- Parameterized itowns layers
- Manipulating components of gameobjects
- Using user inputs
- Pass data from WorldScript to LocalScript
- Play audio
8 changes: 8 additions & 0 deletions examples/assets/config/local_game_config.json
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
{
"assetsManager": {
"sounds": {
"ballon_pop": {
"path": "./assets/sounds/ballon_pop.wav"
}
},
"models": {
"zeppelin": {
"path": "./assets/models/Zeppelin_Labex_IMU.glb",
Expand All @@ -21,6 +26,9 @@
},
"commands": {
"path": "./assets/localScripts/commands.js"
},
"zeppelin": {
"path": "./assets/localScripts/zeppelin.js"
}
}
},
Expand Down
Loading

0 comments on commit 923b121

Please sign in to comment.