statusdatabase

name

statusdatabase

description

StatusDatabase path rules, return types, and provider patterns. Use when referencing StatusDatabasePaths, creating or modifying StatusDatabase providers, querying game state via StatusDatabase, fixing CS0117 errors, choosing GetStatusValueAsync type parameters, detecting popups via OpenPopUps, or applying provider SRP. Covers: mandatory pre-flight grep_search, nested class qualification, return type conventions, popup detection pattern, provider naming, hardcoded string prohibition. stages: test-implementation, test-validation

StatusDatabase Rules & Patterns

When to Use

• Referencing any StatusDatabasePaths.* constant
• Creating or modifying a StatusDatabase provider
• Fixing CS0117 errors on StatusDatabasePaths references
• Choosing the correct GetStatusValueAsync<T>() type parameter
• Detecting popup visibility via OpenPopUps
• Understanding provider SRP (Single Responsibility Principle)

MANDATORY Pre-Flight: StatusDatabase Path References

Before writing ANY StatusDatabasePaths.* reference, you MUST perform these steps in order:

1. Call grep_search with the property name (e.g., ChangeDenomInProgress) scoped to Tests/Shared/Constants/GGA/StatusDatabasePaths.cs.
2. Read the returned line to identify the enclosing nested class (e.g., public static class GameStatus).
3. Only then emit the fully-qualified reference (e.g., StatusDatabasePaths.GameStatus.ChangeDenomInProgress).

There is no exception to this rule. If you have not performed steps 1–2, you MUST NOT emit the reference. A flat reference like StatusDatabasePaths.ChangeDenomInProgress will always produce CS0117.

After grep_search returns a match at line N, call read_file from line N-20 to N to find the public static class XxxStatus declaration that encloses it.

Hardcoded Strings Are Prohibited

NEVER use raw string paths (e.g., "GameStatus.ChangeDenomInProgress") when a constant exists in StatusDatabasePaths.cs. If a constant doesn't exist for a path you need, add it to StatusDatabasePaths.cs rather than hardcoding strings.

Fixing CS0117 Errors

When a StatusDatabasePaths.* reference fails with CS0117: Do NOT guess another nested class or fall back to hardcoded strings. Instead, read_file the 20 lines preceding the grep match to identify the actual enclosing class.

When a Path Does Not Exist

If grep_search returns zero matches, the path does not exist. Do NOT:

• Hardcode the path as a raw string — it will compile but fail silently at runtime
• Add a fictional nested class to StatusDatabasePaths.cs
• Create a provider for data that doesn't come from StatusDatabase

Recovery sequence:

1. Search Shared/Services/, Shared/Facades/, Shared/Validators/, Shared/Utilities/, and Features/*/Services/ for existing code that retrieves the needed data
2. Search StatusDatabasePaths.cs for related paths in the same domain
3. Ask the user if no existing code or related path serves the purpose

Common example: Reel state/visible symbol data comes from the MPT UTP module, not StatusDatabase. See the reel-state skill.

Return Type Conventions

GetStatusValueAsync<T>() requires the correct type parameter:

Path type	Type parameter	Examples
Boolean scalars	<bool>	GameCycleActive, InActivePlayMode, ChangeDenomInProgress
Integer scalars	<int>	NumSpins, TotalSpins, NumSpinningReelslots
String scalars	<string>	DisplayState, Status (WinCounting)
Long scalars	<long>	PlayableMoney, TotalWin
Collection / array	<JsonNode> then cast to JsonArray	OpenPopUps, RunningFeatures, SpinningReelSlots
Nested object	<JsonNode> then node["PropertyName"]	LanguageConfig, ServiceButtonConfig
Typed array	<JsonArray> directly	DenomInformationsConfig

Before choosing a type parameter, search existing providers for usage of the same or similar path:

• JsonNode / JsonArray of objects: ConfigurationStatusProvider.cs
• JsonArray with named property: GameFlowStatusProvider.cs
• Bool / int / string scalars: GameStatusProvider.cs, FreeGameStatusProvider.cs, GambleStatusProvider.cs

Extracting Properties from JsonObject Elements

When a collection path returns JsonObject elements (e.g., OpenPopUps, RunningFeatures):

// CORRECT — extract named property from JsonObject
var name = (item as JsonObject)?["PropertyName"]?.GetValue<string>();

// WRONG — throws InvalidOperationException on JsonObject
var name = item?.GetValue<string>();  // ❌

Popup Detection (Canonical Pattern)

Read StatusDatabasePaths.PopUpStatus.OpenPopUps and check for the popup name:

using System.Text.Json.Nodes;

private const string PopupName = "YourPopupNameHere"; // Ask user for exact name
private const string NameProperty = "Name";

public async Task<bool> IsPopupVisibleAsync()
{
    var openPopUps = await GetStatusValueAsync<JsonNode>(
        StatusDatabasePaths.PopUpStatus.OpenPopUps);

    if (openPopUps is JsonArray array)
    {
        return array.Any(item =>
        {
            var name = (item as JsonObject)
                ?[NameProperty]?.GetValue<string>();
            return string.Equals(
                name, PopupName, StringComparison.Ordinal);
        });
    }

    return false;
}

Key rule: Popup name strings are runtime values produced by the game engine, not present in C# source. Always ask the user for the exact popup name.

Provider SRP: One Provider Per StatusDatabase Module

Each provider maps to one StatusDatabase module (one nested class in StatusDatabasePaths). A method querying GameStatus.* belongs in GameStatusProvider; a method querying PopUpStatus.* belongs in PopUpStatusProvider.

Naming convention: {StatusDatabaseNestedClassName}StatusProvider — use the exact nested class name. Before creating a new provider, verify: (1) the nested class name from StatusDatabasePaths.cs, and (2) whether a provider already exists.

Provider Simplicity

A provider method should call GetStatusValueAsync<T>() with a single, known StatusDatabasePaths constant. If a provider method contains arrays of candidate paths, try/catch fallbacks, or multiple "strategy" branches, the design is wrong.

Self-Check Before Outputting Code

• Every StatusDatabasePaths.* reference was looked up via grep_search or read_file
• No flat references (StatusDatabasePaths.PropertyName) — all qualified with nested class
• No hardcoded string paths when a constant exists
• No provider with candidate-path arrays or multi-strategy fallbacks