v2.1.0 · documentation

Common Game System

A headless C# foundation framework for Unity 6.3 LTS PC single-player projects. Headless means code, not scenes — after import, your Hierarchy does not change. Twenty-three services — save/load, input, scene flow, audio, UI panels, tweening, state machines, and more — all start from one automatic Bootstrap.Run(). No DI container, no scene singletons, no setup code in your game scripts.

Unity 6.3 LTS23 services7 assemblies0 dependenciesIL2CPP-readyAny render pipelineAI-ready
Documentation wiki — every service, step by step →

Start here

Getting started in 6 steps

CGS is code, not scenes. After import, nothing appears in your scene Hierarchy — the framework works invisibly in the background. The visible parts are the Welcome window and the demo scene. Here is the fastest tour:

  1. 1Import Common Game System from the Unity Asset Store (Window > Package Manager > My Assets).
  2. 2The Welcome window opens by itself. If you close it, reopen it any time via Tools > Common Game System > Welcome (also under Window > Common Game System > Welcome).
  3. 3Click Open Demo Scene at the top of the Welcome window. The MotionLab scene opens — no setup required.
  4. 4Press Play. A tween easing gallery animates, scheduler timers count, and a tween-sequence showcase plays.
  5. 5Drag the Time Scale slider to 0. Gameplay freezes mid-motion, while the UI clock spinner keeps turning on its own clock.
  6. 6Open the Console window. The line bootstrap complete (v2.1.0, 23 services) confirms that every service started.

Prefer reading offline? A paginated PDF manual with a table of contents and annotated screenshots ships inside the package at Documentation/CGS-Manual.pdf.

Overview

What you get

Engine

Unity 6.3 LTS (6000.3.11f1) · .NET Standard 2.1

Services

23 — all started by one automatic bootstrap before your first script runs

Runtime assemblies

7 — Core (18 services, zero package references) + Input / UI / Localization / Assets / AddressableScene / Bootstrap. Remove an unused Unity package (Input System / uGUI / Addressables) and the dependent assemblies exclude themselves; Bootstrap falls back instead of breaking your build

Third-party deps

0 — only the Unity engine plus first-party Addressables / Input System / uGUI, each optional since 2.0.0

Scripting backend

Mono and IL2CPP. The framework ships its own preserve rules ([Preserve] + a link.xml per module). CI builds an IL2CPP standalone player on every push

Render pipeline

Works with URP, HDRP, Built-in, or a custom pipeline — the framework contains no rendering code

Tests

2,600+ automated tests ship inside the package, hidden by default. Import them with one click from the Welcome window

Demo scene

MotionLab.unity — open it and press Play, no setup. A tween easing gallery, tween sequences, scheduler timers, and a Time Scale slider that freezes gameplay while the UI clock keeps moving

Samples

6 importable from the Welcome window — 3 runnable scenes (UI Panel Stack · Save/Load + Seeded Random · Command Console) and 3 script templates (Scene Flow · Localization · RPG Starter)

Manual & docs

A paginated PDF manual with a table of contents and annotated screenshots (Documentation/CGS-Manual.pdf), plus a plain-English reference page per service (Documentation/Modules/)

Editor tooling

Welcome window (auto-opens once per package version; reopen via Tools > Common Game System > Welcome) + runtime Service Debugger

License

Proprietary — Unity Asset Store EULA

Platforms

PC (Windows / macOS / Linux), single-player

Quick Start

Your first script — 20 lines

The framework boots itself — there is no initialization call to make. The script below compiles exactly as pasted; drop it on any GameObject in your first scene.

using CommonGameSystem.Core;
using UnityEngine;

[DefaultExecutionOrder(100)] // see "Consumer conventions" below
public sealed class MyGame : MonoBehaviour
{
    [SerializeField] private AudioClip mainTheme; // assign any music clip in the Inspector
    private IAudioService _audio;
    private IScheduler _scheduler;

