GamersLab Platform Whitepaper

1) Executive Summary

GamersLab is a game-native data platform designed for a new era of game development, community engagement, and user-generated applications.

Modern games increasingly rely on live operations, community tooling, analytics, and external integrations. At the same time, the rise of AI-assisted development is radically reducing the cost and complexity of building software. Small teams — and even individual creators — can now build powerful applications, dashboards, overlays, and services with far less code than before.

However, data access and distribution have not evolved at the same pace.

Today, most game data is:

siloed inside studio-specific pipelines,
difficult to share safely with third parties,
inconsistently structured across titles,
or accessed indirectly through client-side scraping without game consent.

GamersLab addresses this gap by acting as a canonical, server-authoritative truth ledger for game events, coupled with controlled distribution mechanisms for both historical and real-time data.

The platform sits between:

game servers (authoritative data producers), and
data consumers (internal tools, community dashboards, overlays, UGC applications, partners, and players),

providing a secure, append-only, permissioned data pipeline that scales with live games.

Crucially, GamersLab is not an overlay, a mod runtime, or a client-side tool. It is infrastructure: a shared, reusable data substrate upon which many applications — including GamersLab’s own SaaS products and third-party UGC apps — can be built once and deployed across many games.

Core Principles

GamersLab is built around four core principles, ordered by how they shape the platform and its ecosystem.

1. Structured, uniform game data

GamersLab provides a consistent, game-native data model for sessions, matches, players, and events.
Regardless of genre or engine, gameplay activity is expressed through a shared set of canonical concepts and schemas.

This uniformity allows developers to:

build tools once and deploy them across many games,
avoid bespoke per-title telemetry pipelines,
and reason about gameplay data in a predictable, reusable way.

Structured data is the foundation that makes cross-game analytics, reputation systems, and UGC applications possible.

2. Canonical game truth

GamersLab records canonical truth as provided by the game itself.

Games submit authoritative events, match state, and results to the platform.

GamersLab acts as a neutral recording layer that:

preserves the order and structure of those events,
stores in append-only canonical tables,
provides auditable data -is backed by cutting-edge cryptography for data integrity while keeping secrets secret

GamersLab does not reinterpret gameplay. It captures and preserves what the game declares happened, creating a reliable historical record that downstream systems can trust and build upon.

3. Controlled access, ownership, and distribution

Games retain control of their data.

All access to GamersLab data is explicitly permissioned:

tenants control whether data is private, subscriber-only, or public,
live-streaming and historical access can be enabled independently,
identities can be redacted, delayed, or scoped by audience.

This model allows games to:

safely expose data to partners, communities, or UGC developers,
and back up or export their historical data at any time.
cut development costs

By creating approved, user-controlled data sources, GamersLab offers a safe alternative to client-side scraping, giving games control over how their data is shared while enabling richer community experiences.

4. Creator First AI-enabled UGC support

AI is dramatically reducing the cost and complexity of building software. Small, focused applications such as dashboards, overlays, analytics tools, and community experiences can now be created with minimal coding experience.

Gamers Lab provides:

high-quality structured data.
authoritative, game studio backend game events.
a platform to distribute UGC apps.
and does not require any AI to be within the game itself.

GamersLab is designed to be the ideal substrate for shift of players becoming UGC creators for their favorite titles (with or without AI coding assistance). By providing standardized schemas, real-time streaming, and controlled historical access, we enable creators to quickly build and deploy UGC applications for brand-new game experiences

Together, these principles position GamersLab as a game-native truth and distribution layer:
structured enough for machines and AI, authoritative enough for trust, and flexible enough to support the next generation of UGC and community-driven applications.

2) Problem Space and Goals

The Changing Landscape of Games, AI, and UGC

Games today are no longer closed systems. They are ecosystems:

Live service games run continuously, not in discrete releases.
Communities expect real-time visibility, statistics, and shared goals.
Players interact with games across Discord, streaming platforms, and external tools.
UGC platforms such as overlays, dashboards, and companion apps are increasingly common.
AI dramatically lowers the barrier to building software, but does not solve data access.

While AI can generate smaller, less complex applications, those applications still require:

structured data, and
a way to reach users.

This creates a paradox:

Software is easier than ever to write, but harder than ever to deploy meaningfully without access to trusted data and distribution.

The Current Reality of Game Data

