[developer] Create the beginner Typescript guide

docs/_partials/defaultProjects.md

@@ -0,0 +1,8 @@
+Ethereal Engine has a few scenes that are installed by default.  
+With the engine running, open the Studio by navigating to https://localhost:3000/studio, and you will see the engine's default project listed in that page.  
+
+Lets give them a test run:
+- Open one of 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

docs/_partials/installUbuntu.md

@@ -0,0 +1,19 @@
+:::important
+Ethereal 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.
+:::
+
+If you are on Ubuntu Linux, there is an automatic installation script to setup and run a local version of Ethereal 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/EtherealEngine/etherealengine/dev/scripts/ubuntu-install.sh && bash -i ./ubuntu-install.sh
+npm run reinit && npm run dev
+```
+You can now open Ethereal Engine on your web browser by navigating to https://localhost:3000

docs/developer/typescript/01_gettingStarted/01_quickstart.md

@@ -0,0 +1,43 @@
+---
+sidebar_label: Quickstart
+---
+import UbuntuInstall from '../../../_partials/installUbuntu.md'
+import DefaultProjects from '../../../_partials/defaultProjects.md'
+
+# Typescript Quickstart
+This QuickStart guide will teach you the basics of Ethereal Engine, and how to run the engine for the first time.  
+
+## Installation
+<UbuntuInstall />
+
+## Projects
+### Default Projects
+<DefaultProjects />
+
+### 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.
+
+:::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.  
+:::
+
+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/EtherealEngine/ee-tutorial-hello packages/projects/projects/ee-tutorial-hello
+npm run dev
+```
+
+You should now be able to see the `ee-tutorial-hello` project listed in Ethereal Engine's Studio by navigating to https://localhost:3000/studio.
+
+## 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
+
+You will know that the code is running if you can see a white sphere in the middle 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.  
+:::

docs/developer/typescript/01_gettingStarted/02_hello/01_ecs.md