    private void Start()
    {
        // Bootstrap already registered all 23 services before Start() ran.
        _audio     = ServiceLocator.Resolve<IAudioService>();
        _scheduler = ServiceLocator.Resolve<IScheduler>();

        _audio.PlayMusic(mainTheme, fadeInSeconds: 2f);
        _scheduler.After(3f, () => Debug.Log("Three seconds of game time later."));
    }
}

That's it — all 23 services were registered before your Start() ran.

Good habits

Consumer conventions

  • Add [DefaultExecutionOrder(100)] to any script that calls ServiceLocator.Resolve<T>(). The framework boots before every scene script; the attribute makes that ordering explicit instead of lucky.
  • Resolve once and cache the instance. Resolve<T>() is a dictionary lookup each time — fine in Start(), wasteful in Update().
  • Building with IL2CPP? List your own settings, event, and save data types in a link.xml file in your project, so Unity's code stripping keeps them.
  • Switching a service off is one line: ServiceLocator.Replace<IAudioService>(new NullAudio()). Every service has a Null (no-op) implementation that honors the same contract.

Reference

The 23 services

Logger

01
ILogger

Categorized logging with build-tiered levels and category filters. Thread-safe.

Object Pool

02
IObjectPoolService

Prefab pooling with an IPoolable lifecycle — per-category pools, prewarm, automatic return.

Time Service

03
ITimeService

Per-clock time, pause, and slow motion — the Gameplay, UI, and Background clocks run independently.

Event Bus

04
IEventBus

Type-safe publish/subscribe for decoupled, game-wide messaging.

Save / Load

05
ISaveService

JSON save slots with safe atomic writes and versioned migration hooks.

Configuration

06
IConfiguration

Typed settings groups (audio / graphics / input) that persist the moment you set them.

Input Key Map

07
IInputKeyMapSource

Owns the Input Actions asset and stores each player's key rebindings across sessions.

Input

08
IInputService

Input System wrapper — action-map contexts and key rebinding.

Audio

09
IAudioService

Music / SFX / voice channels over an AudioMixer — pooled sources, fades, volume binding.

UI Panel Stack

10
IPanelStack

Panel push/pop with modals and full gamepad / keyboard focus handling.

Scene Flow

11
ISceneService

Async scene loading with a loading screen and cancel, plus additive load/unload.

Localization

12
ILocalizationService

Key-to-string lookup with a runtime language switch — bound texts update live, no restart.

Achievements / Stats

13
IAchievementService

Local stats and achievements with threshold auto-unlock, persisted through the save service.

Scheduler / Timer

14
IScheduler

After / Every / NextFrame timers plus run-on-main-thread dispatch — pause and slow-motion aware.

Tween / Easing

15
ITweenService

Pause-aware value tweening with 31 easing curves and typed To/From overloads.

Asset Provider

16
IAssetProvider

Addressables-backed async loading with reference counting and scope-bound auto-unload.

Seeded Random

17
IRandomService

Deterministic seeded RNG with named, forkable streams and save/restore snapshots.

State Machine (FSM)

18
IStateMachineService

Factory for flat finite-state machines over your own context type, with guarded transitions.

Pushdown State Stack

19
IPushdownStackService

A stack of resumable game-state scopes — dialogue over gameplay, menu back-stacks.

Tween Sequencing

20
ITweenSequenceService

Ordered and parallel tween timelines over the tween service, built with a fluent builder.

Addressable Scene

21
IAddressableSceneService

Additive scene load/unload from the Addressables catalog, with per-key reference counting.

Deferred Event Queue

22
IDeferredBus

Queue an event now, publish it at a Flush() you choose — for example, outside a physics callback.

Command Registry

23
ICommandRegistry

Runtime command registry — register, tokenize, execute, history, autocomplete. The console UI is yours.

Every service has a plain-English reference page inside the package (Documentation/Modules/) and a Null (no-op) implementation you can swap in with one line.

How it works