In practice, most studios face one or more of the following problems:

Fragmented telemetry pipelines
Each game builds its own ingestion, storage, and access layer, often duplicated across teams and titles.
Inconsistent schemas
Event names, payloads, and semantics vary widely, making cross-game tooling expensive or impossible.
Unsafe or unofficial data access
In the absence of approved APIs, third-party tools scrape client memory or infer state without game consent.
Limited real-time access
Streaming data safely to partners or spectators requires custom infrastructure and careful privacy controls.
High operational burden
Maintaining analytics pipelines, rate limits, access controls, and audit logs distracts teams from gameplay and community design.

The result is a world where:

games either keep data locked down entirely, or
lose control over how their data is exposed and monetized.

Why Existing Platforms Fall Short

Platforms that operate at the client level (overlays, mods, screen scraping) demonstrate clear demand for UGC and community tooling — but they do so by observing the game client, not the authoritative server.

This creates structural limitations:

client-side data is inherently non-canonical,
outcomes cannot be safely reused for rewards or reputation,
cross-game aggregation is fragile,
games have little control over how data is exposed or monetized.

At the other extreme, internal analytics systems are powerful but closed:

data is trapped inside studio pipelines,
third-party developers cannot build reusable tools,
players have no visibility or agency.

GamersLab is designed to sit between these extremes.

GamersLab’s Goals

GamersLab aims to provide a single, reusable solution by:

Standardizing game-native event data
Gameplay is modeled explicitly as sessions, matches, players, and events, with append-only canonical records.
Enabling both historical and real-time access
Consumers can query past data or subscribe to live streams using Server-Sent Events (SSE), without bespoke infrastructure.
Giving games explicit control over data exposure
Games decide:

whether data is public, subscriber-only, or private,
whether streaming is enabled, historical access is enabled, or both,
how identities are redacted.

Supporting AI-driven and UGC applications
Uniform schemas allow creators to build once and deploy across many games, reducing friction for experimentation and innovation.
Preserving ownership and exit
Games retain ownership of their data and can export or back up historical records at any time.
Creating a safe alternative to scraping
By offering user-approved, game-approved data access, GamersLab enables rich community experiences without undermining trust or violating platform policies.

The Broader Vision

GamersLab is not simply a telemetry service.

It is a game-native data substrate for:

live operations,
community campaigns,
analytics and insights,
overlays and companion apps,
reputation systems,
and future settlement or reward mechanisms.

As AI accelerates software creation, data and distribution become the new scarcity. GamersLab is built to address both — providing structured, authoritative data and a controlled ecosystem where that data can be safely reused.

3) Platform Overview

GamersLab is a multi-tenant SaaS platform designed to act as a canonical game event ledger and distribution layer. It sits between authoritative game servers and a wide range of data consumers, providing structured ingestion, durable storage, integrity controls, planned verifiable proofs, and controlled access to both historical and real-time data.

A core design goal of the platform is to separate truth recording from product experiences. GamersLab itself is the foundational data layer; higher-level products such as community campaigns, analytics tools, overlays, and UGC applications are built on top of it — by GamersLab and by third parties.

Tenants and Isolation

GamersLab is organized around clear company → tenant boundaries.

A tenant represents a single game or environment (e.g., development, staging, production).
Each tenant owns its data, access policies, API keys, and visibility rules.
A single company may operate multiple tenants for multiple titles or environments.

Tenant isolation is enforced at every layer of the system: ingestion, storage, streaming, and historical queries.

Authentication and Identity Sources

GamersLab separates player identity, game server identity, and data consumer identity, allowing each to evolve independently.

Player authentication

Player identity is established using native and widely adopted authentication providers:

Platform-native logins (e.g., Steam, Epic)
Web3 wallet authentication (optional)
Email-based authentication and linking

Once authenticated, players receive scoped JWTs that can be used for identity-gated live streams (self or team views), privacy-aware dashboards, and approved UGC experiences.

This approach ensures GamersLab does not replace platform identity systems, but rather integrates cleanly with them.

Game server authentication

Game servers authenticate using a game auth key (X-Game-Key).

Keys are tenant-scoped and stored as hashes.
Keys can be rotated or revoked at any time.
All ingested data is attributed to a specific tenant and server identity.

Game servers are treated as the authoritative source of gameplay events.

Data consumer authentication

