# secondsun-technologies/games-sdk architecture

> Architecture diagram of the GitHub repository secondsun-technologies/games-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/secondsun-technologies/games-sdk
- Repository: https://github.com/secondsun-technologies/games-sdk

## Overview

The repository provides a games SDK plus a browser simulator for exercising registered games. The principal workflow is to register a game, render it within platform-managed context and session lifecycle, use declared capabilities and SDK UI primitives, then emit validated observational events. The simulator adds profile-driven runtime overrides and event inspection. Several runtime modules are named by the SOURCE INDEX but were not excerpted; edges are limited to relationships explicitly visible in excerpts or the README.

Main entry points: [`packages/games-sdk-simulator/src/App.tsx`](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/App.tsx) (Simulator app), [`packages/games-sdk/src/platform/renderGame.ts`](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/platform/renderGame.ts) (Platform game renderer), [`packages/games-sdk/src/core/create-game.ts`](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/core/create-game.ts) (Game registration), [`packages/games-sdk/src/dev/harness.ts`](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/dev/harness.ts) (Development harness)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk_core["Game Contract"]
  node_game_registration["Game registration<br/>[create-game.ts]"]
  node_metadata["Game metadata<br/>[metadata.ts]"]
  node_branded_types["Branded identifiers<br/>[branded.ts]"]
  node_capability_guard["Capability guard"]
  node_capability_types["Capability contracts<br/>[capabilities.ts]"]
  node_game_context["Lifecycle context<br/>[context.ts]"]
  node_sdk_capability_apis["Dev capability APIs<br/>[capability-apis.ts]"]
  node_dev_harness["Development harness<br/>[harness.ts]"]
  node_mock_context["Mock contexts<br/>[mock-context.ts]"]
  node_dev_event_inspector["SDK event inspector<br/>[event-inspector.ts]"]
end

subgraph group_sdk_runtime["Platform Runtime"]
  node_session_driver["Session lifecycle<br/>[session.ts]"]
  node_game_renderer["Platform game renderer<br/>[renderGame.ts]"]
  node_runtime["Platform runtime<br/>[runtime.ts]"]
  node_event_gate["Event gate<br/>[eventGate.ts]"]
end

subgraph group_sdk_events["Events and State"]
  node_event_contracts["Event contracts<br/>[event-types.ts]"]
  node_event_emitter["Event emitter<br/>[event-emitter.ts]"]
  node_event_validation["Event validation"]
  node_game_state["Game state API<br/>[index.ts]"]
end

subgraph group_sdk_ui["Game UI"]
  node_theme_tokens["Theme tokens<br/>[tokens.ts]"]
  node_theme_defaults["Theme defaults<br/>[defaults.ts]"]
  node_theme_context["Theme context<br/>[context.tsx]"]
  node_ui_primitives["UI primitives"]
  node_ui_animation["Motion helpers<br/>[motion.ts]"]
end

subgraph group_simulator["SDK Simulator"]
  node_simulator_app["Simulator app<br/>[App.tsx]"]
  node_device_profiles["Device profiles<br/>[deviceProfiles.ts]"]
  node_runtime_builder["Runtime builder<br/>[runtimeBuilder.ts]"]
  node_game_loader["Game loader<br/>[gameLoader.ts]"]
  node_control_panel["Control panel<br/>[ControlPanel.tsx]"]
  node_device_frame["Device frame<br/>[DeviceFrame.tsx]"]
  node_session_controls["Session controls"]
  node_event_inspector["Event inspector<br/>[EventInspector.tsx]"]
end

node_game_author(("Game developer"))
node_simulator_user(("Simulator user"))

