cgem-redux v0.2.0

cgem-redux

A TypeScript WebGL2 rendering library, currently WIP.

Disclaimer

This package has been released mainly for personal use in development of my other project. As such, it may not be ready for widespread use.

• Limited Support: This package is not currently actively maintained for public use.
• Documentation may be incomplete or tailored to my specific use cases.
• The package may contain experimental features and might not adhere to semantic versioning.

In case you are still interested in trying out this WIP library, you can follow the instructions and examples.

Installation

For npm use: npm i cgem-redux

Build your project using bundling system, like Webpack.

Usage

Minimal example

import { CGem, RendererType } from 'cgem-redux';

const container = document.getElementById('cgem-container');

if (container) {
    const resolution = { width: window.innerWidth, height: window.innerHeight };

    // Simplified alternative to CGem.createRenderer() which is generic
    CGem.createWebGlRenderer(container, resolution);

    const scale = 0.1;
    CGem.loadModel('./assets/models/cube/cube.obj', {
        scale: [scale, scale, scale],
        pos: [0, 0, 0],
        rot: [0, 0, 0],
    });
}

Add Light Source

Shadow mapping is currently not available since I started working on better, adaptive shadow maps.

const lightPosition = vec3.fromValues(0.0, 0.0, 0.0);
const lightDirection = vec3.fromValues(0.0, -0.5, 1.0);
const castShadows = false; // currently wip (adaptive shadow maps)

CGem.addLightSource(LightSourceType.DIR, lightPosition, lightDirection, castShadows);

Models loading

The CGem library currently supports only Wavefront format (.obj & .mtl). The loader can handle complex mesh hierarchies including materials and textures.

For loading single model, use the following method:

const scale = 0.1;

CGem.loadModel('RELATIVE_PATH_TO_OBJ', {
    scale: [scale, scale, scale],
    pos: [0, 0, 0],
    rot: [0, 0, 0],
});

Additional ModelSpecification object can be passed to set the initial transformation. It is possible, that no content is visible after loading the model, since the geometry is center in the world origin, while camera is also set into the world origin. Since backface culling is enabled by default, no geometry can be seen. Therefore modifying the initial position and scale might be required.

All additional resources (.mtl, textures) must respect the relative paths defined in the obj / mtl files.

Scene loading

In case you need to load multiple objects in a certain hierarchy (scene graph), you can provide a simple json-based scene description file. CGem will handle loading all assets specified together with creating the scene graph representation and transformation relations.

To load a scene, you can use the following method:

CGem.loadSceneFromServer('./assets/scenes/scene_test.json');

Scene file template

[
    {
        "name": "MyScene",
        "transform": {
            "r": [0.0, 0.0, 0.0],
            "t": [0.5, -0.15, 0.0],
            "s": [1.0, 1.0, 1.0]
        },
        "shadow_brightness": 0.25,
        "children": [
            {
                "name": "MyModel1",
                "src": "assets/myModel1.obj",
                "transform": {
                    "r": [0.0, 0.0, 0.0],
                    "t": [0.0, -0.13, 0.0],
                    "s": [1.65, 1.0, 1.65]
                },
                "children": []
            },
            {
                "skip": "false",
                "name": "MyModel2",
                "src": "assets/myModel2.obj",
                "cull": 0,
                "transform": {
                    "r": [0.0, 0.0, 0.0],
                    "t": [0.075, 0.0, -0.0],
                    "s": [1.0, 1.0, 1.0]
                },
                "children": []
            }
        ]
    }
]

Scene file properties description

• name - name of the node, set to the node instance
• transform - base transform of the node (Translation, Rotation (euler angles), Scale)
• children - child nodes, their transformation is composition of nodes transformation together with all its parent nodes transformations in the hierarchy
• src - relative path to the model represented by the node
• cull - whether to apply cull-face (do not render back faces)
• skip - helper flag to temporarily disable processing of the given node
• shadow_brightness - currently disabled flag, since shadow mapping is WIP right now

Changelog

v0.2.0 (2025-02-02)

• feat: Rework Camera class, split its implementation into FirstPerson, ThirdPerson, and Orbit classes
• feat: Add Pawn class representing the player
• feat: Performance tracking module Performance and GlPerformance
• feat: Exposed KeyMap class used for binding custom controls
• feat: Exposed TouchControls and MouseControls
• feat: Exposed RenderState and RenderSettings classes to enable control over various parts of the renderer
• feat: Breaking Change Created new cgem API
• refactor: Breaking Change Refactored majority of classes and files introducing some breaking changes

v0.1.2 (2024-10-31)

• add support for loading texture atlas (Minecraft-like) as array texture
  • each sub-texture in the atlas is treated as a separate texture slice

v0.1.1 (2024-06-08)

• updated readme

v0.1.0 (2024-06-07)

• initial release of the library