Read-only data consumers (dashboards, overlays, partners, and UGC apps) authenticate using data API keys (X-API-Key).

Keys are permissioned and rate-limited.
Tenant baseline rules apply to all subscriber and public keys.
Tenant-owned keys may override defaults for internal workflows.

Core Data Flow

GamersLab follows a deterministic, auditable data flow:

Game servers authenticate using a tenant-scoped game key.
Authoritative gameplay data (sessions, matches, events, results) is submitted to the API.
Data is validated, canonicalized, and row-hashed for append-only ledger writes.
Append-only canonical tables store immutable facts.
Derived state tables are maintained as additional structures for fast reads and live views.
Roadmap: ingestion metadata is signed and integrity proofs are generated and persisted (e.g., IPFS).
Historical and live consumers access data through controlled APIs and SSE streams.

High-Level Data Flow (Conceptual)

Canonical Data and State Tables

GamersLab distinguishes between two complementary categories of data.

Canonical (append-only) data

Canonical tables store immutable facts about gameplay:

match start and end records
match events
player events
login and logout records
match results and outcomes

Once written, these records cannot be updated or deleted. This ensures replayability, auditability, and long-term consistency.

Each canonical record includes:

deterministic row hashing
ingestion metadata
tenant attribution

Derived state tables (additional, not optional)

Derived state tables are always present and are built on top of canonical data.

They provide:

fast lookups
current session state
aggregated views
efficient live streaming

Examples include active session summaries, per-player match participation state, current match status, and tenant access summaries.

Derived tables may change over time, but they are always derivable from canonical records and never replace them.

Data Integrity, Hashing, and Proofs

GamersLab preserves authoritative data by keeping gameplay facts in append-only ledger tables.

Current: append-only enforcement

At ingestion:

records are canonicalized
row hashes are computed for ledger tables
unique indexes prevent exact duplicate rows from being inserted

Append-only triggers block UPDATE and DELETE operations on ledger tables. This keeps historical facts immutable while derived state tables can evolve for fast reads and live views.

Roadmap: signing and integrity proofs

Planned capabilities include:

ingestion metadata signing for verifiable records
batch proofs with cryptographic roots
immutable proof storage (e.g., IPFS) for external verification

Data Access and Distribution

GamersLab exposes data through two primary mechanisms.

Historical APIs

Read-only REST endpoints
Backed by canonical tables
Filtered by tenant rules, key permissions, and visibility constraints
Suitable for analytics, dashboards, and replay

Live streaming via Server-Sent Events (SSE)

Server-authoritative, one-way real-time streams
Configurable per tenant and per key
Supports identity redaction, scoping (self/team/all), and delays
Designed for spectators, overlays, and live community tools

SSE aligns naturally with GamersLab’s append-only ledger model by providing ordered, reconnect-friendly streams.

Summary

This platform design positions GamersLab as:

a canonical recording layer for game-native events
an append-only, audit-friendly data pipeline with planned integrity proofs
a scalable distribution surface for real-time and historical access
a foundation for AI-driven and UGC applications built on shared truth

Higher-level experiences such as community campaigns, analytics products, overlays, and prediction systems are intentionally built on top of this platform rather than embedded within it.

4) Personas and Stakeholders

GamersLab is built to serve distinct audiences with different needs:

Tenant owners/admins:
- Configure tenant settings, keys, and public subscriber options.
- Control visibility rules for live streaming and historical access.
Game data providers (game servers):
- Push authoritative gameplay data into the platform.
- Use a secure game auth key and standard endpoints.
Subscribers/partners:
- Access read-only data for dashboards, overlays, or analytics tools.
- Use tenant-provided API keys with strict limits and scope rules.
Players:
- Authenticate through supported providers (Steam/Epic/Mock) and email.
- Gain privacy protections via redaction and scoped visibility.
Platform operators:
- Monitor usage, enforce limits, and ensure compliance.
- Maintain schema migrations and operational health.

5) Core Architecture

GamersLab is a .NET 10 API with modular features and strong boundaries around data access. It exposes REST endpoints for ingestion and historical queries, plus SSE endpoints for live streaming.

Key architecture elements:

REST API for CRUD, ingestion, and historical reads.
SSE for live event streams (match events and player events).
Postgres as the system of record:
- Append-only tables for events and session logs.
- Mutable tables for stateful views and summaries.
Redis for caching and key validation to reduce database load.
Centralized logging and audit trails for security and compliance.

