# gpm add

Add a package to a game project with automatic engine detection.

## Usage

```bash
gpm add <package[@version]> [flags]
```

## Arguments

* `<package[@version]>` - Package name and optional version (e.g., `com.unity.analytics@2.1.0`)

## Flags

| Flag               | Description                                     | Default           |
| ------------------ | ----------------------------------------------- | ----------------- |
| `--project <path>` | Project path                                    | Current directory |
| `--engine <type>`  | Engine type: `unity`, `godot`, `unreal`, `auto` | `auto`            |
| `--registry <url>` | Override registry URL                           | From config       |
| `--json`           | Output results in JSON format                   | `false`           |

## Description

The `gpm add` command adds a package to your game project, automatically detecting the engine (Unity takes priority) and updating the project's package manifest safely.

### Engine Detection Priority

1. **Unity** (highest priority)
2. **Godot**
3. **Unreal Engine**

### Supported Engines

* **Unity**: Full support with UPM manifest management
* **Godot**: Planned support
* **Unreal Engine**: Planned support

## Examples

### Basic Usage

```bash
# Add latest version
gpm add com.unity.analytics

# Add specific version
gpm add com.unity.analytics@2.1.0

# Add with engine specification
gpm add com.company.sdk --engine unity
```

### Advanced Usage

```bash
# Specify project path
gpm add com.package.name --project ./my-project

# Use custom registry
gpm add com.package.name --registry https://custom.gpm.sh

# JSON output for scripting
gpm add com.unity.analytics --json
```

## Engine-Specific Behavior

### Unity

For Unity projects, `gpm add` will:

1. Detect Unity project structure (`Assets/`, `ProjectSettings/`, `Packages/manifest.json`)
2. Ensure scoped registry entry exists for the effective host
3. Add/merge dependency with requested version in `Packages/manifest.json`
4. Preserve existing structure and validate JSON
5. Create backup before making changes

**Example Unity manifest.json update:**

```json
{
  "dependencies": {
    "com.unity.analytics": "2.1.0"
  },
  "scopedRegistries": [
    {
      "name": "GPM",
      "url": "https://registry.gpm.sh",
      "scopes": ["com.unity"]
    }
  ]
}
```

### Godot (Planned)

For Godot projects, `gpm add` will:

* Place content under `addons/<package>`
* Merge required sections into `project.godot` non-destructively

### Unreal Engine (Planned)

For Unreal projects, `gpm add` will:

* Place content under `Plugins/<PackageName>`
* Update `.uproject` → "Plugins" array without duplicates

## Package Naming

GPM uses Unity UPM-style reverse-DNS package IDs:

**Valid Examples:**

* `com.unity.analytics`
* `com.gameanalytics.sdk`
* `com.company.mygame.analytics`

**Invalid Examples:**

* `@scope/package` (npm scopes not supported)
* `my-package` (missing reverse-DNS structure)

## Output

### Human Format (Default)

```
Package Added Successfully
─────────────────────────────
Engine:   unity
Project:  /path/to/project
Package:  com.unity.analytics@2.1.0
Registry: https://registry.gpm.sh
Backup:   /tmp/gpm-backup-20240101-120000
─────────────────────────────
Package com.unity.analytics@2.1.0 added successfully
```

### JSON Format (`--json`)

```json
{
  "success": true,
  "engine": "unity",
  "project": "/path/to/project",
  "package": "com.unity.analytics",
  "version": "2.1.0",
  "registry": "https://registry.gpm.sh",
  "changed": true,
  "backup_path": "/tmp/gpm-backup-20240101-120000",
  "message": "Package com.unity.analytics@2.1.0 added successfully"
}
```

## Error Handling

### Common Errors

* **Package not found**: `package 'com.example.package' not found in registry`
* **Invalid package name**: `invalid package name: must use reverse-DNS format`
* **Engine not detected**: `no supported engine detected. Please specify --engine unity`
* **Project validation failed**: `project validation failed: not a valid Unity project`

### Backup and Recovery

`gpm add` automatically creates backups before making changes:

* Backup location: `/tmp/gpm-backup-<timestamp>`
* Automatic restoration on failure
* Manual restoration: Copy backup files back to project

## Related Commands

* [`gpm install`](/cli-reference/cli/package-management/install.md) - Install packages with auto-detection
* [`gpm uninstall`](https://github.com/gpm-sh/docs/blob/main/cli/package-management/uninstall.md) - Remove packages
* [`gpm list`](https://github.com/gpm-sh/docs/blob/main/cli/package-management/list.md) - List installed packages
* [`gpm config`](https://github.com/gpm-sh/docs/blob/main/cli/configuration/config.md) - Configure registry settings

## See Also

* [Package Management Overview](https://github.com/gpm-sh/docs/blob/main/cli/package-management/README.md)
* [Unity Engine Support](https://github.com/gpm-sh/docs/blob/main/engines/unity.md)
* [Package Naming Convention](/package-guidelines/packages/naming.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gpm.sh/cli-reference/cli/package-management/add.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.