Host Status, Constants, and Error Codes

1 Host State RuntimeState

During the running process, the host will go through different states, which can be obtained via gameHandle.getGameState().

1.1 Status Enumeration

Status	Value	Description
UNAVAILABLE	unavailable	Unavailable state, host has not been initialized
WAITING	waiting	Waiting state, initialized but game not started
RUNNING	running	Running state, the game is loading
PLAYING	playing	Play state, the game is running

1.2 State Transition Diagram

UNAVAILABLE
    ↓ (initialize)
WAITING
    ↓ (start)
RUNNING
    ↓ (play)
PLAYING
    ↓ (stop/destroy)
WAITING/UNAVAILABLE

1.3 Code Example

const { RuntimeState } = require('webglhost-runtime-pc');

// Get current game state
const state = gameHandle.getGameState();
console.log('Current game state:', state);

// Check state
if (state === RuntimeState.PLAYING) {
  console.log('Game is playing');
} else if (state === RuntimeState.RUNNING) {
  console.log('Game is running');
}

// State constants
console.log('Available states:');
console.log('UNAVAILABLE:', RuntimeState.UNAVAILABLE);
console.log('WAITING:', RuntimeState.WAITING);
console.log('RUNNING:', RuntimeState.RUNNING);
console.log('PLAYING:', RuntimeState.PLAYING);

2 Constant Definition TJConstants

TJConstants contains constant definitions for game startup parameters, and using these constants can avoid hard-coded strings.

2.1 Game Startup Parameter Constants

const { TJConstants } = require('webglhost-runtime-pc');

// Commonly used constants
TJConstants.LAUNCH_KEY              // 'launchKey'
TJConstants.USER_ID                 // 'userId'
TJConstants.GAME_ID                 // 'gameId'
TJConstants.ACCESS_TOKEN            // 'accessToken'

// Debug and inspector
TJConstants.ENABLE_VCONSOLE         // 'enableVConsole'
TJConstants.ENABLE_INSPECTOR        // 'enableInspector'
TJConstants.INSPECTOR_WAIT_FOR_INSPECT  // 'waitForInspect'

// UI configuration
TJConstants.SHOW_MENU_LAYOUT        // 'showMenuLayout'
TJConstants.SHOW_MENU_EXPLORE_BTN   // 'showMenuExploreBtn'
TJConstants.SPLASH_ICON_URL         // 'splashIconUrl'
TJConstants.SPLASH_GAME_TITLE       // 'splashGameTitle'

// Custom scripts
TJConstants.CUSTOM_SCRIPT_FILES     // 'customScriptFiles'
TJConstants.CUSTOM_SCRIPT_CONTENTS  // 'customScriptContents'

// Domain whitelist
TJConstants.ENABLE_DOMAIN_WHITELIST      // 'enableDomainWhiteList'
TJConstants.DOMAIN_WHITELIST_REQUEST     // 'domainWhiteListRequest'
TJConstants.DOMAIN_WHITELIST_SOCKET      // 'domainWhiteListSocket'
TJConstants.DOMAIN_WHITELIST_UDP         // 'domainWhiteListUDP'
TJConstants.DOMAIN_WHITELIST_TCP         // 'domainWhiteListTCP'
TJConstants.DOMAIN_WHITELIST_UPLOAD_FILE // 'domainWhiteListUploadFile'
TJConstants.DOMAIN_WHITELIST_DOWNLOAD_FILE // 'domainWhiteListDownloadFile'

// Audio and visual
TJConstants.ENABLE_MUTE_ALL_AUDIO   // 'enableMuteAllAudio'
TJConstants.ENABLE_TRANSPARENT_MODE // 'enableTransparentMode'

2.2 Usage Example

const { TJConstants } = require('webglhost-runtime-pc');

const options = {
  [TJConstants.LAUNCH_KEY]: 'my-launch-key',
  [TJConstants.USER_ID]: 'user-123',
  [TJConstants.ENABLE_VCONSOLE]: true,
  [TJConstants.SHOW_MENU_LAYOUT]: true,
  [TJConstants.CUSTOM_SCRIPT_FILES]: ['./script1.js', './script2.js'],
  [TJConstants.DOMAIN_WHITELIST_REQUEST]: [
    'https://api.example.com',
    'https://cdn.example.com'
  ]
};

await gameHandle.setGameStartOptions(options);

3 Error Code HostRuntimeError

3.1 Error Class Definition

const { HostRuntimeError } = require('webglhost-runtime-pc');

// All errors are instances of HostRuntimeError class
class HostRuntimeError extends Error {
  constructor(code, message) {
    super(message);
    this.code = code;
    this.name = 'HostRuntimeError';
  }
}

3.2 Core Error Codes

