> For the complete documentation index, see [llms.txt](https://docs.sparkframework.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sparkframework.dev/documentation/developer-guide/welcome.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.sparkframework.dev/documentation/developer-guide/welcome.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.