@@ -0,0 +1,87 @@
+import { TechnicalNote } from '@site/src/components/TechnicalNote';
+
+# 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
+
+<TechnicalNote title="Technical Summary">
+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.
+</TechnicalNote>
+
+:::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.  
+
+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.  
+
+Don't worry if you don't fully understand what some of them explain just yet. We will get there.  
+:::
+
+## Creating an Entity
+Creating an Entity is as simple as calling the `createEntity()` function from Ethereal Engine's `ECS`.  
+This function will return an identifier that can be used to group Components into a unique and distinct Object.
+```ts
+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 Ethereal Engine's `ECS`.
+
+<TechnicalNote>
+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)_.
+</TechnicalNote>
+
+Ethereal 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.
+
+
+### `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
+ECS.setComponent(entity, NameComponent, 'hello-world')
+```
+<TechnicalNote title="Clarification">
+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.  
+</TechnicalNote>
+
+
+### `VisibleComponent`
+Gives the Entity the ability to be visible on the screen.  
+Entities without this Component will be ignored by the renderer.
+```ts
+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
+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
+ECS.setComponent(entity, PrimitiveGeometryComponent, { geometryType: 1 })
+```
+> The `1` here means that we are creating a [`SphereGeometry`](https://github.com/EtherealEngine/etherealengine/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.
+

docs/developer/typescript/01_gettingStarted/02_hello/02_engine.md

@@ -0,0 +1,205 @@
+---
+sidebar_label: The Engine
+---
+import { TechnicalNote } from '@site/src/components/TechnicalNote';
+import { UnstyledDetails } from '@site/src/components/UnstyledDetails';
+
+# Working with Ethereal Engine
+You will need three very important steps for creating a project with Ethereal Engine:
+1. Installing Ethereal 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.  
+
+## Requirements and Dependencies
+We will use `git` and `npm` a lot throughout the guides on this website.  
+
+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.  
+
+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.
+
+## Installing and running Ethereal Engine 
+Ethereal 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.
+
+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.  
+
+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.  
+
+## Installing and running projects
+Ethereal 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)_.
+
+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 Ethereal Engine installation folder:
+```bash
+git clone https://github.com/EtherealEngine/ee-tutorial-hello packages/projects/projects/ee-tutorial-hello
+npm run dev
+```
+:::note
+You will need to stop the engine and re-run it whenever you install a new project.  
+:::
+
+<TechnicalNote>
+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.  
+We did this by adding `-b Step0` to the `git clone` command:
+
+```bash
+git clone -b Step0 https://github.com/EtherealEngine/ee-tutorial-hello packages/projects/projects/ee-tutorial-hello
+```
+
+This step won't be needed for your own projects.
+</TechnicalNote>
+
+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.  
+:::
+
+:::important
+Each project's source code is executed globally.  
+This will become very important later on in this guide.  
+:::
+
+
+## Programming with Ethereal 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 Ethereal Engine's modules
+- We need to export our 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.
+
+<TechnicalNote title="Config File">
+
+```ts title="ee-tutorial-hello/xrengine.config.ts"
+import type { ProjectConfigInterface } from '@etherealengine/projects/ProjectConfigInterface'
+
+const config: ProjectConfigInterface = {
+  onEvent: undefined,
+  thumbnail: '/static/etherealengine_thumbnail.jpg',
+  routes: {},
+  services: undefined,
+  databaseSeed: undefined,
+  // highlight-start
+  worldInjection: () => import('./src/Hello')  // Import our Hello World code
+  // highlight-end
+}
+
+export default config
+```
+</TechnicalNote>
+
+We don't need to know much more about this file for now. We will explore it further in the `Beyond the Basics` guide.
+
+### 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:
+
+```ts title="ee-tutorial-hello/src/Hello.ts"
+import { NameComponent } from '@etherealengine/spatial/src/common/NameComponent'
+import { VisibleComponent } from '@etherealengine/spatial/src/renderer/components/VisibleComponent'
+import { TransformComponent } from '@etherealengine/spatial/src/transform/components/TransformComponent'
+import { PrimitiveGeometryComponent } from '@etherealengine/engine/src/scene/components/PrimitiveGeometryComponent'
+```
+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 Ethereal 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="ee-tutorial-hello/src/Hello.ts"
+import { ECS } from '@etherealengine/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.  
+
+:::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 `ee-tutorial-hello` in every step of the way.  
+:::
+
+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.  
+
+In order to do this, we need to:
+- Open the file `ee-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 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:
+'@etherealengine/engine/src/scene/constants/GeometryTypeEnum'
+
+// Getting the ID number of a Sphere by its enum name will look like:
+GeometryTypeEnum.SphereGeometry
+
+// To be certain that your changes are working, set the geometry to be 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 Ethereal Engine.  
+It is not required, but it is highly recommended.  
+VSCode has support for some important features and plugins that make the Ethereal Engine programming workflow really smooth and featureful.  
+:::
+
+<TechnicalNote title="Solution">
+
+The imports section of our code will now be:
+```ts title="ee-tutorial-hello/src/Hello.ts"
+// ... our other imports
+import { PrimitiveGeometryComponent } from '@etherealengine/engine/src/scene/components/PrimitiveGeometryComponent'
+import { Vector3 } from 'three'
+// highlight-start
+import { GeometryTypeEnum } from '@etherealengine/engine/src/scene/constants/GeometryTypeEnum'
+// highlight-end
+```
+The `PrimitiveGeometryComponent` call will now be:
+```ts title="ee-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
+```
+
+<UnstyledDetails title="Full Solution">
+
+```ts title="ee-tutorial-hello/src/Hello.ts" showLineNumbers
+import { ECS } from '@etherealengine/ecs'
+import { NameComponent } from '@etherealengine/spatial/src/common/NameComponent'
+import { VisibleComponent } from '@etherealengine/spatial/src/renderer/components/VisibleComponent'
+import { TransformComponent } from '@etherealengine/spatial/src/transform/components/TransformComponent'
+import { PrimitiveGeometryComponent } from '@etherealengine/engine/src/scene/components/PrimitiveGeometryComponent'
+// highlight-start
+import { GeometryTypeEnum } from '@etherealengine/engine/src/scene/constants/GeometryTypeEnum'
+// highlight-end
+
+const entity = ECS.createEntity()
+ECS.setComponent(entity, NameComponent, 'hello-world')
+ECS.setComponent(entity, VisibleComponent)
+ECS.setComponent(entity, TransformComponent, { position: new Vector3(0, 1, 0) })
+// highlight-start
+ECS.setComponent(entity, PrimitiveGeometryComponent, { geometryType: GeometryTypeEnum.SphereGeometry })
+// highlight-end
+```
+</UnstyledDetails>
+<!-- Full Solution End -->
+</TechnicalNote>
+<!-- Solution End -->
+