/elm-3d-scene

A high-level 3D rendering engine for Elm, with support for lighting, shadows, and realistic materials.

Primary LanguageElmMozilla Public License 2.0MPL-2.0

elm-3d-scene

elm-3d-scene is a high-level Elm package for producing 3D graphics, with support for lighting, shadows and realistic materials:

Lit scene with shadows

It aims to make creating 3D graphics as easy and enjoyable as possible, without having to worry about low-level details like shader programs and transformation matrices. elm-3d-scene uses elm-explorations/webgl under the hood (and therefore requires WebGL support to work), but no knowledge of WebGL is required to use this package.

Any questions/feedback, please open an issue or please reach out in the #webgl channel or to @ianmackenzie on the Elm Slack!

Who is this for?

elm-3d-scene is built to support a wide range of use cases, from simple 3D loading spinners up to near-photorealistic scenes. It is designed to be beginner-friendly with a smooth onramp to advanced features like shadows, HDR lighting and physically based materials. You can use elm-3d-scene to make:

  • Games
  • Animations
  • Visualizations
  • Scientific/engineering/technical apps and more!

However, if you're a WebGL guru who's comfortable with writing their own shader programs, then elm-3d-scene might not (yet?) be for you - you're currently limited to the material and lighting types that elm-3d-scene supports directly. Eventually elm-3d-scene will likely support custom shaders in some way (see the roadmap), but it's not there yet.

Getting started

The best way to start learning the elm-3d-scene API is by reading through the tutorial and then checking out the examples. For more details on any type/function, the reference documentation is your friend.

Duckling model

One important point to understand is that elm-3d-scene builds heavily on several other packages, making extensive use of types and modules from:

As a result, to start using elm-3d-scene in your own project you will need at least a decent understanding of those packages as well. Check out their READMEs and reference documentation for details, but you can probably get a decent sense of how they work by checking out the elm-3d-scene examples.

When installing elm-3d-scene, you'll also want to install the above packages:

elm install ianmackenzie/elm-3d-scene
elm install avh4/elm-color
elm install ianmackenzie/elm-3d-camera
elm install ianmackenzie/elm-units
elm install ianmackenzie/elm-triangular-mesh
elm install ianmackenzie/elm-geometry

(All of the packages will get downloaded and installed automatically anyways, since they're dependencies of elm-3d-scene, but you'll need to install them explicitly in your own project so that you can use them directly.)

Table and chairs

Climate action

I would like for the projects I work on to be as helpful as possible in addressing the climate crisis. If

  • you are working on a project that helps address the climate crisis (clean energy, public transit, reforestation, sustainable agriculture etc.) either as an individual, as part of an non-profit organization or even as part of a for-profit company, and
  • there is a new feature you would find helpful for that work (or a bug you need fixed) in any of my open-source projects, then

please open a new issue, describe briefly what you're working on and I will treat that issue as high priority.

Spheres and blocks

Roadmap

elm-3d-scene has a decent number of features already, but there are many, many more to add. Check out the issues to get a sense of what features are planned (and add your own feature request if there's something you'd like to see!), but some of the immediate next steps will likely include:

In the longer term, I hope to add support for:

  • Custom vertex and/or fragment shaders (for things like custom procedural texturing, fancy material types or deformable meshes)
  • Skeletal animation (rigging/skinning)

However, these will require some significant API design and implementation work.

Contributing

Contributions are very welcome! Here are some ideas for some that would be very useful at this stage:

  • More examples to add to the examples directory, showing how to create specific kinds of scenes or how to integrate elm-3d-scene with other packages, such as:

    • An example combining elm-3d-scene and elm-gamepad, perhaps using the gamepad to walk around a scene
    • An example with shadows cast from a moving light source (I think something like a point light flying in and amongst a bunch of cubes could look pretty cool)
    • Anything you think would look cool/illustrate part of the API missed by other examples/help others understand something you struggled with

  • Separate packages that parse different 3D model formats so they can be loaded into elm-3d-scene, such as OBJ, STL or DAE.

    I think it makes sense for each file format to have a dedicated package separate from elm-3d-scene. Ideally, I think each package should focus on simply parsing a file into a nice Elm data structure (instead of directly into an elm-3d-scene Entity, for example) so that the data could also be used in other ways (custom rendering engines, 3D printing, analysis etc.).

    Note that some work has already started on GLTF loading, so reach out to me (@ianmackenzie) on the Elm Slack if that's something you're interested in working on.

Once the internals of elm-3d-scene stabilize a bit, there will be lots more opportunities to contribute to the core rendering engine, to add features such as:

  • Textured backgrounds (#53)
  • Rectangular/polygonal light sources (#41)
  • 3D-rendered text (#37)
  • Procedural textures (#22)
  • Debug rendering options (#21)
  • Funky material types like water and ceramics (#5)

For now, though, the internals are changing rapidly enough that coordination/collaboration on these kinds of issues would be tricky.

Physics simulation