Architecture in 60 seconds

  • No DI container. A static ServiceLocator maps each service interface to its instance.
  • Your code: var audio = ServiceLocator.Resolve<IAudioService>() — resolve once, cache the instance, never resolve inside Update().
  • Framework code: Bootstrap constructs every service and passes dependencies through constructors, so each implementation can be tested on its own.
  • Seven runtime assemblies: Core holds 18 services with zero package references; Input, UI, Localization, Assets, AddressableScene, and Bootstrap layer on top. Remove an unused Unity package and the dependent assemblies exclude themselves — Bootstrap skips their registration (the UI panel stack degrades to a no-op) instead of breaking your build.
  • Every service can be replaced or switched off. Each one ships a Null (no-op) implementation: ServiceLocator.Replace<IAudioService>(new NullAudio()) mutes audio game-wide with zero caller changes.
  • AI-ready: ships an AI assistant spec (Documentation/AI/AGENT.md) plus five task skills for Claude Code, Cursor, and GitHub Copilot.

Releases

Changelog

v2.1.02026-08-03

The newcomer release — documentation and packaging rebuilt so someone who has never seen CGS is productive in minutes. Every runtime folder and reference doc now carries a plain English name (Bootstrap, SaveLoad, Tween, …); the old internal number prefixes are gone from folders and file names. A visible demo scene ships at Assets/CommonGameSystem.Core/Demo/MotionLab.unity — open it and press Play, no setup. It shows a tween easing gallery, a tween-sequence showcase, scheduler timers, and a Time Scale slider that freezes gameplay while the UI clock keeps moving; it needs only the built-in uGUI package. The Welcome window was rebuilt around "Try the demo — 60 seconds": it auto-opens once per package version, is reachable via both Tools > Common Game System > Welcome and Window > Common Game System > Welcome, and offers one-click sample import, quick links (PDF manual / documentation / changelog / module reference), and collapsed environment checks. Samples are now six — UI Panel Stack, Save/Load + Seeded Random, and Command Console are runnable scenes; Scene Flow, Localization, and RPG Starter are step-by-step script templates. (Motion Lab graduated from sample to always-visible demo.) A paginated PDF manual with a table of contents and annotated screenshots ships at Documentation/CGS-Manual.pdf; AI assistant files moved to Documentation/AI/. The 2,600+ automated tests still ship inside the package but now stay hidden until you import them with one click from the Welcome window — they no longer compile into every buyer project. Still 23 services and 0 third-party dependencies.

v2.0.02026-07-30

The seven-assembly release. The single CommonGameSystem.Core runtime assembly is now seven — Core (18 services with zero package dependencies, plus the pure UI contracts), Input, UI, Localization, Assets, AddressableScene, Bootstrap — so you reference only what you actually use. Breaking only for projects with their own asmdef, and only in the references list: no source changes, namespaces are all still CommonGameSystem.Core, and Assembly-CSharp projects are unaffected. Removing an unused UPM package (Addressables / Input System / UGUI) is now supported: dependent assemblies — the shipped test and sample assemblies included — self-exclude via defineConstraints, and Bootstrap skips their registration (the UI Panel Stack falls back to NullPanelStack). All three packages still install by default. link.xml is now per-module, so each optional assembly's IL2CPP preserve entries leave with it. Scene-load cancel got an honest contract (breaking behaviour): the old "activation blocked, new-scene OnEnable never runs" promise was unimplementable — Unity stalls the entire AsyncOperation queue behind a non-activated load, so one cancel froze every later scene load for the life of the process. Now a cancel before the backend load is issued is a true cancel; after it, the scene change completes and SceneLoadCanceled is published before activation, while subscribers in the outgoing scene still exist. Fixes: editor play-exit teardown ran as a silent no-op (the registry cleared before the LIFO Dispose chain, skipping achievement flush-to-disk and asset-handle release); SFX auto-release ran on scaled game time while audio plays in real time (now unscaled and pitch-aware); TimeServiceTicker now declares [DefaultExecutionOrder(-100)], so your scripts no longer race it for the frame's delta; IConfiguration.Set<T> stores a private copy instead of clamping your instance in place. New: InputServiceOptions.AlwaysEnabledMaps (keep a UI/Debug action map live across context switches), IPanelVisual (opt-in panel fade transitions plus the modal backdrop the options always promised), GraphicsSettingsApplier (quality / resolution / fullscreen / vSync / frame cap now actually reach Unity), ISaveStorageBackend (the save medium is injectable — encrypted saves, custom locations, Steam Cloud, with a new Steam recipe doc), FileLogger (opt-in rotating file log that survives a relaunch), and deferred settings now also flush on focus loss. Still 23 services and 0 third-party dependencies; 2,665 automated EditMode tests.

