D3pth engine - Gamma - Documentation

Gamma is a simple 3D engine for regular HTML pages. It connects content cards, 3D transforms, scene configuration, and multiple finite state machines into one browser-side interaction system.

1. Purpose

This document explains what Gamma does, what it does not do, and which page structures and configuration objects it expects.

2. Page structure

A Gamma page is built from these main elements:

  • viewport3d
  • scene
  • world
  • card elements
  • scrollSpace

3. Viewport, scene, and world

The viewport3d element is the visible 3D viewport and perspective container. The scene element holds the transformed 3D scene. The world element contains the positioned 3D content.

4. Card elements

Cards are regular HTML elements controlled by Gamma. To include an element in the state system, give it the class name “card”.

Supported data properties:

  • data-item: card identifier used by state machines
  • data-x: default translation on the x axis
  • data-y: default translation on the y axis
  • data-d3pth: default depth value
  • data-alpha: default rotation around the x axis
  • data-beta: default rotation around the y axis
  • data-gamma: default rotation around the z axis

5. Scroll space

The scrollSpace element creates page height for scroll-driven interaction. In normal use, leave it untouched.

6. Configuration: cfg

cfg is the main configuration object for scene geometry, perspective, and depth scaling.

  • gap: spacing between cards
  • perspective: CSS perspective value
  • sceneZ: scene depth offset
  • zScale: scale factor for d3pth values
  • sideFrac, midFrac, modelMax: not used in Gamma
  • rxTop, rxBottom: not used in Gamma

7. Scene states

The states array defines how cards and the camera look in each named scene state.

  • state: state identifier
  • items: card or camera definitions in that state
  • item: card identifier, or camera for camera control
  • props: x, y, d3pth, alpha, beta, and gamma

8. State machines

Multiple finite state machines can consume the same signals and move through shared scene states. The engine returns an action function that you can call from event handlers or from your own custom logic.

A transition contains:

  • event: signal required to trigger the transition
  • from: required current state
  • to: target state
  • time: animation duration
  • fromEvent: logic executed when the transition starts
  • toEvent: logic executed when the transition ends

9. Accessibility

You are responsible for accessibility. Pay attention to semantic headings, link text, keyboard navigation, color contrast, focus states, reduced motion, screen reader behavior, and clickable elements inside transformed 3D containers.

10. Responsive design

You are responsible for responsive design. Test viewport size, card dimensions, mobile layout, perspective, scroll distance, and touch interaction in your local environment first.

11. Styling

You are responsible for CSS, including typography, spacing, colors, card sizes, inline styles, and reusable classes.

12. Example

See d3pth.store for a working example.

13. Summary

Gamma helps regular HTML pages behave like controlled 3D scenes. Let's make the internet 3D!