Error Code	Meaning	Error Handling Suggestions
SDK_INITIALIZATION_FAILED	SDK Initialization Failed	Check SDK Key
GAME_ID_NOT_SET	Game ID not set	Provide a valid game ID
LAUNCH_KEY_NOT_SET	Startup key not set	Provide the startup key
USER_NOT_AVAILABLE	User unavailable	Check User ID
GAME_NOT_FOUND	Game not found	Check Game ID and Key
GAME_QR_SESSION_EXPIRED	The game QR code session has expired	Rescan QR Code
SERVER_RESPONSE_ERROR	Server response error	Check network and service status
GAME_HANDLE_UNINITIALIZED	Game handle is not initialized	First initialize the game handle
NETWORK_ERROR	Network Error	Check network connection
FILE_SYSTEM_ERROR	File system error	Check file path and permissions
AUDIO_ERROR	Audio Error	Check audio device
PERMISSION_ERROR	Permission Error	Check system permissions

3.3 Error Handling Example

const { TJHostHandle, HostRuntimeError } = require('webglhost-runtime-pc');

// Example 1: Handling initialization error
TJHostHandle.initialize('sdk-key', 'sdk-secret', (hostHandle, error) => {
  if (error) {
    if (error.code === 'SDK_INITIALIZATION_FAILED') {
      console.error('SDK initialization failed:', error.message);
      console.error('Please check your SDK credentials');
    } else {
      console.error('Initialization error:', error.code, error.message);
    }
    return;
  }
  
  console.log('SDK initialized successfully');
});

// Example 2: Handling game start error
async function startGame(gameHandle, options) {
  try {
    await gameHandle.setGameStartOptions(options);
    await gameHandle.start();
  } catch (error) {
    if (error instanceof HostRuntimeError) {
      switch (error.code) {
        case 'LAUNCH_KEY_NOT_SET':
          console.error('Launch key is required');
          break;
        case 'USER_NOT_AVAILABLE':
          console.error('User ID is required');
          break;
        case 'GAME_NOT_FOUND':
          console.error('Game not found, check your game ID');
          break;
        case 'NETWORK_ERROR':
          console.error('Network error, please check your connection');
          break;
        default:
          console.error('Game start error:', error.code, error.message);
      }
    } else {
      console.error('Unexpected error:', error);
    }
  }
}

// Example 3: Creating custom errors
const customError = HostRuntimeError.create('CUSTOM_ERROR', 'Custom error message');
throw customError;

// Example 4: Converting network errors
try {
  // Network operation
} catch (networkError) {
  const runtimeError = HostRuntimeError.fromNetworkError(networkError);
  console.error('Runtime error:', runtimeError.code, runtimeError.message);
}

3.4 Error Handling Best Practices

class ErrorHandler {
  constructor() {
    this.errorListeners = [];
  }

  onError(listener) {
    this.errorListeners.push(listener);
  }

  handleError(error) {
    console.error('[ErrorHandler] Error occurred:', error);

    // Notify all listeners
    for (const listener of this.errorListeners) {
      try {
        listener(error);
      } catch (e) {
        console.error('[ErrorHandler] Listener error:', e);
      }
    }

    // Handle specific error types
    if (error instanceof HostRuntimeError) {
      return this.handleHostRuntimeError(error);
    }

    return this.handleGenericError(error);
  }

  handleHostRuntimeError(error) {
    const errorHandlers = {
      'SDK_INITIALIZATION_FAILED': () => {
        return {
          title: 'Initialization Failed',
          message: 'Failed to initialize SDK. Please check your credentials.',
          recoverable: false
        };
      },
      'LAUNCH_KEY_NOT_SET': () => {
        return {
          title: 'Configuration Error',
          message: 'Game launch key is missing.',
          recoverable: false
        };
      },
      'NETWORK_ERROR': () => {
        return {
          title: 'Network Error',
          message: 'Please check your internet connection and try again.',
          recoverable: true
        };
      },
      'GAME_NOT_FOUND': () => {
        return {
          title: 'Game Not Found',
          message: 'The requested game could not be found.',
          recoverable: false
        };
      }
    };

    const handler = errorHandlers[error.code];
    if (handler) {
      return handler();
    }

    return {
      title: 'Error',
      message: error.message || 'An unknown error occurred',
      recoverable: false
    };
  }

  handleGenericError(error) {
    return {
      title: 'Unexpected Error',
      message: error.message || 'An unexpected error occurred',
      recoverable: false
    };
  }
}

// Usage
const errorHandler = new ErrorHandler();

errorHandler.onError((error) => {
  console.log('Error occurred:', error);
  // Show error dialog, send to analytics, etc.
});

// When an error occurs
try {
  await gameHandle.start();
} catch (error) {
  const errorInfo = errorHandler.handleError(error);
  console.log('Error info:', errorInfo);
  
  // Show error UI
  if (errorInfo.recoverable) {
    // Show retry button
  } else {
    // Show error message and exit
  }
}