This architecture emphasizes durability and predictable behavior. Append-only records ensure that analytics are based on immutable facts, while state tables provide fast access to current status without scanning large event logs.

Mermaid: architecture overview

6) Authentication and Authorization

GamersLab separates SaaS users, players, and API consumers with distinct auth flows.

SaaS user auth:

Email signup, verification, login, and password reset.
JWT for admin and tenant management endpoints.

Player auth:

External providers (Steam/Epic/Mock) plus email linking.
Player JWTs for identity-gated live streaming (self/team visibility).
Once email is linked and verified, players can use email login directly.

API keys:

Game auth keys (X-Game-Key) for ingestion.
Data API keys (X-API-Key) for read-only access and streaming.
Keys are stored as hashes (the plaintext is shown once at creation).
Key rotation and revocation are supported for security.

7) Permissions and Access Control

Permissions are multi-layered to support product needs while protecting data.

Layer 1: Tenant baseline settings

Enable or disable public and subscriber keys.
Control whether subscriber keys can access live streams.
Control whether subscriber data requires match end.

Layer 2: Per-key overrides (tenant-owned keys)

Tenant-owned keys can override flags such as:
- allowDataApi
- allowLiveEvents
- allowActiveMatchData
- liveEventsScope (none/all/self/team)

Layer 3: Live events profiles

Each tenant has a default live events profile.
Tenant-owned keys can override the profile per key.
Profiles define:
- visibility per type (match start/end/results, match events, player events, logins/logouts)
- optional delay per type
- allow/deny filters for event keys or categories
- identity redaction for playerId, matchPlayerId, or team info

Privacy filters (live + historical)

GamersLab applies privacy filters through profiles and overrides that shape what data can be seen and by whom.

Tenant owners set the defaults:

Historical data profiles control visibility, allow/deny filters, redaction, and match-end gating.
Live events profiles control visibility by type, allow/deny filters, redaction, and per-type delays.

Subscribers can further restrict what their keys see:

Subscriber key overrides are allowed only when they are more restrictive than the tenant defaults.
This lets subscribers narrow access for their own use cases without expanding beyond the tenant's limits.

Tenants always control the maximum information available:

Tenant defaults define the ceiling for visibility and detail.
Subscriber and partner keys can only reduce access, never expand it.
This keeps tenant data and player privacy protected while allowing flexible, official data sharing.

Example: subscriber baseline

Tenant sets liveEventsSubscriberScope to team and requires match end for data.
Subscriber key can only stream team-scoped match events with a player token.
Historical queries only return completed matches.

Example: tenant-owned debug key

Tenant creates a key with allowActiveMatchData=true and liveEventsScope=all.
Key is assigned a profile that allows match events only but redacts playerId.

This model ensures that partner access is controlled by tenant defaults, while tenant-owned keys can be tuned for internal workflows like debugging or analytics.

Mermaid: access control layers

8) Data Model and Domain Concepts

GamersLab models gameplay as a combination of sessions, matches, and events.

Core domain entities:

Player profiles and tenant access (who belongs to which tenant).
Login sessions (player authentication events).
Match sessions (start, end, metadata).
Match players (per-player participation and team info).
Match results and leaderboards (per-player outcomes).
Event definitions (tenant-specific keys and categories).
Match events and player events (append-only records).

Append-only data and hashing

Event records and session logs are append-only by design.
Each row carries a row hash for uniqueness and integrity checks.
Triggers prevent updates and deletes on append-only tables.

Canonical vs non-canonical tables

Canonical tables store immutable facts (events, match results, login/logout records).
Non-canonical tables store derived state for fast access:
- Current session state (last seen, active session info).
- Player tenant access summaries (last seen, login counts).

Teams

Team data is optional and match-scoped (teamId and teamLabel per match player).
This enables team-based visibility rules without requiring a global team system.

Event definitions

Tenants define event keys and categories once, and events reference those definitions.
This provides a consistent vocabulary while allowing studio-specific customization.

Historical API data models (representative response shapes)

These are the canonical response models used by the read-only API. Many IDs can be null when redaction applies.

MatchSummaryDto (list + summary views):

