|
| 1 | +--- |
| 2 | +sidebar_label: The Engine |
| 3 | +--- |
| 4 | +import { TechnicalNote } from '@site/src/components/TechnicalNote'; |
| 5 | +import { UnstyledDetails } from '@site/src/components/UnstyledDetails'; |
| 6 | + |
| 7 | +# Working with Ethereal Engine |
| 8 | +You will need three very important steps for creating a project with Ethereal Engine: |
| 9 | +1. Installing Ethereal Engine |
| 10 | +2. Installing (or creating) a project |
| 11 | +3. Modify and run the source code of your project |
| 12 | + |
| 13 | +We already solved #1 and #2 in the [Quickstart](../quickstart) guide. |
| 14 | +Lets do a quick review of how #1 and #2 work, and we will start programming with the engine right after. |
| 15 | + |
| 16 | +## Requirements and Dependencies |
| 17 | +We will use `git` and `npm` a lot throughout the guides on this website. |
| 18 | + |
| 19 | +Whether you followed the Quickstart guide for Ubuntu, or installed the engine with the Manual instructions, you will have both `git` and `npm` already installed. |
| 20 | + |
| 21 | +You don't need to understand either of them to get started. This guide will teach you what to do every time they are needed. |
| 22 | +Just remember that they are used a lot to work with the engine locally. |
| 23 | + |
| 24 | +## Installing and running Ethereal Engine |
| 25 | +Ethereal Engine is a web application. |
| 26 | +Just like any other web application, it needs to be run in a server. And that server will provide access to the engine remotely to anyone with access to its address. |
| 27 | + |
| 28 | +We will eventually learn how to work with "deployed" versions of the engine. |
| 29 | +But we need to follow this tutorial in a `local development server` instead. |
| 30 | + |
| 31 | +That's exactly what the Quickstart installation guide automated for us. |
| 32 | +As the `localhost` part of the URL indicates, we are running a `local` version of the engine. |
| 33 | + |
| 34 | +## Installing and running projects |
| 35 | +Ethereal Engine can be **extended** with projects. |
| 36 | +They are equivalent to the concept of "projects" in other engines, except they are modular like npm packages _(they are npm packages too)_. |
| 37 | + |
| 38 | +The engine scans for projects mounted in the `/packages/projects/projects` sub-folder. |
| 39 | +This means that we can install and run new projects by executing the following commands inside our Ethereal Engine installation folder: |
| 40 | +```bash |
| 41 | +git clone https://github.com/EtherealEngine/ee-tutorial-hello packages/projects/projects/ee-tutorial-hello |
| 42 | +npm run dev |
| 43 | +``` |
| 44 | +:::note |
| 45 | +You will need to stop the engine and re-run it whenever you install a new project. |
| 46 | +::: |
| 47 | + |
| 48 | +<TechnicalNote> |
| 49 | +Please note that, in the [Quickstart](../quickstart) guide, we cloned the `Step0` branch from the `ee-tutorial-hello` project specifically, and not the whole project. |
| 50 | +We did this by adding `-b Step0` to the `git clone` command: |
| 51 | + |
| 52 | +```bash |
| 53 | +git clone -b Step0 https://github.com/EtherealEngine/ee-tutorial-hello packages/projects/projects/ee-tutorial-hello |
| 54 | +``` |
| 55 | + |
| 56 | +This step won't be needed for your own projects. |
| 57 | +</TechnicalNote> |
| 58 | + |
| 59 | +These steps will: |
| 60 | +- Download a copy of the project's git repository, so the engine can load it |
| 61 | +- Install all `npm` packages required by the project |
| 62 | +- Run a local development version of the engine |
| 63 | + |
| 64 | +:::note |
| 65 | +This is also the process recommended for installation of your own projects. |
| 66 | +The difference will be that, instead of starting your project from the minimal HelloWorld example like we are doing now, you will start from a pre-made template. |
| 67 | +::: |
| 68 | + |
| 69 | +:::important |
| 70 | +Each project's source code is executed globally. |
| 71 | +This will become very important later on in this guide. |
| 72 | +::: |
| 73 | + |
| 74 | + |
| 75 | +## Programming with Ethereal Engine |
| 76 | +There are two very important steps to take in order to connect the source code of our project to the engine: |
| 77 | +- We need to import some Ethereal Engine's modules |
| 78 | +- We need to export our code so the engine can run it |
| 79 | + |
| 80 | +### Project Configuration File |
| 81 | +Every project has an `xrengine.config.ts` file that defines how it will behave in the engine. |
| 82 | +There are multiple options available, but the important thing to remember is that our `src/Hello.ts` code will be connected to the engine from here. |
| 83 | + |
| 84 | +<TechnicalNote title="Config File"> |
| 85 | + |
| 86 | +```ts title="ee-tutorial-hello/xrengine.config.ts" |
| 87 | +import type { ProjectConfigInterface } from '@etherealengine/projects/ProjectConfigInterface' |
| 88 | + |
| 89 | +const config: ProjectConfigInterface = { |
| 90 | + onEvent: undefined, |
| 91 | + thumbnail: '/static/etherealengine_thumbnail.jpg', |
| 92 | + routes: {}, |
| 93 | + services: undefined, |
| 94 | + databaseSeed: undefined, |
| 95 | + // highlight-start |
| 96 | + worldInjection: () => import('./src/Hello') // Import our Hello World code |
| 97 | + // highlight-end |
| 98 | +} |
| 99 | + |
| 100 | +export default config |
| 101 | +``` |
| 102 | +</TechnicalNote> |
| 103 | + |
| 104 | +We don't need to know much more about this file for now. We will explore it further in the `Beyond the Basics` guide. |
| 105 | + |
| 106 | +### Module Imports |
| 107 | +In this minimal tutorial we are adding a sphere primitive to the scene. |
| 108 | +As this sphere will be a `Spatial` object, we will import a few components from the Spatial engine module: |
| 109 | + |
| 110 | +```ts title="ee-tutorial-hello/src/Hello.ts" |
| 111 | +import { NameComponent } from '@etherealengine/spatial/src/common/NameComponent' |
| 112 | +import { VisibleComponent } from '@etherealengine/spatial/src/renderer/components/VisibleComponent' |
| 113 | +import { TransformComponent } from '@etherealengine/spatial/src/transform/components/TransformComponent' |
| 114 | +import { PrimitiveGeometryComponent } from '@etherealengine/engine/src/scene/components/PrimitiveGeometryComponent' |
| 115 | +``` |
| 116 | +We will be adding these Components to our Entity, and Components are part of the ECS pattern. |
| 117 | +As such, we will need to use the Ethereal Engine ECS management functions. |
| 118 | +The engine provides a convenient way to import all ECS related functions at once through the `ECS` [namespace](https://www.typescriptlang.org/docs/handbook/namespaces.html). |
| 119 | +```ts title="ee-tutorial-hello/src/Hello.ts" |
| 120 | +import { ECS } from '@etherealengine/ecs' |
| 121 | +``` |
| 122 | + |
| 123 | +## Modifying our Source Code |
| 124 | +We have learned how our minimal example works, but so far we haven't needed to modify any of its source code. |
| 125 | +This will be our first modification to the code of the project. |
| 126 | + |
| 127 | +:::important |
| 128 | +This guide uses [`Project-based Learning`](https://en.wikipedia.org/wiki/Project-based_learning) as its core teaching philosophy. |
| 129 | +From now on, you will be actively modifying the source code of the `ee-tutorial-hello` in every step of the way. |
| 130 | +::: |
| 131 | + |
| 132 | +Lets start with a simple change. |
| 133 | +We will modify our Sphere `PrimitiveGeometryComponent` to load our geometry with a name, instead of the hardcoded number `1` that we used before. |
| 134 | + |
| 135 | +In order to do this, we need to: |
| 136 | +- Open the file `ee-tutorial-hello/src/Hello.ts` with a text editor. |
| 137 | +- Import the `GeometryTypeEnum` from the `scene/constants/` sub-module inside the `engine` module. |
| 138 | +- Replace the `1` with a call to the `SphereGeometry` name that is stored inside it `GeometryTypeEnum`. |
| 139 | + |
| 140 | +Try to figure out the changes by yourself before looking at the solution. |
| 141 | +I don't expect you to know where that enum is stored, so here are some hints to make it easier: |
| 142 | +```ts |
| 143 | +// The full path to the GeometryTypeEnum is: |
| 144 | +'@etherealengine/engine/src/scene/constants/GeometryTypeEnum' |
| 145 | + |
| 146 | +// Getting the ID number of a Sphere by its enum name will look like: |
| 147 | +GeometryTypeEnum.SphereGeometry |
| 148 | + |
| 149 | +// To be certain that your changes are working, set the geometry to be a cylinder instead: |
| 150 | +GeometryTypeEnum.CylinderGeometry |
| 151 | +``` |
| 152 | +> As we said before, you will need to stop the engine and re-run it whenever you _install_ a new project. |
| 153 | +> But you can just refresh the webpage when you update your source code and the engine will load your changes correctly. |
| 154 | +
|
| 155 | +:::note |
| 156 | +`VSCode` is the recommended editor for programming with Ethereal Engine. |
| 157 | +It is not required, but it is highly recommended. |
| 158 | +VSCode has support for some important features and plugins that make the Ethereal Engine programming workflow really smooth and featureful. |
| 159 | +::: |
| 160 | + |
| 161 | +<TechnicalNote title="Solution"> |
| 162 | + |
| 163 | +The imports section of our code will now be: |
| 164 | +```ts title="ee-tutorial-hello/src/Hello.ts" |
| 165 | +// ... our other imports |
| 166 | +import { PrimitiveGeometryComponent } from '@etherealengine/engine/src/scene/components/PrimitiveGeometryComponent' |
| 167 | +import { Vector3 } from 'three' |
| 168 | +// highlight-start |
| 169 | +import { GeometryTypeEnum } from '@etherealengine/engine/src/scene/constants/GeometryTypeEnum' |
| 170 | +// highlight-end |
| 171 | +``` |
| 172 | +The `PrimitiveGeometryComponent` call will now be: |
| 173 | +```ts title="ee-tutorial-hello/src/Hello.ts" |
| 174 | +const entity = ECS.createEntity() |
| 175 | +// ... our other calls to setComponent |
| 176 | +// highlight-start |
| 177 | +ECS.setComponent(entity, PrimitiveGeometryComponent, { geometryType: GeometryTypeEnum.SphereGeometry }) |
| 178 | +// highlight-end |
| 179 | +``` |
| 180 | + |
| 181 | +<UnstyledDetails title="Full Solution"> |
| 182 | + |
| 183 | +```ts title="ee-tutorial-hello/src/Hello.ts" showLineNumbers |
| 184 | +import { ECS } from '@etherealengine/ecs' |
| 185 | +import { NameComponent } from '@etherealengine/spatial/src/common/NameComponent' |
| 186 | +import { VisibleComponent } from '@etherealengine/spatial/src/renderer/components/VisibleComponent' |
| 187 | +import { TransformComponent } from '@etherealengine/spatial/src/transform/components/TransformComponent' |
| 188 | +import { PrimitiveGeometryComponent } from '@etherealengine/engine/src/scene/components/PrimitiveGeometryComponent' |
| 189 | +// highlight-start |
| 190 | +import { GeometryTypeEnum } from '@etherealengine/engine/src/scene/constants/GeometryTypeEnum' |
| 191 | +// highlight-end |
| 192 | + |
| 193 | +const entity = ECS.createEntity() |
| 194 | +ECS.setComponent(entity, NameComponent, 'hello-world') |
| 195 | +ECS.setComponent(entity, VisibleComponent) |
| 196 | +ECS.setComponent(entity, TransformComponent, { position: new Vector3(0, 1, 0) }) |
| 197 | +// highlight-start |
| 198 | +ECS.setComponent(entity, PrimitiveGeometryComponent, { geometryType: GeometryTypeEnum.SphereGeometry }) |
| 199 | +// highlight-end |
| 200 | +``` |
| 201 | +</UnstyledDetails> |
| 202 | +<!-- Full Solution End --> |
| 203 | +</TechnicalNote> |
| 204 | +<!-- Solution End --> |
| 205 | + |
0 commit comments