@yred/mgc-web-bridge
v1.0.3
Published
A bridge for two-way communication between a web app and WebGL games in iframes.
Maintainers
yreddReadme
MGC Game Center Bridge
A lightweight, modular, and extendable JavaScript library for enabling two-way communication between a web application (a "Game Center") and WebGL games running in iframes.
game-center-bridge abstracts away the complexities of window.postMessage, providing a simple, event-driven API for sending commands and data between your main application and your games.
Features
Simple Event-Driven API: Uses familiar on() and emit() methods.
Two-Way Communication: Send commands from the Game Center to the Game, and emit events from the Game back to the Game Center.
Secure: Specifies message origins to prevent cross-origin conflicts.
Extendable: Easily define and handle custom events and commands for your specific application needs.
Lightweight: No dependencies, minimal footprint.
UMD Build: Can be used via tags or imported in modern JavaScript projects (e.g., with React, Vue, Angular).
How It Works
The library consists of two main classes:
GameCenterHost: This class is used by your main web application (the "host"). It creates and manages communication with a game loaded in an .
GameClient: This class is used by your WebGL game (the "client"). It connects to the host window and sends events to it.
Communication is handled securely via window.postMessage. The library wraps this mechanism in a clean, developer-friendly API.
Installation
npm install @yred/mgc-web-bridgeUsage
1. In Your Game Center Application (The Host)
First, import or include the GameCenterHost class. Then, instantiate it by passing the game's element and the expected origin of the game.
<!-- game-center.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<title>Game Center</title>
<style>
iframe { width: 800px; height: 600px; border: 2px solid #ccc; }
</style>
</head>
<body>
<h1>My Awesome Game Center</h1>
<iframe id="game-iframe" src="http://localhost:8081/game.html"></iframe>
<button id="pause-button">Pause Game</button>
<button id="play-button">Play Game</button>
<script src="dist/game-center-bridge.umd.js"></script>
<script>
const iframe = document.getElementById('game-iframe');
const pauseBtn = document.getElementById('pause-button');
const playBtn = document.getElementById('play-button');
// The origin where the game is hosted. For security.
// Use '*' for development only, not for production.
const gameOrigin = 'http://localhost:8081';
const gameHost = new window.GameCenterBridge.GameCenterHost(iframe, gameOrigin);
// Listen for events from the game
gameHost.on('game_loaded', () => {
console.log('Host: Game has loaded its assets and is ready!');
// Example: Send user data to the game after it loads
gameHost.sendCommand('load_user_profile', { username: 'Player1', level: 15 });
});
gameHost.on('score_update', (data) => {
console.log(`Host: Received score update! New score: ${data.score}`);
document.getElementById('score-display').innerText = `Score: ${data.score}`;
});
gameHost.on('game_over', (data) => {
console.log(`Host: Game over! Final score: ${data.finalScore}`);
alert(`Game Over! Your final score was ${data.finalScore}`);
});
// Send commands to the game
pauseBtn.addEventListener('click', () => {
gameHost.sendCommand('pause');
});
playBtn.addEventListener('click', () => {
gameHost.sendCommand('play');
});
</script>
</body>
</html>2. In Your WebGL Game (The Client)
In your game's code, import or include the GameClient class and instantiate it.
<!-- game.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<title>My Awesome WebGL Game</title>
</head>
<body>
<canvas id="game-canvas"></canvas>
<script src="dist/game-center-bridge.umd.js"></script>
<script>
// Use the same origin as the host, or '*' for development
const hostOrigin = 'http://localhost:8080';
const gameClient = new window.GameCenterBridge.GameClient(hostOrigin);
// Listen for commands from the Game Center
gameClient.on('load_user_profile', (profile) => {
console.log('Game: Received user profile', profile);
// myGame.loadPlayer(profile);
});
gameClient.on('pause', () => {
console.log('Game: Pause command received.');
// myGame.pause();
});
gameClient.on('play', () => {
console.log('Game: Play command received.');
// myGame.play();
});
// --- Game Logic Example ---
// Simulate the game loading
setTimeout(() => {
// Emit an event to the host when the game is ready
gameClient.emit('game_loaded');
}, 1000);
// Simulate score updates
let score = 0;
setInterval(() => {
score += 100;
// Emit a score update
gameClient.emit('score_update', { score: score });
}, 2000);
// Simulate game over
setTimeout(() => {
// Emit a game over event with the final score
gameClient.emit('game_over', { finalScore: score });
}, 10000);
</script>
</body>
</html>API Reference
GameCenterHost new GameCenterHost(iframeElement, targetOrigin) iframeElement (HTMLIFrameElement): The iframe element where the game is running.
targetOrigin (String): The origin of the game's URL. This is a crucial security feature. For example, 'https://my-game-domain.com'. Use '*' only for development.
host.on(eventName, listener) eventName (String): The name of the event to listen for from the client.
listener (Function): A callback function that will be executed when the event is received. It will be passed the event payload.
host.sendCommand(commandName, [payload]) commandName (String): The name of the command to send to the client.
payload (*, optional): Any data to send along with the command. The data must be serializable (can be converted to JSON).
host.dispose() Removes the message event listener. Call this when the iframe is removed or the host component is unmounted to prevent memory leaks.
GameClient new GameClient(targetOrigin) targetOrigin (String): The origin of the host window. Crucial for security.
client.on(commandName, listener) commandName (String): The name of the command to listen for from the host.
listener (Function): A callback function that will be executed when the command is received. It will be passed the command payload.
client.emit(eventName, [payload]) eventName (String): The name of the event to emit to the host.
payload (*, optional): Any data to send along with the event. Must be serializable.
client.dispose() Removes the message event listener.
Building from Source
If you want to contribute or modify the library, you'll need to build it from the source code.
Clone the repository:
git clone https://github.com/Y0red/mgc-web-bridge.git
cd game-center-bridgeInstall dependencies:
npm installRun the build:
npm run buildThis will generate the distributable files in the /dist directory.
By Y@red
License This project is licensed under the MIT License.