MatchSessionId (Guid)
HostPlayerIds (Guid[])
LevelName (string)
IsMultiplayer (bool)
StartedAt (DateTime)
EndedAt (DateTime?)
EndReason (string?)
DurationSeconds (int?)

MatchDetailDto (single match view):

Inherits MatchSummaryDto fields
Metadata (Dictionary<string, object>?)
EndMetadata (Dictionary<string, object>?)

MatchPlayerDto (match roster):

MatchPlayerId (Guid?)
PlayerId (Guid?)
LoginSessionId (Guid?)
JoinedAt (DateTime)
TeamId (short?)
TeamLabel (string?)
IsHost (bool)
LastEventType (string?)
LastEventAt (DateTime?)

MatchPlayerResultDto (per-player results for a match):

ResultId (Guid)
MatchPlayerId (Guid?)
PlayerId (Guid?)
TeamId (short?)
TeamLabel (string?)
Result (string)
FinalScore (long?)
MatchPosition (int?)
RecordedAt (DateTime)

MatchResultRecordDto (tenant-wide results view):

ResultId (Guid)
MatchSessionId (Guid)
MatchPlayerId (Guid?)
PlayerId (Guid?)
TeamId (short?)
TeamLabel (string?)
Result (string)
FinalScore (long?)
MatchPosition (int?)
RecordedAt (DateTime)

EventRecordDto (match events, historical):

EventId (Guid)
MatchSessionId (Guid)
MatchPlayerId (Guid?)
PlayerId (Guid?)
TeamId (short?)
TeamLabel (string?)
EventDefinitionId (Guid)
EventKey (string)
EventValue (string?)
EventCategory (string?)
Value (long?)
OccurredAt (DateTime)

PlayerEventRecordDto (player events, historical):

EventId (Guid)
PlayerId (Guid?)
LoginSessionId (Guid?)
EventDefinitionId (Guid)
EventKey (string)
EventValue (string?)
EventCategory (string?)
Value (long?)
OccurredAt (DateTime)

SessionLoginRecordDto (logins):

Id (Guid)
SessionId (Guid?)
PlayerId (Guid?)
DeviceId (Guid?)
Platform (string)
PlatformDisplayName (string)
ClientVersion (string?)
IpAddress (string?)
OccurredAt (DateTime)

SessionLogoutRecordDto (logouts):

Id (Guid)
SessionId (Guid?)
PlayerId (Guid?)
DeviceId (Guid?)
Platform (string)
PlatformDisplayName (string)
ClientVersion (string?)
IpAddress (string?)
Reason (string)
Message (string?)
OccurredAt (DateTime)

TimelineItemDto (merged historical feed):

Type (string)
ItemId (Guid?)
OccurredAt (DateTime)
MatchSessionId (Guid?)
MatchPlayerId (Guid?)
PlayerId (Guid?)
LoginSessionId (Guid?)
EventDefinitionId (Guid?)
EventKey (string?)
EventValue (string?)
EventCategory (string?)
Value (long?)
TeamId (short?)
TeamLabel (string?)
LevelName (string?)
IsMultiplayer (bool?)
HostPlayerIds (Guid[]?)
EndReason (string?)
DurationSeconds (int?)
Result (string?)
FinalScore (long?)
MatchPosition (int?)
SessionId (Guid?)
DeviceId (Guid?)
Platform (string?)
PlatformDisplayName (string?)
ClientVersion (string?)
IpAddress (string?)
LogoutReason (string?)
Message (string?)

Live streaming data models (representative SSE payloads)

SSE payloads are the live equivalents of historical events with optional redaction.

LiveMatchEventDto:

EventId (Guid)
MatchSessionId (Guid)
MatchPlayerId (Guid?)
PlayerId (Guid?)
TeamId (short?)
TeamLabel (string?)
EventDefinitionId (Guid)
EventKey (string)
EventValue (string?)
EventCategory (string?)
Value (long?)
OccurredAt (DateTime)

LivePlayerEventDto:

EventId (Guid)
PlayerId (Guid?)
LoginSessionId (Guid?)
EventDefinitionId (Guid)
EventKey (string)
EventValue (string?)
EventCategory (string?)
Value (long?)
OccurredAt (DateTime)

9) Data Ingestion (Game Providers)

Game servers authenticate with X-Game-Key and submit authoritative data.

Common ingestion flows:

Player creation and login through auth providers.
Match start (session metadata, players, optional team info).
Match events (in-match telemetry).
Player events (player-specific actions).
Match end and match results.

