sprunk-engine

Sprunk - A TypeScript Web Game Engine

Description

A TypeScript game engine designed to be simple and small (Only 50 kb once minified) but modular, and extensible. It is intended to be used primarily in the browser.

This engine architecture focus on event driven architecture and enforcing a strict separation of concerns between the different components of the engine. Not only for the engine itself but also for the games built on top of it.

Features

• WebGPU 3D rendering engine (with support for Sprites, Meshes, Line drawing and Text)
• 2D polygon physics engine
• Audio engine
• Input system supporting multiple gamepads, keyboard, and mouse
• Dependency injection system
• Debugging tools

Use sprunk in your project

Prerequisites

• npm 10.2+ official doc
• node v21+ official doc
• Any other browser that runs WebGPU (eg. Google Chrome 130+)

Install the package with npm

npm i sprunk-engine

Fork a empty project to get started (with guided sample code)

Go to the empty project and click on the "Fork" button.

How to use ? (Examples)

Depending on what you want to do, you can check these examples:

• Sprunk Hero - A full 3D game example
• Flappy Sprunk - A 2D game example
• Sprunk Empty - Forkable Project to Get Started with basic usage examples

You can also check the end-to-end tests of this project, providing small examples of how to use the engine:

• Basic usage (3D engine)
• Gamepad visualizer
• Physics engine example

Documentation

The documentation is available in the doc folder. Here are some useful links:

• Architecture (You should start with this one)
• Game Window Components
• Events and Callbacks
• Behaviors
• Dependency Injection
• Rendering Engine
  • Transform, parenting and 3d transformations
  • Text Rendering
• Physics Engine
• Input System
  • Gamepad System
• Game Object Debugger
• Audio Engine
• Limitations

Getting Started (for maintainers)

Prerequisites

• IDE used PhpStorm 2024.2 or Webstorm 2024.2
• npm 10.2+ official doc
• node v21+ official doc
• git version 2.39 official doc
• git-lfs/3.5 + official doc
• Astah UML 8+ official doc
• Google Chrome 130+ (or any other browser that runs WebGPU)

Run the project

Install packages

npm install

Run vite dev server

npm run dev 

Run the tests

npm run test

Deployment

Build the project as a library

  npm run build

This will generate a dist folder containing the library files.

Build the project as a web application

  vite build

This will generate static files in the dist folder. You can then deploy these files to a any web server.

Generate documentation

Class diagrams

  npm run generate-uml

Website documentation

  npm run generate-doc

This will generate a /doc/site/build folder containing the documentation (static website).

Collaborate

Directory structure

├───doc                     # Documentation
├───src                     # Source code
│   ├───Core                # Core components
│   │   ├───Caching         # Cache management system
│   │   ├───DependencyInjection  # Dependency injection system
│   │   ├───EventSystem     # Event and callback helpers
│   │   ├───Initialisation  # Engine initialization
│   │   ├───MathStructures  # Math structures (Vector, Quaternion, Transform)
│   │   ├───Tickers         # Time management and game loop control
│   │   ├───Utilities       # Utility functions (Array, Math, etc.)
│   ├───Extensions          # Extensions and modules
│   │   ├───AudioEngine     # Audio behaviors
│   │   ├───Debugger        # Debugging tools
│   │   ├───InputSystem     # Web input system (Gamepads, Keyboard, Mouse)
│   │   ├───PhysicsEngine   # 2D polygon physics engine using SAT
│   │   ├───RenderEngine    # WebGPU rendering engine
├───test                    # Unit tests (Vitest)
│   ├───CommonResources     # Shared resources (assets) for tests
│   ├───Core                # Core component tests
│   ├───ExampleBehaviors    # Reusable example behaviors for tests
│   ├───Extensions          # Extension tests
│   │   ├───Some Extension  # One folder per extension
│   │   │   ├───Assets      # Assets used for the specific extension
│   │   │   ├───Mocks       # Mocks for the extension
│   │   │   ├───Integration # Integration tests for the extension (html files, etc.)

Class syntax

The classes are written in order to follow the Google TypeScript style guidelines

Workflow

• Gitflow
• How to commit
• How to use your workflow
• Propose a new feature in Jira
  • We only use tasks
• Pull requests are open to merge in the develop branch.
• Release on the main branch we use GitFlow and not with GitHub release.
• When creating a new feature, the branch name must be feature/SPR-XX-NameOfTheFeature
• Before merging a feature into develop, the code should be reviewed by one other person (by opening a pull request).
• Issues are added to the github issues page

License

Distributed under the MIT License. See LICENSE.txt for more information.

Contact

• If needed you can create an issue on GitHub we will try to respond as quickly as possible.