v1.15.02026-07-25

The initial published release. Three Core services were added since the unpublished 1.14.0 build (20 → 23), wired by the same single Bootstrap.Run(): Addressable Scene (IAddressableSceneService — async additive scene load/unload from the Addressables catalog, per-key refcount, never-throw runtime data), Deferred Event Queue (IDeferredBus — capture an event now and publish it later at a chosen Flush() point), and Command Registry (ICommandRegistry — a runtime command nucleus with register / tokenize / execute, history and prefix autocomplete; the in-game console UI stays yours). Samples grew to 7 importable, 4 of them fully assembled runnable scenes: Motion Lab (8-ease tween gallery, waypoint sequencing, and the per-Clock money shot — gameplay TimeScale 0 freezes the gallery while the UI spinner keeps moving), Save/Load + Seeded Random (after Load, the next three seeded rolls exactly match the prediction armed at Save), M25 Command Console (working in-game dev console with history and autocomplete), plus an RPG Starter code template. New editor tooling under Tools ▸ Common Game System: a Welcome / Quick Start window (environment checks, one-click sample import) and a runtime Service Debugger (live service registry, per-Clock time scales, active tween/FSM/audio/command stats). Fixes: persisted audio settings now apply at boot (mixer early-init race), the UI sample's volume/mute controls act immediately and now ship a Canon in D BGM loop (public-domain composition, first-party synthesized recording) so you can hear them work, panel-navigation NullReferenceException, the "No cameras rendering" watermark, and a play-exit teardown exception. Still 0 third-party dependencies; IL2CPP-ready; URP-agnostic; 2,550 automated EditMode tests.

v1.14.02026-06-14

Submitted for review; never published. This build was sent to the Unity Asset Store on 2026-06-15 but was never reviewed, so it never reached anyone — it is kept here as part of the engineering record, not as a version you could have installed. 20 production services wired by a single Bootstrap.Run() — Service Locator, Logger, Event Bus, Save/Load, Configuration, Input, Time, Object Pool, Audio, UI Panel Stack, Scene Flow (+additive), Localization, Achievements/Stats, Scheduler, Tween, Asset Provider, Random, FSM, Pushdown Stack, Tween Sequencing. 0 third-party dependencies, IL2CPP-ready, URP-agnostic, AI-ready (AGENT.md + 5 task skills). Versions prior to 1.14.0 were internal development milestones.

Full per-version engineering changelog ships inside the package (CHANGELOG.md).

Legal

License

Common Game System is proprietary software distributed exclusively through the Unity Asset Store. Use is governed by the Unity Asset Store EULA.

  • ✓ Use in commercial & non-commercial games shipped on Unity-supported platforms.
  • ✓ Modify consumer-side code that calls the framework's public APIs.
  • ✗ Re-publishing the framework (or substantial derivatives) on any asset marketplace.
  • ✗ Removing copyright / license notices or sub-licensing the source.

0 third-party runtime dependencies; bundled Unity packages use the Unity Companion License (see THIRD-PARTY-NOTICES.md). Copyright © 2026 JoGyoungJun. All Rights Reserved.

Support

Get help

Questions or support requests:yoop80075@gmail.com· or the Asset Store publisher Q&A tab on the package page.