gsots3d
Version:
Getting S**t On The Screen in 3D. A library for doing 3D graphics in the browser.
121 lines (80 loc) âĸ 5.53 kB
Markdown
<img src="https://code.benco.io/gsots3d/icon.png" align="left" width="120px"/>
A library for _Getting Stuff On The Screen_ in 3D
So you can get cool looking 3D things happening in your browser, with hopefully minimal effort.
This library is an opinionated set of abstractions and wrappers around WebGL & [twgl.js](https://twgljs.org/). GSOTS takes the pain out of loading models, defining a camera, rendering a scene, lighting etc. It is based on the classic Blinn-Phong shading model, rather than the more modern PBR based shaders, because I'm old.
Feature Set:
- **đŋ Models**: Loading, parsing & rendering of meshes and multi-part objects from OBJ & MTL files.
- **⨠Materials**: With diffuse texture mapping, specular maps & normal/bump mapping.
- **đĒŠ Environment mapping**: Scene based reflections, skyboxes & dynamic realtime reflections
- **đĻ Lights**: Global directional and dynamic point lights.
- **đ Nodes**: Hierarchical node system for instances and grouping.
- **đĻ Primitives**: Sphere, cube, plane.
- **đ Particles**: GPU based particle system.
- **đ§ Transparency**: Transparent materials & primitives
- **đ Shadows**: Realtime shadows from directional light sources.
- **đ Reflection**: Both dynamic and static environment mapping.
- **âī¸ Physics**: Helpers to integrate with with [cannon-es](https://pmndrs.github.io/cannon-es/) physics engine.
- **đĒ§ Billboarding**: For adding 'flat' 2D sprites into the 3D scene.
- **đĨ Camera**: Perspective and orthographic projection, and first person mouse & keyboard controls
This is a gallery of examples which will run live in the browser. [Try it out!](<(https://code.benco.io/gsots3d/examples/)>)
The hello world equivalent in GSOTS is putting a simple object on the screen, This example creates a GSOTS `Context` to render a simple red sphere
```html
<html>
<body>
<!-- This canvas will be used for rendering -->
<canvas width="800" height="600"></canvas>
<script type="module">
import { Context, Material } from './gsots3d.js'
// Create rendering context
const gsots = await Context.init('canvas')
// Create a red sphere of radius 5 at the origin
gsots.createSphereInstance(Material.RED, 5.0)
// Start and render into the canvas
gsots.start()
</script>
</body>
</html>
```
The NPM package is published on [NPMJS.com](https://www.npmjs.com/package/gsots3d, to install the package, simply run:
```bash
npm install benc-uk/gsots3d
```
A standalone ESM single file bundle is delivered via jsDelivr & GitHub, this can be used directly in a vanilla HTML+JS app to import the library, e.g.
```js
// Import from main, getting latest code
import { Context } from 'https://cdn.jsdelivr.net/gh/benc-uk/gsots3d@main/dist-single/gsots3d.min.js'
```
If you want to reference a specific released version you can do so by changing `benc-uk/gsots3d@main` for example `benc-uk/gsots3d@0.0.4`
OBJ files can be parsed and loaded, MTL files will be loaded and materials parsed when referenced from the OBJ, and and OBJ can consist of multiple materials. When parsing the OBJ the UV texture coordinates are flipped in the Y direction, this makes them consistent with the rest of the rendering internally.
Normal maps will be parsed from any MTL (or can added to a _Material_ with `addNormalTexture()`) using the unofficial `map_bump` keyword.
Normal maps must be in OpenGL format, i.e. Y+ or "green at top", see this [reference image](https://doc.babylonjs.com/img/how_to/Materials/normal_maps1.jpg)
Due to the vast inconsistencies in OBJ & MTL exporting from the thousands of software packages and tools out there (and the age of the format), it's fairly unlikely any OBJ you download or export will work without some modification, often to just the MTL file.
## đ¤ Known Limitations & Issues
- Transparency
- Works OK with primitives, you can override a OBJ model material with a transparent one, but results might not be great.
- Billboards: Shading on spherical billboards might not be correct
- OBJ & MTL: The parsers are far from comprehensive and may not handle all features
- Due to the performance overhead only a single dynamic environment map is supported
- Shadow mapping follows the active camera by default in a not very good way
- Particle system: The emitter source is limited to a cuboid shape
## đ Documentation & Links
### [Full API Reference Guide](https://code.benco.io/gsots3d/docs/)
### [Link to GitHub Project](https://github.com/benc-uk/gsots3d)
## đ Sources & Reading
- https://learnopengl.com/
- https://twgljs.org/
- https://webglfundamentals.org/
- https://github.com/benc-uk/doom-lite