hmans/composer-suite

A suite of libraries for making game development with Three.js and React not only awesome, but "so good, it would feel wrong to use anything else." – hmans

Building games with React and Three.js is already pretty cool, but a lot of tooling you need to make those games really nice is still missing. This project tries to fill some of these gaps by providing a collection of libraries for various aspects of game development, from GPU-driven particle systems and VFX, to game UI, editor tooling, camera rigs, audio, multi-device input, and more.

Note While this suite of libraries targets building games with React and React-Three-Fiber, some of them can also be used outside of React, just like some others are not specific to Three.js or React-Three-Fiber. But building games with React is where our hearts are at, which is why you will find most example code in this document to be written in React. 😎

Sponsors ❤️

This project wouldn't be possible without the support from its lovely sponsors. If you'd like to sponsor this project and help make game development with React & Three.js incredible, click here!

Getting Started

Most of the packages in this repository are under heavy development, and even though I regularly push new bits to NPM, expect much of it to be largely undocumented and unstable, particularly anything that has yet to reach version 1.0.0.

If you'd like to give this stuff a try today, the easiest way would be to either clone this repository to your local computer and run one of the many example apps (or the demo game, Space Rage; see below). Alternatively, you can also open this repository on CodeSandbox and play with the code there!

Space Rage

The development of the Composer Suite is primarily driven by that of Space Rage, an open-source top-down twin-stick shooter game that is also intended to be a showcase for the libraries here.

• Play Space Rage (development build!)
• Play and edit Space Rage in CodeSandbox
• Source code

Packages 📦

Shader Composer takes a graph of nodes (here called "units") and compiles it to a working GLSL shader. It provides a library of ready-to-use shader units, but you can, of course, add your own. Parameterized sub-graphs of your shaders can be implemented as plain JavaScript functions.

const ShaderComposerExample = () => {
  const shader = useShader(() =>
    ShaderMaterialMaster({
      color: pipe(
        Vec3(new Color("red")),
        (v) => Mix(v, new Color("white"), NormalizePlusMinusOne(Sin(Time()))),
        (v) => Add(v, Fresnel())
      )
    })
  )

  return (
    <mesh>
      <sphereGeometry />
      <shaderMaterial {...shader} />
    </mesh>
  )
}

Material Composer provides a mechanism to hook into Three.js materials and customize their behavior using a sequence of material modules. Modules are higher-level implementations of Shader-based functionality, and implemented using Shader Composer. Material Composer provides a library of these material modules that are easy to extend and customize; but, as always, you can add your own.

const MaterialComposerExample = () => (
  <mesh position-y={1.5} castShadow>
    <sphereGeometry />

    <Composable.MeshStandardMaterial>
      <Modules.Color color="#d62828" />

      <Layer opacity={NormalizePlusMinusOne(Sin(Time()))}>
        <Modules.Color color="#003049" />
      </Layer>

      <Modules.Fresnel intensity={0.2} />
    </Composable.MeshStandardMaterial>
  </mesh>
)

TODO

Timeline Composer provides a small, but powerful collection of React components that can be used to orchestrate an animation sequence:

<Lifetime seconds={5}>
  <SmokeRing />
  <Fireball />

  <Delay seconds={0.3}>
    <CameraShake decay />
    <Fireball />

    <Delay seconds={0.2}>
      <Rocks />
      <SmokeCloud />
    </Delay>
  </Delay>
</Lifetime>

Render Composer

A preconfigured, opinionated render pipeline for your React-Three-Fiber games.

TODO

Input Composer

Composable multi-device game input.

TODO

UI Composer

Screen-space UI for games and game tooling.

TODO

Camera Composer

Composable camera automation.

TODO

State Composer

Helpers for managing game state.

TODO

Development 🛠

Repository Structure

The repository is structured as a monorepo. You will find all packages that are part of the Composer Suite inside the packages directory, and a collection of applications (examples and otherwise) inside apps.

Development Mode

This repository uses Preconstruct for building packages and providing a development environment. To start the development environment, run:

pnpm dev:link

This will cause Preconstruct to link all apps and packages together so they consume each others' TypeScript source, allowing you to modify code without having to rebuild after every change.

Running Example Apps

Use the pnpm dev task to start up all available apps in development mode, or supply a --filter argument to just start one of them. Examples:

# Start all apps
pnpm dev

# Start individual apps
pnpm dev --filter spacerage
pnpm dev --filter vfx-composer-examples
pnpm dev --filter shader-composer-examples

Note The pnpm dev task uses Turborepo. Please refer to their CLI Documentation to learn about additional options.

Core Tenets

All of the libraries in the Composer Suite are aiming for the following:

• Authored in and for TypeScript.
  All libraries are authored in TypeScript, with first-class type support. This means that you can use these libraries in JavaScript, but you will get the best experience when using TypeScript. If you're using them from within JavaScript, please be aware that these libraries will not make any significant effort to provide runtime type checking or similar.
• Flawless HMR.
  The libraries should provide a fun and flawless development experience with the best support for hot-module reloading possible. The user should be able to hot-reload their code and see the changes immediately in the browser. Where possible, state should be retained; there must never be errors when hot-reloading.
• Prefer Declarative over Imperative.
  Where possible, allow the user to declare logic and data using JSX, instead of forcing them out of the declarative JSX layer and towards hooks (or even further into the imperative world.)
• Usable Individually, and Together.
  Where possible, libraries should be designed so they can be used individually, but also together.

License 👩‍⚖️

Copyright (c) 2022 Hendrik Mans

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.