TypeScript guides
Hello World tutorial
Create a scene component
16 min
so far, your hello world system successfully creates a sphere however, there is a critical issue ❌ the sphere is created globally in every scene ✅ the goal is to create it only in specific scenes this happens because ir engine executes projects globally , and you have not defined when the sphere should be created understanding the problem right now, your implementation does the following creates a file ( src/hello ts ) that contains the code connects the code to the engine using the project’s configuration file defines a system using definesystem creates the sphere directly inside the system ❌ does not define the sphere as a component ❌ does not associate the sphere with a specific scene because of steps 5 and 6 , the sphere appears in every project that runs in the engine , which is not the expected behavior ℹ️ info without a component, the engine has no way to determine when to create the sphere the current implementation lacks a trigger to tell the system when to execute the solution locking the sphere behind a component you need to define a custom component that controls when and where the sphere is created to restrict the sphere’s execution, you need to define a custom component to track when the sphere should appear use a query to execute logic only when an entity has this component ensure the system only runs under the right conditions by following this approach, your system will only create the sphere when needed rather than running globally step 1 define a custom component a component is a structured way to store information about an entity in the engine for this example, define a new component that tracks whether the sphere has been initialized we'll call this component hellocomponent export const hellocomponent = ecs definecomponent({ name 'ee tutorial hellocomponent', jsonid 'ee tutorial hello', oninit () => ({ initialized false }) // default state }) right now, this component does nothing on its own you will connect it to your system in the next step what does this do? property description name a unique identifier for the component jsonid an internal identifier used by the engine oninit defines the default state of the component (initialized as false ) step 2 store component state to track whether the sphere has been created, retrieve and update the component’s state inside your system let { initialized } = ecs getmutablecomponent(entity, hellocomponent) if (initialized value) continue initialized set(true) // set initialized to true why is this necessary? initialized value retrieves the current value of the component initialized set(true) updates the component’s state in a way that is compatible with ir engine using initialized set(true) ensures that state changes are properly managed within the ecs system 💡 state management in ecs component states must be managed through getmutablecomponent() to ensure proper updates 📝 checkpoint at this point, you have a component that stores an initialization state 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 this prevents the sphere from being created in every scene export const helloworldsystem = ecs definesystem({ uuid 'helloworld system', query { entities \[hellocomponent] }, // run only when hellocomponent is present execute ({ entities }) => { for (const entity of entities) { let { initialized } = ecs getmutablecomponent(entity, hellocomponent) if (initialized value) continue initialized set(true) ecs setcomponent(entity, namecomponent, 'hello world') ecs setcomponent(entity, visiblecomponent) ecs setcomponent(entity, transformcomponent, { position new vector3(0, 1, 0) }) ecs setcomponent(entity, primitivegeometrycomponent, { geometrytype geometrytypeenum spheregeometry }) } }, insert { after physicssystem } }) how does this fix the issue? issue before now sphere appears in every scene system runs globally runs only for entities with hellocomponent no way to track state used an external initialized variable state is now inside the component unrestricted execution system always executes system only runs when needed now, the sphere is only created when an entity has the hellocomponent , ensuring correct behavior final implementation after making these changes, your hello ts file should look like this import { ecs } from '@ir engine/packages/ecs' import { physicssystem } from '@ir engine/packages/spatial/src/physics/physicsmodule' 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' import { geometrytypeenum } from '@ir engine/packages/engine/src/scene/constants/geometrytypeenum' // define the custom component export const hellocomponent = ecs definecomponent({ name 'ee tutorial hellocomponent', jsonid 'ee tutorial hello', oninit () => ({ initialized false }) }) // define the system with a query for hellocomponent export const helloworldsystem = ecs definesystem({ uuid 'helloworld system', query { entities \[hellocomponent] }, execute ({ entities }) => { for (const entity of entities) { let { initialized } = ecs getmutablecomponent(entity, hellocomponent) if (initialized value) continue initialized set(true) ecs setcomponent(entity, namecomponent, 'hello world') ecs setcomponent(entity, visiblecomponent) ecs setcomponent(entity, transformcomponent, { position new vector3(0, 1, 0) }) ecs setcomponent(entity, primitivegeometrycomponent, { geometrytype geometrytypeenum spheregeometry }) } }, insert { after physicssystem } }) confirming the changes to verify your system is now scene specific run the project in ir engine open the " hello final " scene (pre configured to include hellocomponent ) ✅ the sphere should appear in the scene switch to another scene (e g , default project/apartment ) ✅ the sphere should not appear in unrelated scenes if both conditions are met, your system is now correctly scene specific 🎉 you have successfully restricted the system’s execution using components! ➡️ next steps now that the sphere creation is locked behind a component , let’s optimize execution using queries 📌 continue to define a query docid\ qw4mkitlr8ooyjv9ftemn