electron-game-engine

Introduction

electron-game-engine is a lightweight, Electron-based game engine designed for creating canvas-based games with robust mod support. It features a persistent draw stack system for rendering graphics, a mod loader with auto-update capabilities, and a secure architecture adhering to Electron's security best practices. This engine is perfect for developers building cross-platform games with a focus on modularity, extensibility, and ease of use.

Installation

npm install electron-game-engine

Usage

Basic Setup

To integrate the engine into your Electron project:

const { app } = require('electron');
const GameEngine = require('electron-game-engine');

GameEngine.initialize('./mods'); // Specify your mod folder

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit();
});

Adding Items to the Draw Stack

Add renderable items to the draw stack with a unique name. Items persist until explicitly removed:

GameEngine.addToDrawStack({
  name: 'player',
  type: 'rect',
  x: 100,
  y: 100,
  width: 50,
  height: 50,
  color: 'blue',
  onClick: () => console.log('Player clicked!')
});

Removing Items from the Draw Stack

Remove items by their unique name:

GameEngine.removeFromDrawStack('player');

Managing Mods

• Toggle Mods: Enable or disable a mod by name:

  GameEngine.toggleMod('Sample Mod');

• Load Mods: Activate or deactivate mods based on their enabled state:

  GameEngine.loadMods();

Mod Format

Mods are ZIP files with the following structure:

mod.zip/
├── manifest.json
└── main.js

manifest.json

{
  "name": "Sample Mod",
  "author": "Author Name",
  "description": "A sample mod",
  "entry": "main.js",
  "updateKey": "https://example.com/sample-mod/manifest.json",
  "version": "1.0.0"
}

• updateKey: URL to a remote manifest for auto-updates (optional).
• version: Semantic version of the mod (e.g., "1.0.0").

main.js

module.exports = {
  activate: () => {
    console.log('Mod activated');
  },
  deactivate: () => {
    console.log('Mod deactivated');
  },
  render: (drawStack) => {
    drawStack.push({
      name: 'modRect',
      type: 'rect',
      x: 50,
      y: 50,
      width: 100,
      height: 100,
      color: 'red'
    });
  }
};

• Required: Mods must implement activate() and deactivate() functions.

Place mod ZIP files in the specified modFolder (default: ~/.my-game-engine/mods).

API Reference

GameEngine.initialize(modFolder)

• modFolder (string, optional): Directory to scan for mod ZIP files. Defaults to ~/.my-game-engine/mods.
• Initializes the engine within app.whenReady, creating a fullscreen window, scanning mods, and setting up a temporary folder for mod extraction.

GameEngine.addToDrawStack(item)

• item (object): Item to add to the draw stack.
  • name (string, required): Unique identifier for the item.
  • type (string, required): Type of item (e.g., rect).
  • Other properties: x, y, width, height, color, text, onClick.
• Adds an item to the draw stack, persisting until removed.

GameEngine.removeFromDrawStack(name)

• name (string): Name of the item to remove.
• Removes an item from the draw stack by its name and re-renders.

GameEngine.toggleMod(modName)

• modName (string): Name of the mod to toggle.
• Toggles the enabled state of a mod. Call loadMods to apply changes.

GameEngine.loadMods()

• Deactivates all active mods by calling their deactivate functions, cleans up their temp folders, then unzips and activates enabled mods by calling their activate functions. Updates the draw stack.

GameEngine.handleClick(x, y)

• x (number): X-coordinate of the click.
• y (number): Y-coordinate of the click.
• Triggers the onClick function of any draw stack item at the clicked coordinates.

Draw Stack System

The draw stack is a persistent array of renderable items drawn each frame. Items remain until removed using removeFromDrawStack.

Item Properties

• name (string, required): Unique identifier for removal and management.
• type (string, required): Defines the rendering method.
• x, y (number): Position coordinates.
• width, height (number): Size for applicable types (e.g., rect).
• color (string): Fill color (e.g., 'red', '#FF0000').
• text (string, optional): Text to display (for rect).
• onClick (function, optional): Callback for click events.

Supported Types

• rect: A rectangle with position, size, color, and optional text.

Mod System

Mods extend the engine's functionality and are loaded from ZIP files in the mod folder.

Mod Lifecycle

• Scanning: Mods are scanned on initialization, storing their metadata and ZIP paths.
• Enabling/Disabling: Use toggleMod to change the enabled state.
• Activation: On loadMods, enabled mods are unzipped to a hidden .temp folder, loaded via require, and their activate function is called. Must have activate and deactivate.
• Deactivation: On loadMods or app exit, active mods' deactivate functions are called, and their temp folders are deleted.
• Rendering: Active mods can add to the draw stack via their render function.

Auto-Update

Mods with an updateKey URL are checked for updates on load:

• Fetches the remote manifest.
• Compares versions; if newer, downloads the updated ZIP and updates the mod metadata.

Example Remote Manifest

{
  "version": "1.0.1",
  "updateUrl": "https://example.com/sample-mod/mod.zip"
}

Temporary Folder

• Located at modFolder/.temp.
• Created on initialization.
• Subfolders named after mods are created on activation and deleted on deactivation or app exit.

Security

• Node Integration: Disabled (nodeIntegration: false) to prevent renderer access to Node.js.
• Context Isolation: Enabled (contextIsolation: true) for secure renderer context.
• Mod Execution: Runs in the main process, isolated from the renderer, with temp folder cleanup.

Development

Testing Locally

npm start

Publishing to npm

npm publish --access public

Contributing

Fork the repository, make changes, and submit a pull request. Ensure tests pass and adhere to the MIT license.

License

MIT