Options
All
  • Public
  • Public/Protected
  • All
Menu

toupie

Small 2D game library for TS and JS

toupie logo

Table of Contents

Disclaimer

toupie is currently in very early state and the API is changing quickly and compatibility is constantly broken. If you plan on using it before 1.0.0 get released, make sure to pin a specific version.

About

toupie (french for spinning top, pronounce "to pee") is a flexible game library for TypeScript and JavaScript.

It was originally based of a fork of bottlecap.js. If you are interested in a small Vanilla JS library definitely check that too.

Goals of the project include:

  • good documentation: you should easily find most information in the autogenerated doc
  • clear code: if the documentation is not enough, at least the code should be crystal clear
  • flexibility: aims at being a toolbox, not a frame

Toupie does not want to lock you in a given architecture like most game engine do. Instead it tries to give you a useful selection of tools to build your game the way you like.

The intended use of toupie is small 2D games. It is well suited to quick prototyping and game jam creations. But it can also be used for more fleshed out projects.

Features

toupie offer the following tools to build a game:

  • Easy to use yet powerful main loop facility
  • Asynchrone ressource loader.
  • Geometric primitives (AABB and 2D vector)
  • Sprite based graphic system for HTML5 canvas
  • Simple 2D camera system.
  • Simple animation facilities for sprites and for properties.
  • Thin wrapper for DOM manipulation.
  • Basic AABB collision system.
  • Simple input API for mouse, keyboard and gamepads.
  • Small ECS system
  • State machine facility for game stage handling.
  • Simple interface to local storage.
  • Gamepad handling with abstraction of the various layouts (credit goes to ericlathrop for the mappings).

Everything (except the geometric primitives that are used throughout the library) is opt-in and you can use your own implementation if that's what you want.

Docs

The reference generated from inline doc is available here.

Examples

Some demos are available here.

Usage

toupie can be used both for JS and TS games.

Write a game in TypeScript

If you want to use it from a TypeScript app, you will have to create a npm or yarn based project. Simply install toupie and import it from you files. For example you index.ts may look like that:

import { ready, run } from "toupie";

const game = {}

game.update = function(dt) {
}

game.render = function() {
}

ready(() => {
  run(game);
});

And your index.html may look like that:

<!DOCTYPE html>
<html class="default">
<head>
    <meta charSet="utf-8"/>
    <title>toupie demo</title>
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <meta http-equiv="Pragma" content="no-cache">
    <meta http-equiv="Expires" content="-1">
    <meta http-equiv="CACHE-CONTROL" content="NO-CACHE">
</head>
<body>
    <script type=module src="./index.ts"/>
</body>
</html>

Then use your favorite build system to build the app into a regular HTML+JS bundle. We recommend parcel.js for its ease of use.

A more complete example of using toupie with TS is provided here.

Write a game in JavaScript

When writing the code directly in JS you have two options:

  • The heavy but modern one
  • The lite but old school one

The heavy/modern approach is to follow the same steps as for TypeScript but writing you code in JavaScript. The old school one is to use the compiled version of toupie to build your project. You can find it in here.

You can simply import this from you index.html:

<!DOCTYPE html>
<html class="default">
  <head>
    <meta charset="utf-8" />
    <title>toupie demo</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta http-equiv="Pragma" content="no-cache" />
    <meta http-equiv="Expires" content="-1" />
    <meta http-equiv="CACHE-CONTROL" content="NO-CACHE" />
  </head>
  <body>
  </body>
  <script type="module">
    import { ready, run } from  "https://lattay.srht.pages/toupie/dist/toupie.mjs";

    const game = {}

    /*
     * This method is called by the game engine to update the game on each frame.
     * dt is the amount of time elapsed since last frame in seconds.
     */
    game.update = function(dt) {
    }


    /*
     * This function is used by the game engine to render the game on each frame.
     */
    game.render = function() {
    }

    ready(() => {
    run(game);
    });
  </script>
</html>

A more complete example of this approach is provided here.

Generated using TypeDoc