# Install Feather 2

> Build and run the Feather 2 editor from a source checkout, or package it as a macOS app.

Source: https://feather-engine.com/docs/getting-started/install/

Feather 2 is in preview and is built from source. One Cargo workspace produces three programs: the
editor, the standalone game player and a command-line tool for automation.

:::caution
Development and packaging are currently verified on Apple Silicon macOS only. The engine is written
to build on Windows and Linux, but those platforms have not been validated yet.
:::

## Requirements

| Requirement | Notes |
| --- | --- |
| Rust 1.89 or newer | The crate declares `rust-version = "1.89"` and uses the 2024 edition |
| Platform build tools | On macOS, install the Xcode Command Line Tools (`xcode-select --install`) |
| Python 3 | Only for the packaging and example build scripts |

## Run the editor from source

1. Clone the engine repository and open a terminal in its root folder.
2. Start the editor:

   ```bash
   cargo run --bin feather-editor
   ```

3. The first build compiles every dependency and takes a while. Later builds are incremental.

The editor opens the included **Shred & Sort** starter. It is a template: **Save** asks you for a
destination, so your own copy never overwrites the example. Use **File → New project…** to start
from an empty scene instead.

To open a specific project:

```bash
cargo run --bin feather-editor -- --project examples/paper-shredder/project.feather.json
```

## The three programs

| Binary | What it is |
| --- | --- |
| `feather-editor` | The editor. The default target for `cargo run` |
| `feather-player` | The standalone game runtime, without editor features. Exported games ship with it |
| `feather-cli` | The JSON command runner and MCP server used by scripts and AI agents |

Build all three at once with `cargo build`. The binaries are written to `target/debug/`.

## Editor command-line options

| Option | Effect |
| --- | --- |
| `PROJECT` | Open a `.feather` or `.feather.json` project given as a bare path. This is how Windows and Linux open a double-clicked project file |
| `--project FILE` | Open a saved project |
| `--new` | Start with a new, empty project |
| `--panel NAME` | Open a tool panel on launch, for example `code`, `blueprint`, `landscape`, `prefab`, `ai`, `navigation`, `material-graph` or `automation` |
| `--workspace DIR --automation FILE` | Enable a live automation session for AI tools; see [MCP setup](/docs/agents/mcp/) |
| `--check` | Validate the project, print a summary and exit without opening a window |
| `--export` | Build the game for this computer into an `exports/` folder and exit: in the engine repository from a source checkout, or in the Feather data folder from the app. See [Build a game](/docs/shipping/export/) |
| `--screenshot PNG` | Capture the editor window once the scene has loaded, then exit |

For example, to validate a project without opening a window:

```bash
cargo run --bin feather-editor -- --project examples/paper-shredder/project.feather.json --check
```

## Build a macOS app

On macOS you can package the editor as a Finder application:

```bash
python3 scripts/package_macos.py
open "dist/Feather v2.app"
```

The script builds all three programs and assembles `dist/Feather v2.app`:

| Location in the bundle | Contents |
| --- | --- |
| `Contents/MacOS/feather-editor` | The editor |
| `Contents/MacOS/feather-cli` | The automation CLI, ready for MCP client configuration |
| `Contents/Resources/feather-player` | The player used by **Build** for macOS games |
| `Contents/Resources/` | The Shred & Sort and Fluid Playground examples |

The bundle is ad-hoc signed for local use. It is a development build for your Mac's architecture,
not a signed or notarised installer. A source-checkout editor builds the player with Cargo when you
build a game; the app uses the player inside its bundle instead.

The app registers the `.feather` project type with Finder, so double-clicking a project opens it in
the editor, whether or not the editor is already running.

## Where Feather stores data

Feather keeps its working data outside your projects: the imported-asset cache, the converted model
library, thumbnails, crash reports and recovery autosaves.

| Platform | Location |
| --- | --- |
| macOS | `~/Library/Application Support/Feather v2/` |
| Windows | `%LOCALAPPDATA%/Feather v2/` |
| Linux | `${XDG_DATA_HOME:-$HOME/.local/share}/feather-v2/` |

If the editor closes unexpectedly, it offers to restore the recovery autosave the next time it
starts.

## Next steps

- [Make your first game](/docs/getting-started/first-game/)
- [Tour the editor](/docs/getting-started/editor-tour/)
- [Example projects](/docs/examples/)