Face Filter sample: Stuck on loading on engine 5.x / Vite 8 (workaround included)

đŸŒ” Needle Engine
,
1

and decorator errors until tsconfigRaw is set. (<<Add to title)

Hi all, I’m new to Needle and used the “Needle Face Filter Examples” sample from Unity for a uni project. I hit a chain of problems that ended in a working setup. I’m posting the details in case they help others, and in case the sample or templates could be updated.

Setup

  • Windows, Unity 6000.0.82f1, Node v22.20.0, BASIC (non-commercial) license
  • Web project in Library/Needle/Sample
  • Face filter: Unity side uses the local tarball com.needle.face-filter-1.0.0-beta.12.tgz (the registry returns an authentication error for com.needle.face-filter). Web side: @needle-tools/facefilter 1.0.4 from npm.

Symptoms and causes

  1. Infinite white screen on engine 5.1.14 / 6.0.0-alpha.3 with Vite 8
    The dev server stopped at “bundling dependencies
” and the page never loaded. The default sandbox worked. I didn’t find the exact cause. It went away after I moved to the combination below.

  2. Build error on engine 5.1.14: “hasProLicense is not exported”
    This appeared when building with the facefilter package, so it looks like a version mismatch between the facefilter package and the engine. It disappeared on engine 4.10.2.

  3. Unity kept resolving the engine to 5.1.2
    com.needle.engine-samples 1.5.1 depends on com.needle.engine-exporter 5.1.2, which overrode my manifest.json entry of 4.10.2. I had to remove com.needle.engine-samples from Packages/manifest.json, delete Packages/packages-lock.json and reopen Unity.

  4. Build error on engine 4.10.2 with Vite 8: “Failed to convert builtin plugin ‘ViteAlias’”
    Fixed with: npm i -D vite@7 (7.3.6). The FAQ currently says recent engine versions need Vite 8+, which seems to be true for 5.x but not for 4.10.2.

  5. Runtime errors on engine 4.10.2 / Vite 7

  • ReferenceError: Cannot access ‘_ShaderToyFaceFilter’ before initialization

  • TypeError: Cannot read properties of undefined (reading ‘__internalAwake’)

  • warnings about “@serializable without a target” and “Unknown components in scene”
    My tsconfig.json already had experimentalDecorators: true, but the facefilter package ships TypeScript source (main: index.ts) under node_modules, and my guess is the project tsconfig isn’t applied to those files, so the decorators were compiled incorrectly. Setting tsconfigRaw directly in vite.config.js fixed it:

  esbuild: {
    tsconfigRaw: { compilerOptions: { experimentalDecorators: true, useDefineForClassFields: false } },
  },
  optimizeDeps: {
    esbuildOptions: {
      tsconfigRaw: { compilerOptions: { experimentalDecorators: true, useDefineForClassFields: false } },
    },
  },

Working combination

  • @needle-tools/engine 4.10.2 (Unity package and npm)
  • Vite 7.3.6, @vitejs/plugin-basic-ssl 2.3.0
  • @needle-tools/facefilter 1.0.4 (npm), Unity face-filter package from the local beta.12 tarball
  • Needle Engine Samples package removed
  • tsconfigRaw added to vite.config.js as above
    With this the camera permission prompt appears and the face filter runs.

Questions

  1. Is there a recommended engine/facefilter/Vite combination for the face filter sample on engine 5.x? Is a newer facefilter build planned?
  2. Should the Vite config in the face filter template set tsconfigRaw (or should the package ship compiled JS)?
  3. Is there a supported way to stop the Unity integration from overwriting vite.config.js and package.json in Library/Needle/Sample? I know the npm: prefix protects the engine version, but I couldn’t find anything about the other files.
  4. Is the authentication error for com.needle.face-filter on packages.needle.tools expected?

I haven’t tested the production build (vite build / preview) after the fix, and I can’t be sure the root causes are exactly as I described.

Thanks!

2

The mixing is the problem: you’ve got the tarball face-filter-1.0.0-beta.12 on the Unity side and @needle-tools/facefilter@1.0.4 from npm on the web side. Those are different builds, and your “hasProLicense is not exported” error is the classic symptom of the web package expecting a different engine API than the one you’re running. Pin both sides to the same facefilter version — pull the web package at the beta.12 tag to match the tarball.

The decorator errors (and probably the hang during “bundling dependencies
”) are esbuild not seeing experimentalDecorators. That’s why tsconfigRaw fixes it: Vite’s dep-optimizer doesn’t read your tsconfig.json unless you pass it. Add to vite.config.js:

esbuild: { tsconfigRaw: { compilerOptions: { experimentalDecorators: true } } }

One question: are you pinned to a specific engine version in package.json, or floating? If floating, what does npm ls @needle-tools/engine say?

Sources: Needle Engine Docs (69%), Needle Engine Docs (65%), Needle Engine Docs (64%), Needle Engine Docs (63%), Needle Engine Docs (63%), Needle Engine Docs (61%), Needle Engine Docs (60%), Needle Engine Docs (59%), Needle Engine Docs (59%), Needle Engine Docs (58%)

1 replies left - Become PRO for more replies.
Reply to this post directly if you need further help (bottom right button)