diff --git a/docs/developer/typescript/01_gettingStarted/02_hello/01_ecs.md b/docs/developer/typescript/01_gettingStarted/02_hello/01_ecs.md index 1bb3080efef1..cbab62db45da 100644 --- a/docs/developer/typescript/01_gettingStarted/02_hello/01_ecs.md +++ b/docs/developer/typescript/01_gettingStarted/02_hello/01_ecs.md @@ -1,87 +1,96 @@ - - # The ECS Pattern -The [Entity Component System](https://en.wikipedia.org/wiki/Entity_component_system) is a pattern used to organize our code when writing software. -In this pattern: -- Logic is represented as `Systems`, and they define the behavior of the application -- Data is represented as `Components` that have no behavior or identifiers attached to them -- Components are attached to Entities -- `Entities` are identifiers - -The ECS pattern represents [Objects](https://en.wikipedia.org/wiki/Object_(computer_science)) by attaching Components (data) to an Entity (identifiers) without behavior. -The behavior of the application is then controlled by having separate Systems (logic) that process that data. -Systems don't need to know where that data is coming from. They only know what data is stored in the Components that they can operate on. - +# The ECS pattern + +The [Entity-Component-System (ECS)](https://en.wikipedia.org/wiki/Entity_component_system) is a software architecture pattern used to structure code efficiently. -:::note -Clicking on the `Technical Summary` note right above will open a drop-down with information about what the ECS pattern is in more advanced/technical terms. +In this pattern: + +- **Logic** is represented as `systems`, which define the application's behavior. +- **Data** is stored in `components`, which do not have behavior or identifiers. +- **Entities** are identifiers that group components together. -You will find a lot of these `Technical` drop-downs throughout the guides. -Their goal is to give you extra information that is not mandatory to understand to follow the guide, but is very useful to achieve a deeper understanding of the content. +:::hint{type="info"} +**How this works**: -Don't worry if you don't fully understand what some of them explain just yet. We will get there. +- The ECS pattern represents [objects](https://en.wikipedia.org/wiki/Object_\(computer_science\)) by attaching components (data) to an entity (identifier) without behavior +- Application behavior is controlled by separate systems (logic) that process that data. +- Systems do not need to know where data comes from—they only operate on the components available to them. ::: -## Creating an Entity -Creating an Entity is as simple as calling the `createEntity()` function from iR Engine's `ECS`. -This function will return an identifier that can be used to group Components into a unique and distinct Object. -```ts +## Creating an entity + +Creating an entity is as simple as calling the `createEntity()` function from iR Engine’s `ECS`. +This function returns an identifier that allows grouping components into a unique object. + +```typescript const entity = ECS.createEntity() ``` -## Adding Components -Components represent data that has no behavior or identification. -The way to attach Components to Entities is by calling the `setComponent` function from iR Engine's `ECS`. +## Adding components + +Components store data and have no behavior or unique identifiers. +To attach components to an entity, use the `setComponent` function from iR Engine’s `ECS`. + +:::hint{type="info"} +The `setComponent` function does not return a value, but it: - -The `setComponent` function will not return anything, but it will: -- Add the given Component to the Entity. -- Store the Component's data in the internal records of the ECS, so it can used by the engine or accessed through the API _(eg: with `getComponent` and similar functions)_. - +- Adds the specified component to the entity. +- Stores the component’s data in the ECS, making it accessible through the API (e.g., `getComponent` and similar functions). +::: + +To display an entity in iR Engine, it must have specific components: -iR Engine requires a specific set of Components in order to create an object that can be presented on the screen: - **VisibleComponent** - **TransformComponent** - **PrimitiveGeometryComponent** or **MeshComponent** -- _(optional)_ **NameComponent**: Not required, but good practice. +- *(Optional)* **NameComponent**: Not required but recommended for better debugging. + +### NameComponent +A `NameComponent` provides a human-readable identifier for an entity. +The assigned name appears in the **Studio** and the **debugger**, making it easier to manage entities. -### `NameComponent` -Gives a human-readable identifier to an Entity. -Whatever name you add on this field is the name that will show up in the Studio and the debugger. -They are not mandatory, but it is good practice to add them to all your entities. -```ts +```typescript ECS.setComponent(entity, NameComponent, 'hello-world') ``` - -We said that an entity is an identifier, but we are also giving that identifier a `NameComponent`. -Every Entity represents its internal "name" _(aka identifier)_ as an [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier), which does not need to be human-readable. -And `NameComponents` give a human-readable identifier to an Entity, independent of what its UUID is. - +:::hint{type="info"} +An entity is an identifier, yet we assign it a `NameComponent`. +Internally, every entity is identified by a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier), which is not human-readable. +A `NameComponent` provides a readable name while keeping the UUID unchanged. +::: + +### VisibleComponent + +A `VisibleComponent` makes an entity visible on the screen. Entities without this component are ignored by the renderer. -### `VisibleComponent` -Gives the Entity the ability to be visible on the screen. -Entities without this Component will be ignored by the renderer. -```ts +```typescript ECS.setComponent(entity, VisibleComponent) ``` -### `TransformComponent` -In simple terms, `TransformComponents` give an Entity the ability to have a [position in the world](https://en.wikipedia.org/wiki/Transformation_matrix). -There would be no way to position the Entity in 3D space without attaching this Component to the Entity. -```ts +### TransformComponent + +A `TransformComponent` gives an entity a **position** in 3D space. Without this component, the entity cannot be placed in the world. + +```typescript ECS.setComponent(entity, TransformComponent, { position: new Vector3(0, 1, 0) }) ``` -> In more technical terms, `TransformComponents` give the Entity the ability to be affected by [linear transformations](https://en.wikipedia.org/wiki/Linear_transformation). -### `PrimitiveGeometryComponent` -This Component gives Entities a primitive "visual body". -Entities without it would not have any [3D geometry](https://en.wikipedia.org/wiki/Polygon_mesh), so the renderer would not be able to draw them on the screen. -```ts +:::hint{type="info"} +In technical terms, a `TransformComponent` allows an entity to be affected by [linear transformations](https://en.wikipedia.org/wiki/Linear_transformation). +::: + +### PrimitiveGeometryComponent + +A `PrimitiveGeometryComponent` assigns a **primitive shape** to an entity. Without this component, the entity lacks a [3D geometry](https://en.wikipedia.org/wiki/Polygon_mesh) and will not be rendered. + +```typescript ECS.setComponent(entity, PrimitiveGeometryComponent, { geometryType: 1 }) ``` -> The `1` here means that we are creating a [`SphereGeometry`](https://github.com/ir-engine/ir-engine/blob/dev/packages/engine/src/scene/constants/GeometryTypeEnum.ts#L28) object. -> We will create the component using a more readable name in the next section of the tutorial. + +:::hint{type="info"} +The `1` here represents a [`SphereGeometry`](https://github.com/ir-engine/ir-engine/blob/dev/packages/engine/src/scene/constants/GeometryTypeEnum.ts#L28) object. +In the next section, we will use a more readable name to create this component. +::: diff --git a/docs/developer/typescript/01_gettingStarted/02_hello/02_engine.md b/docs/developer/typescript/01_gettingStarted/02_hello/02_engine.md index 96348aba00f4..03cbe92a24fe 100644 --- a/docs/developer/typescript/01_gettingStarted/02_hello/02_engine.md +++ b/docs/developer/typescript/01_gettingStarted/02_hello/02_engine.md @@ -1,202 +1,186 @@ - - - # Working with iR Engine -You will need three very important steps for creating a project with iR Engine: -1. Installing iR Engine -2. Installing (or creating) a project -3. Modify and run the source code of your project -We already solved #1 and #2 in the [Quickstart](../quickstart) guide. -Lets do a quick review of how #1 and #2 work, and we will start programming with the engine right after. +To start working on a project in the engine, you need to follow three key steps: -## Requirements and Dependencies -We will use `git` and `npm` a lot throughout the guides on this website. +1. **Install iR Engine** +2. **Install or create a project** +3. **Modify and run the project’s source code** -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. +For installation instructions, consult the [Installation](./../../../../manual/01_install/index.md) section on the [Technical manual](./../../../../manual/index.md) -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. -Just remember that they are used a lot to work with the engine locally. +## Requirements and dependencies -## Installing and running iR Engine -iR Engine is a web application. -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. +Throughout this guide, we frequently use `git` and `npm`. If you followed the [TypeScript Quickstart](./../index.md) guide or [installed](./../../../../manual/01_install/index.md) the iR Engine manually, you already have both tools installed. -We will eventually learn how to work with "deployed" versions of the engine. -But we need to follow this tutorial in a `local development server` instead. +## Installing and running projects -That's exactly what the Quickstart installation guide automated for us. -As the `localhost` part of the URL indicates, we are running a `local` version of the engine. +iR Engine can be extended by using **projects**, which function similarly to projects in other game engines but are modular, like `npm` packages. Projects are `npm` packages too. -## Installing and running projects -iR Engine can be **extended** with projects. -They are equivalent to the concept of "projects" in other engines, except they are modular like npm packages _(they are npm packages too)_. +:::hint{type="info"} +**ℹ️ Info** + +Each project's source code is executed **globally**. +This will become an important concept later in this guide. +::: + +The engine automatically scans for projects inside the `/packages/projects/projects/` directory. This means that we can install and run new projects by executing the following commands inside our iR Engine installation folder: -The engine scans for projects mounted in the `/packages/projects/projects` sub-folder. -This means that we can install and run new projects by executing the following commands inside our iR Engine installation folder: ```bash git clone https://github.com/ir-engine/ir-tutorial-hello packages/projects/projects/ir-tutorial-hello npm run dev ``` -:::note -You will need to stop the engine and re-run it whenever you install a new project. + +:::hint{type="info"} +**ℹ️ Important** + +Whenever you install a new project, you must stop and restart the engine for the changes to take effect. ::: - -Please note that, in the [Quickstart](../quickstart) guide, we cloned the `Step0` branch from the `ir-tutorial-hello` project specifically, and not the whole project. -We did this by adding `-b Step0` to the `git clone` command: +These commands perform the following actions: + +1. Clone the project’s repository so iR Engine can load it. +2. Install all required `npm` packages. +3. Run a local development instance of iR Engine. + +This is also the recommended method for working with projects of your authoring–instead of starting from **Hello World**, you can use a pre-made template as a starting point. + +:::hint{type="info"} +**ℹ️ Info** + +In the [TypeScript Quickstart](./../index.md) document, we cloned only the `Step0` branch of the `ir-tutorial-hello` project instead of the entire repository. +This was done by using `-b Step0` in the `git clone` command: ```bash git clone -b Step0 https://github.com/ir-engine/ir-tutorial-hello packages/projects/projects/ir-tutorial-hello ``` -This step won't be needed for your own projects. - - -These steps will: -- Download a copy of the project's git repository, so the engine can load it -- Install all `npm` packages required by the project -- Run a local development version of the engine - -:::note -This is also the process recommended for installation of your own projects. -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. +For your own projects, this is not required, and you can clone without `-b Step0` on your command. ::: -:::important -Each project's source code is executed globally. -This will become very important later on in this guide. -::: +## Configuring projects +To integrate a project's source code with iR Engine, two critical steps are required: -## Programming with iR Engine -There are two very important steps to take in order to connect the source code of our project to the engine: -- We need to import some iR Engine's modules -- We need to export our code so the engine can run it +1. **Importing iR Engine’s modules** +2. **Exporting the code so the engine can run it** -### Project Configuration File -Every project has an `xrengine.config.ts` file that defines how it will behave in the engine. -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. +### Project configuration file - +Every project includes an `xrengine.config.ts` file, which defines how the project interacts with iR Engine. -```ts title="ir-tutorial-hello/xrengine.config.ts" +The key part to note in this file is that our `src/Hello0.ts` file is connected to the engine through this configuration. See the code below: + +```typescript import type { ProjectConfigInterface } from '@ir-engine/packages/projects/ProjectConfigInterface' const config: ProjectConfigInterface = { onEvent: undefined, - thumbnail: '/static/IR_thumbnail.jpg', + thumbnail: '/static/ir-engine_thumbnail.jpg', routes: {}, services: undefined, databaseSeed: undefined, // highlight-start - worldInjection: () => import('./src/Hello') // Import our Hello World code + worldInjection: () => import('./src/Hello0') // Import our Hello World code // highlight-end } export default config ``` - -We don't need to know much more about this file for now. We will explore it further in the `Beyond the Basics` guide. +For now, it is enough to understand that this file connects your project’s code to the engine. More details will be covered in the [Beyond the Basics]() guide. + +## **Importing required modules** + +In this tutorial, we are adding a sphere primitive to the scene. This section explains the importing process. -### Module Imports -In this minimal tutorial we are adding a sphere primitive to the scene. -As this sphere will be a `Spatial` object, we will import a few components from the Spatial engine module: +:::hint{type="info"} +ℹ️ **Tip** -```ts title="ir-tutorial-hello/src/Hello.ts" +For now, focus on understanding the concepts exclusively. We'll get hands on with the project in the Modifying the source code section in just a bit. +::: + +### **Importing spatial components** + +Since the sphere is a **spatial** object, we must import several components from the spatial** **engine module, as well as our sphere from the PrimitiveGeometry component from the components module. + +```typescript import { NameComponent } from '@ir-engine/packages/spatial/src/common/NameComponent' import { VisibleComponent } from '@ir-engine/packages/spatial/src/renderer/components/VisibleComponent' import { TransformComponent } from '@ir-engine/packages/spatial/src/transform/components/TransformComponent' import { PrimitiveGeometryComponent } from '@ir-engine/packages/engine/src/scene/components/PrimitiveGeometryComponent' +import { Vector3 } from 'three' ``` -We will be adding these Components to our Entity, and Components are part of the ECS pattern. -As such, we will need to use the iR Engine ECS management functions. -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). -```ts title="ir-tutorial-hello/src/Hello.ts" + +### **Importing ECS utilities** + +Since we are working with the **ECS pattern**, we also need to import the ECS management functions. iR Engine provides a way to import all ECS-related functions simultaneously via the `ECS` **namespace**. + +```typescript import { ECS } from '@ir-engine/packages/ecs' ``` -## Modifying our Source Code -We have learned how our minimal example works, but so far we haven't needed to modify any of its source code. -This will be our first modification to the code of the project. +## Modifying the source code -:::important -This guide uses [`Project-based Learning`](https://en.wikipedia.org/wiki/Project-based_learning) as its core teaching philosophy. -From now on, you will be actively modifying the source code of the `ir-tutorial-hello` in every step of the way. +So far, we have only reviewed how our example works—we haven’t modified any source code yet. + +:::hint{type="info"} +This guide follows a **project-based learning** approach. +From this point onward, you will actively modify the `ir-tutorial-hello` project as you progress. ::: -Lets start with a simple change. -We will modify our Sphere `PrimitiveGeometryComponent` to load our geometry with a name, instead of the hardcoded number `1` that we used before. +Let's start with a simple change: replacing the hardcoded `1` in `PrimitiveGeometryComponent` with a readable **enum value**. + +### **Modifying the sphere geometry type** + +1. Open the file `ir-tutorial-hello/src/Hello0.ts` in a text editor. +2. Import `GeometryTypeEnum` from the `scene/constants/` submodule. +3. Replace `1` with `GeometryTypeEnum.SphereGeometry`. -In order to do this, we need to: -- Open the file `ir-tutorial-hello/src/Hello.ts` with a text editor. -- Import the `GeometryTypeEnum` from the `scene/constants/` sub-module inside the `engine` module. -- Replace the `1` with a call to the `SphereGeometry` name that is stored inside it `GeometryTypeEnum`. +Try implementing these changes on your own before checking the solution. If you’re unsure where the enum is located, use these hints: -Try to figure out the changes by yourself before looking at the solution. -I don't expect you to know where that enum is stored, so here are some hints to make it easier: -```ts -// The full path to the GeometryTypeEnum is: +```none +/ The full path to the GeometryTypeEnum: '@ir-engine/packages/engine/src/scene/constants/GeometryTypeEnum' -// Getting the ID number of a Sphere by its enum name will look like: +// Getting the ID number of a Sphere by its enum name: GeometryTypeEnum.SphereGeometry -// To be certain that your changes are working, set the geometry to be a cylinder instead: +// To verify your changes, set the geometry to a cylinder instead: GeometryTypeEnum.CylinderGeometry ``` -> As we said before, you will need to stop the engine and re-run it whenever you _install_ a new project. -> But you can just refresh the webpage when you update your source code and the engine will load your changes correctly. -:::note -`VSCode` is the recommended editor for programming with iR Engine. -It is not required, but it is highly recommended. -VSCode has support for some important features and plugins that make the iR Engine programming workflow really smooth and featureful. +:::hint{type="info"} +You only need to restart the engine when **installing** a new project. +When modifying source code, simply **refresh the webpage** to see your changes. ::: - +### Solution -The imports section of our code will now be: -```ts title="ir-tutorial-hello/src/Hello.ts" -// ... our other imports +Once updated, the **import section** should look like this: + +```typescript +// Other imports import { PrimitiveGeometryComponent } from '@ir-engine/packages/engine/src/scene/components/PrimitiveGeometryComponent' import { Vector3 } from 'three' // highlight-start import { GeometryTypeEnum } from '@ir-engine/packages/engine/src/scene/constants/GeometryTypeEnum' // highlight-end ``` -The `PrimitiveGeometryComponent` call will now be: -```ts title="ir-tutorial-hello/src/Hello.ts" -const entity = ECS.createEntity() -// ... our other calls to setComponent -// highlight-start -ECS.setComponent(entity, PrimitiveGeometryComponent, { geometryType: GeometryTypeEnum.SphereGeometry }) -// highlight-end -``` - - -```ts title="ir-tutorial-hello/src/Hello.ts" showLineNumbers -import { ECS } from '@ir-engine/packages/ecs' -import { NameComponent } from '@ir-engine/packages/spatial/src/common/NameComponent' -import { VisibleComponent } from '@ir-engine/packages/spatial/src/renderer/components/VisibleComponent' -import { TransformComponent } from '@ir-engine/packages/spatial/src/transform/components/TransformComponent' -import { PrimitiveGeometryComponent } from '@ir-engine/packages/engine/src/scene/components/PrimitiveGeometryComponent' -// highlight-start -import { GeometryTypeEnum } from '@ir-engine/packages/engine/src/scene/constants/GeometryTypeEnum' -// highlight-end +The **PrimitiveGeometryComponent** assignment should be updated as follows: +```typescript const entity = ECS.createEntity() -ECS.setComponent(entity, NameComponent, 'hello-world') -ECS.setComponent(entity, VisibleComponent) -ECS.setComponent(entity, TransformComponent, { position: new Vector3(0, 1, 0) }) +// Other setComponent calls // highlight-start ECS.setComponent(entity, PrimitiveGeometryComponent, { geometryType: GeometryTypeEnum.SphereGeometry }) // highlight-end ``` - - - - + +### **Confirming the changes** + +1. Open [http://localhost:3000/studio](http://localhost:3000/studio). +2. Open the **ir-tutorial-hello** project. +3. Create a new scene. +4. A **white sphere** should appear in the center. diff --git a/docs/developer/typescript/01_gettingStarted/02_hello/index.md b/docs/developer/typescript/01_gettingStarted/02_hello/index.md index 998a750cb421..1e9a9d3083b7 100644 --- a/docs/developer/typescript/01_gettingStarted/02_hello/index.md +++ b/docs/developer/typescript/01_gettingStarted/02_hello/index.md @@ -1,18 +1,19 @@ -# Hello World from iR Engine -The quickstart tutorial helped us create a project and run the engine for the first time. +# Hello World in iR Engine -This is our starting point. -The Quickstart has automated a lot for us, so lets review what we have. +The [TypeScript Quickstart](./../index.md) guide helped us create a project and run iR Engine for the first time. Now, let's review what we have before diving deeper. -:::note -Don't dwell too much on this page. -This is a quick preview, so please skim read and don't go into too much detail. -The purpose of the next few pages of this tutorial is to teach you how these concepts work. +:::hint{type="info"} +This is a brief overview. Skim through this page without focusing on details—the next sections will explain these concepts in depth. ::: -## Hello World Code -This is how the code for our project looks like at the moment. -```ts title="ir-tutorial-hello/src/Hello.ts" showLineNumbers +## Hello world code + +At this stage, our project contains the following code: + +:::codeblocktabs +ir-tutorial-hello/src/Hello.ts + +```typescript import { ECS } from '@ir-engine/packages/ecs' import { NameComponent } from '@ir-engine/packages/spatial/src/common/NameComponent' import { VisibleComponent } from '@ir-engine/packages/spatial/src/renderer/components/VisibleComponent' @@ -26,30 +27,34 @@ ECS.setComponent(entity, VisibleComponent) ECS.setComponent(entity, TransformComponent, { position: new Vector3(0, 1, 0) }) ECS.setComponent(entity, PrimitiveGeometryComponent, { geometryType: 1 }) ``` +::: ## Conceptual overview -Conceptually, this is what the example project does: -- It creates an entity called `hello-world` -- It gives the entity a primitive geometry component _(a Sphere)_ -- It defines the position of the sphere in the scene + +This example project performs the following actions: + +- Creates an entity named `hello-world`. +- Assigns a **primitive geometry component** (a sphere) to the entity. +- Sets the sphere's **position** in the scene. ## Technical overview -In technical terms, this is what the example's source code does: -- It imports some iR Engine's typescript modules in its code -- It uses the `ECS` pattern -- It creates an `Entity` -- It adds a few `Components` to the Entity -- It adds its code to the engine through the `xrengine.config.ts` file -## The Path Forward -Our example from the quickstart tutorial is as minimal as it can possibly be. -But there is a lot happening already, as you can see, even in such a minimal example! -So, the first step we will take is to spend some time understanding how everything in the example works. +From a technical perspective, this code: + +- Imports **iR Engine's TypeScript modules**. +- Uses the **Entity-Component-System (ECS) pattern**. +- Creates an **entity**. +- Adds **components** to the entity. +- Integrates the code into the engine via the `xrengine.config.ts` file. + +## What’s next? -Next we will get our hands into the code, and learn how to program with iR Engine. +This project is as minimal as possible, but it already introduces key concepts. -Then, at the end of this guide, we will have a very minimal project that we can load with the Engine. -But, more importantly, we will have enough knowledge to be able to continue our learning through the `iR Engine: Basics` guide. +Next, we'll break down how each part of the code works and begin programming with iR Engine. By the end of this guide, you will: -Lets not delay any longer, and get started with our journey! +- Understand the fundamental concepts behind iR Engine. +- Write and modify code within an iR Engine project. +- Be prepared to continue learning through the **iR Engine: Basics** guide. +Let's get started! 🚀 diff --git a/docs/developer/typescript/01_gettingStarted/index.md b/docs/developer/typescript/01_gettingStarted/index.md index 9081800cc0bc..46bfdfb43b7e 100644 --- a/docs/developer/typescript/01_gettingStarted/index.md +++ b/docs/developer/typescript/01_gettingStarted/index.md @@ -1,71 +1,66 @@ - - +# TypeScript quickstart -# TypeScript Quickstart -This QuickStart guide will teach you the basics of iR Engine, and how to run the engine for the first time. +This guide walks you through the basics of iR Engine and how to install and run it for the first time. ## Installation - -:::important -iR Engine is a web application. -We are going to install and run a local version of the engine. -But this setup might not reflect how you will use the engine on a day to day basis. -::: -:::note -These installation instructions assume you are using Ubuntu Linux. -You can find alternative _(and more advanced)_ installation instructions for [Windows](/manual/install/windowsWSL), [Mac](/manual/install/macOSX) and [Linux](/manual/install/linux) in the Manual. +Before you begin, note that iR Engine is a web application. The following steps will help you install and run a local version, which may differ from how you use the engine in production. + +:::hint{type="info"} +These instructions are for Ubuntu Linux. For Windows, macOS, or other Linux distributions, refer to the [installation manual](). ::: -If you are on Ubuntu Linux, there is an automatic installation script to setup and run a local version of iR Engine. -Open a terminal window and run these two lines: -> Make sure that you open the terminal in the folder where you want to install the engine -```bash -wget https://raw.githubusercontent.com/ir-engine/ir-engine/dev/scripts/ubuntu-install.sh && bash -i ./ubuntu-install.sh -npm run reinit && npm run dev -``` -You can now open iR Engine on your web browser by navigating to [https://localhost:3000](https://localhost:3000) +### Install iR Engine on Ubuntu - +To install and run a local version of iR Engine on Ubuntu, follow these steps: + +1. Open a terminal in the directory where you want to install the engine. +2. Run the following command: + ```bash + wget https://raw.githubusercontent.com/ir-engine/ir-engine/dev/scripts/ubuntu-install.sh && bash -i ./ubuntu-install.sh + npm run reinit && npm run dev + ``` +3. Once the installation is complete, open [https://localhost:3000](https://localhost:3000) in your web browser to access iR Engine. ## Projects -### Default Projects - -iR Engine has a few scenes that are installed by default. -With the engine running, open the Studio by navigating to [https://localhost:3000/studio](https://localhost:3000/studio), and you will see the engine's default project listed in that page. -Lets give it a test run: -- Open the default project by clicking on its card -- Click on one of the scenes to open it -- Click on the `Play` button to enter the scene with an Avatar -- Move around the scene with `WASD` and/or clicking on the ground +iR Engine includes default projects and scenes that are pre-installed. You can explore them through the Studio. + +### Default projects - +To access the default project and test its functionality: -### Install and Run the tutorial project -Whether you installed the engine with method above, or with the installation instructions for your specific system, your next step will be to install the tutorial project. +1. Open the Studio by navigating to [https://localhost:3000/studio](https://localhost:3000/studio). +2. Click on the default project card. +3. Select a scene to open it. +4. Click the **Play** button to enter the scene with an avatar. +5. Move around using the **WASD** keys or by clicking on the ground. -:::danger -This `HelloWorld` project should never be installed in a remote deployment. -A local version of the engine is required to follow this introductory tutorial. +### Install and run the tutorial project + +To follow the introductory tutorial, you need to install the **Hello World** project. This project provides a step-by-step introduction to iR Engine’s features. + +:::hint{type="danger"} +This tutorial project should only be installed locally. Do not install it in a remote deployment. ::: -The previous commands will have the engine running locally. -Lets stop it by pressing `Ctrl+C`, and then run these commands to install and run the tutorial's template project: -```bash -git clone -b Step0 https://github.com/ir-engine/ir-tutorial-hello packages/projects/projects/ir-tutorial-hello -npm run dev -``` +1. Stop the running engine by pressing **Ctrl+C** in the terminal. +2. Install the tutorial project by running: + ```bash + git clone -b Step0 https://github.com/ir-engine/ir-tutorial-hello packages/projects/projects/ir-tutorial-hello + npm run dev + ``` +3. Open [https://localhost:3000/studio](https://localhost:3000/studio), and you should see the **ir-tutorial-hello** project listed. -You should now be able to see the `ir-tutorial-hello` project listed in iR Engine's Studio by navigating to [https://localhost:3000/studio](https://localhost:3000/studio). +## Verify the installation -## Confirm the installation -Lets make sure that our `hello world` code is running: -1. Open the project from the Studio by clicking on its card -2. Create a new empty scene +To confirm that the Hello World project is running correctly, follow these steps: -You will know that the code is running if you can see a white sphere in the middle of the scene. +1. Open the project in **Studio** by clicking on its card. +2. Create a new empty scene. +3. If the installation was successful, a white sphere should appear in the center of the scene. -:::note -You can also enter the scene and move around with an avatar by pressing the `Play` button in the editor like we did before. +:::hint{type="info"} +You can also enter the scene and move around with an avatar by pressing the **Play** button in the editor. ::: + diff --git a/docs/manual/01_install/050_advanced/07_troubleshooting.md b/docs/manual/01_install/050_advanced/07_troubleshooting.md index 177e4d8be3e7..aae4ff1ee351 100644 --- a/docs/manual/01_install/050_advanced/07_troubleshooting.md +++ b/docs/manual/01_install/050_advanced/07_troubleshooting.md @@ -1,47 +1,51 @@ # Troubleshooting +Find here the solution to most common issues you might run into when working with the engine. + ### Browser Debug + `p key` debug colliders view ### Invalid Certificate errors in local environment -As of this writing, the cert provided in the iR Engine package for local use is not adequately signed. -Browsers will throw up warnings about going to insecure pages. + +As of this writing, the cert provided in the iR Engine package for local use is not adequately signed. +Browsers will throw up warnings about going to insecure pages. You should be able to tell the browser to ignore it, usually by clicking on some sort of 'advanced options' button or link and then something along the lines of 'go there anyway'. -Chrome sometimes does not show a clickable option on the warning. If so, just type `badidea` or `thisisunsafe` when on that page. +Chrome sometimes does not show a clickable option on the warning. If so, just type `badidea` or `thisisunsafe` when on that page. You don't enter that into the address bar or into a text box, Chrome is just passively listening for those commands. ### Allow instanceserver address connection via installing local Certificate Authority -For more detailed instructions check: https://github.com/FiloSottile/mkcert +For more detailed instructions check: [https://github.com/FiloSottile/mkcert](https://github.com/FiloSottile/mkcert) Short version (common for development process on Ubuntu): 1. Execute `sudo apt install libnss3-tools` -2. Execute `brew install mkcert` (if you don't have brew, check it's page: https://brew.sh/) +2. Execute `brew install mkcert` (if you don't have brew, check it's page: [https://brew.sh/](https://brew.sh/)) 3. Execute `mkcert --install` 4. Navigate to `./certs` folder 5. Execute `mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1 ::1` ### Allow local file http-server connection with invalid certificate -Open the developer tools in your browser by pressing ```Ctrl+Shift+i``` at the -same time. Go to the 'Console' tab and look at the message history. If there are +Open the developer tools in your browser by pressing `Ctrl+Shift+i` at the +same time. Go to the 'Console' tab and look at the message history. If there are red errors that say something like -```GET https://127.0.0.1:3030/socket.io/?EIO=3&transport=polling&t=NXlZLTa net::ERR_CERT_AUTHORITY_INVALID```, +`GET https://127.0.0.1:3030/socket.io/?EIO=3&transport=polling&t=NXlZLTa net::ERR_CERT_AUTHORITY_INVALID`, then right-click that URL, then select 'Open in new tab', and accept the invalid certificate. ### Allow instanceserver address connection with invalid certificate The instanceserver functionality is hosted on an address other than 127.0.0.1 in the local environment. Accepting an invalid certificate for 127.0.0.1 will not apply to this address. -Open the dev console for Chrome/Firefox by pressing ```Ctrl+Shift+i``` simultaneously, and +Open the dev console for Chrome/Firefox by pressing `Ctrl+Shift+i` simultaneously, and go to the Console or Network tabs. If you see errors about not being able to connect to -something like ```https://192.168.0.81:3031/socket.io/?location=```, right click on +something like `https://192.168.0.81:3031/socket.io/?location=`, right click on that URL and open it in a new tab. You should again get a warning page about an invalid -certificate, and you again need to allow it. +certificate, and you again need to allow it. ### AccessDenied connecting to mariadb @@ -52,9 +56,9 @@ lsof -i :3306 ``` On Linux, you can also check if any processes are running on port 3306 with -```sudo netstat -utlp | grep 3306``` -The last column should look like ```/``` +`sudo netstat -utlp | grep 3306` +The last column should look like `/` ### Error: listen EADDRINUSE :::3030 @@ -73,17 +77,17 @@ kill -3 ### 'CORS error' in terminal -Try accessing the page using ```https://localhost:3000``` -instead of ```https://127.0.0.1:3000``` +Try accessing the page using `https://localhost:3000` +instead of `https://127.0.0.1:3000` ### Default blank screen -Try typing ```“thisisunsafe”``` or ```"iknowwhatiamdoing"``` then reload page +Try typing `“thisisunsafe”` or `"iknowwhatiamdoing"` then reload page ### Instanceserver or resource loading error? -Open dev console, click on the GET link in new tab and accept certificate by -typing ```thisisunsafe”``` or ```"iknowwhatiamdoing"``` then reload original page +Open dev console, click on the GET link in new tab and accept certificate by +typing `thisisunsafe”` or `"iknowwhatiamdoing"` then reload original page ### To install a new package for editor react components in monorepo @@ -102,26 +106,22 @@ Currently MinIO is used as default storage for local development. If you want to ### Accessing MinIO S3 storage provider running in local docker -**Using [MinIO Console](https://min.io/docs/minio/linux/administration/minio-console.html):** +**Using **[**MinIO Console**](https://min.io/docs/minio/linux/administration/minio-console.html)**:** - When MinIO contain is running in your docker, navigate to [https://localhost:9001/](https://localhost:9001/) in your browser. > Make sure to accept invalid certificate warning. - - Login using username as `server` and password as `password`. > You can find these credentials in `scripts/docker-compose.yml` as `MINIO_ROOT_USER` & `MINIO_ROOT_PASSWORD` -**Using [S3 Browser](https://s3browser.com/) (Windows Only):** +**Using **[**S3 Browser**](https://s3browser.com/)** (Windows Only):** - Download & install S3 Browser from [https://s3browser.com/download.aspx](https://s3browser.com/download.aspx). - Launch and connect using following details: - - Account Type: **S3 Compatible Storage** - - REST Endpoint: **127.0.0.1:9000** - - Access Key ID: **server** - - Secret Access Key: **password** - - Use secure transfer (SSL/TLS): **Check / On / True** ### Clear all data from MinIO S3 storage provider running in local docker + Run following commands in your terminal: + ```bash docker container stop etherealengine_minio_s3 docker container rm etherealengine_minio_s3 @@ -134,10 +134,13 @@ npm run dev-reinit ### DB not seeding routes (E.g. Error: No project installed- please contact site admin) Try + ```bash npm run dev-reinit ``` + or + ```bash docker container stop ir-engine_db docker container rm ir-engine_db @@ -147,6 +150,7 @@ npm run dev-reinit ``` ### Weird issues with your database? + Try ```bash @@ -154,6 +158,8 @@ npm run dev-reinit ``` Or if on windows + ```bash npm run dev-reinit-windows ``` + diff --git a/docs/manual/01_install/index.md b/docs/manual/01_install/index.md index f53fc52a3690..7c5bf3ae44a7 100644 --- a/docs/manual/01_install/index.md +++ b/docs/manual/01_install/index.md @@ -1,8 +1,22 @@ - - # Installation -Getting up and running requires just a few steps, but this can be tricky depending on your platform and current environment. -Please follow the instructions for your specific environment. +Getting up and running requires just a few steps. Find the instructions for your specific environment here. + +Choose your environment: + +::::link-array +:::link-array-item{headerImage headerColor} +[Installation on Linux](./01_linux.md) +::: + +:::link-array-item{headerImage headerColor} +[Installing on macOS](./02_macOSX.md) +::: + +:::link-array-item{headerImage headerColor} +[Installing on Windows with WSL2](./03_windowsWSL.md) +::: +:::: + + -