World Activity System

v1.0.0

Core Concepts

Understand the fundamental architecture and components of the World Activity System.

Overview

World Activity System is built around four core concepts that work together to create dynamic world content:

Spatial Activities

Fixed-location content discovered through proximity

Temporal Activities

Time-based events that trigger automatically or conditionally

Activity Manager

Central singleton managing all activities and state

Event Scheduler

Automated scheduling with smart caching and performance optimization

Spatial Activities (Encounters)

Spatial Activities represent discoverable content at fixed locations in your world. They use a hybrid ScriptableObject + MonoBehaviour architecture.

Key Concept: Activity data is stored in a ScriptableObject asset (reusable), while placement is handled by an Anchor component in the scene (visual positioning).

Use Cases

Shrines

Prayer locations for buffs/blessings

Dungeons

Instanced combat challenges

Landmarks

Map reveals and fast-travel points

Secrets

Hidden treasures and collectibles

NPCs

Merchants, quest givers, trainers

Hazard Zones

Environmental dangers

Key Properties

PropertyDescription
Discovery RangeDistance at which player can discover the activity
Auto DiscoverWhether discovery triggers automatically on proximity
CategoryClassification (Shrine, Dungeon, Landmark, etc.)
One-Time OnlyWhether activity can only be completed once
PrerequisitesConditions that must be met before discovery

Temporal Activities (Events)

Temporal Activities are time-based or condition-triggered events that run automatically via the Event Scheduler. Unlike spatial activities, they don't require scene placement.

Event Lifecycle

Scheduled

Event is queued and waiting for trigger time

→
Pending

Trigger conditions being evaluated

→
Active

Event is running, On Activate actions executed

→
Completed

Duration expired, On Deactivate actions executed

→
Cooldown

Waiting before event can be scheduled again

Trigger Types

Interval

Triggers repeatedly at fixed time intervals

Example: Merchant spawns every 5 minutes

Time-of-Day

Triggers at specific times (Dawn, Noon, Dusk, Midnight)

Example: Night market opens at Dusk

Conditional

Triggers when GC2 conditions become true

Example: Boss spawns when all totems destroyed

OneShot

Triggers once when conditions are met, then never again

Example: Tutorial event on first dungeon discovery

Activity Manager

The WorldActivityManager is a singleton MonoBehaviour that serves as the central hub for all activity management.

Responsibilities

  • Tracking all spatial and temporal activities
  • Managing discovery state and persistence
  • Coordinating with EventScheduler
  • Providing API for GC2 Instructions
  • Handling save/load via Remember system

Architecture

┌─────────────────────────────────────────────────────┐
│              WorldActivityManager                   │
│                  (Singleton)                        │
├─────────────────────────────────────────────────────┤
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │      Activity Registry                      │   │
│  │  • SpatialActivity[] (ScriptableObjects)    │   │
│  │  • TemporalActivity[] (ScriptableObjects)   │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │      Discovery System                       │   │
│  │  • OnTriggerEnter (immediate)               │   │
│  │  • Proximity checks (periodic)              │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │      EventScheduler                         │   │
│  │  • Interval scheduling                      │   │
│  │  • Time-of-day scheduling                   │   │
│  │  • Conditional monitoring                   │   │
│  │  • Priority queue                           │   │
│  │  • Prerequisite caching                     │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
              ↓                    ↓
    ┌──────────────┐      ┌──────────────┐
    │   Spatial    │      │  Temporal    │
    │  Activities  │      │  Activities  │
    │ (Encounters) │      │   (Events)   │
    └──────────────┘      └──────────────┘
              ↓                    ↓
    ┌──────────────┐      ┌──────────────┐
    │   Anchors    │      │  Scheduler   │
    │  (Scene)     │      │  (Auto)      │
    └──────────────┘      └──────────────┘

Event Scheduler

The EventScheduler automates temporal activity execution. It evaluates triggers, manages the priority queue, and handles event lifecycle transitions.

Performance: The scheduler uses intelligent caching for conditional events, achieving 80-95% cache hit rates. Monitor via Debug Window.

Key Features

Priority Queue

Events sorted by priority (0.0-1.0), higher priority triggers first

Smart Caching

Conditional prerequisites cached for 80%+ hit rate

Conflict Resolution

Incompatible events list prevents conflicting events from running simultaneously

Time Integration

Works with Cozy Weather or custom time providers

Debug Tools

Timeline, history, and performance monitoring in Editor