Ingestion characteristics:

Append-only writes for integrity and replayability.
Row hashes for uniqueness and integrity checks.
Validation rules ensure tenant isolation and correct relationships.

Tenant isolation:

Each game runs inside its own private tenant (per environment).
A company can own multiple tenants (e.g., dev, staging, production, or multiple titles).
Game auth keys are tenant-scoped, so ingestion always lands in the correct tenant boundary.

Data durability:

The system of record is Postgres for canonical and state tables.
Replication and backups are handled at the deployment layer for availability and recovery.

10) Historical Data API

Historical data is served through a read-only API using X-API-Key.

Capabilities:

Query matches, players, results, events, and leaderboards.
Filter by player ID, match ID, time range, and status.
Pagination with limits and offsets.
Timeline helper endpoint for merged views across data types.
Player lookup endpoints for display names (emails are never exposed).

Access rules:

allowDataApi must be true.
allowActiveMatchData gates access to in-progress match data.
Subscriber keys inherit tenant baseline settings.

Append-only canonical data and hashing

Historical endpoints are backed by append-only canonical tables for facts that should never change once recorded (match events, player events, match results, login/logout records). This preserves auditability and protects downstream analytics from “silent edits.”

Why append-only:

Ensures historical queries remain consistent over time.
Supports replayability and debugging when investigating incidents.
Makes it easier to validate integrity with immutable records.

Row hashing:

Each append-only record stores a deterministic hash (“row_hash”) derived from key fields and timestamps.
A hash is a fixed-length fingerprint of data; if any input changes, the hash changes.
Unique indexes on row_hash enforce append-only uniqueness within a tenant.

Practical impact:

Exact duplicate rows (same hash) are rejected by uniqueness constraints.
If the data differs, the new record is treated as a distinct fact (not a mutation).

Example row hash inputs (conceptual):

Match event: tenant_id + match_session_id + match_player_id + event_definition_id + occurred_at + value
Player event: tenant_id + player_id + event_definition_id + occurred_at + value
Login: tenant_id + session_id + player_id + occurred_at

Mermaid: append-only vs state tables

11) Live Streaming (SSE)

GamersLab provides Server-Sent Events streams for live data:

Match events stream.
Player events stream.

Streaming controls:

Key scope (none/all/self/team) sets the ceiling.
Live events profile further restricts visibility and redacts fields.
Player bearer token is required for self or team scopes.
Delays can be applied to reduce real-time leakage.

This balance allows tenants to expose live data safely for spectators or partners while protecting competitive integrity.

Host-aware streaming:

Profiles can include host-specific visibility for match events, allowing the match host to see up-to-date data while other players receive delayed or restricted views.
This supports live broadcast use cases (Twitch, X, streaming overlays) without exposing full real-time telemetry to all players.
Example: a host key uses a profile with includeHostByType for match events, while player keys remain self/team-scoped with redaction and delays.

Live events profiles (SSE customization)

Live events profiles are JSON configurations that shape what live data is visible and how it is presented. They let a tenant create audience-specific streams without changing the game server or client code. Profiles can be set as the tenant default or assigned per key.

Common uses:

Scores-only public stream (no event detail, delayed).
Team-only stream (redact player identity, show team score and match results).
Internal debugging stream (all events, no redaction).

All parameters (kitchen sink example):

{
  "version": 1,
  "enabled": true,
  "visibilityByType": {
    "matchStart": "all",
    "matchEnd": "all",
    "matchResults": "team",
    "matchEvents": "team",
    "playerEvents": "self",
    "sessionLogins": "self",
    "sessionLogouts": "self"
  },
  "delaysSeconds": {
    "matchStart": 0,
    "matchEnd": 5,
    "matchResults": 10,
    "matchEvents": 15,
    "playerEvents": 0,
    "sessionLogins": 0,
    "sessionLogouts": 0
  },
  "overrides": {
    "allowEventCategories": [
      "combat",
      "objective",
      "resource"
    ],
    "denyEventCategories": [
      "ui"
    ],
    "allowEventKeys": [
      "kill",
      "assist",
      "objective_score",
      "flag_capture"
    ],
    "denyEventKeys": [
      "headshot",
      "weapon_pickup"
    ],
    "allowEventValues": [
      "ctf",
      "oddball",
      "diamond_ore"
    ],
    "denyEventValues": [
      "susanoo",
      "kyuubi"
    ]
  },
  "includeHostByType": [
    "matchEvents",
    "matchResults"
  ],
  "identityRedaction": {
    "playerId": true,
    "matchPlayerId": true,
    "teamId": false,
    "teamLabel": false
  },
  "identityRedactionByType": {
    "matchEvents": {
      "playerId": false,
      "matchPlayerId": true,
      "teamId": false,
      "teamLabel": false
    },
    "playerEvents": {
      "playerId": true,
      "matchPlayerId": true,
      "teamId": true,
      "teamLabel": true
    }
  }
}

