Define a Query

now that you've locked sphere creation behind a component , it's time to optimize execution further using queries what are queries in ecs? a query allows you to retrieve all entities that contain a specific set of components this provides a dynamic way to access entities instead of manually tracking them how queries work a query does the following accepts a list of components as input returns a function that retrieves all entities containing those components can be used anywhere in your code to fetch matching entities important rules when using queries, consider the following the query only matches entities that have all the specified components even if you are searching for one component , you must pass it inside an array the query does not create entities ; it only retrieves existing ones ℹ️ info queries return a javascript generator , which efficiently fetches matching entities without creating unnecessary objects to learn more, see javascript generators https //developer mozilla org/en us/docs/web/javascript/guide/iterators and generators#generator functions step 1 define a query define a query using definequery() , specifying the component(s) you want to search for // define the query that will find all entities with hellocomponent const helloquery = ecs definequery(\[hellocomponent]) this query returns all entities that have the hellocomponent understanding the query definition 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 at this stage, the query does not run automatically you need to integrate it into your system step 2 use the query in a system to process entities before integrating the query into a system, it's important to understand how to retrieve and process its results iterating over query results calling helloquery() does not return an array of entities instead, it returns a generator function that dynamically yields each matching entity one at a time to process all entities returned by the query, use a for of loop for (const entity of helloquery()) { // process each entity } this loop retrieves each entity that contains the hellocomponent , one at a time the engine handles this efficiently, ensuring that only relevant entities are returned now, use the query in a system to retrieve and modify the correct entities function hello() { for (const entity of helloquery()) { // check if the entity has already been initialized let { initialized } = ecs getmutablecomponent(entity, hellocomponent) if (initialized value) continue initialized set(true) // mark as initialized // add required components to the entity ecs setcomponent(entity, namecomponent, 'ee tutorial hello entity') ecs setcomponent(entity, visiblecomponent) ecs setcomponent(entity, transformcomponent, { position new vector3(0, 1, 0) }) ecs setcomponent(entity, primitivegeometrycomponent, { geometrytype geometrytypeenum spheregeometry }) } } step 3 integrate the query into the system now, modify the system to execute the hello() function export const hellosystem = ecs definesystem({ uuid 'ee tutorial hellosystem', execute hello, insert { after physicssystem } }) how does this improve the system? problem before now entities were processed manually had to store entity references query retrieves matching entities dynamically inefficient execution system executed every frame now only executes for relevant entities no filtering mechanism processed all entities now limited to entities with hellocomponent step 4 load the component in a scene for the system to process entities, the hellocomponent must exist in a scene the hello final scene (inside ir tutorial hello ) is already pre configured to include hellocomponent when this scene is loaded, the query will automatically retrieve the correct entity step 5 confirm the changes to verify that queries and components are working run the project and open the hello final scene ✅ the sphere should appear in the scene switch to another scene (e g , default project/apartment ) ✅ the sphere should not appear if both conditions are met, the query is correctly filtering entities 🎉 you have successfully optimized execution using queries! final implementation after making these updates, your hello ts file should look like this 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' import { vector3 } from 'three' import { geometrytypeenum } from '@ir engine/packages/engine/src/scene/constants/geometrytypeenum' import { physicssystem } from '@ir engine/packages/spatial' // define the custom component export const hellocomponent = ecs definecomponent({ name 'ee tutorial hellocomponent', jsonid 'ee tutorial hello', oninit () => ({ initialized false }) }) // define the query to find entities with hellocomponent const helloquery = ecs definequery(\[hellocomponent]) // define the function to execute const hello = () => { for (const entity of helloquery()) { let { initialized } = ecs getmutablecomponent(entity, hellocomponent) if (initialized value) continue initialized set(true) ecs setcomponent(entity, namecomponent, 'ee tutorial hello entity') ecs setcomponent(entity, visiblecomponent) ecs setcomponent(entity, transformcomponent, { position new vector3(0, 1, 0) }) ecs setcomponent(entity, primitivegeometrycomponent, { geometrytype geometrytypeenum spheregeometry }) } } // define the system export const hellosystem = ecs definesystem({ uuid 'ee tutorial hellosystem', execute hello, insert { after physicssystem } }) summary ✅ you have now successfully implemented queries in ir engine! by using definequery() , your system now retrieves entities dynamically instead of creating them manually key takeaways queries find existing entities based on components 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 ➡️ next steps now that you have structured entities, components, systems, and queries , it's time to recap what you've learned and move forward 📌 continue to recap and next steps docid\ lanvlv43dcapya3o3dvk5