node_game_author -->|"registers game"| node_game_registration
node_game_registration -->|"validates metadata"| node_metadata
node_game_author -->|"requests capabilities"| node_capability_guard
node_capability_guard -->|"checks declarations"| node_capability_types
node_game_registration -->|"checks declarations"| node_capability_types
node_session_driver -->|"creates snapshots"| node_game_context
node_game_renderer -->|"renders registered game"| node_game_registration
node_game_renderer -->|"provides context"| node_game_context
node_game_renderer -->|"uses runtime"| node_runtime
node_game_renderer -->|"uses session"| node_session_driver
node_game_renderer -->|"uses event gate"| node_event_gate
node_game_author -->|"emits observations"| node_event_emitter
node_event_emitter -->|"validates events"| node_event_validation
node_event_emitter -->|"accepts event types"| node_event_contracts
node_event_validation -->|"validates event shapes"| node_event_contracts
node_game_author -->|"requests state save"| node_game_state
node_theme_context -->|"uses tokens"| node_theme_tokens
node_theme_context -->|"loads defaults"| node_theme_defaults
node_ui_primitives -->|"styles with tokens"| node_theme_tokens
node_simulator_user -->|"configures and inspects"| node_simulator_app
node_simulator_app -->|"selects profile"| node_device_profiles
node_simulator_app -->|"builds runtime"| node_runtime_builder
node_simulator_app -->|"renders controls"| node_control_panel
node_simulator_app -->|"renders device"| node_device_frame
node_simulator_app -->|"renders events"| node_event_inspector
node_device_frame -->|"loads game"| node_game_loader
node_device_frame -->|"renders controls"| node_session_controls
node_simulator_app -->|"records events"| node_event_inspector
node_game_loader -->|"loads SDK game"| node_game_registration
node_sdk_capability_apis -->|"implements APIs"| node_capability_types
node_dev_harness -->|"uses mock contexts"| node_mock_context
node_dev_harness -->|"uses capability APIs"| node_sdk_capability_apis
node_dev_harness -->|"uses event inspector"| node_dev_event_inspector
node_mock_context -->|"creates branded values"| node_branded_types
node_ui_animation -.->|"supports UI motion"| node_ui_primitives

