Skip to content

a library to create 2.5d realtime graphics and pixelart with three.js

License

Notifications You must be signed in to change notification settings

spearwolf/twopoint5d

Repository files navigation


A javascript side project about rendering 2.5D realtime graphics on the web.

ultra fast rendering of 2D sprites in 3D space • billboards • texture atlas • frame-based animations • parallax • tiled 2D maps • pixelart

github actions main workflow status License

twopoint5d cover

Introduction

It all started with the desire to render 2d sprites (lots of them!) in the browser. it has been a long way, starting with a naive html-canvas-based solution. the second iteration used a custom webgl renderer, which turned out to be quite complex in the long run. today, in its current form, the library uses three.js as the rendering layer.

A declarative description (called a "vertex object description") is used to describe the sprite properties (how many vertices, indices, texture coords, etc.).

Using the vertex object description, the library can create javascript objects that provide getters and setters for the respective sprite properties. the actual data ends up in internal buffers that are efficiently rendered in batches by three.js/webgl, usually via instanced rendering.

While the developer can use the "sprites" / vertex objects comfortably and conveniently via javascript objects, the "backend" of the library ensures that webgl can render the current sprite pool with high performance with a single draw call. the cumbersome handling of webgl buffers and state setup becomes transparent for the developer.

Whether a "sprite" is a classic quad with a texture or a freeform polygon with special properties used in a custom vertex shader is completely up to the creator of the vertex object description and the associated shaders that use those properties.

🚀 In other words, this library wants to empower the developer's creativity by allowing him to quickly and easily create his own sprites, particles or whatever using instanced rendering and his own custom shaders, without having to study the documentation every time to understand the boring details of the WebGL API.

Of course, this library offers several ready-to-use sprite shaders (better known as Mesh in three.js) based on this. the developer can just use them and doesn't have to worry about how.

There are sprite shaders that render textured quads as billboards or on a plane in the 3d space. there is also a sprite shader that uses animated textures (using frame-based animations). and there are other highly specialized sprite shaders that are used for rendering tiled 2d maps, among other things.

Obviously, textures can be loaded from texture atlases or tilesets.

‼️ However, the developer should not expect an all-encompassing sprite engine, that is not the intention of this library, it rather wants to reduce and speed up the developer's workload to do what he wants to do (but without hiding the rendering API three.js).

There are a few more features that this library offers to make the life of a creative web developer easier, but not to take all the fun out of discovering them, let's just mention them here 😉

What's in this repository 👀

twopoint5d is a monorepo that contains the following javascript / typescript libraries:

So it's up to you if you want to go the react, web components or "vanilla" way 😉

| 🔎 However, it should also be mentioned at this point that the vanilla library is the only real and stable library here. both the react / r3f library and the web components library are rather experimental in nature. in the end, i do not consider either technology to be optimal for a rendering engine. currently (as a side note), i am working on a component architecture that works offscreen in web workers, for the brave among you who dare to take a look at it, here is the link: spearwolf/shadow-objects

📖 Documentation

Some features have been around for a long time and are stable, others are in flux and highly experimental. as an independent solo developer, it is not possible for me to create detailed written documentation and keep it up to date. this is a living open source project and is subject to constant change. therefore, the developer is advised to do the following

"Read the source, Luke!"

To take this to the extreme, there is a LOOKBOOK app with lots of code examples, all of which can be used as a starting point for new projects or as documentation for one or the other feature.

🚀 The LOOKBOOK app can easily be started locally using pnpm lookbook. See next section Development Setup for details.

And of course there are one or two READMEs in the **/src/* subdirectories that provide a high-level overview of the features. Enjoy exploring!

Development Setup

This repository is structured as a monorepo; based on nx !

1. Install dependencies

First, you need a current node v18+ with PNpm as package manager setup. Install the dependencies with:

$ pnpm install

2. Build and test everything

$ pnpm cbt  # => pnpm run clean > build > test

3. Run the local LOOKBOOK app

$ pnpm lookbook

Getting involved

Everyone is welcome to contribute to this project, no matter if it's just bug-fixes, new features, ideas or documentation or graphics!

Copyright and License

Copyright © 2021-2024 by Wolfger Schramm.

The source code is licensed under the Apache-2.0 License.