Getting Started

9 min read

Install Scylla Core, wire the bootstrap into a scene, and get the framework running and logging in a couple of minutes.

This page takes you from a fresh Unity project to a running Scylla framework: import the package, let the Setup Wizard wire up a scene, press Play, and start logging, sending events, and reading pause-aware time. Plan on about two minutes for the install and a few more to try the day-one features.

Installation

You install Scylla Core through Unity’s built-in Package Manager, the same way you import any Asset Store package. You need Unity 6.3 (6000.3) or later and a URP project; the framework itself is render-pipeline-neutral, so HDRP works too for the modules that touch rendering.

  1. Open your project and choose Window > Package Manager.
  2. Switch the Packages dropdown at the top-left to My Assets.
  3. Sign in with the Unity account you used to buy Scylla Core, if you are not already signed in.
  4. Find Scylla Core in the list. If you do not see it, click Refresh (the circular arrow, top-right).
  5. Select it, click Download, then Import. Leave everything checked in the import dialog and click Import again.
  6. Wait for Unity to copy the files into Assets/Scylla/Core/ and finish compiling.

When the compile finishes, a new Scylla menu appears in the menu bar between Window and Help. That menu is your sign the import landed cleanly: it hosts the Getting Started window, the Setup Wizard, the per-module wizards, and the editor tools.

Open Scylla’s own Getting Started window for an overview of the framework’s package dependencies. It shows which required and optional packages are present and lets you install any that are missing, so you do not have to track them down in the Package Manager yourself.

If you also want the demo scenes, import the optional Demos sample from the package’s page in the Package Manager. The demos are self-contained and safe to delete later.

Setup and Configuration

The framework starts from one component, ScyllaBootstrap, that lives on a single GameObject in your first-loaded scene. You can create that by hand, but the Setup Wizard does it for you and registers everything in a single undo step, so you can back out with one Ctrl+Z (Cmd+Z on macOS).

  1. Open the scene that loads first when your game runs (usually your boot or splash scene).
  2. Choose Scylla > Setup Wizard… (Ctrl+Shift+W, or Cmd+Shift+W on macOS).
  3. Step through Welcome, Scylla Core, Configuration, Modules, and Review. The defaults are right for almost every project, so you can click Next through them unless you want to change the Resources path or the initialization delay.
  4. Click Finish. The wizard creates a GameObject named Scylla with the ScyllaBootstrap component, plus a ScyllaCoreConfiguration asset under Assets/Resources/Scylla/.

Select the Scylla GameObject and you will see the bootstrap in the Inspector with four configuration slots: Core, Logger, Time, and Event. Each slot takes an optional ScriptableObject asset. When you leave a slot empty, the framework falls back to a Resources/Config/ asset of the matching name, and failing that to its compiled defaults, so an empty slot is a perfectly good starting point.

When you do want to tune something, the ScyllaCoreConfiguration asset the wizard created is the place to do it. These are the fields you are most likely to touch:

FieldWhat it controlsDefault
Initialization DelaySeconds between Awake and the moment your modules initialize. The gap exists so code in Start can register modules dynamically before the framework scans for them.1.0
Debug Draw Max CommandsUsed for the Debug Draw utils. Determines the cap on the per-frame debug-draw command queue.4096

Every Scylla config asset (the Core one and every module’s) also carries a Config Files foldout that controls whether runtime JSON overrides load. It is a two-level gate, so the runtime only reads an override when both levels agree. The foldout shows a Global group (the framework-wide master switch, which physically lives on the Core configuration) and a per-asset group (just this Core or module config):

Foldout fieldScopeWhat it controlsDefault
Config Files in DBGGlobalMaster switch for loading JSON overrides in development builds (Editor and Development Builds).false
Config Files in PRDGlobalMaster switch for loading JSON overrides in production (non-development) builds.false
Config File in DBGThis configWhether this specific asset reads its JSON override in development builds, once the global switch is on.true
Config File in PRDThis configWhether this specific asset reads its JSON override in production builds, once the global switch is on.true

The per-asset switches are on by default, so each config is ready to accept overrides; the global master switches are off by default, so a fresh project ignores JSON entirely until you opt in. To let players edit config files in a shipped game, turn on the Global Config Files in PRD switch; the per-asset Config File in PRD is already on. The configuration asset itself is only the project-defaults layer, and the full two-level gate plus the four-tier fallback (User Documents, Application, Unity asset, compiled defaults) is covered in Configuration.

Usage

