From e25d4a83baf75df3e95ab5cafa82eb27d6181fb6 Mon Sep 17 00:00:00 2001 From: Archbee BOT Date: Fri, 14 Feb 2025 17:39:13 +0000 Subject: [PATCH] Archbee draft docs --- .../typescript/01_quickstart/index.md | 6 ++-- .../02_hello_world/00_initial_setup.md | 6 ++-- .../00_project_code_overview.md | 4 +-- .../typescript/02_hello_world/01_ecs.md | 5 ++-- .../typescript/02_hello_world/02_engine.md | 6 +--- .../typescript/02_hello_world/03_system.md | 2 +- .../typescript/02_hello_world/04_component.md | 6 ++-- .../typescript/02_hello_world/05_query.md | 29 ++++++++++--------- .../typescript/02_hello_world/index.md | 5 ++-- docs/developer/typescript/index.md | 22 +++----------- 10 files changed, 37 insertions(+), 54 deletions(-) diff --git a/docs/developer/typescript/01_quickstart/index.md b/docs/developer/typescript/01_quickstart/index.md index f9834aa6bf17..991a56de8adb 100644 --- a/docs/developer/typescript/01_quickstart/index.md +++ b/docs/developer/typescript/01_quickstart/index.md @@ -2,9 +2,9 @@ Welcome to the developer quickstart. This guide prepares you for your first experience with the engine as a TypeScript developer. This guide prepares you to: -1. Install the iR Engine in your local environment -2. Access the default projects to test and develop -3. Introduce you to the **Hello world tutorial** for your first hands-on experience with the engine +1. Install the iR Engine in your local environment. +2. Access the default projects to test and develop. +3. Introduce you to the [Hello World tutorial](./../02_hello_world/index.md) for your first hands-on experience with the engine. ## Initial setup diff --git a/docs/developer/typescript/02_hello_world/00_initial_setup.md b/docs/developer/typescript/02_hello_world/00_initial_setup.md index 926192c09307..204930150740 100644 --- a/docs/developer/typescript/02_hello_world/00_initial_setup.md +++ b/docs/developer/typescript/02_hello_world/00_initial_setup.md @@ -1,10 +1,10 @@ -# Install the Tutorial Project +# Initial setup -For this tutorial, you will use the introductory **Hellow World project** to learn your way around the engine. +For this tutorial, you will use the introductory Hellow World project to learn your way around the engine. ## Prerequisites -Ensure you have completed the [Developer quickstart](./../01_quickstart/index.md) and that you have the engine installed. +Ensure you have completed the [Quickstart guide](./../01_quickstart/index.md) and that you have the engine installed. :::hint{type="info"} ℹ️ **Important** diff --git a/docs/developer/typescript/02_hello_world/00_project_code_overview.md b/docs/developer/typescript/02_hello_world/00_project_code_overview.md index 05a932c561a9..b269e5e249b3 100644 --- a/docs/developer/typescript/02_hello_world/00_project_code_overview.md +++ b/docs/developer/typescript/02_hello_world/00_project_code_overview.md @@ -1,6 +1,6 @@ -# Project code overview +# Project overview -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. +The [Quickstart guide](./../01_quickstart/index.md) helped us create a project and run iR Engine for the first time. Now, let's review what we have before diving deeper. :::hint{type="info"} ℹ️ **Info** diff --git a/docs/developer/typescript/02_hello_world/01_ecs.md b/docs/developer/typescript/02_hello_world/01_ecs.md index 8403f975c3ba..9786447a51c8 100644 --- a/docs/developer/typescript/02_hello_world/01_ecs.md +++ b/docs/developer/typescript/02_hello_world/01_ecs.md @@ -1,6 +1,6 @@ -# Using the ECS pattern +# The ECS pattern -The engine uses the [Entity-Component-System (ECS)](https://en.wikipedia.org/wiki/Entity_component_system) patterna software architecture pattern used to structure code efficiently. In this pattern: +The engine uses the [Entity-Component-System (ECS)](https://en.wikipedia.org/wiki/Entity_component_system) pattern. A software architecture pattern used to structure code efficiently. 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. @@ -95,4 +95,3 @@ In the next section, we will use a more readable name to create this component. ## Next steps Now that you know what the ECS pattern is and how to use it, you can [Start working in the engine](./02_engine.md) and extend its functionalities. - diff --git a/docs/developer/typescript/02_hello_world/02_engine.md b/docs/developer/typescript/02_hello_world/02_engine.md index 4faa7cd305b8..cb219ccc6a99 100644 --- a/docs/developer/typescript/02_hello_world/02_engine.md +++ b/docs/developer/typescript/02_hello_world/02_engine.md @@ -1,4 +1,4 @@ -# Start working in the engine +# Work in the engine In this guide, you will finally get your hands on your first task to learn the engine by modifying a project's source code, importing components, setting up ECS, and modifying an object's geometry. @@ -57,8 +57,6 @@ These commands perform the following actions: - [ ] Did you clone the repository with no issues? - - *If you run into any trouble with the commands above, consult the *[Troubleshooting](./../../../manual/01_install/050_advanced/07_troubleshooting.md)* guides for guidance.* ::: @@ -230,5 +228,3 @@ To see your new changes in place: You have had your first experience working in the engine. Now, let's learn to add logic through [Systems](./03_system.md). ::: - - diff --git a/docs/developer/typescript/02_hello_world/03_system.md b/docs/developer/typescript/02_hello_world/03_system.md index 1ca6a4596657..92921ec26218 100644 --- a/docs/developer/typescript/02_hello_world/03_system.md +++ b/docs/developer/typescript/02_hello_world/03_system.md @@ -1,4 +1,4 @@ -# Adding Systems +# Define a System So far, you have used the **Entity-Component-System (ECS)** pattern by: diff --git a/docs/developer/typescript/02_hello_world/04_component.md b/docs/developer/typescript/02_hello_world/04_component.md index a001063c177c..9a7d1d87a8c2 100644 --- a/docs/developer/typescript/02_hello_world/04_component.md +++ b/docs/developer/typescript/02_hello_world/04_component.md @@ -1,7 +1,7 @@ -# Work with Components +# Create a custom Component :::hint{type="info"} -📝 You must complete [Manage Systems](./03_system.md) before starting this guide. +📝 You must complete [Adding Systems](./03_system.md) before starting this guide. ::: Your current implementation has a **critical issue**: The sphere is being created **globally in every scene** rather than being restricted to a specific scene. @@ -110,7 +110,7 @@ Next, modify the system to **only execute when this component is present**. ## Step 3: Restrict execution using a query -Modify the system so that it **only runs for entities that have the `HelloComponent`**. +Modify the system so that it **only runs for entities that have the **`HelloComponent`. This prevents the sphere from being created in every scene. diff --git a/docs/developer/typescript/02_hello_world/05_query.md b/docs/developer/typescript/02_hello_world/05_query.md index 12a4ec73322c..95d68a6e6435 100644 --- a/docs/developer/typescript/02_hello_world/05_query.md +++ b/docs/developer/typescript/02_hello_world/05_query.md @@ -1,4 +1,4 @@ -# Using queries +# Define a Query Queries are a core feature of the **Entity Component System (ECS)** pattern in iR Engine. @@ -41,11 +41,11 @@ This query **returns all entities** that have the `HelloComponent`. Here's a table to help you understand the query: -| **Function** | **Description** | -| --- | --- | -| defineQuery([...]) | Creates a query to filter entities based on components. | -| [HelloComponent] | The query will match **only** entities containing this component. | -| helloQuery() | When called, it returns **all matching entities**. | +| **Function** | **Description** | +| :------------------ | :---------------------------------------------------------------- | +| defineQuery(\[...]) | Creates a query to filter entities based on components. | +| \[HelloComponent] | The query will match **only** entities containing this component. | +| helloQuery() | When called, it returns **all matching entities**. | At this stage, the query **does not run automatically**. You need to integrate it into your system. @@ -115,11 +115,11 @@ export const HelloSystem = ECS.defineSystem({ ### How does this solve the problem? -| **Issue** | **Before** | **Now** | -| --- | --- | --- | -| Entities created manually | Used `createEntity()` | Now retrieved dynamically via `defineQuery()` | -| Code ran globally | Executed every time | Now runs **only for specific entities** | -| No filtering mechanism | Affected all scenes | Now **restricted to entities with HelloComponent** | +| **Issue** | **Before** | **Now** | +| :------------------------ | :-------------------- | :------------------------------------------------- | +| Entities created manually | Used `createEntity()` | Now retrieved dynamically via `defineQuery()` | +| Code ran globally | Executed every time | Now runs **only for specific entities** | +| No filtering mechanism | Affected all scenes | Now **restricted to entities with HelloComponent** | ## Step 4: Loading the component @@ -139,9 +139,9 @@ With this setup, the system runs only inside `hello-final`, preventing unwanted Follow these steps to verify that queries and components are working correctly: 1. **Run the project** and open the `hello-final` scene. - ✅ The sphere should appear in the scene. -1. **Switch to another scene** (e.g., `default-project/apartment`). - ✅ The sphere should not appear. + ✅ The sphere should appear in the scene. +2. **Switch to another scene** (e.g., `default-project/apartment`). + ✅ The sphere should not appear. If everything works as expected, the system is correctly filtering and processing entities based on their components. @@ -205,3 +205,4 @@ By using `defineQuery()`, your system now **retrieves entities dynamically inste - Systems **process only matching entities**, reducing unnecessary execution. - The sphere now **only appears in the correct scene**, rather than globally. - Using **JavaScript Generators** improves performance by avoiding unnecessary data storage. + diff --git a/docs/developer/typescript/02_hello_world/index.md b/docs/developer/typescript/02_hello_world/index.md index f2dbc7074dfe..cfb89fd50ca5 100644 --- a/docs/developer/typescript/02_hello_world/index.md +++ b/docs/developer/typescript/02_hello_world/index.md @@ -21,7 +21,8 @@ This tutorial covers the following core concepts: By the end of this tutorial, you will have a **basic functional project** and an introductory foundation for working with the engine. :::hint{type="info"} -## Where to start +➡️ **Start here** -Begin with Step 1: Initial setup, where you will configure your project and prepare your development environment. +Begin with [Install the Tutorial Project](./00_initial_setup.md), where you will configure your project and prepare your development environment. ::: + diff --git a/docs/developer/typescript/index.md b/docs/developer/typescript/index.md index 082ef579adcb..ded6dcef7230 100644 --- a/docs/developer/typescript/index.md +++ b/docs/developer/typescript/index.md @@ -2,15 +2,13 @@ Welcome to the TypeScript guides for iR Engine. This section provides structured tutorials and documentation to help you learn how to develop with the engine efficiently. -Whether you're just getting started or diving into advanced features, this guide will walk you through everything you need to know about entities, components, systems, physics, state management, and more. - -## 🚀 Learning pathway +## Learning pathway If you are new to iR Engine, we recommend following this structured learning path. It will guide you from setting up your environment to building a complete project and eventually mastering the engine’s internals. ::::link-array :::link-array-item{headerImage headerColor} -🌱 Pt 1. [Hello World tutorial]() +🌱 [Hello World tutorial](./02_hello_world/index.md) Your first step into iR Engine. @@ -20,7 +18,7 @@ Your first step into iR Engine. ::: :::link-array-item{headerImage headerColor} -🛠️ Pt. 2 [Engine basics tutorial](./../03_basics_tutorial/index.md) +🛠️ [Engine basics tutorial](./03_basics_tutorial/index.md) Continue expanding your knowledge. @@ -29,7 +27,7 @@ Continue expanding your knowledge. ::: :::link-array-item{headerImage headerColor} -📚 Pt. 3 [Technical manual](./../../../manual/index.md) +📚 [Technical manual](./../../manual/index.md) Detailed documentation on iR Engine’s internals. @@ -38,15 +36,3 @@ Detailed documentation on iR Engine’s internals. ::: :::: -