Skip to content

LoL Gameplay Kit — Documentation

LoL Engine is the plumbing. The Gameplay Kit is the grammar.

One page per module lands here as the module ships (part of the definition of done).

Release 0.1.0 (Tier 1)

Module Page Milestone
Core (contracts, config) this page M0 ✅
WorldFlags worldflags.md M1 ✅
Calendar calendar.md M1 ✅
Items items.md M2 ✅
Tooltip (UI) tooltip.md M2 ✅
Interaction interaction.md M2 ✅
Contracts contracts.md M3 ✅
Deduction deduction.md M3 ✅

The four contracts

Every module obeys:

  1. Save — a versioned GameplayKitSaveData domain (gameplaykit.<module>), registered with ISaveSystem only when the module is enabled; migrations from v1.
  2. RNG — draws only from IRngService named streams (names reserved in GameplayKitRngStreams); UnityEngine.Random is banned and guard-tested.
  3. Events — typed pooled GameEvents outward; no hard sibling references where an event suffices.
  4. Config — ScriptableObject tuning; LocString for anything player-facing.

Getting started

  1. Add LoL Engine and the Kit to Packages/manifest.json (both lines — git deps don't resolve transitively; see README).
  2. Create a GameplayKitConfig asset (Create → LoLGameplayKit), toggle the modules you use, and place it in a Resources folder (asset name GameplayKitConfig). Modules with their own config (e.g. CalendarConfig) also live in Resources.
  3. That's it — registration is automatic. Each module ships an IServiceRegistrar that the engine's initializer discovers by assembly scan, constructs parameterlessly, and runs after all engine services are up. Note: the engine does not call Initialize/Shutdown on externally registered services; the Kit's registrars initialize their own services.

Sample Scenes

Playable demos that live entirely inside the package (Assets/GameplayKit/Samples/), so they work in a brand-new project that imports only the package — no engine setup, no Kit setup. Open any scene and enter Play Mode. Each scene shows an on-screen instructions panel (a "What this demonstrates" / "Try" card, matching LoLEngine's own samples); for deeper detail, watch the Console for each sample's LogInstructions() banner, or use component Context Menus.

Self-containment has three layers, mirroring LoLEngine's own Samples:

  1. Engine bootstrap — every scene carries a LoLEngineBootstrap GameObject (ImprovedGameInitializer + Samples/Content/Configs/KitSamplesServiceConfiguration, which enables only events, object pool, time, and RNG). Engine initialization is asynchronous, so sample scripts yield on SampleEngineWait.UntilReady() before resolving services or calling EventStartListening (which throws pre-initialization).
  2. Kit configuration — Samples/Content/Resources/ holds the five Resources-loaded catalogs (GameplayKitConfig, CalendarConfig, ItemDatabase, ContractCatalog, DeductionMatrix). Resources.Load searches package Resources folders, so the Kit registrars find them with zero setup. If your game defines its own GameplayKitConfig in a Resources folder, remove the samples' copy (or the whole Samples/ folder) to avoid the ambiguity.
  3. Demo content — prefabs under Samples/Prefabs/, items/contracts/deduction assets under Samples/Content/.
Scene What it demonstrates
Samples/Scenes/KitShowcase.unity Integrated console-driven modules (WorldFlags, Calendar, Items, Contracts, Deduction) plus a small calendar HUD (day/phase + Next Phase / Next Day). Cross-module story: advance days to expire a contract deadline; complete a contract and inspect reward flags in Tools → LoLGameplayKit → World Flags. Also carries TooltipSample for the headless Show/Hide path (console only — no tooltip canvas in this scene; use TooltipDemo for the uGUI skin).
Samples/Scenes/InteractionDemo.unity Movable player (SamplePlayer prefab) with InteractionDetectorComponent, facing-origin cone, and 4 interactables. WASD move, E interact; focus tint + verb label.
Samples/Scenes/TooltipDemo.unity uGUI tooltip panel (TooltipPanel prefab) + hoverable item slots wired to demo ItemDefinitions. Hover for rarity-tinted tooltips; TooltipSample keys for scripted Show/Hide.

The host project's Assets/Scenes/KitDev.unity stays as an empty URP 2D sandbox (dev-only, not shipped). Rebuild everything via Tools → LoLGameplayKit → Build Sample Scenes.