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
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 😉
twopoint5d is a monorepo that contains the following javascript / typescript libraries:
- @spearwolf/twopoint5d : is the "vanilla" core library and relies on three.js as a rendering framework
- @spearwolf/twopoint5d-r3f : builds on top of this and provides react components based on @react-three/fiber
- In contrast, @spearwolf/twopoint5d-elements goes the way of vanilla web components
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
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!
This repository is structured as a monorepo; based on nx !
First, you need a current node v18+ with PNpm as package manager setup. Install the dependencies with:
$ pnpm install$ pnpm cbt # => pnpm run clean > build > test$ pnpm lookbookEveryone is welcome to contribute to this project, no matter if it's just bug-fixes, new features, ideas or documentation or graphics!
Copyright © 2021-2024 by Wolfger Schramm.
The source code is licensed under the Apache-2.0 License.