Refactor to CLI+API, typescript, and more

[rosskevin]

Temporary fork published

Temporary fork published: https://github.com/rosskevin/gltfjsx

I hope this is a temporary package and this PR is accepted, but I've got to move on and start using it in a production/published environment.

Goal

• Allow for external reuse via API (load, transform, analyze, generate)
• Allow for customization of analyze/duplicates/pruning
• Allow external users to generate non-r3f components through direct api access
• Allow for customization of generated code

Included

• Added eslint
• Removed rollup for simpler tsup config
• Converted to typescript
• Updated all dependencies
• Integrated auto for automatic releases (NEED a committer to work with me or commit access to complete setup)
• Separate generate code from analyze, simplifying and reducing some duplicate logic with better maintainability
• Allow pluggable pruning strategies for the analyze phase
• Allow subclassing for analyze and generate phases.
• Integrated ts-morph for AST access or string building, whichever is easiest. API consumer can direct access and modify the AST. Allows for easy tsx | jsx stringification.
• Removed copied loaders src and instead use community maintained node-three-gltf
• Add tests (just the start, but it's a start!)
• Resolution is nodenext, so this is an ESM build with top-level await for node 16+
• Optimized npm package via ignores
• Better naming in generated code for typescript types.
• Fix for duplicate named nodes in the typescript interface
• new flatten optimation exposed that defaults to true (existing behavior) but can be turned off via API or CLI (this can unexpectedly remove named node references)
• new exposeProps option in generation API, allowing for generating component props that propagate to Object3D one to many jsx properties e.g. shadows -> [castShadow, receiveShadow] with optional matcher fn.

Motivation

We have three CAD models that have continuous development. We are building online configurators, and we effectively need a way to customize gltfjsx to instrument the code with our additions in a continuous integration way.

Testing

• I have written basic tests, previously there were none. Additional assertions have been added to support new features like exposeProps.
• I have performed some comparison generations via CLI that look good.
• I am using the code published in the fork as an API (for customized/advanced options)

TL;DR

I need this, and I spent a lot of time on it. I'll be moving forward with it regardless, but I think it belongs here. I hope to have this PR reconciled and merged so that the entire community can collaborate.

Samples

GLTF r3f

/*
  FOO header 
*/

import {
  useAnimations,
  useGLTF,
  Merged,
  PerspectiveCamera,
  OrthographicCamera,
} from '@react-three/drei'
import { GroupProps, MeshProps, useGraph } from '@react-three/fiber'
import * as React from 'react'
import { AnimationClip, Mesh, MeshPhysicalMaterial, MeshStandardMaterial } from 'three'
import { GLTF, SkeletonUtils } from 'three-stdlib'

interface FlightHelmetGLTF extends GLTF {
  nodes: {
    Hose_low: Mesh
    RubberWood_low: Mesh
    GlassPlastic_low: Mesh
    MetalParts_low: Mesh
    LeatherParts_low: Mesh
    Lenses_low: Mesh
  }
  materials: {
    HoseMat: MeshStandardMaterial
    RubberWoodMat: MeshStandardMaterial
    GlassPlasticMat: MeshStandardMaterial
    MetalPartsMat: MeshStandardMaterial
    LeatherPartsMat: MeshStandardMaterial
    LensesMat: MeshPhysicalMaterial
  }
}

export interface FlightHelmetProps extends GroupProps {}

const modelLoadPath = '/FlightHelmet.gltf'
const draco = false

export function FlightHelmet(props: FlightHelmetProps) {
  const { nodes, materials } = useGLTF(modelLoadPath, draco) as FlightHelmetGLTF

  return (
    <group {...props} dispose={null}>
      <mesh
        name="Hose_low"
        castShadow
        receiveShadow
        geometry={nodes.Hose_low.geometry}
        material={materials.HoseMat}
      />
      <mesh
        name="RubberWood_low"
        castShadow
        receiveShadow
        geometry={nodes.RubberWood_low.geometry}
        material={materials.RubberWoodMat}
      />
      <mesh
        name="GlassPlastic_low"
        castShadow
        receiveShadow
        geometry={nodes.GlassPlastic_low.geometry}
        material={materials.GlassPlasticMat}
      />
      <mesh
        name="MetalParts_low"
        castShadow
        receiveShadow
        geometry={nodes.MetalParts_low.geometry}
        material={materials.MetalPartsMat}
      />
      <mesh
        name="LeatherParts_low"
        castShadow
        receiveShadow
        geometry={nodes.LeatherParts_low.geometry}
        material={materials.LeatherPartsMat}
      />
      <mesh
        name="Lenses_low"
        castShadow
        receiveShadow
        geometry={nodes.Lenses_low.geometry}
        material={materials.LensesMat}
      />
    </group>
  )
}

useGLTF.preload(modelLoadPath, draco)

Draco instanceall r3f

/*
  FOO header 
*/

import {
  useAnimations,
  useGLTF,
  Merged,
  PerspectiveCamera,
  OrthographicCamera,
} from '@react-three/drei'
import { GroupProps, MeshProps, useGraph } from '@react-three/fiber'
import * as React from 'react'
import { AnimationClip, Mesh, MeshPhysicalMaterial, MeshStandardMaterial } from 'three'
import { GLTF, SkeletonUtils } from 'three-stdlib'

interface FlightHelmetGLTF extends GLTF {
  nodes: {
    GlassPlastic_low: Mesh
    Hose_low: Mesh
    Lenses_low: Mesh
    RubberWood_low: Mesh
    MetalParts_low: Mesh
    LeatherParts_low: Mesh
  }
  materials: {
    GlassPlasticMat: MeshStandardMaterial
    HoseMat: MeshStandardMaterial
    LensesMat: MeshPhysicalMaterial
    RubberWoodMat: MeshStandardMaterial
    MetalPartsMat: MeshStandardMaterial
    LeatherPartsMat: MeshStandardMaterial
  }
}

export interface FlightHelmetProps extends GroupProps {}

const modelLoadPath = '/FlightHelmet-transformed.glb'
const draco = true

type ContextType = Record<string, React.ForwardRefExoticComponent<MeshProps>>

const context = React.createContext<ContextType>({})

export function FlightHelmetInstances({ children, ...props }: FlightHelmetProps) {
  const { nodes } = useGLTF(modelLoadPath, draco) as FlightHelmetGLTF
  const instances = React.useMemo(
    () => ({
      GlassPlastic_low: nodes.GlassPlastic_low,
      Hose_low: nodes.Hose_low,
      Lenses_low: nodes.Lenses_low,
      RubberWood_low: nodes.RubberWood_low,
      MetalParts_low: nodes.MetalParts_low,
      LeatherParts_low: nodes.LeatherParts_low,
    }),
    [nodes],
  )
  return (
    <Merged meshes={instances} {...props}>
      {(instances: ContextType) => <context.Provider value={instances} children={children} />}
    </Merged>
  )
}

export function FlightHelmet(props: FlightHelmetProps) {
  const instances = React.useContext(context)

  return (
    <group {...props} dispose={null}>
      <instances.GlassPlastic_low name="GlassPlastic_low" />
      <instances.Hose_low name="Hose_low" />
      <instances.Lenses_low name="Lenses_low" />
      <instances.RubberWood_low name="RubberWood_low" />
      <instances.MetalParts_low name="MetalParts_low" />
      <instances.LeatherParts_low name="LeatherParts_low" />
    </group>
  )
}

useGLTF.preload(modelLoadPath, draco)

Closes/supercedes PRs

This closes the majority of open PRs through fixes or through reuse of external loaders that are maintained:

• (merged) closes feat: Add options to configure pruning unused vertex attributes #279
• (manual merge) closes Better DX: Refactor GLTFJSX readme.md and gitignore, add vscode extensions.json, and format with prettier #275
• closes Update bin/GLTFLoader.js - Support skinned instanced (not tested) #272
• closes Add support for KTX2 loader #266
• closes refact: replace decodeText with TextDecoder #264
• closes Fix/246: Cannot find name 'GLTFAction'. #260
• closes Add parseRaw to output parsed component tree jsx string without passing though prettier #256
• closes work in progress: avoid shipping a modify copy of three's GLTFLoader and DRACOLoader #232
• closes Lint README.md & Organizing Imports #189
• closes prevent empty file from being added when file path doesn't match #185
• closes Update three.js dependency #181
• closes Bump dns-packet from 1.3.1 to 1.3.4 in /example #91
• closes Bump url-parse from 1.4.7 to 1.5.1 in /example #81
• closes Bump ssri from 6.0.1 to 6.0.2 in /example #77
• closes Bump elliptic from 6.5.2 to 6.5.4 in /example #72
• closes Bump ini from 1.3.5 to 1.3.8 in /example #58
• closes Bump dot-prop from 4.2.0 to 4.2.1 in /example #51

Closes issues

This PR allows-for/solves/obsoletes/no longer present the following issues:

• closes Allow for API usage with customization/extensions #284
• closes suggestion: convert the codebase to typescript #274
• closes --transform or -T does not work #285
• closes How to rewrite gltfjsx generated jsx file to separate geometry and material #257
• closes Expose materials attributes/properties / Explode materials #251
• closes Parsing input arbitrary three.js scene graph to component tree #255
• closes stylelint fails with meow #243
• closes v6.2.12 - Cannot read properties of undefined (reading 'length') #242
• closes Export of transform and gltfjsx default function  #204
• closes When .glb file does not exist (or path is wrong), command still adds .jsx file to repo #184
• closes Method toVector3 was removed from three.js, still used in gltfjsx #179
• closes Does not work with relative paths #176
• closes Basic demo in line with documentation #159
• closes Unexpected token g in JSON when using GLTFStructureLoader #150
• closes error with command npx gltfjsx #149
• closes integration in typescript react project #145
• closes Parser stand alone error - ReferenceError: Blob is not defined #144
• closes No matching version found for [email protected] #137
• closes Parser Stand Alone Error - ReferenceError: Request is not defined #135
• closes memory access out of bounds, Decoding failed #132
• closes transform with more custom control i.e only prune and draco and not resize textures? #122
• closes Changing individual mesh color without changing material color #119
• closes Cannot find module 'gl-matrix/vec3' #116
• closes Running npx gltfjsx Model.gltf fails with Error: Invalid hook call. #112
• closes [BUG] Type 'GLTFActions' does not satisfy the constraint 'AnimationClip'. #101
• closes When using typescript - Property 'nodes' does not exist on type 'GLTF' #63
• closes [FEATURE] maybe we should add some decomposition to the generated code? #46
• closes [QUESTION] maybe we should use babel ast to generate code? #45

[rosskevin]

For watchers, I updated the original text, but:

Temporary fork published: https://github.com/rosskevin/gltfjsx @rosskevin/gltfjsx

I hope this is a temporary package and #286 is accepted, but I've got to move on and start using it in a production/published environment.

[donmccurdy]

Hi @rosskevin! Awesome work here, thank you! I'm in favor of the direction. But I'm only an occasional contributor on this repository, and so I think we'll need @drcmda to sign off on the plan. It is a pretty large PR, so I'll wait to do a deeper review until getting some signal one way or the other.