Skill — Debug

Activation

Append ?debug to the URL:

http://localhost:5173?debug

The free debug camera is toggled from the debug panel, not mounted permanently.

Debug singleton

// src/debug/Debug.ts
import GUI from "lil-gui";

export class Debug {
  private static _instance: Debug | null = null;

  readonly active: boolean;
  gui: GUI | null = null;

  static getInstance(): Debug {
    if (!Debug._instance) Debug._instance = new Debug();
    return Debug._instance;
  }

  private constructor() {
    this.active = new URLSearchParams(window.location.search).has("debug");
    if (this.active) {
      this.gui = new GUI({ title: "La-Fabrik Debug" });
    }
  }

  destroy(): void {
    this.gui?.destroy();
    Debug._instance = null;
  }
}

Adding debug controls

const debug = Debug.getInstance();

if (debug.active) {
  const folder = debug.gui!.addFolder("Lighting");
  folder.add(params, "intensity", 0, 5).name("Sun intensity");
  folder.addColor(params, "color").name("Sun color");
}

r3f-perf (lazy loaded)

r3f-perf is loaded only in debug mode to avoid dependency issues in production:

// src/debug/DebugPerf.tsx
import { Suspense, lazy } from "react";
import { Debug } from "@/debug/Debug";

const Perf = lazy(() => import("r3f-perf").then((m) => ({ default: m.Perf })));

export function DebugPerf() {
  const debug = Debug.getInstance();
  if (!debug.active) return null;

  return (
    <Suspense fallback={null}>
      <Perf position="top-left" />
    </Suspense>
  );
}

Usage in Canvas:

<Canvas>
  {/* scene content */}
  <DebugPerf />
</Canvas>

Rules

All debug UI goes through Debug.getInstance() — never inline if (isDev) checks
r3f-perf is always lazy-imported, never a hard dependency in scene components
Debug folders should be organized by domain (Lighting, PostFX, Player, Zone)
Debug panel must not affect production builds — it simply doesn't mount when ?debug is absent
Clean up debug folders in destroy() when relevant

2.0 KiB Raw Blame History