@playcraft/skills 0.0.2

package/skills/threejs.aicomponent/ref/AssetLoader.ts

@@ -0,0 +1,158 @@
+import * as THREE from "three";
+import { GLTFLoader, type GLTF } from "three/addons/loaders/GLTFLoader.js";
+
+export type TextureEntry = { key: string; url: string };
+export type ModelEntry = { key: string; url: string };
+export type AudioEntry = { key: string; url: string };
+export type CubeTextureEntry = { key: string; urls: [string, string, string, string, string, string] };
+
+export type AssetManifest = {
+  textures?: TextureEntry[];
+  models?: ModelEntry[];
+  audio?: AudioEntry[];
+  cubeTextures?: CubeTextureEntry[];
+};
+
+export type LoadedAssets = {
+  textures: Map<string, THREE.Texture>;
+  models: Map<string, GLTF>;
+  audio: Map<string, AudioBuffer>;
+  cubeTextures: Map<string, THREE.CubeTexture>;
+};
+
+type ProgressCallback = (progress: number) => void;
+
+/**
+ * 统一资源加载器。
+ *
+ * 支持 Texture / GLTF 模型 / 音频 / CubeTexture 批量加载，
+ * 提供 0~1 的进度回调。加载结果按 key 存入 Map，方便后续使用。
+ *
+ * ```typescript
+ * const loader = new AssetLoader();
+ * await loader.loadAll({
+ *   textures: [{ key: "logo", url: logoUrl }],
+ *   models: [{ key: "char", url: charUrl }],
+ * }, (p) => console.log(`${(p*100).toFixed(0)}%`));
+ *
+ * const tex = loader.getTexture("logo");
+ * const gltf = loader.getModel("char");
+ * ```
+ */
+export class AssetLoader {
+  private assets: LoadedAssets = {
+    textures: new Map(),
+    models: new Map(),
+    audio: new Map(),
+    cubeTextures: new Map(),
+  };
+
+  private textureLoader = new THREE.TextureLoader();
+  private gltfLoader = new GLTFLoader();
+  private cubeTextureLoader = new THREE.CubeTextureLoader();
+  private audioContext: AudioContext | null = null;
+
+  async loadAll(manifest: AssetManifest, onProgress?: ProgressCallback): Promise<LoadedAssets> {
+    const tasks: (() => Promise<void>)[] = [];
+
+    for (const entry of manifest.textures ?? []) {
+      tasks.push(() => this.loadTexture(entry));
+    }
+    for (const entry of manifest.models ?? []) {
+      tasks.push(() => this.loadModel(entry));
+    }
+    for (const entry of manifest.audio ?? []) {
+      tasks.push(() => this.loadAudio(entry));
+    }
+    for (const entry of manifest.cubeTextures ?? []) {
+      tasks.push(() => this.loadCubeTexture(entry));
+    }
+
+    if (tasks.length === 0) {
+      onProgress?.(1);
+      return this.assets;
+    }
+
+    let done = 0;
+    const total = tasks.length;
+
+    await Promise.all(
+      tasks.map(async (task) => {
+        await task();
+        done++;
+        onProgress?.(done / total);
+      }),
+    );
+
+    return this.assets;
+  }
+
+  getTexture(key: string): THREE.Texture | undefined {
+    return this.assets.textures.get(key);
+  }
+
+  getModel(key: string): GLTF | undefined {
+    return this.assets.models.get(key);
+  }
+
+  getAudioBuffer(key: string): AudioBuffer | undefined {
+    return this.assets.audio.get(key);
+  }
+
+  getCubeTexture(key: string): THREE.CubeTexture | undefined {
+    return this.assets.cubeTextures.get(key);
+  }
+
+  private loadTexture(entry: TextureEntry): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.textureLoader.load(
+        entry.url,
+        (tex) => {
+          tex.colorSpace = THREE.SRGBColorSpace;
+          this.assets.textures.set(entry.key, tex);
+          resolve();
+        },
+        undefined,
+        reject,
+      );
+    });
+  }
+
+  private loadModel(entry: ModelEntry): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.gltfLoader.load(
+        entry.url,
+        (gltf) => {
+          this.assets.models.set(entry.key, gltf);
+          resolve();
+        },
+        undefined,
+        reject,
+      );
+    });
+  }
+
+  private async loadAudio(entry: AudioEntry): Promise<void> {
+    if (!this.audioContext) {
+      this.audioContext = new AudioContext();
+    }
+    const response = await fetch(entry.url);
+    const arrayBuffer = await response.arrayBuffer();
+    const audioBuffer = await this.audioContext.decodeAudioData(arrayBuffer);
+    this.assets.audio.set(entry.key, audioBuffer);
+  }
+
+  private loadCubeTexture(entry: CubeTextureEntry): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.cubeTextureLoader.load(
+        entry.urls,
+        (tex) => {
+          this.assets.cubeTextures.set(entry.key, tex);
+          resolve();
+        },
+        undefined,
+        reject,
+      );
+    });
+  }
+}

