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 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 for a thorough understanding of each pillar

2. Creating Your First Plugin for a hands-on walkthrough

3. Database Entries to learn how to define custom data types

4. Extensions to learn how plugins add data to other plugins

5. Event System and Command System for inter-plugin communication

6. Entity System 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.