X3DOM: X3D scenes written as ordinary HTML elements

What the framework is and where it sits

X3DOM is a framework for integrating and manipulating X3D scenes as HTML5 DOM elements, which are rendered via WebGL without additional plugins. The open-source system allows defining 3D scene description and runtime behaviour declaratively, without any low-level JavaScript or GLSL coding. That is the whole pitch and it is narrower than it first sounds: X3D is an ISO standard for describing 3D scenes, and X3DOM is one way of consuming it, in which the scene graph is a DOM tree rather than an object graph you build by hand. The alternative was the browser plugin model that X3D originally assumed, and X3DOM is the answer to the fact that plugins disappeared. The homepage is x3dom.org and the primary language of the repository is HTML, which is a hint about the shape of the codebase.

Documentation, downloads and the starter scene

The README sends you to the official documentation to get started, at doc.x3dom.org, with the development documentation at a separate path for documentation under development. A specific tutorial is linked for a minimal starter scene, described as the hello world of the framework, and the download page serves various versions of the framework, with the x3dom-dev repository available for the latest development work and the changelog linked for the changes. The split between the stable documentation and the documentation for the development branch is worth noticing, because it tells you the project is in a state where the two are out of step, which is normal for a long-lived project but does mean you should pick one and read only that.

Where support actually happens

The support section is unusually explicit about the division of labour. If you want to use X3DOM and need help or want to share knowledge, you should use the x3dom-users mailing list or the forums, and the README says beginner questions usually have been asked already, with the mailing list and forum archives providing quick answers. If you decide to post, you should include as much information as possible and describe your problem and what you tried already, succinctly. The developers list is a different address, x3dom-dev, used for discussion of the development of the library itself rather than for help with using it. There is also a gitter chat room for real-time interaction if preferred. The issue tracker is for issues and patches, and general help questions are directed to the mailing list instead.

The issue tracker cannot take files, so there is a workaround

The README documents a limitation of the tracker and a workaround for it. The GitHub issue tracker does not allow uploading files, so for sharing files the recommendation is to use a gist: copy and paste the file contents there and then copy the gist URL into the issues form. There is a second request, which is the more valuable one. It immensely helps the maintainers if you can provide a live web page illustrating your problem, so if you have webspace and can upload and post the URL with your issue, the chances of it being looked at increase. For a framework whose entire purpose is rendering a scene in a browser, a broken scene is very hard to diagnose from a description alone, and the request for a live URL is a sensible response to that rather than a formality.

The licence arrangement is unusual and worth reading twice

The contribution guidelines include a point about licensing that is more detailed than most projects bother with. The files within the repository are under the GPL3 or later, but as the original creators the project is still allowed to create non-free derivatives. However, if patches are given under the GPL then those cannot make it into any non-free derivatives the project may later wish to create, so to make it easier for the maintainers and to avoid legal issues the preference is that patches are released as public domain. That is a coherent arrangement and an unusual one: it lets the project keep the option of a commercial edition while asking contributors not to foreclose it. The package metadata records the licence as MIT or GPL-3.0, which is consistent with the files being GPL while the tooling and the packaging are more permissive, though the repository's own licence field carries a custom classification that GitHub cannot label, and that is the document to read.

The development workflow, and rebase over merge

The workflow section is a fork, clone, add upstream, branch, work, push, pull request sequence, and the useful commands section is the part worth copying. If a lot of changes have happened upstream you can replay your local changes on top of them with a rebase.

git fetch upstream
git rebase upstream/master

The README explains why this is generally better than merge: it gives a clear picture of which commits are local to your branch, and it prunes any of your local commits if the same changes have been applied upstream. The interactive form with the -i flag allows you to drop, rearrange, merge and reword commits, which is the tool you reach for when a branch has picked up a few commits that upstream already took. The commit conventions are stated too, including a summary line below 80 characters followed by a blank line and then the reasoning, and a fixup prefix for commits that fix a previously merged one.

Building it

The build instructions are four steps. Install Node.js, navigate into your cloned repository, then run npm install and npm run build.

npm install
npm run build

The package manifest shows what the build is made of. The build script runs a node script called src-builder.js, and the development dependencies give a good picture of the pipeline: concat and zip-lib to assemble and package the distribution files, terser for minification, jsdoc for the API documentation, fs-extra for file handling, and eslint with a stylistic plugin for linting. The package keywords list webgl, x3d, gltf, html and javascript, and the version in the manifest is a development build rather than a released tag, which tells you the repository tracks a moving head while the released versions come from the download page.

Where X3DOM is the wrong choice

Four limits apply. It is a framework for X3D specifically, so a project that wants general 3D on the web has other options and the standards argument is a real cost rather than a free win. It inherits the X3D feature set, which means you are constrained to a scene description model designed in an era before modern GPU pipelines, and the abstraction of DOM elements means the performance characteristics are those of a DOM tree rather than of a hand-built scene graph. The release story is the practical concern: the tagged versions in the repository date from 2019, 2021 and 2023, while commits continue, so the gap between what is released and what is on master is wide and the documentation reflects that split. And the licensing arrangement, while it protects the project's options, gives a contributor no assurance about what happens to their patch, which is a real consideration if you intend to use the code commercially.

Editorial conclusion

Use X3DOM when you need a 3D scene in a web page and want to describe it in markup rather than build a renderer, because the DOM element model means you can generate and manipulate scenes with the tools you already use for the rest of the page. Do not expect a modern graphics stack underneath, since the project has released a tagged version in 2023 while continuing to commit to the repository, so the balance between the two has shifted. Verify first which release you are building against, since the package version in the repository is a development build rather than a published tag, and whether your browser support assumptions hold, because the whole design depends on WebGL being present.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. x3dom/x3dom on GitHub