Skip to main content

Troubleshooting

Use this guide when luxy does not render, build, or feel correct in a host Expo or React Native app.

Install and peer dependency issues​

  • Confirm the app installed native peers with expo install.
  • Scratch card requires Skia, Gesture Handler, Reanimated, Expo Haptics, and Expo Image.
  • Slot machine requires Skia, Reanimated, and Expo Haptics.
  • Confirm Reanimated is configured for the host app's Expo SDK.
  • If Metro resolves duplicate workspace packages, clear the bundler cache and verify only one copy of each luxy package is linked.

Resolver and backend-first issues​

  • If a card never reveals or a spin never settles, verify the resolver resolves exactly once per interaction.
  • Resolver errors should surface through onError and host-app error UI.
  • Backend-first outcomes should return stable reward ids.
  • Slot-machine stop ids must exist in symbols or per-reel symbol lists.
  • Do not debug production reward fairness in the client. Validate campaign fairness, eligibility, and inventory on the backend.

Skia and visual fallback issues​

  • Shader or foil compatibility failures should fall back to static gradients.
  • If Android GPUs show shader or path-cost issues, force lower quality and verify native performance.
  • If custom symbol rendering is expensive, simplify the tree while state.isSpinning is true.

Haptics​

Haptics are additive feedback and may be unavailable on simulators, web, low-power settings, or some Android devices. Do not treat haptic absence as a functional failure if visual state and callbacks still work.

Release validation​

Run the full local gate before requesting review:

pnpm run test
pnpm run lint
pnpm run typecheck
pnpm run build
git diff --check