Projects

this guide explains the project structure, configuration, and key functionalities overview projects in ir engine are modular, git based repositories containing custom code, assets, and scenes they enable developers to create, modify, and manage their own features, scenes, and content each project can be installed, updated, or removed independently, making it easy to extend and customize the engine projects are stored in the /packages/projects/ directory and can be managed in both production and local development environments project management by environment the way projects are managed differs between production and local development environments environment project management production projects are installed based on the projects database table, and assets are downloaded from a storage provider local development the local file system is the source of truth any project folders added or removed are automatically synchronized with the database by default, only the default project is installed in production environments, it is read only and is located at /packages/projects/default project/ each project is also a git repository , allowing for version control and seamless collaboration project structure projects follow a standardized folder structure to ensure consistency and maintainability /packages/projects/\[github org]/\[your project]/ │── assets/ # uploaded files │── src/ # source code for custom logic and components │── tests/ # test files for automated testing │── \[scenename] scene json # scene configuration file │── \[scenename] thumbnail png # auto generated scene preview │── xrengine config ts # project configuration file │── package json # project metadata and dependencies key directories and files before diving into project configuration, let’s break down the essential directories and files inside a project path description assets/ stores uploaded files from the editor src/ contains source code for project logic tests/ includes test files for validation \[scenename] scene json defines scene data and object positions \[scenename] thumbnail png stores an auto generated preview image of a scene xrengine config ts the main project configuration file package json defines dependencies and compatibility with ir engine code organization to maintain optimal performance and efficient code splitting, projects should follow these best practices scene related systems must be stored in /src/systems/ and end with system ts this ensures that vite’s bundling process properly handles dynamic imports dependencies from @ir engine/ are symlinked and do not need to be explicitly listed however, package managers like pnpm may require them in peerdependencies project configuration ( xrengine config ts ) the xrengine config ts file defines how a project interacts with the engine it allows customization of routes, services, database settings, and world behavior configuration interface below is the structure of the configuration file export interface projectconfiginterface { onevent? string thumbnail? string routes? { \[route string] { component () => promise<{ default (props any) => jsx element }> props? { \[x string] any exact? boolean } } } webappinjection? () => promise<{ default (props any) => void | jsx element }> worldinjection? () => promise<{ default () => promise\<void> }> services? string databaseseed? string settings? array\<projectsettingschema> } configuration properties each property inside xrengine config ts defines specific behaviors for the project event hooks ( onevent ) the onevent property specifies a relative path to a file that defines project lifecycle hooks these hooks allow developers to execute custom logic when a project is installed, updated, or removed export interface projecteventhooks { oninstall? (app application) => promise\<any> onload? (app application) => promise\<any> onupdate? (app application) => promise\<any> onuninstall? (app application) => promise\<any> onoembedrequest? (app application, url url, currentoembed oembed) => promise\<oembed | null> } hook trigger oninstall when the project is installed onload when the project is loaded onupdate when the project is updated (e g , after saving a scene) onuninstall when the project is removed onoembedrequest when an oembed preview is requested for a project url the default ir engine project uses oninstall to install default avatars you can find this implementation at /packages/projects/default project/projecteventhooks ts 🔗 link to the file thumbnail ( thumbnail ) the thumbnail property is used to specify a url to an image , which will be displayed as the project’s studio thumbnail example thumbnail "/static/thumbnail jpg" custom routes ( routes ) the routes property enables projects to define custom web routes , dynamically loading react components routes { '/' { component () => import('@ir engine/client/src/pages/index'), props { exact true } }, '/admin' { component () => import('@ir engine/client/src/pages/admin') }, '/location' { component () => import('@ir engine/client/src/pages/location/location') }, '/studio' { component () => import('@ir engine/client/src/pages/editor') }, '/room' { component () => import('@ir engine/client/src/pages/room') }, '/capture' { component () => import('@ir engine/client/src/pages/capture') }, '/chat' { component () => import('@ir engine/client/src/pages/chat/chat') } } key description route path the url path for the route (must start with / ) component a react component dynamically loaded on demand webapp injection ( webappinjection ) the webappinjection property runs before web routes are loaded , allowing projects to initialize logic globally webappinjection () => import(' /webappinjection') world injection ( worldinjection ) the worldinjection property allows logic to be run every time a new world is created this logic is loaded on all instances of the engine, such as a location and the editor an example use case of this property would be registering custom scene loader and editor prefabs worldinjection () => import(' /src/hello') services ( services ) the services property defines feathers js services for apis and game logic it is a relative path that points to a file which must return the type ((app application) => promise\<any>)\[] this return type will be run on all instance servers and api servers at startup services ' /services/services ts' database seeding ( databaseseed ) the databaseseed property points to a database seed file for initial data population databaseseed ' /services/seeder config ts' internationalization (i18n) projects can support multiple languages using i18n files located in /i18n/\[language]/\[namespace] json example structure /i18n/en/admin json /i18n/fr/admin json you can find example i18n files in the ir engine i18n repository https //github com/ir engine/ir engine/tree/dev/packages/client core/i18n