click node_game_registration "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/core/create-game.ts"
click node_metadata "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/types/metadata.ts"
click node_branded_types "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/types/branded.ts"
click node_capability_guard "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/core/capability-guard.ts"
click node_capability_types "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/types/capabilities.ts"
click node_game_context "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/types/context.ts"
click node_session_driver "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/platform/session.ts"
click node_game_renderer "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/platform/renderGame.ts"
click node_runtime "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/platform/runtime.ts"
click node_event_gate "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/platform/eventGate.ts"
click node_event_contracts "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/events/event-types.ts"
click node_event_emitter "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/events/event-emitter.ts"
click node_event_validation "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/events/event-validators.ts"
click node_game_state "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/state/index.ts"
click node_theme_tokens "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/theme/tokens.ts"
click node_theme_defaults "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/theme/defaults.ts"
click node_theme_context "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/theme/context.tsx"
click node_ui_primitives "https://github.com/secondsun-technologies/games-sdk/tree/main/packages/games-sdk/src/ui/primitives"
click node_ui_animation "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/ui/animation/motion.ts"
click node_simulator_app "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/App.tsx"
click node_device_profiles "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/deviceProfiles.ts"
click node_runtime_builder "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/runtimeBuilder.ts"
click node_game_loader "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/gameLoader.ts"
click node_control_panel "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/components/ControlPanel.tsx"
click node_device_frame "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/components/DeviceFrame.tsx"
click node_session_controls "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/components/SessionControls.tsx"
click node_event_inspector "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/components/EventInspector.tsx"
click node_sdk_capability_apis "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/dev/capability-apis.ts"
click node_dev_harness "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/dev/harness.ts"
click node_mock_context "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/dev/mock-context.ts"
click node_dev_event_inspector "https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/dev/event-inspector.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_game_registration,node_metadata,node_branded_types,node_capability_guard,node_capability_types,node_game_context,node_sdk_capability_apis,node_dev_harness,node_mock_context,node_dev_event_inspector,node_simulator_user toneBlue
class node_session_driver,node_game_renderer,node_runtime,node_event_gate toneAmber
class node_event_contracts,node_event_emitter,node_event_validation,node_game_state toneMint
class node_theme_tokens,node_theme_defaults,node_theme_context,node_ui_primitives,node_ui_animation toneRose
class node_simulator_app,node_device_profiles,node_runtime_builder,node_game_loader,node_control_panel,node_device_frame,node_session_controls,node_event_inspector,node_game_author toneIndigo
```

## Components

### Game Contract

- [Game registration](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/core/create-game.ts): `packages/games-sdk/src/core/create-game.ts`
- [Game metadata](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/types/metadata.ts): `packages/games-sdk/src/types/metadata.ts`
- [Branded identifiers](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/types/branded.ts): `packages/games-sdk/src/types/branded.ts`
- [Capability guard](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/core/capability-guard.ts): `packages/games-sdk/src/core/capability-guard.ts`
- [Capability contracts](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/types/capabilities.ts): `packages/games-sdk/src/types/capabilities.ts`
- [Lifecycle context](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/types/context.ts): `packages/games-sdk/src/types/context.ts`
- [Dev capability APIs](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/dev/capability-apis.ts): `packages/games-sdk/src/dev/capability-apis.ts`
- [Development harness](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/dev/harness.ts): `packages/games-sdk/src/dev/harness.ts`
- [Mock contexts](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/dev/mock-context.ts): `packages/games-sdk/src/dev/mock-context.ts`
- [SDK event inspector](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/dev/event-inspector.ts): `packages/games-sdk/src/dev/event-inspector.ts`

### Platform Runtime

- [Session lifecycle](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/platform/session.ts): `packages/games-sdk/src/platform/session.ts`
- [Platform game renderer](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/platform/renderGame.ts): `packages/games-sdk/src/platform/renderGame.ts`
- [Platform runtime](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/platform/runtime.ts): `packages/games-sdk/src/platform/runtime.ts`
- [Event gate](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/platform/eventGate.ts): `packages/games-sdk/src/platform/eventGate.ts`

### Events and State

- [Event contracts](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/events/event-types.ts): `packages/games-sdk/src/events/event-types.ts`
- [Event emitter](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/events/event-emitter.ts): `packages/games-sdk/src/events/event-emitter.ts`
- [Event validation](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/events/event-validators.ts): `packages/games-sdk/src/events/event-validators.ts`
- [Game state API](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/state/index.ts): `packages/games-sdk/src/state/index.ts`

### Game UI

- [Theme tokens](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/theme/tokens.ts): `packages/games-sdk/src/theme/tokens.ts`
- [Theme defaults](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/theme/defaults.ts): `packages/games-sdk/src/theme/defaults.ts`
- [Theme context](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/theme/context.tsx): `packages/games-sdk/src/theme/context.tsx`
- [UI primitives](https://github.com/secondsun-technologies/games-sdk/tree/main/packages/games-sdk/src/ui/primitives): `packages/games-sdk/src/ui/primitives`
- [Motion helpers](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk/src/ui/animation/motion.ts): `packages/games-sdk/src/ui/animation/motion.ts`

### SDK Simulator

- [Simulator app](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/App.tsx): `packages/games-sdk-simulator/src/App.tsx`
- [Device profiles](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/deviceProfiles.ts): `packages/games-sdk-simulator/src/deviceProfiles.ts`
- [Runtime builder](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/runtimeBuilder.ts): `packages/games-sdk-simulator/src/runtimeBuilder.ts`
- [Game loader](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/gameLoader.ts): `packages/games-sdk-simulator/src/gameLoader.ts`
- [Control panel](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/components/ControlPanel.tsx): `packages/games-sdk-simulator/src/components/ControlPanel.tsx`
- [Device frame](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/components/DeviceFrame.tsx): `packages/games-sdk-simulator/src/components/DeviceFrame.tsx`
- [Session controls](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/components/SessionControls.tsx): `packages/games-sdk-simulator/src/components/SessionControls.tsx`
- [Event inspector](https://github.com/secondsun-technologies/games-sdk/blob/main/packages/games-sdk-simulator/src/components/EventInspector.tsx): `packages/games-sdk-simulator/src/components/EventInspector.tsx`

### Other components

- **Game developer**
- **Simulator user**

## Connections

- Game developer → Game registration: registers game
- Game registration → Game metadata: validates metadata (evidence: `packages/games-sdk/src/core/create-game.ts`)
- Game developer → Capability guard: requests capabilities
- Capability guard → Capability contracts: checks declarations (evidence: `packages/games-sdk/src/core/capability-guard.ts`)
- Game registration → Capability contracts: checks declarations (evidence: `packages/games-sdk/src/core/create-game.ts`)
- Session lifecycle → Lifecycle context: creates snapshots (evidence: `packages/games-sdk/src/platform/session.ts`)
- Platform game renderer → Game registration: renders registered game (evidence: `packages/games-sdk/src/platform/renderGame.ts`)
- Platform game renderer → Lifecycle context: provides context (evidence: `packages/games-sdk/src/platform/renderGame.ts`)
- Platform game renderer → Platform runtime: uses runtime (evidence: `packages/games-sdk/src/platform/renderGame.ts`)
- Platform game renderer → Session lifecycle: uses session (evidence: `packages/games-sdk/src/platform/renderGame.ts`)
- Platform game renderer → Event gate: uses event gate (evidence: `packages/games-sdk/src/platform/renderGame.ts`)
- Game developer → Event emitter: emits observations
- Event emitter → Event validation: validates events (evidence: `packages/games-sdk/src/events/event-emitter.ts`)
- Event emitter → Event contracts: accepts event types (evidence: `packages/games-sdk/src/events/event-emitter.ts`)
- Event validation → Event contracts: validates event shapes (evidence: `packages/games-sdk/src/events/event-validators.ts`)
- Game developer → Game state API: requests state save
- Theme context → Theme tokens: uses tokens (evidence: `packages/games-sdk/src/theme/context.tsx`)
- Theme context → Theme defaults: loads defaults (evidence: `packages/games-sdk/src/theme/context.tsx`)
- UI primitives → Theme tokens: styles with tokens (evidence: `packages/games-sdk/src/ui/primitives/View.tsx`)
- Simulator user → Simulator app: configures and inspects (evidence: `packages/games-sdk-simulator/src/App.tsx`)
- Simulator app → Device profiles: selects profile (evidence: `packages/games-sdk-simulator/src/App.tsx`)
- Simulator app → Runtime builder: builds runtime (evidence: `packages/games-sdk-simulator/src/App.tsx`)
- Simulator app → Control panel: renders controls (evidence: `packages/games-sdk-simulator/src/App.tsx`)
- Simulator app → Device frame: renders device (evidence: `packages/games-sdk-simulator/src/App.tsx`)
- Simulator app → Event inspector: renders events (evidence: `packages/games-sdk-simulator/src/App.tsx`)
- Device frame → Game loader: loads game (evidence: `packages/games-sdk-simulator/src/components/DeviceFrame.tsx`)
- Device frame → Session controls: renders controls (evidence: `packages/games-sdk-simulator/src/components/DeviceFrame.tsx`)
- Simulator app → Event inspector: records events (evidence: `packages/games-sdk-simulator/src/App.tsx`)
- Game loader → Game registration: loads SDK game (evidence: `packages/games-sdk-simulator/src/gameLoader.ts`)
- Dev capability APIs → Capability contracts: implements APIs
- Development harness → Mock contexts: uses mock contexts (evidence: `packages/games-sdk/src/dev/index.ts`)
- Development harness → Dev capability APIs: uses capability APIs (evidence: `packages/games-sdk/src/dev/index.ts`)
- Development harness → SDK event inspector: uses event inspector (evidence: `packages/games-sdk/src/dev/index.ts`)
- Mock contexts → Branded identifiers: creates branded values (evidence: `packages/games-sdk/src/dev/mock-context.ts`)
- Motion helpers → UI primitives: supports UI motion
