# How Editor Projects Work

A PlayCanvas Editor project holds everything that makes up one app: its scenes, the assets they use, its scripts and its settings. This page explains how those pieces fit together, so the rest of this manual makes sense. If you haven't yet, build [Your First App](https://developer.playcanvas.com/user-manual/editor/getting-started/your-first-app.md) first. It touches every piece described here in about 15 minutes.

```mermaid
flowchart TD
    Project["Project"] --> Branch["Branch<br/>main, and any you create"]
    Branch --> Scenes["Scenes"]
    Branch --> Assets["Assets<br/>models, materials, textures,<br/>audio, scripts, templates"]
    Branch --> Settings["Project settings"]
    Scenes --> Entities["Entities, in a hierarchy"]
    Entities --> Components["Components<br/>render, light, camera,<br/>collision, script and more"]
    Assets -. used by .-> Components
```

## Scenes, Entities and Components

A **scene** is one world your app can show, such as a level or a menu. A project can have many scenes. An app starts in one of them and can [load others while it runs](https://developer.playcanvas.com/user-manual/editor/scenes/loading-scenes.md). You create and open scenes from [Managing Scenes](https://developer.playcanvas.com/user-manual/editor/scenes/managing-scenes.md).

A scene is a hierarchy of **entities**, which you see in the [Hierarchy panel](https://developer.playcanvas.com/user-manual/editor/interface/hierarchy.md). On its own, an entity is only a position, rotation and scale. **Components** give it abilities: a Render component draws a shape or a model, a Light lights the scene, Collision and Rigid Body components put it in the physics simulation, and a Script component runs your code. Select an entity to edit its components in the [Inspector](https://developer.playcanvas.com/user-manual/editor/interface/inspector.md). [Entity Component System](https://developer.playcanvas.com/user-manual/ecs.md) explains the model in depth.

Each scene also has settings of its own, such as its skybox, ambient light and physics gravity.

## Assets

**Assets** are the files and data your scenes use: models, materials, textures, audio, fonts, scripts and more. They belong to the project rather than to one scene, so every scene can use them, and you manage them in the [Assets panel](https://developer.playcanvas.com/user-manual/editor/assets/asset-panel.md). An entity uses an asset when one of its components refers to it, such as a Render component's material.

When you upload a file, the Editor's [import pipeline](https://developer.playcanvas.com/user-manual/editor/assets/import-pipeline.md) keeps the original as a **source asset** and creates the **target assets** your app loads. Uploading a 3D model, for example, creates a template with the model's hierarchy, render assets for its meshes, and its materials and textures. To update a model, upload the file again, and every asset made from it updates with it.

[Templates](https://developer.playcanvas.com/user-manual/editor/templates.md) are assets too. A template is a saved hierarchy of entities, like a prefab, that you can place many times and then change everywhere at once.

## Scripts

Scripts are JavaScript assets. To give an entity behavior, add a Script component and attach a script to it. Script attributes expose values in the Inspector, so you can tune a script without editing its code. Write scripts in the built-in [Code Editor](https://developer.playcanvas.com/user-manual/editor/scripting/code-editor.md), or in Visual Studio Code with the [PlayCanvas extension](https://developer.playcanvas.com/user-manual/editor/scripting/vscode-extension.md).

Scripts work directly with the PlayCanvas Engine, so everything in [Scripting](https://developer.playcanvas.com/user-manual/scripting.md) applies to them.

## What Saves, and Who Sees It

There is no Save button for scenes. Every change you make to entities, components, assets and settings is saved as you make it, and everyone else working on the same branch sees it straight away. See [Real-time Collaboration](https://developer.playcanvas.com/user-manual/editor/realtime-collaboration.md).

- **Scripts are the exception.** Code Editor changes are saved when you save the file with <kbd>Ctrl</kbd>+<kbd>S</kbd> (<kbd>Cmd</kbd>+<kbd>S</kbd> on macOS), and only saved code runs when you launch.
- **Undo is yours.** <kbd>Ctrl</kbd>+<kbd>Z</kbd> (<kbd>Cmd</kbd>+<kbd>Z</kbd> on macOS) steps back through your own changes, not other people's.
- **Most settings are shared.** Project settings apply to everyone on the branch, but a few are just for you, such as the Editor camera and gizmo preferences. [Project Settings](https://developer.playcanvas.com/user-manual/editor/interface/settings.md) explains which are which.

A project belongs to a user or an organization, and its [team](https://developer.playcanvas.com/user-manual/editor/projects/team-management.md) decides who can see it and who can edit it.

## Testing with the Launch Page

Select **Launch** at the top right of the Viewport to run the current scene in a new browser tab. The [Launch Page](https://developer.playcanvas.com/user-manual/editor/interface/launch-page.md) stays connected to the Editor, so changes to entities, components, materials and settings show up in the running app as you make them. Reload it to pick up new assets and script changes, unless a script is written to [hot reload](https://developer.playcanvas.com/user-manual/editor/scripting/hot-reloading.md).

You can open the same page on a phone or tablet that is signed in to your PlayCanvas account, to test on a real device.

## Branches and Checkpoints

Every project starts with a **main** branch, and everything in the diagram above lives on a branch. A [checkpoint](https://developer.playcanvas.com/user-manual/editor/version-control/checkpoints.md) is a snapshot of the project that you can return to. A [branch](https://developer.playcanvas.com/user-manual/editor/version-control/branches.md) is a separate line of work, so you can try something out without affecting the main branch, then [merge](https://developer.playcanvas.com/user-manual/editor/version-control/merging.md) it back when it's ready. See [Version Control](https://developer.playcanvas.com/user-manual/editor/version-control.md).

## Builds

When your app is ready to share, [publish](https://developer.playcanvas.com/user-manual/editor/publishing.md) a **build**: a snapshot of the scenes you choose, packaged to run on its own. You can [host it on playcanvas.com](https://developer.playcanvas.com/user-manual/editor/publishing/web/playcanvas-hosting.md) at a link you can send to anyone, or [download it](https://developer.playcanvas.com/user-manual/editor/projects/downloading.md) to host yourself. Changes you make afterwards don't affect a build until you publish a new one.

## The Editor and the Engine

The Editor is built on the [PlayCanvas Engine](https://developer.playcanvas.com/user-manual/engine.md). The Viewport renders your scene with it, and the app you launch and publish runs on it. That's why the Common Topics in this manual, such as [Graphics](https://developer.playcanvas.com/user-manual/graphics.md), [Physics](https://developer.playcanvas.com/user-manual/physics.md) and [Animation](https://developer.playcanvas.com/user-manual/animation.md), apply to Editor projects too, often with an **Editor** tab showing how to do each step in the Editor. [Engine settings](https://developer.playcanvas.com/user-manual/editor/interface/settings/engine.md) choose the Engine version for launching and publishing.

## Next Steps

- [Editor Interface](https://developer.playcanvas.com/user-manual/editor/interface.md) — a map of the panels you'll use most.
- [What to Learn Next](https://developer.playcanvas.com/user-manual/editor/getting-started/next-steps.md) — a suggested order for the tutorials and topics that come after your first app.
