Skip to main content
m.global is a special roSGNode provided by the Roku SceneGraph runtime. Unlike local m fields, m.global is shared across all components and tasks simultaneously — reads and writes are thread-safe and changes are immediately visible to any observer registered with observeField. GTV_InitGlobalState() in source/AppState.brs calls m.global.addFields({...}) once at startup inside MainScene.init() to declare every field with its initial value.

​
Reading and writing global fields

From a component (render thread): 
' Write
m.global.playerState = "playing"
m.global.currentChannelIndex = 3

' Read
channels = m.global.channelList
if m.global.isAuthenticated = true
    ' ...
end if
From a Task node (background thread) — Tasks access m.global through the same m.global reference available in their script scope: 
' Task writes result back to a task field, not directly to m.global
' MainScene then reads the task field and updates m.global
m.global.activeServer  ' readable from tasks
Observing changes — components can react to global field changes: 
' In PlayerScreen.init()
m.global.observeField("channelList", "OnChannelListChanged")
Tasks should write to their own output fields (e.g., done, result) rather than writing directly to m.global. MainScene reads task output and updates m.global on the render thread. This avoids race conditions between the render thread and task threads.

​
Field reference

​
Server and connectivity

FieldTypeDefaultDescription
activeServerstring""Base URL of the currently active backend server, e.g. "https://admin.globaltv.lat". Set by HandshakeTask or when the user applies a server from Settings.
realtimeModestring"polling"Reserved for future realtime transport selection. Currently always "polling".
isOnlinebooleantrueWhether a network interface is available (GTV_IsOnline()). Updated by PlayerScreen on each netCheckTimer fire.
hasInternetbooleantrueWhether the network interface has verified internet reachability. Updated by ConnectivityTask and PlayerScreen.

​
Authentication

FieldTypeDefaultDescription
isAuthenticatedbooleanfalseSet to true by AuthTask on success; cleared to false on logout, session invalidation, or playlist failure.
usernamestring""The authenticated user’s username. Written by MainScene after successful login.
rokuEmailstring""Roku account email obtained via ChannelStore.getUserData. Written by LoginScreen and passed to MainScene.
userIdstring""Backend user ID returned by the auth endpoint.
subscriberActivebooleanfalseWhether the subscriber account is active. Used by GTV_AuthLooksInactive() to classify inactive-account failures.
userInactiveReasonstring""Human-readable message shown in the inactivity or session-issue dialog.
authNoticestring""One-time notice displayed on the LoginScreen after a forced logout. Consumed and cleared immediately on login init.
authReasonCodeinteger0Current failure classification: 0 = none, 460 = network down, 401 = credentials, 470 = inactive, 471 = password changed.
authReasonCode constants are defined in AppConstants() as AUTH_REASON_NONE, AUTH_REASON_NETWORK_DOWN, AUTH_REASON_CREDENTIALS, AUTH_REASON_INACTIVE, and AUTH_REASON_PASSWORD_CHANGED.

​
Channel list and selection

FieldTypeDefaultDescription
channelListarray[]Flat array of channel objects parsed from the M3U8 playlist. Each entry contains contentId, name, number, url, group, and logo.
categoriesarray[]Array of category labels derived from M3U8 group-title tags.
currentChannelIndexinteger0Zero-based index into channelList for the channel currently being played. Written by PlayerScreen.PlayChannel() and updated on every channel switch.
currentChannelIdstring""contentId of the current channel. Used by the ad system to match snapshots and by MetricsTask for event attribution.
overlaySelectedChannelIndexinteger-1Flat index of the channel highlighted in the overlay grid. Kept in sync by MainScreen.UpdateOverlaySelectedFlatIndex().
overlayHasManualContextbooleanfalsetrue when the user has manually navigated to a different category in the overlay. Used by MainScene to restore the exact category and row when re-opening the overlay.
overlaySelectedCategoryIndexinteger0Category tab index remembered for overlay restoration.
overlaySelectedRowIndexinteger-1Row index within the selected category, remembered for overlay restoration.

​
Player state

FieldTypeDefaultDescription
playerStatestring"stopped"Mirror of m.video.state. Updated on every OnVideoStateChanged() event. Values: "stopped", "buffering", "playing", "paused", "finished", "error".
isOverlayActivebooleanfalsetrue while the channel-selection overlay is visible on top of the player. Written by SetOverlayActive() in MainScene and read by PlayerScreen to route key events.

​
Ad state

FieldTypeDefaultDescription
adsVersioninteger0Version counter incremented by AdsPollingTask on each successful poll response. Cleared to 0 on logout or session reset.
adsNextCheckAtinteger0Unix timestamp (seconds) of the next scheduled ad poll. Used by the task to enforce ADS_POLL_MS intervals.

​
Device info