4 Complete Example

const { 
  TJHostHandle, 
  RuntimeState, 
  TJConstants, 
  HostRuntimeError 
} = require('webglhost-runtime-pc');

class GameManager {
  constructor() {
    this.hostHandle = null;
    this.gameHandle = null;
    this.currentState = RuntimeState.UNAVAILABLE;
  }

  async initialize(sdkKey, sdkSecret) {
    return new Promise((resolve, reject) => {
      TJHostHandle.initialize(sdkKey, sdkSecret, (hostHandle, error) => {
        if (error) {
          this.handleError(error);
          reject(error);
          return;
        }
        
        this.hostHandle = hostHandle;
        this.currentState = RuntimeState.WAITING;
        resolve();
      });
    });
  }

  async createGame() {
    try {
      this.gameHandle = await this.hostHandle.createGameHandle();
      this.setupStateTracking();
      console.log('Game handle created');
    } catch (error) {
      this.handleError(error);
      throw error;
    }
  }

  setupStateTracking() {
    // Monitor state changes
    const checkState = () => {
      const newState = this.gameHandle.getGameState();
      if (newState !== this.currentState) {
        console.log(`State changed: ${this.currentState} -> ${newState}`);
        this.currentState = newState;
        this.onStateChanged(newState);
      }
    };

    // Check state periodically
    setInterval(checkState, 1000);
  }

  onStateChanged(newState) {
    console.log(`Current state: ${newState}`);
    
    switch (newState) {
      case RuntimeState.UNAVAILABLE:
        console.log('Game is unavailable');
        break;
      case RuntimeState.WAITING:
        console.log('Ready to start game');
        break;
      case RuntimeState.RUNNING:
        console.log('Game is loading');
        break;
      case RuntimeState.PLAYING:
        console.log('Game is playing');
        break;
    }
  }

  async startGame(launchKey, userId) {
    try {
      const options = {
        [TJConstants.LAUNCH_KEY]: launchKey,
        [TJConstants.USER_ID]: userId,
        [TJConstants.ENABLE_VCONSOLE]: false,
        [TJConstants.SHOW_MENU_LAYOUT]: true
      };

      await this.gameHandle.setGameStartOptions(options);
      await this.gameHandle.start();
      this.gameHandle.play();
      
      console.log('Game started successfully');
    } catch (error) {
      this.handleError(error);
      throw error;
    }
  }

  handleError(error) {
    if (error instanceof HostRuntimeError) {
      console.error(`[${error.code}] ${error.message}`);
      
      // Handle specific errors
      switch (error.code) {
        case 'SDK_INITIALIZATION_FAILED':
          console.error('Please verify your SDK credentials');
          break;
        case 'LAUNCH_KEY_NOT_SET':
          console.error('Launch key is required to start the game');
          break;
        case 'NETWORK_ERROR':
          console.error('Network connection failed, please check your internet');
          break;
        default:
          console.error('An error occurred:', error.message);
      }
    } else {
      console.error('Unexpected error:', error);
    }
  }

  getState() {
    return this.currentState;
  }

  isPlaying() {
    return this.currentState === RuntimeState.PLAYING;
  }

  isPaused() {
    return this.currentState === RuntimeState.PAUSED;
  }

  canStart() {
    return this.currentState === RuntimeState.WAITING;
  }
}

// Usage
async function main() {
  const manager = new GameManager();

  try {
    // Initialize
    await manager.initialize('sdk-key', 'sdk-secret');
    console.log('Manager initialized, state:', manager.getState());

    // Create game
    await manager.createGame();
    console.log('Game created, state:', manager.getState());

    // Start game
    await manager.startGame('launch-key', 'user-123');
    console.log('Game started, state:', manager.getState());

    // Check state
    if (manager.isPlaying()) {
      console.log('Game is now playing');
    }

  } catch (error) {
    console.error('Failed to start game:', error);
  }
}

main();

5 Status and Error Code Reference Quick Lookup

5.1 Quick Status Check

// Check if game can be started
if (gameHandle.getGameState() === RuntimeState.WAITING) {
  await gameHandle.start();
}

// Check if game is playing
if (gameHandle.getGameState() === RuntimeState.PLAYING) {
  console.log('Game is currently playing');
}

// Check if game is running
if (gameHandle.getGameState() === RuntimeState.RUNNING) {
  console.log('Game is loading/running');
}

5.2 Quick Error Handling

try {
  // Game operations
} catch (error) {
  if (error.code === 'NETWORK_ERROR') {
    // Retry logic
  } else if (error.code === 'SDK_INITIALIZATION_FAILED') {
    // Show error and exit
  }
}