gsots3d
đ¨ GSOTS-3D
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. 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 physics engine.
- đĒ§ Billboarding: For adding 'flat' 2D sprites into the 3D scene.
- đĨ Camera: Perspective and orthographic projection, and first person mouse & keyboard controls
đšī¸ Demos & Samples
Live Demo & Example Gallery
This is a gallery of examples which will run live in the browser. Try it out!
đŧī¸ Screenshots
đŦ Hello World - Example
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>
<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>
đģ Using & Install
Import as package
The NPM package is published on NPMJS.com, to install the package, simply run:
npm install gsots3d
Directly in browser
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.
// 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
đĻ Supported Models & Textures
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
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