Samengine 🎮

A lightweight, TypeScript-first web game engine framework for building 2D games and maybe 3D Games in the Future.

Index

• Features
• Info
• Quick Start
  • Basic Game Loop
• Development & Building
  • Using Bun (local development)
• Config
• API Reference
  • Core Engine
  • Rendering
  • Input System
  • Types
  • Utilities
• License
• More Addons in the Game Library
• More Tools for samengine and Game Making by me lol
• Commit Tags

Features

• 🎯 Simple game loop management
• 🎨 Rendering system with text and sprite support
• ⌨️ Input handling (keyboard & mouse)
• 📦 TypeScript support out of the box
• 🛠️ Build tools included
• 📝 Logging utilities
• 💾 Save/Load system

Info

For better Infos read the Docs

Quick Start

# Make sure both of them have the same Version

npm init
npm install samengine
npm install samengine-build
npx samengine-build --new
npx samengine-build

Basic Game Loop

import { startEngine, setupInput, dlog, renderText
} from 'samengine';

const { canvas, ctx, applyScaling, virtualWidth, virtualHeight

} = createCanvas({ fullscreen: true, scaling: "fit",
virtualWidth: 1920, virtualHeight: 1080 });
setupInput(canvas, virtualWidth, virtualHeight);

function init() {
  dlog('🎮 Game initialized!');
}

function gameLoop(dt: number) {
  // Clear canvas
  ctx.fillStyle = 'black';
  ctx.fillRect(0, 0, canvas.width, canvas.height);
  
  // Your game logic here
  renderText(ctx, `FPS: ${(1 / dt).toFixed(0)}`, 10, 20);
}

startEngine(init, gameLoop);

Development & Building

Using Bun (local development)

npx samengine-build                       # Start Dev Server
npx samengine-build --release             # Production build
npx samengine-build --new (newproject)    # Create a new project with a
                                          # simple Snake Clone as Template
npx samengine-build --new-empty (new)     # Create a new empty project

Config

// Project File for the Game

import { type buildconfig, new_buildconfig
} from "samengine-build";

export function defineConfig(): buildconfig {
    let config: buildconfig = new_buildconfig();
    return config;
}

API Reference

Core Engine

• startEngine(init, gameLoop) - Initialize game loop

Rendering

• renderText(ctx, text, x, y, color?, font?) - Render text
• renderBitmapText() - Render bitmap font text

Input System

• setupInput(canvas, width?, height?) - Initialize input
• getKeyState(key) - Check key state
• Mouse state available via input module

Types

• Vector2D / Vector3D - Vector mathematics
• Color - Color management
• Rect - Rectangle collision
• Math utilities for game logic

Utilities

• startEngine() - Manage game loop

License

MIT

More Addons in the Game Library

• a Full Markdown Parser (maybe for notes or easy docs, feel free to use)
• a JSON with Comments Parser

(I dont now why i added this)

More Tools for samengine and Game Making by me lol

• samengine-build
• samengine-cli
• old deprecated npm package
• linksaver

Commit Tags

The tags which are ending with -build are for the samengine-build Tool and the which end with -cli are for the samengine-cli package.

Samengine CLI Tools

Build, export, and development-server tooling for games built with samengine.

The package provides the samengine-build CLI. It bundles the code from the game folder, generates a playable index.html, copies or embeds assets from resources, and starts a local development server with automatic rebuilds in development mode.

What This Package Does

• Creates new game projects with --new or --new-empty.
• Loads samengine.config.ts and uses it as the source of truth for build options.
• Bundles the game entry from game/<entryname> with esbuild.
• Generates the HTML start page with title, description, author, version, optional fullscreen button, optional settings menu, and Markdown notes.
• Copies resources from resources to dist/resources in normal multi-file builds.
• Can embed used resources directly into the generated HTML as Data URIs in single-file mode.
• Minifies release builds.
• Starts a local HTTP server in development mode and rebuilds when files in game, resources, or samengine.config.ts change.

Installation

npm install samengine

Add these scripts to the package.json of your game project:

{
  "scripts": {
    "dev": "samengine",
    "build": "samengine --release"
  }
}

You can also run the CLI directly with npx samengine.

Project Structure

game/
  main.ts              Game entry point
resources/
  ...                  Images, audio, JSON, and other assets
samengine.config.ts    Build configuration
dist/
  index.html           Generated build output
  main.js              Bundled game, except in single-file mode

CLI

samengine

Runs a development build, writes dist/index.html, starts the development server, and watches project files.

samengine --release

Runs a release build. The output directory is recreated, JavaScript and HTML are minified, and no development server is started.

samengine --new MyGame

Creates a new project with an example game.

samengine --new-empty MyGame

Creates a new project with an empty starter game.

Configuration

A typical samengine.config.ts looks like this:

import type { buildconfig } from "samengine/config";
import { new_buildconfig } from "samengine/config";

export default function defineConfig(): buildconfig {
  const config = new_buildconfig();
  config.title = "My Game";
  config.description = "Short game description";
  config.gameauthor = "Your Name";
  return config;
}

Important options:

• title: Browser title and start-screen title.
• description: Description shown on the start screen.
• version: Game version shown on the start screen.
• entryname: Entry file inside the game folder, defaults to main.
• outdir: Build output folder, defaults to dist.
• show_fullscreen_button: Adds a fullscreen button to the generated page.
• enable_audio: Unlocks the browser AudioContext after the start click.
• markdown_notes: Shows collapsible Markdown notes before the game starts.
• htmlMenu: Configures an optional settings menu.
• devMode.singlefile: Generates a single HTML file in development mode.
• releaseMode.singlefile: Generates a single HTML file in release mode.
• dev_server_port: Initial port for the local development server.

Single-File Builds

When devMode.singlefile or releaseMode.singlefile is enabled, the tool reads the bundled JavaScript and scans the resources folder. Assets whose filename or relative path appears in the bundle are written into the HTML file as Base64 Data URIs. In the browser, they are available through window.__getResource(path) and window.__loadResource(path).

Code Exports

The main package entry exports build types and factory functions:

import {
  new_buildconfig,
  newHTMLMenu,
  newMarkdownStyle,
  type buildconfig,
} from "samengine/config";

Additional utilities are available from samengine/nonbrowser:

import { compressHTML } from "samengine/nonbrowser";

Learn more about samengine on GitHub or NPM.

Project Templates

Project Templates can be found here

Webtools

• releases are made on tags which are starting with webtools-v*

IGN

Git ignore Adder Infos are here