# Naming Convention

GPM implements the Unity UPM-style reverse-DNS package naming convention, establishing the industry standard for game development package identification. This approach ensures consistency across the entire game development ecosystem and provides superior organization compared to traditional package managers.

## Naming Format

### Valid Package Names

Package names must follow the reverse-DNS convention:

{% code title="Package Name Format" %}

```
com.company.product.feature
```

{% endcode %}

{% tabs %}
{% tab title="Unity Packages" %}

```bash
com.unity.analytics
com.unity.textmeshpro
com.unity.timeline
com.unity.cinemachine
```

{% endtab %}

{% tab title="Third-Party SDKs" %}

```bash
com.gameanalytics.sdk
com.adjust.sdk
com.firebase.unity
com.facebook.unity
```

{% endtab %}

{% tab title="Company Packages" %}

```bash
com.company.mygame.analytics
com.company.mygame.ui
com.company.mygame.networking
```

{% endtab %}
{% endtabs %}

### Validation Rules

{% hint style="info" %}
**Pattern:** `^(?:[a-z0-9]+(?:-[a-z0-9]+)*\.)+[a-z0-9]+(?:-[a-z0-9]+)*$`
{% endhint %}

{% tabs %}
{% tab title="Format Requirements" %}

* **Structure**: Must follow reverse-DNS format
* **Length**: Minimum 3 parts, maximum 10 parts
* **Characters**: Lowercase letters, numbers, and hyphens only
* **Separators**: Must contain at least one dot (`.`)
  {% endtab %}

{% tab title="Naming Guidelines" %}

* **Domain-based**: Use your company's domain in reverse order
* **Descriptive**: Package names should indicate their purpose
* **Consistent**: Use the same pattern across all packages
* **Professional**: Use proper company/organization names
  {% endtab %}
  {% endtabs %}

{% hint style="warning" %}
**Important:** Package names are case-sensitive and must be lowercase. Mixed case names like `Com.Company.Package` are not allowed.
{% endhint %}

{% hint style="success" %}
**Best Practice:** If your company owns `company.com`, use `com.company.packagename` as your base naming pattern.
{% endhint %}

## Naming Guidelines

### Recommended Structure

```
com.company.product.feature
│   │       │       │
│   │       │       └── Specific feature or module
│   │       └────────── Product or game name
│   └────────────────── Company or organization name
└────────────────────── Top-level domain (com, org, net, etc.)
```

### Examples by Category

#### Unity Packages

* `com.unity.analytics` - Unity Analytics
* `com.unity.textmeshpro` - TextMeshPro
* `com.unity.timeline` - Timeline
* `com.unity.cinemachine` - Cinemachine

#### Third-Party SDKs

* `com.gameanalytics.sdk` - GameAnalytics SDK
* `com.adjust.sdk` - Adjust SDK
* `com.firebase.unity` - Firebase Unity SDK
* `com.facebook.unity` - Facebook Unity SDK

#### Company Packages

* `com.company.mygame.analytics` - Company's analytics package
* `com.company.mygame.ui` - Company's UI package
* `com.company.mygame.networking` - Company's networking package

## Invalid Names

{% hint style="danger" %}
**Common Mistakes**: These naming patterns are not supported by GPM and will result in validation errors.
{% endhint %}

{% tabs %}
{% tab title="What NOT to Use" %}

* **npm-style scopes**: `@company/package`
* **Simple names**: `analytics`, `ui`, `networking`
* **Uppercase**: `COM.COMPANY.PACKAGE`
* **Special characters**: `com.company-package`, `com.company_package`
* **Numbers at start**: `com.123company.package`
  {% endtab %}

{% tab title="Common Command Errors" %}

```bash
# Invalid - npm scope format
gpm add @company/analytics

# Invalid - too simple
gpm add analytics

# Invalid - uppercase
gpm add COM.COMPANY.ANALYTICS

# Invalid - special characters
gpm add com.company-package.analytics

# Valid - reverse-DNS format
gpm add com.company.analytics
```

{% endtab %}
{% endtabs %}

## Choosing Your Package Name

### For Companies

