# Naming Conventions

This page documents the naming conventions used throughout Spark. Follow these when creating custom plugins to keep everything consistent.

## File and Class Naming

| Type                  | Pattern                          | Example                            |
| --------------------- | -------------------------------- | ---------------------------------- |
| Plugin Interface      | `I{Name}Plugin`                  | `IFactionPlugin`                   |
| Plugin Implementation | `{Name}Plugin`                   | `FactionPlugin`                    |
| Database Entry        | `{Name}Entry`                    | `FactionEntry`                     |
| Nested Data           | `{Name}Data`                     | `FactionReputationData`            |
| Extension Data        | `{Feature}{Target}ExtensionData` | `CombatStatsItemExtensionData`     |
| Scene Entity          | `{Name}Entity`                   | `FactionTrackerEntity`             |
| Event                 | `{PastTense}Event`               | `ReputationChangedEvent`           |
| Command               | `{Verb}{Noun}Command`            | `ModifyReputationCommand`          |
| Command Handler       | `{Command}Handler`               | `ModifyReputationCommandHandler`   |
| Plugin Settings       | `{Plugin}PluginSettings`         | `FactionPluginSettings`            |
| Trigger Type          | `{Action}TriggerType`            | `GiveReputationTriggerType`        |
| Requirement Type      | `{Condition}RequirementType`     | `FactionReputationRequirementType` |
| Save Data             | `{Plugin}SaveData`               | `FactionSaveData`                  |
| Save Registration     | `{Plugin}SaveDataRegistration`   | `FactionSaveDataRegistration`      |
| UI Component          | `{Purpose}UI`                    | `FactionPanelUI`                   |
| Formatter Type        | `{Event}FormatterType`           | `ReputationChangedFormatterType`   |

## Assembly Definition Naming

| Type                      | Pattern                                   | Example                                |
| ------------------------- | ----------------------------------------- | -------------------------------------- |
| Runtime Assembly          | `Spark.{PluginName}`                      | `Spark.Factions`                       |
| Editor Assembly           | `Spark.{PluginName}.Editor`               | `Spark.Factions.Editor`                |
| Extension Assembly        | `Spark.{Plugin}.{Target}Extension`        | `Spark.Factions.QuestExtension`        |
| Extension Editor Assembly | `Spark.{Plugin}.{Target}Extension.Editor` | `Spark.Factions.QuestExtension.Editor` |

## Folder Structure

```
{PluginName}/
    Editor/
        Scripts/
            {EditorClasses}.cs
        {PluginName}Manifest.asset
        Spark.{PluginName}.Editor.asmdef
    Runtime/
        Scripts/
            API/
                I{PluginName}Plugin.cs
                {PluginName}Plugin.cs
            Data/
                {Name}Entry.cs
            Components/
                {Name}Entity.cs
            Events/
                {Name}Event.cs
            Commands/
                {Name}Command.cs
                {Name}CommandHandler.cs
            Persistence/
                {PluginName}SaveData.cs
                {PluginName}SaveDataRegistration.cs
        Resources/
            {PluginName}Data/
        Spark.{PluginName}.asmdef
    Extensions/
        {TargetPlugin}Extension/
            Editor/
            Runtime/
```

## Event Naming

Events use past tense to describe what happened:

* `ItemAddedEvent` (not `AddItemEvent`)
* `QuestCompletedEvent` (not `CompleteQuestEvent`)
* `LevelChangedEvent` (not `ChangeLevelEvent`)
* `ReputationChangedEvent` (not `ChangeReputationEvent`)

## Command Naming

Commands use imperative verb + noun:

* `GiveItemCommand`
* `AcceptQuestCommand`
* `ModifyReputationCommand`
* `AwardExperienceCommand`

## ID Conventions

* Entry IDs are lowercase with underscores: `iron_sword`, `quest_the_missing_merchant`
* Entry IDs are auto-generated and immutable after creation
* Plugin registration keys are lowercase: `"factions"`, `"combat"`, `"items"`
* Panel IDs are lowercase with underscores: `"inventory_panel"`, `"quest_log_panel"`

## Code Style

* `[SerializeField] private` with public getter properties for all serialized data
* PascalCase for public members, camelCase for private members
* Prefix private fields with underscore: `_instance`, `_handlers`
* One public class per file
* Use `#if UNITY_EDITOR` for editor-only code in runtime assemblies
* Use null-conditional operator (`?.`) for optional plugin access


---

# 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.sparkframework.dev/documentation/developer-guide/reference/naming-conventions.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.