package/skills/threejs.aicomponent/ref/BaseScene.ts

@@ -0,0 +1,88 @@
+import * as THREE from "three";
+import type { SceneKey } from "../SceneKeys";
+
+export type SceneTransitionFn = (targetKey: SceneKey) => void;
+
+/**
+ * 所有场景的基类，提供统一的生命周期接口。
+ *
+ * 生命周期：
+ *   init()    → 首次进入时调用，初始化 Three.js 对象
+ *   enter()   → 每次切到此场景时调用（含首次）
+ *   update(dt, elapsed) → 每帧调用
+ *   exit()    → 离开此场景时调用
+ *   dispose() → 销毁场景资源
+ */
+export abstract class BaseScene {
+  readonly key: SceneKey;
+  readonly scene: THREE.Scene;
+
+  protected _camera: THREE.PerspectiveCamera | null = null;
+  protected _initialized = false;
+  protected _goToScene: SceneTransitionFn = () => {};
+
+  constructor(key: SceneKey) {
+    this.key = key;
+    this.scene = new THREE.Scene();
+  }
+
+  get camera(): THREE.PerspectiveCamera | null {
+    return this._camera;
+  }
+
+  /** SceneManager 注入，子类不要覆盖 */
+  _bind(goToScene: SceneTransitionFn): void {
+    this._goToScene = goToScene;
+  }
+
+  /** 首次进入时由 SceneManager 调用 */
+  init(camera: THREE.PerspectiveCamera): void {
+    this._camera = camera;
+    this._initialized = true;
+    this.onInit();
+  }
+
+  /** 每次切入场景时调用 */
+  enter(): void {
+    this.onEnter();
+  }
+
+  /** 每帧由 SceneManager 调用，dt 单位秒 */
+  update(dt: number, elapsed: number): void {
+    this.onUpdate(dt, elapsed);
+  }
+
+  /** 离开场景时调用 */
+  exit(): void {
+    this.onExit();
+  }
+
+  /** 销毁场景，释放 GPU 资源 */
+  dispose(): void {
+    this.onDispose();
+    this.scene.traverse((obj) => {
+      if (obj instanceof THREE.Mesh) {
+        obj.geometry?.dispose();
+        const materials = Array.isArray(obj.material) ? obj.material : [obj.material];
+        for (const mat of materials) {
+          if (mat && typeof mat.dispose === "function") {
+            mat.dispose();
+          }
+        }
+      }
+    });
+    this.scene.clear();
+  }
+
+  protected goToScene(key: SceneKey): void {
+    this._goToScene(key);
+  }
+
+  // ─── 子类覆盖 ───
+
+  protected onInit(): void {}
+  protected onEnter(): void {}
+  protected onUpdate(_dt: number, _elapsed: number): void {}
+  protected onExit(): void {}
+  protected onDispose(): void {}
+}

package/skills/threejs.aicomponent/ref/GameConfig.ts

@@ -0,0 +1,47 @@
+/**
+ * 游戏全局配置（通用基础版）。
+ *
+ * 具体游戏的业务常量（关卡参数、物理系数等）应在各自模块中声明，
+ * 不要污染此文件。
+ */
+export const GameConfig = {
+  // ─── 渲染 ───
+  antialias: true,
+  shadows: true,
+  toneMapping: "ACESFilmic" as "ACESFilmic" | "Linear" | "Reinhard" | "Cineon",
+  toneMappingExposure: 1.0,
+  maxPixelRatio: 2,
+
+  // ─── 相机 ───
+  camera: {
+    fov: 60,
+    near: 0.1,
+    far: 1000,
+    position: { x: 0, y: 3, z: 5 } as { x: number; y: number; z: number },
+    lookAt: { x: 0, y: 0, z: 0 } as { x: number; y: number; z: number },
+  },
+
+  // ─── 灯光 ───
+  lighting: {
+    ambientColor: 0x404040,
+    ambientIntensity: 1.0,
+    directionalColor: 0xffffff,
+    directionalIntensity: 1.5,
+    directionalPosition: { x: 5, y: 8, z: 5 } as { x: number; y: number; z: number },
+  },
+
+  // ─── 场景 ───
+  clearColor: 0x1a1a2e,
+  debugScene: "main" as "preloader" | "main",
+
+  // ─── 调试 ───
+  showFps: false,
+  showGrid: true,
+  enableOrbitControls: true,
+
+  // ─── 音频 ───
+  settings: {
+    musicOn: true,
+    soundOn: true,
+  },
+};

