Skip to content

Game.PSI.Telemetry

Assembly:
Namespace: Game.PSI

Type: static class

Base: none

Summary:
Telemetry is a static helper used by the game to collect and send telemetry (analytics) events to the platform backend (via PlatformManager). It defines payload structs for events, maintains a play session state, and exposes methods to emit telemetry for hardware, language, graphics settings, gameplay events (achievements, milestones, policies, building placements, chirper messages, city stats, panels opened/closed, idle time, etc.), installed mods and DLCs, and session open/close. Many methods are annotated with a TelemetryEvent attribute which maps the method to an event name and payload type.

Fields

  • private struct HardwarePayload
    Contains fields sent for the "hardware" event: os_version, ram, gfx_memory, cpucount, cpu_model, gpu_model. Used by Hardware().

  • private struct LanguagePayload
    Contains os_language and game_language used by Language().

  • private struct GraphicsSettingsPayload
    Contains display_mode, resolution, graphics_quality used by GraphicsSettings().

  • private struct AchievementPayload
    Contains playthrough_id, achievement_name, achievement_number used by AchievementUnlocked().

  • private struct TutorialEventPayload
    Contains playthrough_id and advice_followed used by TutorialEvent().

  • private struct MilestoneUnlockedPayload
    Contains playthrough_id, milestone_index, ingame_days used by MilestoneUnlocked().

  • private struct DevNodePurchasedPayload
    Contains playthrough_id, dev_node_name, node_type, tier_id used by DevNodePurchased().

  • private struct ControlInputPayload
    Contains playthrough_id and control_scheme used by ControlSchemeChanged().

  • private struct PanelClosedPayload
    Contains playthrough_id, panel_name, time_spent used by PanelClosed().

  • private struct CityStatsPayload
    Contains many city statistics (playthrough_id, map_id, n_buildings, population, happiness, ingame_days, map_tiles, resource_output, tagged_citizens, cash_balance, cash_income) used by CityStats().

  • private struct ChirperPayload
    Contains playthrough_id, message_type, likes used by Chirp().

  • private struct BuildingPlacedPayload
    Contains playthrough_id, map_id, building_id, type, building_level, coordinates, origin used by PlaceBuilding().

  • private struct PolicyPayload
    Contains playthrough_id, policy_id, policy_category, policy_range used by Policy().

  • private struct InputIdleEndPayload
    Contains playthrough_id, simulation_speed_start, simulation_speed_end, duration used by InputIdleEnd().

  • private struct OpenSessionPayload
    Contains session open metadata used by OpenSession().

  • private struct CloseSessionPayload
    Contains session close metadata used by CloseSession().

  • private struct ModUsedPayload (and nested Mod struct)
    Describes active mods (name, id, tags) used by ModsUsed().

  • private struct DlcPayload (and nested Dlc struct)
    Describes installed DLCs (name and platform id) used by DlcsInstalled().

  • private struct Session
    Internal session state (guid, start times, panel time bookkeeping, idle tracking and helper methods). Managed as a single static instance s_Session.

  • private static ILog log
    Logger used for warnings and debug messages.

  • private const string kHardwareEvent, kLanguageEvent, kGraphicsSettings, ... etc (many constants)
    String constants representing telemetry event names used across the class.

  • private static Session s_Session
    Static instance that tracks the current telemetry session state.

Properties

  • public static GameplayData gameplayData { get; set; }
    Holds a GameplayData instance (nested class) that provides accessors to in-game state used for telemetry (population, buildingCount, map name, simulation speed, money, DLC/content info, etc.). This must be set by game systems (or mods that initialize telemetry) before emitting many gameplay-related events.

Constructors

  • (none - static class)
    Telemetry is a static class; there are no public constructors. Initialization is done via static members and the gameplayData property (GameplayData needs to be constructed with a World).

