Iframe Adventure

A minimal browser game where a fullscreen iframe serves as the background and a terminal-style overlay runs a text adventure on top.

Features

• Frontend: Vite + React with a clean, minimal single-screen interface
• Terminal Overlay: Retro terminal styling with scrolling log and single input field
• Dynamic Background: Fullscreen iframe that changes based on game events
• Backend: Node.js Express server with clean architecture
• Provider Interface: Extensible text generation with pluggable providers
• File-Based Persistence: Each game run saved as a single JSON file
• Automatic Cleanup: File rotation and cleanup for old game runs

Getting Started

Installation

npm install

Development

Run both frontend and backend in development mode:

npm run dev

This starts:

• Frontend on http://localhost:3000
• Backend API on http://localhost:3001

Build

Build the frontend for production:

npm run build

Architecture

Frontend (src/)

• App.jsx: Main game component with iframe background and terminal overlay
• App.css: Terminal styling with retro green-on-black aesthetic
• One screen, one input, scrolling log

Backend (server/)

• index.js: Express server with game API endpoints
• gameManager.js: Core game logic, state management, and file operations
• providers/: Text generation provider interface and implementations

Provider Interface

Create custom text generation providers by extending the TextProvider class:

import { TextProvider } from './providers/textProvider.js'

export class CustomProvider extends TextProvider {
  async generateResponse(action, gameState) {
    // Your implementation here
    return {
      text: 'Response text',
      context: 'optional-context-id',
      iframeUrl: 'optional-url-for-iframe'
    }
  }
}

Replace SimpleTextProvider in server/index.js with your custom provider.

Game Persistence

Each game run is saved as a JSON file in the runs/ directory:

• Filename format: game_<timestamp>_<random>.json
• Contains full game history and state
• Automatic cleanup of old files (configurable in gameManager.js)
• Default: keeps up to 100 runs, deletes files older than 7 days

API Endpoints

POST /api/game/start

Start a new game session.

Response:

{
  "gameId": "game_1234567890_abc123",
  "message": "Welcome message"
}

POST /api/game/action

Process a game action.

Request:

{
  "gameId": "game_1234567890_abc123",
  "action": "go north"
}

Response:

{
  "response": "Game response text",
  "iframeUrl": "https://example.com"
}

GET /api/game/:gameId

Retrieve game state.

Response:

{
  "gameId": "game_1234567890_abc123",
  "startTime": "2025-10-22T20:00:00.000Z",
  "lastUpdateTime": "2025-10-22T20:05:00.000Z",
  "history": [...],
  "currentContext": "start"
}

Customization

Text Provider

Swap out SimpleTextProvider with:

• OpenAI GPT integration
• Local LLM (Ollama, etc.)
• Other AI services
• Rule-based systems

Styling

Modify src/App.css to customize:

• Terminal colors
• Overlay position and size
• Font and text styling

Game Logic

Update server/providers/simpleTextProvider.js to add:

• More locations
• Complex interactions
• Dynamic URL mappings

License

MIT