A hackable template for creating small and fast browser games

Goodluck is great for:

Learning game programming and game design.
Prototyping gameplay ideas.
Building size-constrained games.
Experimenting with algorithms and APIs.
Modeling problems through animated simulations

Show me the code!

Here's what a typical system looks like in Goodluck:

const QUERY = Has.LocalTransform2D | Has.Shake;

export
function sys_shake2d(game: Game, delta: number) {
    for (let entity = 0; entity < game.World.Signature.length; entity++) {
        if ((game.World.Signature[entity] & QUERY) == QUERY) {
            // The entity has the LocalTransform2D and Shake components.

            let shake = game.World.Shake[entity];
            let local = game.World.LocalTransform2D[entity];

            local.Translation[0] = (Math.random() - 0.5) * shake.Radius * 2;
            local.Translation[1] = (Math.random() - 0.5) * shake.Radius * 2;

            // Tag the entity as dirty so that sys_transform2d applies the new translation.
            game.World.Signature[entity] |= Has.Dirty;
        }
    }
}

Features

Goodluck is a template for creating small browser games which fit in a few kilobytes. It's designed for extreme hackability. The codebase is small and simple; it's mostly just ifs and fors. The code is easy to understand and modify.

A tiny core with an expressive and fast ECS implementation, which keeps the data (components) separate from the logic (systems).
2D rendering pipeline using WebGL's instancing, resulting in very good performance (tens of thousands of sprites).
3D rendering pipeline supporting Gouraud and Phong shading with gamma-corrected directional and point lights; diffuse, specular, and normal texture mapping; real-time shadows; forward and deferred rendering, both with a post-processing step; instanced rendering, and more.
A versatile toolkit of useful systems for movement, animation, collisions, particles, entity life cycle (spawn, autodestruct), UI, mouse, keyboard, touch and gamepad input, etc.
Capable of great performance, even on older mobile devices.

Getting Started

Goodluck is not a typical library. You don't install it via npm install. Instead, use it as a template: generate a new repository from it, remove features you don't need, and hack away. Consult the README to learn more.

Documentation

What is Goodluck?: A high-level overview of what makes Goodluck special. It also includes an honest list of reasons why you might want to consider other solutions.
Why is Goodluck the way it is?: A list of questions you might be asking yourself with regards to Goodluck's design choices.
API Reference: The annotated source code of Goodluck's core components, systems, and utilities.

Tutorials

js13kBreakout (2022): Part of the js13kBreakouts project.
Castle Peskenstein (2020): A Twitter thread with a step-by-step account of creating a Wolfenstein3D clone.
Breakout (2020): Support material from a workshop on gamedev. Follow the commits on the tutorial branch.

Starter Templates

Good defaults with most of Goodluck's components and systems.

Platformer2D 7.0KB w/o tile sprites src

Run ./bootstrap.sh Platformer2D and remove anything you don't need to trim the size even further

Hardware-accelerated 2D renderer
Import maps and tilesets from Tiled
2D tile animation system
Zoomable and pannable camera which maintains constant pixel size on resizes
Context2D drawing API in the background

NewProject3D 11.2KB src

Run ./bootstrap.sh NewProject3D and remove anything you don't need to trim the size even further

Examples

All examples are WebGL2. The reported sizes are minified, Roadrolled, and zipped.

Animate 8.2KB src

Animation system
Skinning
Audio listener and spatial audio source

DeferredShading 10.0KB src

Deferred shading pipeline using light volumes
Diffuse, specular, and emissive materials
Real-time shadows
Bloom, tone-mapping, and FXAA post-processing
Smooth-shaded icospheres

FirstPerson 7.3KB src

First-person camera
Keyboard, mouse, gamepad and touch controls
Fullscreen
2D elements drawn in the 3D space, always facing the camera

FollowCamera 13.3KB src

Third-person camera
A mesh exported from Blender (through GLTF)

ForwardShading 10.7KB w/o textures src

Forward shading pipeline
Basic shading: points, wireframe, unlit
Flat shading via GLSL ES 3.0's flat qualifier
Gouraud shading: diffuse, specular x3
Phong shading: diffuse, specular x3
Textures: unlit, Gouraud (shininess = 0), Phong (shininess = 512), normal and roughness maps
Render to texture
Real-time shadows

Instancing 5.0KB src