feat: add cli for generating model code & add .glb support (#24)

Co-authored-by: Thorsten Seyschab <business@todde.tv>

Author: fehnomenal

README.md

@@ -27,8 +27,8 @@ With this plugin you get:
 - ✅ Only the used models are bundled in the final product, not all included in your dev project.
 - ⚠️ Detects and handles [Draco Compression](https://github.com/google/draco) during type generation automatically,
   see [Draco Compression handling](#draco-compression-handling) below for more information.
-- ✅ Works with glTF Seperate (`.gltf` + `.bin` + textures) and glTF Embedded (only `.gltf`) files,
-  see [glTF Versions and Representations](#gltf-versions-and-representations) below for more information.
+- ✅ Works with glTF Seperate (`.gltf` + `.bin` + textures), glTF Embedded (only `.gltf`) and glTF Binary (`.glb`)
+  files, see [glTF Versions and Representations](#gltf-versions-and-representations) below for more information.
 - ✅ ESM ready.
 - ⚠️ Build tool & bundler agnostic thanks to [Unplugin](https://github.com/unjs/unplugin), so use it with your
   favorite one, but see chapter
@@ -119,14 +119,16 @@ to different folders, changing paths, or adjusting how the model is handled afte
 3. Start your dev to generate all files. With our example model we get:
 
    ```diff
-   @/assets/models/MyModel.gltf
-   @/assets/models/MyModel.bin
-   @/assets/models/MyModel-texture1.png
-   @/assets/models/MyModel-texture2.png
+    @/assets/models/MyModel.gltf
+    @/assets/models/MyModel.bin
+    @/assets/models/MyModel-texture1.png
+    @/assets/models/MyModel-texture2.png
    +@/assets/models/MyModel.gltf.d.ts    <- the typing
-   +@/assets/models/MyModel.gltf.js      <- actual code with node get helper function and scene/ model graph representation
+   +@/assets/models/MyModel.gltf.js      <- actual code with node get helper function and model graph representation
    ```
 
+   > Alternatively, you can run the script `gltf-codegen` supplied by the package to manually create those files. More details at [Binary scripts](#binary-scripts).
+
 4. Import the type safe model in your code and use it, e.g.:
 
    ```ts
@@ -165,14 +167,14 @@ resulting in the following compatibility in our project:
 
 ## glTF Versions and Representations
 
-(Legend: 🟢 Tested & Supported | 🟡 Not Yet Tested | 🔴 Not Supported)
+(Legend: 🟢 Tested & Supported | 🟡 Partially Supported | 🔴 Not Supported)
 
-| glTF Version | File Representation                    | Status | Note                                                                                                                                                            |
-| ------------ | -------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| glTF 1.0     | Any                                    | 🔴     | glTF 2.0 was introduced in 2017 with major improvements. Avoid using the outdated glTF 1.0 standard in your projects.                                           |
-| glTF 2.0     | Separate (`.gltf` + `.bin` + textures) | 🟢     | Recommended! Offers better performance, version control, caching, transferability, and debugging.                                                               |
-| glTF 2.0     | Embedded (only `.gltf`)                | 🟢     | Assets are embedded directly into the `.gltf` file as base64 encoded `data:` sources within the `uri` fields, making single-file management simpler.            |
-| glTF 2.0     | Binary (`.glb`)                        | 🔴     | Currently not supported because we scan JSON-encoded `.gltf` files for type generation and cannot yet process binary representations. Contributions welcome! ❤️ |
+| glTF Version | File Representation                    | Status | Note                                                                                                                                                 |
+| ------------ | -------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| glTF 1.0     | Any                                    | 🔴     | glTF 2.0 was introduced in 2017 with major improvements. Avoid using the outdated glTF 1.0 standard in your projects.                                |
+| glTF 2.0     | Separate (`.gltf` + `.bin` + textures) | 🟢     | Recommended! Offers better performance, version control, caching, transferability, and debugging.                                                    |
+| glTF 2.0     | Embedded (only `.gltf`)                | 🟢     | Assets are embedded directly into the `.gltf` file as base64 encoded `data:` sources within the `uri` fields, making single-file management simpler. |
+| glTF 2.0     | Binary (`.glb`)                        | 🟡     | Currently, only works with models that contain all referenced files in the binary chunk without external file references. Contributions welcome! ❤️  |
 
 ## Draco Compression handling
 
@@ -210,6 +212,20 @@ const gltfLoader = new GLTFLoader().setDRACOLoader(dracoLoader)
 export default gltfLoader
 ```
 
+## Binary scripts
+
+In addition to the commands in the `scripts` section of the `package.json`, this plugin also provides binary scripts.
+
+Run them by adding this plugin to your project, be sure to have the dependencies installed and then
+add `npx` or `pnpx` before the commands.
+
+### `gltf-codegen [DIR]`
+
+This script generates types and runtime code for all models found in `DIR` and sub-directories. `DIR` defaults to
+the current directory.
+
+Run `gltf-codegen --help` for more options and details.
+
 ## idea behind the scenes
 
 On runtime it runs `useGLTF` under the hood. So no extra layer and therefore correct objects that

package.json

@@ -96,6 +96,9 @@
       ]
     }
   },
+  "bin": {
+    "gltf-codegen": "dist/cli.js"
+  },
   "files": [
     "CHANGELOG.md",
     "LICENSE.md",
@@ -108,14 +111,15 @@
     "pnpm": "9"
   },
   "scripts": {
-    "prepare": "run-s \"precompile-templates\"",
-    "precompile-templates": "esno scripts/precompile-templates.ts",
+    "bin:gltf-codegen": "esno src/cli.ts",
     "build": "tsup",
-    "dev": "tsup --watch src",
     "build:post": "esno scripts/postbuild.ts",
+    "dev": "tsup --watch src",
     "lint": "eslint .",
     "lint:fix": "run-s \"lint --fix\"",
-    "playground": "pnpm -C playground run dev"
+    "playground": "pnpm -C playground run dev",
+    "precompile-templates": "esno scripts/precompile-templates.ts",
+    "prepare": "run-s \"precompile-templates\""
   },
   "peerDependencies": {
     "@farmfe/core": ">=1",
@@ -160,6 +164,8 @@
     }
   },
   "dependencies": {
+    "citty": "~0.1.6",
+    "consola": "~3.4.0",
     "handlebars": "~4.7.8"
   },
   "devDependencies": {

pnpm-lock.yaml

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+import { resolve } from 'node:path'
+import { cwd } from 'node:process'
+import { defineCommand, runMain } from 'citty'
+import { consola } from 'consola'
+import { version } from '../package.json'
+import { generateModelTypes } from './core/generate.js'
+import { findAllModelsInDir } from './core/utils/find-models.js'
+
+const main = defineCommand({
+  args: {
+    dir: {
+      default: cwd(),
+      description: 'Directory to scan for *.gltf files',
+      type: 'positional',
+    },
+
+    loader: {
+      description: 'Path to a module providing an GLTFLoader instance as default export.',
+      type: 'string',
+    },
+
+    verbose: {
+      default: false,
+      description: 'Print more info',
+      type: 'boolean',
+    },
+  },
+
+  meta: {
+    description: '',
+    name: 'gltf-codegen',
+    version,
+  },
+
+  async run(context) {
+    const dir = resolve(context.args.dir)
+
+    consola.start(`Looking for models in ${dir}`)
+
+    const models = await findAllModelsInDir(dir)
+
+    await Promise.all(
+      models.map(modelFile => generateModelTypes(modelFile, {
+        customGltfLoaderModule: context.args.loader,
+        verbose: context.args.verbose,
+      })),
+    )
+
+    consola.success(`Generated types for ${models.length} model file${models.length === 1 ? '' : 's'}.`)
+  },
+})
+
+runMain(main)

src/cli.ts

@@ -0,0 +1,4 @@
+export const BINARY_GLTF_MODEL_EXTENSION = '.glb'
+export const SEPARATE_GLTF_MODEL_EXTENSION = '.gltf'
+
+export const GLTF_MODEL_EXTENSIONS = [BINARY_GLTF_MODEL_EXTENSION, SEPARATE_GLTF_MODEL_EXTENSION]

src/core/constants.ts

@@ -0,0 +1,66 @@
+import type { Options } from '../types.js'
+import { writeFile } from 'node:fs/promises'
+import { basename, dirname, relative, resolve } from 'node:path'
+import consola from 'consola'
+import { DRACOLoader, GLTFLoader } from 'three-stdlib'
+import { name } from '../../package.json'
+import { analyzeGltfModel, type GltfAnalysis } from '../core/analyze.js'
+import { parseGltfModel } from '../core/parse.js'
+import { generateModelDeclaration } from './generate/model-declaration.js'
+import { generateModelRuntime } from './generate/model-runtime.js'
+
+const gltfLoader = new GLTFLoader().setDRACOLoader(new DRACOLoader())
+
+// TODO: Make variable.
+const identifiers = {
+  nodeGetter: 'getNode',
+}
+
+export async function generateModelTypes(
+  modelFile: string,
+  options: Options | undefined,
+): Promise<void> {
+  if (options?.verbose) {
+    consola.info(`Parsing model ${modelFile}`)
+  }
+
+  const parsedGltf = await parseGltfModel(gltfLoader, modelFile)
+  const analysis = analyzeGltfModel(parsedGltf)
+
+  const declarationFile = resolve(dirname(modelFile), `${basename(modelFile)}.d.ts`)
+  const runtimeFile = resolve(dirname(modelFile), `${basename(modelFile)}.js`)
+
+  await Promise.all([
+    generateDeclarationFile(options, declarationFile, analysis),
+    generateRuntimeFile(options, runtimeFile, analysis, modelFile),
+  ])
+}
+
+async function generateDeclarationFile(options: Options | undefined, targetFile: string, analysis: GltfAnalysis): Promise<void> {
+  if (options?.verbose) {
+    consola.info(`Generating declaration file: ${targetFile}`)
+  }
+
+  await writeFile(targetFile, `${generateModelDeclaration(analysis, identifiers)}\n`, {
+    encoding: 'utf8',
+  })
+}
+
+async function generateRuntimeFile(options: Options | undefined, targetFile: string, analysis: GltfAnalysis, modelFile: string): Promise<void> {
+  if (options?.verbose) {
+    consola.info(`Generating runtime file: ${targetFile}`)
+  }
+
+  let relativeGltfPath = relative(dirname(targetFile), modelFile)
+  if (!relativeGltfPath.startsWith('.')) {
+    relativeGltfPath = `./${relativeGltfPath}`
+  }
+
+  const loaderPath = options?.customGltfLoaderModule ?? `${name}/gltf-loader`
+
+  await writeFile(
+    targetFile,
+    `${generateModelRuntime(analysis, relativeGltfPath, loaderPath, identifiers)}\n`,
+    { encoding: 'utf8' },
+  )
+}

src/core/generate.ts

@@ -18,9 +18,9 @@ export function generateModelRuntime(
 
   return runtime({
     gltfLoaderPath: JSON.stringify(gltfLoaderPath),
-    gltfPath: JSON.stringify(relativeGltfPath),
     identifiers: { ...identifiers, nodeName },
     imports: imports.toTemplateData(false),
+    relativeGltfPath: JSON.stringify(relativeGltfPath),
     scenes,
   }).trim()
 }

src/core/generate/model-runtime.ts

@@ -1,5 +1,5 @@
 {{> imports.hbs}}
-import gltf from {{{gltfPath}}};
+import gltf from {{{relativeGltfPath}}};
 import gltfLoader from {{{gltfLoaderPath}}};
 
 {{!-- This symbol is needed to restrict node accessors to this model. --}}

src/core/generate/templates/runtime.hbs

@@ -3,7 +3,7 @@ import type { GLTF, GLTFLoader } from 'three-stdlib'
 import { readFile, stat } from 'node:fs/promises'
 import { dirname } from 'node:path'
 
-export async function parseGltfModel(gltf: GLTFLoader, modelFile: string): Promise<GLTF> {
+export async function parseGltfModel(gltfLoader: GLTFLoader, modelFile: string): Promise<GLTF> {
   let stats: Stats
   try {
     stats = await stat(modelFile)
@@ -16,9 +16,9 @@ export async function parseGltfModel(gltf: GLTFLoader, modelFile: string): Promi
     throw new Error(`"${modelFile}" is not a file!`)
   }
 
-  const json = (await readFile(modelFile, { encoding: 'utf8' }))
+  const gltf = (await readFile(modelFile)).buffer as ArrayBuffer
 
-  const model = await gltf.parseAsync(json, dirname(modelFile))
+  const model = await gltfLoader.parseAsync(gltf, dirname(modelFile))
 
   return model
 }

src/core/parse.ts

@@ -0,0 +1,11 @@
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { GLTF_MODEL_EXTENSIONS } from '../constants.js'
+
+export async function findAllModelsInDir(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { recursive: true, withFileTypes: true })
+
+  return entries
+    .filter(e => GLTF_MODEL_EXTENSIONS.some(ext => e.name.endsWith(ext)))
+    .map(entry => join(entry.parentPath, entry.name))
+}