Game Interface Components
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Game Interface Components reside primarily within the cyoa-engine, a Next.js 14 application that serves as the interactive frontend for the Model Context Protocol (MCP) Games ecosystem. Its purpose is to provide a user-facing layer for engaging with Choose Your Own Adventure (CYOA) narratives that are dynamically personalized through semantic queries to connected MCP servers like GitHub, Linear, and Notion.
The interface manages real-time story progression, choice selection, and MCP connection configurations. It bridges the gap between the core logic in the story-engine and the AI-generated content from the narrative-ai service, ensuring a seamless flow of state and narrative data to the player.
Sources: apps/cyoa-engine/README.md:1-12, README.md:21-30
Core UI Structure and Layout
The application utilizes the Next.js App Router architecture. The root layout provides the global styling and font configuration, while individual pages define the functional areas of the game.
Main Landing Interface
The primary entry point (page.tsx) features a landing container that introduces the user to the CYOA engine and provides immediate actions for starting adventures and configuring integrations.
| Component Element | Description |
|---|---|
| Adventure Title | Displays "MCP Games - CYOA Engine" as the primary heading. |
| Contextual Narrative | Paragraph explaining the integration of semantic MCP querying for personalized stories. |
| Feature Highlights | Visual indicators for MCP Integration, AI-Powered Narratives, and Personalized Choices. |
| Action Buttons | "Start Adventure" for game entry and "Configure MCPs" for management. |
Sources: apps/cyoa-engine/app/page.tsx:1-42, apps/cyoa-engine/app/layout.tsx:1-24
UI Flow Diagram
The following diagram illustrates the high-level user flow from the entry page into the core game loop.
State and Data Components
The interface relies on structured data types to render the narrative and handle user interactions. These types ensure consistency between the frontend components and the backend services.
Scene and Choice Representation
The UI renders a Scene object which contains the text of the narrative and an array of Choice objects. Each choice is interactive and triggers state transitions.
| Field | Type | Description |
|---|---|---|
narrative | string | The main story text to be displayed to the user. |
choices | Choice[] | Interactive elements the user can click to progress. |
id | string | Unique identifier for the current scene. |
Sources: packages/shared-types/src/index.ts:54-61
Game Progress and Persistence
The interface tracks progress through the GameProgress interface, which is used for saving and loading states.
export interface GameProgress {
storyId: string;
currentSceneId: string;
variables: StoryVariables;
choices: string[];
timestamp: string;
}
Sources: packages/shared-types/src/index.ts:114-120
Integration and Communication
The interface components communicate with external services and internal engines to maintain the game loop.
Service Connectivity
The frontend is configured to communicate with two primary backend services via environment variables.
- MCP Connector: Handles data from GitHub, Linear, etc.
- Narrative AI: Generates the dynamic story text.
Logic Processing
When a user selects a choice in the interface, the StoryEngine processes the logic to determine the next scene and apply variable effects.
- Requirement Check: The UI must verify if
ChoiceRequirements(variables or MCP data) are met before enabling a choice button. - Effect Application: When clicked, the engine applies
VariableEffectoperations (set, increment, decrement, append) to the global story variables. - State Update: The UI re-renders based on the updated
StoryState.
Sources: packages/story-engine/src/index.ts:55-80, packages/shared-types/src/index.ts:70-85
Technical Configuration
The cyoa-engine uses Tailwind CSS for styling and is optimized through the Next.js compiler settings.
- Transpilation: The app is configured to transpile internal monorepo packages:
shared-types,mcp-sdk, andstory-engine. - Styling: Utilizes a dark/light mode compatible theme with specific color accents (Blue-500 for MCP, Green-500 for AI).
Sources: apps/cyoa-engine/next.config.js:4-10, apps/cyoa-engine/app/page.tsx:21-32
Summary
The Game Interface Components provide a sophisticated, context-aware environment for CYOA gameplay. By integrating the StoryEngine logic directly with the Next.js frontend and connecting to the mcp-connector, the system allows players to experience stories that are not static, but rather respond to both their in-game choices and their real-world professional context.