package/skills/threejs.aicomponent/ref/MainScene.ts

@@ -0,0 +1,170 @@
+import * as THREE from "three";
+import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+import { BaseScene } from "./BaseScene";
+import { SceneKeys } from "../SceneKeys";
+import { GameConfig } from "../GameConfig";
+
+/**
+ * 主游戏场景（空白骨架）。
+ *
+ * 执行脚手架后，此场景显示旋转的 Torus Knot + 网格 + 坐标轴，
+ * 作为开发起点。替换 onInit() / onUpdate() 中的内容即可开始编写游戏逻辑。
+ */
+export class MainScene extends BaseScene {
+  private controls: OrbitControls | null = null;
+  private torusKnot: THREE.Mesh | null = null;
+  private fpsDiv: HTMLDivElement | null = null;
+  private frameCount = 0;
+  private fpsTime = 0;
+
+  constructor() {
+    super(SceneKeys.Main);
+  }
+
+  protected onEnter(): void {
+    const overlay = document.getElementById("loading-overlay");
+    if (overlay) overlay.classList.add("hidden");
+  }
+
+  protected onInit(): void {
+    if (!this._camera) return;
+
+    // ─── 背景 ───
+    this.scene.background = new THREE.Color(GameConfig.clearColor);
+    this.scene.fog = new THREE.Fog(GameConfig.clearColor, 20, 80);
+
+    // ─── 灯光 ───
+    const { lighting } = GameConfig;
+
+    const ambient = new THREE.AmbientLight(lighting.ambientColor, lighting.ambientIntensity);
+    this.scene.add(ambient);
+
+    const dirLight = new THREE.DirectionalLight(lighting.directionalColor, lighting.directionalIntensity);
+    dirLight.position.set(
+      lighting.directionalPosition.x,
+      lighting.directionalPosition.y,
+      lighting.directionalPosition.z,
+    );
+    dirLight.castShadow = GameConfig.shadows;
+    if (dirLight.shadow) {
+      dirLight.shadow.mapSize.setScalar(1024);
+      dirLight.shadow.camera.near = 0.5;
+      dirLight.shadow.camera.far = 50;
+      const s = 10;
+      dirLight.shadow.camera.left = -s;
+      dirLight.shadow.camera.right = s;
+      dirLight.shadow.camera.top = s;
+      dirLight.shadow.camera.bottom = -s;
+    }
+    this.scene.add(dirLight);
+
+    // ─── 地面 ───
+    const groundGeo = new THREE.PlaneGeometry(30, 30);
+    const groundMat = new THREE.MeshStandardMaterial({
+      color: 0x222244,
+      roughness: 0.9,
+      metalness: 0.1,
+    });
+    const ground = new THREE.Mesh(groundGeo, groundMat);
+    ground.rotation.x = -Math.PI / 2;
+    ground.receiveShadow = true;
+    this.scene.add(ground);
+
+    // ─── 参考网格 + 坐标轴 ───
+    if (GameConfig.showGrid) {
+      const grid = new THREE.GridHelper(20, 20, 0x444466, 0x333355);
+      grid.position.y = 0.01;
+      this.scene.add(grid);
+
+      const axes = new THREE.AxesHelper(3);
+      axes.position.y = 0.02;
+      this.scene.add(axes);
+    }
+
+    // ─── Hello Three.js — 旋转 Torus Knot ───
+    const geometry = new THREE.TorusKnotGeometry(0.8, 0.3, 128, 32);
+    const material = new THREE.MeshStandardMaterial({
+      color: 0x4488ff,
+      roughness: 0.3,
+      metalness: 0.6,
+    });
+    this.torusKnot = new THREE.Mesh(geometry, material);
+    this.torusKnot.position.y = 1.5;
+    this.torusKnot.castShadow = true;
+    this.scene.add(this.torusKnot);
+
+    // ─── "Hello Three.js!" 文字精灵 ───
+    const canvas = document.createElement("canvas");
+    canvas.width = 512;
+    canvas.height = 128;
+    const ctx = canvas.getContext("2d")!;
+    ctx.fillStyle = "transparent";
+    ctx.fillRect(0, 0, 512, 128);
+    ctx.font = "bold 48px Arial, sans-serif";
+    ctx.fillStyle = "#ffffff";
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.fillText("Hello Three.js!", 256, 64);
+
+    const spriteTex = new THREE.CanvasTexture(canvas);
+    const spriteMat = new THREE.SpriteMaterial({ map: spriteTex, transparent: true });
+    const sprite = new THREE.Sprite(spriteMat);
+    sprite.position.set(0, 3.2, 0);
+    sprite.scale.set(4, 1, 1);
+    this.scene.add(sprite);
+
+    // ─── OrbitControls ───
+    if (GameConfig.enableOrbitControls) {
+      const rendererDom = document.querySelector("#game-container canvas");
+      if (rendererDom) {
+        this.controls = new OrbitControls(this._camera, rendererDom as HTMLElement);
+        this.controls.enableDamping = true;
+        this.controls.dampingFactor = 0.08;
+        this.controls.target.set(0, 1, 0);
+        this.controls.update();
+      }
+    }
+
+    // ─── FPS 显示 ───
+    if (GameConfig.showFps) {
+      this.fpsDiv = document.createElement("div");
+      Object.assign(this.fpsDiv.style, {
+        position: "fixed",
+        top: "8px",
+        left: "8px",
+        padding: "2px 6px",
+        background: "rgba(0,0,0,0.5)",
+        color: "#0c0",
+        fontSize: "12px",
+        fontFamily: "monospace",
+        zIndex: "9999",
+        pointerEvents: "none",
+      });
+      document.body.appendChild(this.fpsDiv);
+    }
+  }
+
+  protected onUpdate(dt: number, elapsed: number): void {
+    if (this.torusKnot) {
+      this.torusKnot.rotation.y = elapsed * 0.5;
+      this.torusKnot.rotation.x = elapsed * 0.3;
+    }
+
+    this.controls?.update();
+
+    if (this.fpsDiv) {
+      this.frameCount++;
+      this.fpsTime += dt;
+      if (this.fpsTime >= 0.5) {
+        this.fpsDiv.textContent = `FPS: ${Math.round(this.frameCount / this.fpsTime)}`;
+        this.frameCount = 0;
+        this.fpsTime = 0;
+      }
+    }
+  }
+
+  protected onDispose(): void {
+    this.controls?.dispose();
+    this.fpsDiv?.remove();
+  }
+}

