Projects, scenes, entities, components, and assets

A game in OasisW is made up of five units: project, scene, entity, component, and asset. This page explains how the five units contain one another, and which editor panel shows each unit.

The concepts themselves are the same as in other engines. This page covers their names and locations in OasisW, and the points where they behave differently from other engines.

How they contain each other

The five units relate as follows.

Project
├─ Scenes (several)
│   └─ Entities (hierarchy, Root at the top)
│       └─ Components (RENDER, COLLISION, SCRIPT …)
│               │
│               └─ reference assets (materials, script files …)
└─ Assets (shared by the whole project)

• The project is the largest unit. One project can hold several scenes.
• A scene holds one hierarchy of entities. Each scene has its own entity list.
• An entity is an object placed in a scene. An entity itself has a name and Position, Rotation, and Scale. Components handle features such as making it visible or making it collide.
• A component attaches to an entity and adds a feature. Components reference the assets they need. For example, a RENDER component references a material asset, and a SCRIPT component references a script file asset.
• Assets belong to the project, not to a scene. That's why every scene in the same project shows the same ASSETS list.

The last point is the most important part of this structure. Entities and components are separate for each scene, but the assets that components reference are shared by the whole project. For how this difference affects your work, see What's per scene and what the project shares.

Where to see each unit

The buttons and fields of each panel are covered in detail in Editor layout.

Project

A project is a container for scenes and assets. The screens for creating a project and choosing one from the list are covered Pending once the project creation and list screens are finalized in Create a project and open the editor.

When you open a new project, the SCENES window appears first. A new project has one default scene.

Scene

Click the scene name at the left of the top bar to open the SCENES window. In this window you see the scene list, switch to another scene, and create a new scene with + New Scene. The ··· menu to the right of a scene name has Duplicate Scene and Delete Scene.

A new project's default scene and a newly created scene start with different contents.

When no entity is selected, the right panel shows SETTINGS. SETTINGS holds settings for the whole scene. Pending Once the SETTINGS panel items are documented

For how to create and switch scenes, see Create and switch scenes.

Entity

The HIERARCHY panel shows the current scene's entities as a hierarchy. Parent-child relationships work the same as in other engines.

When AI GAME BUILDER builds a game, it often groups entities under parent entities such as Environment, Lighting, Gameplay, and UI. The names and makeup of these groups differ each time. Click the + in front of a group to expand its child entities. If you can't see the entity you're looking for, type its name in the Search box at the top of the panel.

Entities with <> in front of their name have a script attached. When an entity has several components, only one icon is shown, so an entity without <> may still have a script attached.

Selecting an entity changes three things at once: its row in HIERARCHY is highlighted, a gizmo appears on the entity in the viewport, and the right panel changes to ENTITY. Click the same row again to deselect it, and the right side returns to SETTINGS.

Component

At the top of the ENTITY panel are the entity's own Position, Rotation, and Scale fields. Below them, each attached component appears under a header such as RENDER, COLLISION, SCRIPT, LIGHT, SCREEN, or ELEMENT.

Add components with the + ADD COMPONENT button below Position, Rotation, and Scale. The menu is divided into categories.

Components that are already attached appear dimmed in the menu. Which components get attached to entities the AI creates differs each time. For how to add and remove components, see Add and remove components.

Asset

The ASSETS panel shows the project's assets. The folder tree on the left starts at the root /. Projects the AI built get folders such as Materials and Scripts.

• Upload at the right end uploads files from your computer.
• + is the menu for creating a new asset. It includes Folder, Material, Script, and more.
• Turn on list view (the three-line icon) to see each asset's type in the Type column.

How components connect to assets

Components reference assets rather than copying them. Two examples show this.

Materials — Materials the AI creates appear in the Materials folder with color-code names such as Color E63946. Entities that use the same color share a single material. In one test run, 5 Enemy entities used the single material Color E63946. So changing this material's color would likely change all 5 together. Pending Test whether changing a shared material's color changes several entities together On the entity side, the Materials field of the RENDER component determines which material it uses. For details, see Change an entity's color.

Scripts — A script file (for example, ballMove.js) is an asset in ASSETS. On the entity, a SCRIPT component references this file. The values of attributes the script declares are stored separately in the fields of the entity's SCRIPT component. In one check, changing the default: value in the code from 11 to 22 left the game at 11. The value 11 stored in the entity's field appears to have been used. For details, see Change script attribute values.

In short, code is an asset, so the project shares it. Which entity a script is attached to, and its attribute values, live on the entity, so they are likely separate for each scene. We haven't yet tested directly whether they are separate per scene.

Next steps

• What's per scene and what the project shares — problems caused by shared assets, and how to handle them
• Terms from other engines
• Editor layout
• HIERARCHY panel
• Add and remove components
• Create and switch scenes