@beincom/bic-miner-adventure

A comprehensive game SDK for the BIC Miner Adventure game, providing seamless integration with React applications and robust API management.

🚀 Features

• Easy Integration: Simple setup with React applications
• Type Safety: Full TypeScript support with comprehensive type definitions
• Automatic Token Refresh: Built-in session management with automatic token renewal
• Customizable Hooks: Flexible event handling system for game interactions
• Modern API Client: RESTful API integration with error handling and retry mechanisms
• Lightweight: Optimized bundle size for production applications

📦 Installation

Choose your preferred package manager:

# npm
npm i @beincom/bic-miner-adventure

# yarn
yarn add @beincom/bic-miner-adventure

# pnpm
pnpm add @beincom/bic-miner-adventure

# bun
bun add @beincom/bic-miner-adventure

🛠️ Quick Start

1. Basic Setup

import React, { useRef, useEffect } from 'react';
import {
  setApiServer,
  GameApi,
  setGameHook,
  StartGame
} from '@beincom/bic-miner-adventure';

// Configure API client
setApiServer(new GameApi({
  baseUrl: 'https://game.beincom.io/v1/miner-adventure',
  baseApiParams: {
    format: 'json',
    headers: {
      'Content-Type': 'application/json',
      // Add your custom headers here
    }
  },
  refreshSession: async () => {
    // Implement your token refresh logic
    const newToken = await refreshAuthToken();
    return newToken;
  }
}));

// Configure game event hooks
setGameHook({
  openShop: (item: string) => {
    // Handle shop opening
    console.log('Opening shop for item:', item);
    // Your shop opening logic here
  },
  reload: () => {
    // Handle game reload on critical errors
    console.log('Reloading game...');
    window.location.reload();
  }
});

// Game container component
export const GameContainer: React.FC = () => {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (containerRef.current) {
      StartGame(containerRef.current);
    }
  }, []);

  return (
    <div 
      ref={containerRef}
      style={{ width: '100%', height: '100vh' }}
    />
  );
};

2. Advanced Configuration

import { GameApi, GameHookConfig } from '@beincom/bic-miner-adventure';

// Advanced API configuration
const gameApi = new GameApi({
  baseUrl: process.env.REACT_APP_GAME_API_URL,
  baseApiParams: {
    format: 'json',
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json',
      'X-Client-Version': '1.0.0',
    }
  },
  refreshSession: async () => {
    try {
      const response = await fetch('/api/auth/refresh', {
        method: 'POST',
        credentials: 'include',
      });
      
      if (!response.ok) {
        throw new Error('Token refresh failed');
      }
      
      const { token } = await response.json();
      localStorage.setItem('authToken', token);
      return token;
    } catch (error) {
      console.error('Failed to refresh session:', error);
      // Redirect to login or handle accordingly
      window.location.href = '/login';
      throw error;
    }
  }
});

// Advanced game hooks configuration
const gameHooks: GameHookConfig = {
  openShop: (item: string) => {
    // Track analytics
    analytics.track('shop_opened', { item });
    
    // Open custom shop modal
    openShopModal(item);
  },
  
  reload: () => {
    // Log error before reload
    console.error('Game encountered critical error, reloading...');
    
    // Show loading indicator
    showLoadingSpinner();
    
    // Reload after delay
    setTimeout(() => {
      window.location.reload();
    }, 1000);
  },
};

setApiServer(gameApi);
setGameHook(gameHooks);

📚 API Reference

Core Functions

setApiServer(api: GameApi)

Configures the game API client.

Parameters:

• api: GameApi instance with configuration

setGameHook(hooks: GameHookConfig)

Sets up event handlers for game interactions.

Parameters:

• hooks: Object containing event handler functions

StartGame(container: HTMLElement)

Initializes and starts the game in the specified container.

Parameters:

• container: HTML element where the game will be rendered

GameApi Configuration

interface GameApiConfig {
  baseUrl: string;
  baseApiParams?: {
    format?: 'json' | 'text' | 'blob';
    credentials?: RequestCredentials;
    headers?: Record<string, string>;
  };
  refreshSession?: () => void;
}

Game Hook Configuration

interface GameHookConfig {
  openShop: (item: string) => void;
  reload: () => void;
  // Additional hooks as needed
}

🔧 Environment Variables

Create a .env file in your project root:

REACT_APP_GAME_API_URL=https://game.beincom.io/v1/miner-adventure

🎮 Game Integration Examples

With Next.js

// pages/game.tsx
import dynamic from 'next/dynamic';

const GameContainer = dynamic(
  () => import('../components/GameContainer'),
  { ssr: false }
);

export default function GamePage() {
  return (
    <div>
      <h1>BIC Miner Adventure</h1>
      <GameContainer />
    </div>
  );
}

With Vite

// src/Game.tsx
import { GameContainer } from './components/GameContainer';

function App() {
  return (
    <div className="app">
      <header>
        <h1>BIC Miner Adventure</h1>
      </header>
      <main>
        <GameContainer />
      </main>
    </div>
  );
}

export default App;

Development Setup

# Clone the repository
git clone https://github.com/beincom/bic-mini-games/bic-miner-adventure.git

# Install dependencies
pnpm install

# Run development server
pnpm run dev

🚀 Roadmap

• [x] Mobile optimization
• [x] WebGL renderer improvements
• [x] Offline mode support
• [x] Advanced analytics integration
• [x] Multi-language support

Made with ❤️ by the Beincom team