package/skills/threejs.aicomponent/ref/PreloaderScene.ts

@@ -0,0 +1,93 @@
+import { BaseScene } from "./BaseScene";
+import { SceneKeys } from "../SceneKeys";
+import { AssetLoader, type AssetManifest } from "../utils/AssetLoader";
+
+/**
+ * 预加载场景。
+ *
+ * 使用 HTML overlay 显示加载进度（CSS 动画，无需 Three.js 渲染）。
+ * 加载完成后自动切换到 Main 场景。
+ *
+ * 要加载资源，在 getManifest() 中返回资源清单即可。
+ */
+export class PreloaderScene extends BaseScene {
+  private loader = new AssetLoader();
+
+  constructor() {
+    super(SceneKeys.Preloader);
+  }
+
+  protected onEnter(): void {
+    this.showOverlay();
+    this.startLoading();
+  }
+
+  /**
+   * 定义资源清单。按需添加资源条目。
+   *
+   * 示例：
+   * ```typescript
+   * import logoTexture from "assets/images/logo.webp";
+   * import modelFile from "assets/models/character.glb";
+   *
+   * return {
+   *   textures: [{ key: "logo", url: logoTexture }],
+   *   models: [{ key: "character", url: modelFile }],
+   * };
+   * ```
+   */
+  protected getManifest(): AssetManifest {
+    return {};
+  }
+
+  private async startLoading(): Promise<void> {
+    const manifest = this.getManifest();
+
+    try {
+      await this.loader.loadAll(manifest, (progress) => {
+        this.updateProgress(progress);
+      });
+    } catch (err) {
+      console.error("[PreloaderScene] Loading failed:", err);
+    }
+
+    this.updateProgress(1);
+    this.setLoadingText("Ready");
+
+    await this.delay(300);
+    this.hideOverlay();
+    this.goToScene(SceneKeys.Main);
+  }
+
+  private showOverlay(): void {
+    const overlay = document.getElementById("loading-overlay");
+    if (overlay) {
+      overlay.classList.remove("hidden");
+    }
+  }
+
+  private hideOverlay(): void {
+    const overlay = document.getElementById("loading-overlay");
+    if (overlay) {
+      overlay.classList.add("hidden");
+    }
+  }
+
+  private updateProgress(value: number): void {
+    const bar = document.getElementById("loading-bar");
+    if (bar) {
+      bar.style.width = `${Math.round(value * 100)}%`;
+    }
+  }
+
+  private setLoadingText(text: string): void {
+    const el = document.getElementById("loading-text");
+    if (el) {
+      el.textContent = text;
+    }
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/skills/threejs.aicomponent/ref/SceneKeys.ts

@@ -0,0 +1,6 @@
+export const SceneKeys = {
+  Preloader: "Preloader",
+  Main: "Main",
+} as const;
+
+export type SceneKey = (typeof SceneKeys)[keyof typeof SceneKeys];

package/skills/threejs.aicomponent/ref/SceneManager.ts

@@ -0,0 +1,69 @@
+import * as THREE from "three";
+import { BaseScene } from "./scenes/BaseScene";
+import type { SceneKey } from "./SceneKeys";
+
+/**
+ * 场景生命周期管理器。
+ *
+ * 管理多个 BaseScene 实例的注册、切换和更新。
+ * 同一时刻只有一个活跃场景，切换时自动调用 exit/enter。
+ */
+export class SceneManager {
+  private scenes = new Map<SceneKey, BaseScene>();
+  private _activeScene: BaseScene | null = null;
+  private _camera: THREE.PerspectiveCamera;
+
+  constructor(camera: THREE.PerspectiveCamera) {
+    this._camera = camera;
+  }
+
+  get activeScene(): BaseScene | null {
+    return this._activeScene;
+  }
+
+  get activeThreeScene(): THREE.Scene | null {
+    return this._activeScene?.scene ?? null;
+  }
+
+  register(...scenes: BaseScene[]): void {
+    for (const s of scenes) {
+      s._bind((key) => this.switchTo(key));
+      this.scenes.set(s.key, s);
+    }
+  }
+
+  switchTo(key: SceneKey): void {
+    const next = this.scenes.get(key);
+    if (!next) {
+      console.warn(`[SceneManager] Scene "${key}" not registered`);
+      return;
+    }
+
+    if (this._activeScene) {
+      this._activeScene.exit();
+    }
+
+    if (!next["_initialized"]) {
+      next.init(this._camera);
+    }
+
+    next.enter();
+    this._activeScene = next;
+
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      console.log(`[SceneManager] → ${key}`);
+    }
+  }
+
+  update(dt: number, elapsed: number): void {
+    this._activeScene?.update(dt, elapsed);
+  }
+
+  dispose(): void {
+    for (const s of this.scenes.values()) {
+      s.dispose();
+    }
+    this.scenes.clear();
+    this._activeScene = null;
+  }
+}

package/skills/threejs.aicomponent/ref/ViewportManager.ts

@@ -0,0 +1,62 @@
+import * as THREE from "three";
+
+/**
+ * 响应式视口管理器。
+ *
+ * 监听 container resize（通过 ResizeObserver），自动更新：
+ * - renderer 尺寸与像素比
+ * - camera 宽高比
+ *
+ * 比 Phaser 的 reload 方案更高效，无需刷新页面。
+ */
+export class ViewportManager {
+  private renderer: THREE.WebGLRenderer;
+  private camera: THREE.PerspectiveCamera;
+  private container: HTMLElement;
+  private observer: ResizeObserver | null = null;
+  private maxPixelRatio: number;
+
+  constructor(
+    renderer: THREE.WebGLRenderer,
+    camera: THREE.PerspectiveCamera,
+    container: HTMLElement,
+    maxPixelRatio = 2,
+  ) {
+    this.renderer = renderer;
+    this.camera = camera;
+    this.container = container;
+    this.maxPixelRatio = maxPixelRatio;
+  }
+
+  enable(): void {
+    this.observer = new ResizeObserver(() => this.handleResize());
+    this.observer.observe(this.container);
+  }
+
+  disable(): void {
+    this.observer?.disconnect();
+    this.observer = null;
+  }
+
+  /** 手动触发一次 resize 计算 */
+  refresh(): void {
+    this.handleResize();
+  }
+
+  getSize(): { width: number; height: number; aspect: number } {
+    const width = this.container.clientWidth;
+    const height = this.container.clientHeight;
+    return { width, height, aspect: width / height };
+  }
+
+  private handleResize(): void {
+    const { width, height, aspect } = this.getSize();
+    if (width === 0 || height === 0) return;
+
+    this.camera.aspect = aspect;
+    this.camera.updateProjectionMatrix();
+
+    this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, this.maxPixelRatio));
+    this.renderer.setSize(width, height);
+  }
+}