FieldTypeDefaultDescription
deviceIdstring""Roku device serial or unique identifier. Populated during handshake.
deviceModelstring""Roku model name, e.g. "3900X".
osVersionstring""Roku OS version string.
ridastring""Roku ID for Advertisers (RIDA). Used by the ad system for targeting.
latbooleanfalseLimit Ad Tracking flag. true means the user has opted out of ad tracking.
deviceIpstring""LAN IP address of the device.
deviceTimezoneinteger0UTC offset in seconds.
FieldTypeDefaultDescription
launchDeepLinkassocarrayinvalidThe raw deep link args from Main(args) when mediaType = "live". Set on MainScene (not m.global) and triggers onLaunchDeepLink() via onChange.
inputDeepLinkassocarrayinvalidWarm-start deep link received as roInputEvent. Set on MainScene (not m.global) and triggers onInputDeepLink() via onChange.
appLaunchBeaconSentbooleanfalsePrevents duplicate AppLaunchComplete beacons. Set to true the first time MainScreen.SignalAppLaunchCompleteOnce() fires. Never reset during the session.
launchDeepLink and inputDeepLink are fields on m.top (the MainScene node), not on m.global. They are declared in MainScene.xml with onChange handlers and appear here for completeness.

​
Complete initialisation listing

The full addFields call from source/AppState.brs: 
sub GTV_InitGlobalState()
    m.global.addFields({
        activeServer        : "",
        realtimeMode        : "polling",
        isOnline            : true,
        hasInternet         : true,

        isAuthenticated     : false,
        username            : "",
        rokuEmail           : "",
        userId              : "",
        subscriberActive    : false,
        userInactiveReason  : "",
        authNotice          : "",
        authReasonCode      : 0,

        channelList         : [],
        categories          : [],
        currentChannelIndex : 0,
        currentChannelId    : "",
        overlaySelectedChannelIndex : -1,
        overlayHasManualContext : false,
        overlaySelectedCategoryIndex : 0,
        overlaySelectedRowIndex : -1,

        playerState         : "stopped",
        isOverlayActive     : false,

        adsVersion          : 0,
        adsNextCheckAt      : 0,

        deviceId            : "",
        deviceModel         : "",
        osVersion           : "",
        rida                : "",
        lat                 : false,
        deviceIp            : "",
        deviceTimezone      : 0,

        launchDeepLink      : invalid,
        inputDeepLink       : invalid,

        appLaunchBeaconSent : false
    })
end sub

​
Registry fields

Some state is persisted across sessions in the Roku Registry (roRegistrySection named "GlobalTV"). These values survive channel updates and device reboots.
Registry key (AppConstants)ConstantDescription
REG_KEY_USER"username"Saved username for auto-login. Written by MainScene after successful login; cleared on logout or credential failure.
REG_KEY_PASS"password"Saved password for auto-login. Stored alongside username; cleared on the same conditions.
REG_KEY_SERVER"lastServer"Base URL of the last successfully used server. Written by HandshakeTask and by the server-apply action in Settings.
REG_KEY_CHANNEL"lastChannelIndex"Zero-based index of the last channel played. Written by PlayerScreen.PlayChannel() on every channel switch. Used by ResolveStartupChannelIndex() to resume where the user left off.
REG_KEY_SAFE_MARGIN"uiSafeMarginPct"Integer percentage (0–10) for the UI safe-area margin. Written by SettingsScreen.AdjustSafeArea() and read by GTV_GetSafeMarginPct() on every layout pass.
REG_KEY_SERVER_PROFILES"serverProfiles"JSON-encoded array of server profile objects. Managed by ServerManager.brs functions (GTV_LoadServerProfiles, GTV_SaveServerProfiles).
' Reading registry credentials
creds = GTV_RegLoadCredentials()
if creds <> invalid
    ' creds.username and creds.password are available
    RunAutoLogin(creds.username, creds.password)
end if

' Saving after successful login
GTV_RegSaveCredentials(creds.username, creds.password)
GTV_RegSaveLastServer(serverUrl)
GTV_RegSaveLastChannelIndex(channelIndex)
Credentials are stored in plaintext in the Roku Registry. The registry is device-local and not accessible to other channels, but you should not store sensitive data beyond what is required for auto-login.

​
State lifecycle

The following events reset or clear portions of global state:
EventFields cleared
LogoutisAuthenticated, userId, rokuEmail, channelList, categories, currentChannelIndex, currentChannelId, playerState, adsVersion, adsNextCheckAt, subscriberActive, username, activeServer
Session invalidation (credentials)Same as logout; also clears registry credentials
Session invalidation (inactive account)Same as logout; registry credentials preserved to allow retry
Server switch (Settings → Apply now)activeServer, realtimeMode, hasInternet, isOnline, authReasonCode, userInactiveReason; then restarts handshake
Playlist refreshchannelList and categories are replaced with fresh data; currentChannelIndex is re-resolved by content ID