Press Play. You do not need to write any code yet: the bootstrap brings up logging, time, and the event bus, then runs every installed module through its lifecycle and prints a short startup sequence to the Console. Seeing it reach Framework initialized is how you confirm the install is good.

[System] ScyllaBootstrap initializing...
[System] Framework initialized

From here, the handful of things you will reach for on day one are logging, events, pause-aware time, and a safe way to run code once the framework is up. Everything below assumes the framework is running.

Wait for the framework, then run your code

The framework finishes initializing a moment after Start (that is what the initialization delay is for), so you cannot assume it is ready inside your own Awake or Start. Instead, hand your startup code to RunWhenReady. It fires immediately if the framework is already up, or queues your callback for the moment it becomes ready:

using UnityEngine;
using Scylla.Core;
using Scylla.Core.Scenes;

/* Your own game entry-point class: drop it on a GameObject in the boot scene. */
public sealed class GameStartup : MonoBehaviour
{
    private void Start()
    {
        /* RunWhenReady is your safe gate for "do this once the framework is up".
           The optional priority orders multiple ready-handlers; Medium is the default. */
        ScyllaCore.Instance.RunWhenReady(() =>
        {
            /* Every module is fully enabled by the time you get here, so it's
               safe to talk to them and to publish events. This handler is your
               real game startup: kick off the things that needed the framework. */
            Log.Info("Scylla is up", LogCategory.Game);

            /* Now that Scylla is initialized, engage your custom game logic. For
               example leaving a boot scene and bringing up the main menu. Load
               through ScyllaSceneManager so the framework persists across the
               switch and the load runs through the managed pipeline (scene events,
               transition hygiene, progress). See the Scene Manager page. */
            ScyllaSceneManager.Instance.LoadSceneAsync("MainMenu");
        });
    }
}

Log with categories

Route your messages through the static Log instead of Debug.Log. You get one call site, multiple sinks (the Unity console and a log file are wired up for you at startup), and a category you can filter on at runtime. Trace and Debug calls compile out of release builds, so you can leave them in.

/* Level plus message. The category shows as a prefix and lets you filter later. */
Log.Info("Player spawned", LogCategory.Game);
Log.Warning("Save file missing, starting fresh", LogCategory.File);

/* Pick the category up front. Switching the receiver to "only errors from Game"
   is one assignment when your categories are consistent. */
Log.FilterLevel = LogLevel.Info;

Send and receive events

When one system needs to tell the rest of the game that something happened (damage taken, checkpoint reached, quest advanced) without caring who is listening, publish an event. Define a class that inherits from ScyllaEvent, publish instances with ScyllaEvents.Publish, and listen with ScyllaEvents.Listen. Here is an example for an event that fires when a player’s health changes:

using Scylla.Core;
using Scylla.Core.Events;

/* Your event type. Add typed, init-only payload fields so the payload is
   effectively immutable once published. */
public sealed class PlayerHealthChangedEvent : ScyllaEvent
{
    public int OldHealth { get; init; }
    public int NewHealth { get; init; }
}

/* Publish from wherever health changes. Every subscriber receives it synchronously. */
ScyllaEvents.Publish(new PlayerHealthChangedEvent { OldHealth = 100, NewHealth = 80 });

/* Listen from anywhere. Store the returned subscription and dispose it when you
   stop listening, or the listener outlives its usefulness. */
ScyllaEventSubscription subscription = ScyllaEvents.Listen<PlayerHealthChangedEvent>(
    subscriber: this,
    handler:    evt => Log.Info($"Health: {evt.OldHealth} -> {evt.NewHealth}", LogCategory.Game));

/* Later, in OnDestroy or OnDisable: */
subscription.Dispose();

Read pause-aware time

Read gameplay time from ScyllaTime instead of UnityEngine.Time. DeltaTime returns 0 while the framework is paused and scales with slow-motion or fast-forward, so pause and time-scale just work without you threading a flag through every system. UnscaledDeltaTime keeps running during pause for UI and tooling.

using Scylla.Core.Time;

/* Pause-aware: freezes at 0 when paused, scales with the active time scale. */
float dt = ScyllaTime.Instance.DeltaTime;

/* Pause and slow-motion through one knob. */
ScyllaTime.Instance.Pause();
ScyllaTime.Instance.Resume();
ScyllaTime.Instance.SetSlowMotion(scale: 0.3f);

That is the day-one surface. When you are ready to go deeper, here is where to look:

Troubleshooting

A few things commonly trip up a first install. Each has a quick fix.

Updated on July 9, 2026