Time System Technical Specification - wwestlake/Steamforge GitHub Wiki

// Time System Technical Specification

Time System Technical Specification

Overview

This document defines the technical architecture and requirements for the in-game Time System in Steamforge. It establishes a scalable, modular framework for simulating time passage, managing time-based events, and supporting multiple map persistence using UGameInstance.

Components

1. FGameDateTime

A custom struct that tracks all in-world time information.

Fields

  • int32 Year
  • int32 Month
  • int32 Day
  • int32 Hour
  • int32 Minute
  • int32 Second
  • int32 DayOfWeek

Constants

  • HoursPerDay = 24
  • MinutesPerHour = 60
  • DaysPerWeek = 6
  • DaysPerMonth = 30
  • MonthsPerYear = 8
  • WeeksPerMonth = 5
  • SeasonsPerYear = 4

Functions

  • void AdvanceTime(float GameSeconds)
  • void AdvanceOneDay()
  • FString GetFormattedTime() const
  • FString ToString() const

2. UTimeComponent

An ActorComponent that handles ticking and advancing game time.

Fields

  • float TimeScale = 72.0f (default, adjustable)
  • Reference to UGameInstance to pull/push canonical time state

Responsibilities

  • Advance time using DeltaSeconds * TimeScale
  • Broadcast changes (delegates or direct notification)
  • Sync with FGameDateTime in UGameInstance

3. USteamforgeGameInstance

Subclass of UGameInstance to hold canonical FGameDateTime.

Responsibilities

  • Persistent time state across maps
  • Save/load compatibility
  • Central source of truth for all time systems

4. UTimeEventComponent

Optional component that manages time-based events.

Responsibilities

  • Register and trigger events
  • Track system and soft events

Data Sources

  • UDataTable* BuiltInEventTable — Static, read-only events
  • TArray<FSoftTimeEvent> — Runtime-generated, saveable events

Functions

  • void LoadBuiltInEvents()
  • void LoadSoftEventsFromSave(const USteamforgeSaveGame*)
  • void RegisterSoftEvent(const FSoftTimeEvent&)
  • void CheckEvents(const FGameDateTime&)

Data Structures

FTimeEventRow (Static Events)

USTRUCT(BlueprintType)
struct FTimeEventRow : public FTableRowBase
{
    GENERATED_BODY();

    FName EventID;
    int32 Hour;
    int32 Minute;
    int32 DayOfMonth;
    bool bRepeatsDaily;
    // Optional metadata fields
};

FSoftTimeEvent (Dynamic Events)

USTRUCT(BlueprintType)
struct FSoftTimeEvent
{
    GENERATED_BODY();

    FName EventID;
    FGameDateTime TargetTime;
    FText Description;
    // Optional: Creator info, event tags, etc.
};

Multi-Map Support

Method: GameInstance-Based Persistence

  • Time state is stored in USteamforgeGameInstance
  • On map load, UTimeComponent queries and syncs time
  • Works for single-player and non-seamless world travel
  • Future expansion to network replication is modular

Next Steps

  • Implement FGameDateTime
  • Create UTimeComponent
  • Extend USteamforgeGameInstance
  • Add UTimeEventComponent
  • Wire into save/load pipeline

This architecture is extensible, componentized, and stable for both design-time and runtime interaction.