Example: scores-only public stream (no event detail)

{
  "version": 1,
  "enabled": true,
  "visibilityByType": {
    "matchStart": "all",
    "matchEnd": "all",
    "matchResults": "all",
    "matchEvents": "none",
    "playerEvents": "none",
    "sessionLogins": "none",
    "sessionLogouts": "none"
  },
  "delaysSeconds": {
    "matchStart": 0,
    "matchEnd": 10,
    "matchResults": 10,
    "matchEvents": 0,
    "playerEvents": 0,
    "sessionLogins": 0,
    "sessionLogouts": 0
  },
  "overrides": {},
  "identityRedaction": {
    "playerId": true,
    "matchPlayerId": true,
    "teamId": false,
    "teamLabel": false
  }
}

Example: team-only + scores (no player identity)

{
  "version": 1,
  "enabled": true,
  "visibilityByType": {
    "matchStart": "team",
    "matchEnd": "team",
    "matchResults": "team",
    "matchEvents": "none",
    "playerEvents": "none",
    "sessionLogins": "none",
    "sessionLogouts": "none"
  },
  "delaysSeconds": {
    "matchStart": 0,
    "matchEnd": 0,
    "matchResults": 5,
    "matchEvents": 0,
    "playerEvents": 0,
    "sessionLogins": 0,
    "sessionLogouts": 0
  },
  "overrides": {},
  "identityRedaction": {
    "playerId": true,
    "matchPlayerId": true,
    "teamId": false,
    "teamLabel": false
  }
}

Example: allow-only specific match events (public highlights)

{
  "version": 1,
  "enabled": true,
  "visibilityByType": {
    "matchStart": "all",
    "matchEnd": "all",
    "matchResults": "all",
    "matchEvents": "all",
    "playerEvents": "none",
    "sessionLogins": "none",
    "sessionLogouts": "none"
  },
  "delaysSeconds": {
    "matchStart": 0,
    "matchEnd": 0,
    "matchResults": 10,
    "matchEvents": 20,
    "playerEvents": 0,
    "sessionLogins": 0,
    "sessionLogouts": 0
  },
  "overrides": {
    "allowEventKeys": [
      "kill",
      "assist",
      "objective_score"
    ],
    "denyEventKeys": [
      "headshot"
    ]
  },
  "identityRedaction": {
    "playerId": true,
    "matchPlayerId": true,
    "teamId": false,
    "teamLabel": false
  }
}

Example: internal debugging (no redaction, no delay)

{
  "version": 1,
  "enabled": true,
  "visibilityByType": {
    "matchStart": "all",
    "matchEnd": "all",
    "matchResults": "all",
    "matchEvents": "all",
    "playerEvents": "all",
    "sessionLogins": "all",
    "sessionLogouts": "all"
  },
  "delaysSeconds": {
    "matchStart": 0,
    "matchEnd": 0,
    "matchResults": 0,
    "matchEvents": 0,
    "playerEvents": 0,
    "sessionLogins": 0,
    "sessionLogouts": 0
  },
  "overrides": {},
  "identityRedaction": {
    "playerId": false,
    "matchPlayerId": false,
    "teamId": false,
    "teamLabel": false
  }
}

Notes:

allow lists and deny lists apply only to match and player events.
If any allow list is present, items not on the allow list are excluded.
Deny lists always win over allow lists.

12) Subscriber and Public Access

Studios can enable public or subscriber access to their data.

Key behaviors:

Public tenant catalog lists tenants that opt in to discovery.
Subscribers generate read-only keys via authenticated endpoints.
Subscriber keys inherit tenant defaults for live scope and historical gating.
Usage is rate-limited and auditable.