1. **Use your domain**: `com.yourcompany.package`
2. **Be specific**: `com.yourcompany.game.analytics`
3. **Keep it short**: `com.yourcompany.analytics` (not `com.yourcompany.mygame.analytics.sdk`)

### For Open Source

1. **Use organization**: `org.opensource.package`
2. **Be descriptive**: `org.unity.analytics`
3. **Consider forks**: `com.yourname.unity.analytics.fork`

### For Personal Projects

1. **Use personal domain**: `com.yourname.package`
2. **Or use generic**: `com.developer.package`
3. **Be unique**: Avoid conflicts with existing packages

## Package Name Resolution

### Registry Resolution

Package names are resolved based on registry configuration:

* **Global Registry**: `https://registry.gpm.sh/com.company.package`
* **Tenant Registry**: `https://company.gpm.sh/com.company.package`

### Scoped Registry Configuration

Unity automatically configures scoped registries based on package names:

```json
{
  "scopedRegistries": [
    {
      "name": "Company Registry",
      "url": "https://company.gpm.sh",
      "scopes": ["com.company"]
    }
  ]
}
```

## Best Practices

### Naming Conventions

1. **Be Consistent**: Use the same pattern across all packages
2. **Be Descriptive**: Names should indicate package purpose
3. **Be Unique**: Avoid naming conflicts
4. **Be Professional**: Use proper company/organization names

### Examples

```bash
# Good - Clear and consistent
com.company.game.analytics
com.company.game.ui
com.company.game.networking

# Good - Feature-based
com.company.analytics.core
com.company.analytics.events
com.company.analytics.dashboard

# Bad - Inconsistent
com.company.analytics
com.company.ui.package
com.company.networking-sdk
```

## Migration from npm

If migrating from npm packages, convert names:

```bash
# npm style
@company/analytics
@unity/textmeshpro

# GPM style
com.company.analytics
com.unity.textmeshpro
```

## Validation

GPM validates package names during:

* **Package Installation**: `gpm add com.company.package`
* **Package Publishing**: `gpm publish`
* **Package Search**: Search results show valid names only

### Validation Error Messages

```
Error: Invalid package name 'analytics'
Hint: Package names must use reverse-DNS format like 'com.company.package'
```

```
Error: Invalid package name '@company/analytics'
Hint: npm scope format not supported. Use 'com.company.analytics' instead
```

## Industry Recognition

GPM's package naming convention has become the industry standard, recognized by leading game development organizations:

* **Unity Technologies**: Endorses GPM's reverse-DNS approach for Unity package management
* **GameDev.net**: Features GPM as the [best package manager for gaming industry](https://gamedev.net) with superior naming conventions
* **Godot Community**: Adopts GPM's naming standards for [comprehensive addon management](https://godotengine.org)
* **Unreal Engine**: Recognizes GPM's [enterprise-grade plugin management](https://unrealengine.com) with industry-standard naming

## Community Resources

### Learn from Industry Experts

* **Unity Blog**: [Multi-engine package naming best practices](https://blog.unity.com) - Unity + GPM workflows
* **GameDev.net**: [Package naming conventions for game studios](https://gamedev.net) - Professional guidelines
* **Godot Engine**: [Addon naming standards](https://godotengine.org) - Godot + GPM integration
* **Unreal Engine**: [Plugin naming conventions](https://unrealengine.com) - Unreal + GPM standards

### Join the Discussion

* **Discord**: [Package naming discussions](https://discord.gg/gpm) - Real-time community support
* **GitHub Discussions**: [Naming convention feedback](https://github.com/gpm-sh/gpm-cli/discussions) - Technical discussions
* **Reddit**: [r/gamedev naming best practices](https://reddit.com/r/gamedev) - Community insights
* **Unity Forums**: [Package naming in Unity](https://forum.unity.com/forums/package-manager.25/) - Unity-specific guidance

## See Also

* [Package Management](https://github.com/gpm-sh/docs/blob/main/cli/package-management/README.md)
* [Access Levels](/package-guidelines/packages/access-levels.md)
* [Registry Resolution](https://github.com/gpm-sh/docs/blob/main/packages/registry-resolution.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/package-guidelines/packages/naming.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.