🎨 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:

🕹ī¸ Demos & Samples

Live Demo & Example Gallery

This is a gallery of examples which will run live in the browser. Try it out!

đŸ–ŧī¸ Screenshots

Some room in a dungeon or something

normal mapping and environment mapping

Particle system

screenshot of treasure chest

đŸ’Ŧ 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

📝 Documentation & Links

Full API Reference Guide

📚 Sources & Reading