# Welcome

This guide is for programmers who want to extend Spark with custom plugins, new database entry types, events, commands, and editor tooling. If you are looking to build games using Spark's existing visual tools without writing code, see the [User Guide](/documentation/user-guide/welcome.md) instead.

## Who This Is For

You should read this guide if you want to:

* Create your own Spark plugins
* Define custom database entry types
* Add extension data to existing entry types
* Write custom triggers, requirements, or rules
* Implement custom commands and event handlers
* Build custom editor tabs and property drawers
* Integrate Spark with networking middleware
* Understand Spark's architecture for debugging or optimization

## Prerequisites

* Familiarity with C# and Unity development
* Basic understanding of ScriptableObjects, MonoBehaviours, and Unity's component model
* Spark Core installed in your project

## Architecture at a Glance

Spark is built on four pillars:

1. **Spark Service Locator** (`Spark.cs`): A static registry where plugins register themselves and can be retrieved by interface type. This is how plugins find each other without hard dependencies.
2. **SparkDatabaseRegistry**: A runtime cache of all `SparkDatabaseEntry` ScriptableObjects. Entries are loaded from `Resources/` folders at startup and indexed by ID and type for O(1) lookups.
3. **SparkEventBus**: A priority-based publish/subscribe event bus. Plugins communicate by publishing events and subscribing to events from other plugins. No direct references needed.
4. **SparkEntityRegistry**: A runtime registry of all `SparkEntity` components in the scene. Provides O(1) lookups by instance ID, entity ID, GameObject, or collider.

Data flows through the framework in a consistent pattern:

```
Input -> Command -> Handler -> State Change -> Event -> Subscribers -> UI Update
```

A player action triggers a command. The command handler validates and executes the action, then publishes an event. Other systems subscribe to that event and react accordingly (update UI, play sounds, check quest objectives, etc.).

## Recommended Reading Order

If you are new to Spark development, read these sections in order:

1. [Architecture Deep Dive](/documentation/developer-guide/core-systems/architecture.md) for a thorough understanding of each pillar
2. [Creating Your First Plugin](/documentation/developer-guide/creating-your-first-plugin.md) for a hands-on walkthrough
3. [Database Entries](/documentation/developer-guide/core-systems/database-entries.md) to learn how to define custom data types
4. [Extensions](/documentation/developer-guide/core-systems/extensions.md) to learn how plugins add data to other plugins
5. [Event System](/documentation/developer-guide/core-systems/event-system.md) and [Command System](/documentation/developer-guide/core-systems/command-system.md) for inter-plugin communication
6. [Entity System](/documentation/developer-guide/core-systems/entity-system.md) for scene-level integration

After that, read whichever sections are relevant to what you are building.

## Community Plugins

The Spark community has already created and released custom plugins without any official developer documentation. This guide aims to make that process much easier. If you build something, consider sharing it with the community.

## Conventions Used in This Guide

* Code examples use C# and target Unity 6.2+.
* `Spark.GetPlugin<T>()` calls always include null checks in production code. Examples may omit them for brevity, but you should always guard against null in real implementations.
* Assembly definition names follow the pattern `Spark.YourPluginName`.
* File paths are relative to your plugin's root folder unless stated otherwise.


---

# 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/welcome.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.