This model supports community dashboards, partner integrations, and external analytics without exposing internal databases or requiring custom access policies per partner.

13) Observability and Security

GamersLab includes built-in observability to protect data and enforce policy:

Audit logs for key actions and admin events.
Usage tracking for API keys and rate limits.
Redis-backed caching to reduce query pressure.
Explicit error handling and structured responses.

Security considerations:

API keys are stored only as hashes; plaintext is shown once.
Profiles can redact identifiers to protect player privacy.
Tenant isolation is enforced at every data access layer.

14) Deployment and Operations

GamersLab is designed for predictable deployment:

Consolidated schema script plus incremental patches for migrations.
Environment-based configuration for auth, storage, and caching.
Clear separation of dev/staging/prod tenants.

Operational focus is on reliability, low latency, and data integrity.

15) Roadmap

Future enhancements focus on scale, visibility, and ecosystem growth:

Expanded analytics modules and reporting.
Additional identity integrations and provider ecosystems.
Integrity proof batching with immutable proof storage (IPFS).

extra

Data Shape and Typical Game Flow

A typical game session flows through the platform in a natural sequence that mirrors gameplay:

Login → Player Events → Match Start → Match Events (K/V pairs) → Score → Match End → Logout

Login — the game client authenticates the player through a supported provider (Steam, Epic, wallet, email). The platform returns a session ID, player ID, and tokens. A login ledger row is appended.
Player Events — before or between matches, the game server can record player-level events (e.g. menu_open, loadout_change, tutorial_complete). These are tied to the player and login session, not to any match.
Match Start — the game server creates a match session with metadata (level, mode, players). Each player is assigned a matchPlayerId for the duration of the match.
Match Events (key/value pairs) — during gameplay, the server submits match events as structured key/value records. Each event carries an eventKey, an optional eventValue, and an optional numeric value. This is explained further below.
Score / Results — when the match concludes, the server submits per-player results including result (win/loss/draw), finalScore, and matchPosition.
Match End — the server closes the match session with an endReason (completed, abandoned, timeout, etc.) and optional end metadata.
Logout — the player's session is closed and a logout ledger row is appended with the reason.

Every step in this flow produces an append-only ledger record with a deterministic row hash. The full history of a player's journey — from login through every match event to logout — is preserved and queryable.

The Power of Key/Value Events

The event model is intentionally simple and universally flexible. Every match event and player event is a key/value pair with an optional numeric value:

Field	Purpose	Example
`eventKey`	What happened	`kill`, `flag_capture`, `item_craft`, `damage_dealt`
`eventValue`	Contextual detail (optional)	`headshot`, `red_flag`, `diamond_sword`, `fire`
`value`	Numeric magnitude (optional)	`1`, `250`, `3`, `89`

This three-part structure is deceptively powerful. A single schema handles:

Counting events — eventKey: "kill", value: 1 — aggregated into kill counts, leaderboards, and streaks
Measuring quantities — eventKey: "damage_dealt", eventValue: "fire", value: 89 — total fire damage across a match or career
Tracking resources — eventKey: "gold_earned", value: 250 — economy analytics, inflation tracking
Recording milestones — eventKey: "level_up", eventValue: "warrior", value: 12 — progression analytics
Categorical tagging — eventKey: "objective_score", eventValue: "oddball" — filtering by game mode or objective type

Because value is a number, the platform can natively sum, average, rank, and aggregate across events without the game needing to define custom schemas. A leaderboard for total kills, highest single-match damage, or career gold earned is just a query over the same event table — filtered by key, grouped by player, sorted by the numeric value.

Studios define their own event keys and categories once per tenant. After that, every tool, dashboard, and overlay built on the platform understands the data shape automatically. A community app built for one game's kill events works identically for another game's kill events, because the structure is the same.

Data Access and Distribution

Consumers access data through two channels:

Historical REST API — read-only endpoints for querying matches, players, events, results, and leaderboards. Backed by canonical append-only tables. Supports pagination, filtering, and cursor-based event queries.
Live Streaming via Server-Sent Events (SSE) — real-time, one-way event streams for match events and player events. Supports configurable delays, identity redaction, and audience scoping (all/self/team).

Both channels are gated by API keys with layered access controls. Tenant owners set baseline visibility rules, and subscriber keys can only narrow access further — never expand it.

Whitepaper

On this page