Methods

  • private static void Hardware()
    Gathers system/graphics/CPU/RAM info into HardwarePayload and sends the "hardware" telemetry event.

  • private static void Language()
    Collects system and game language into LanguagePayload and sends the "language" telemetry event.

  • public static void GraphicsSettings()
    Reads current graphics settings into GraphicsSettingsPayload and sends the "graphics_settings" telemetry event.

  • public static void AchievementUnlocked(AchievementId id)
    If a session is active and the achievement is unlocked, sends an "achievement" event with AchievementPayload.

  • public static void TutorialEvent(Entity tutorial)
    Sends a "tutorial_event" with tutorial advice information (if gameplayData and session are active).

  • public static void MilestoneUnlocked(int milestoneIndex)
    Sends "milestone_unlocked" with milestone index and current ingame days.

  • public static void DevNodePurchased(DevTreeNodePrefab nodePrefab)
    Sends "dev_node" when a dev tree node is purchased.

  • public static void ControlSchemeChanged(InputManager.ControlScheme controlScheme)
    Sends "control_input" with the current control scheme.

  • public static void PanelOpened(GamePanel panel)
    Records panel open time in the session (no direct telemetry send). Use PanelClosed to produce telemetry.

  • public static void PanelClosed(GamePanel panel)
    If the panel was tracked as opened, computes time spent and sends "panel_closed" with PanelClosedPayload.

  • public static void CityStats()
    Collects city statistics (population, buildings, money, resources, etc.) into CityStatsPayload and sends "city_stats".

  • public static void Chirp(Entity chirpPrefab, uint likes)
    Sends "chirper" with chirp type and likes.

  • public static void PlaceBuilding(Entity entity, PrefabBase building, float3 position)
    Sends "building_placed" when valid building prefabs are placed. Includes prefab name, type, coordinates and origin (base game or content prerequisite).

  • public static void Policy(ModifiedSystem.PolicyEventInfo eventInfo)
    Sends "policy" when a non-hidden policy is applied or changed, including category and range.

  • public static void InputIdleStart()
    Marks the start of player input idle period in the session state (used later by InputIdleEnd).

  • public static void InputIdleEnd()
    Sends "idle_time_end" with start/end simulation speeds and idle duration.

  • public static void FireSessionStartEvents()
    Convenience method that calls Hardware(), Language(), and GraphicsSettings() — used when a session starts.

  • public static Guid GetCurrentSession()
    Returns the current session GUID (s_Session.guid).

  • public static void OpenSession(Guid guid)
    Closes any existing session, opens a new session if gameplayData is available, sends "playsession_start" with OpenSessionPayload, and also sends active mods and DLCs (via ModsUsed() and DlcsInstalled()).

  • private static void ModsUsed()
    Collects active Paradox workshop mods (if available) and sends "mod_used".

  • private static void DlcsInstalled(GameplayData data)
    Collects installed DLCs (with store/backend IDs) and sends "dlc".

  • public static void CloseSession()
    If a session is active, sends "playsession_close" with CloseSessionPayload and clears the session.

Notes on error handling: Most methods wrap payload generation and sending in try/catch and will log warnings if payload generation fails, preventing exceptions from propagating.

Additional nested type: GameplayData (public class inside Telemetry) - Purpose: Provides read-only accessors to in-game state needed for telemetry: buildingCount, population (Population struct), moneyAmount, moneyDelta, followedCitizens, ownedMapTiles, mapName, simulationSpeed, unlimitedMoney, unlockAll, naturalDisasters, tutorialEnabled, currentGameMode, methods like GetResourcesOutputCount(), GetDay(), GetPrefab(), GetDLCsFromContent(), etc. - Usage: Construct with a Unity.Entities.World (it looks up multiple game systems) and assign to Telemetry.gameplayData so telemetry calls can use in-game values.

Usage Example

// Example from a mod/system that can access a World instance and relevant entities:

// Initialize gameplay data once you have a World reference:
Telemetry.gameplayData = new Telemetry.GameplayData(world);

// Open a telemetry session (guid can be persisted or newly created)
Telemetry.OpenSession(Guid.NewGuid());

// Fire session-start hardware/language/graphics (OpenSession already triggers mods+DLC sends)
// Telemetry.FireSessionStartEvents(); // optional, already called by OpenSession's flow

// Report a building placement (when your building placement code runs)
// Telemetry.PlaceBuilding(buildingEntity, prefabBase, new float3(x, y, z));

// When player is idle and resumes, track idle periods:
Telemetry.InputIdleStart();
// ... player idle ...
Telemetry.InputIdleEnd();

// When closing/ending the play session:
Telemetry.CloseSession();

If you are modding, ensure Telemetry.gameplayData is initialized with a valid World and that calls are made on the main thread/context expected by the game. Most Telemetry methods are safe to call: they internally check gameplayData and session state and swallow exceptions while logging warnings.