# miniYX

**Repository Path**: baby_lee/mini-yx

## Basic Information

- **Project Name**: miniYX
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-28
- **Last Updated**: 2026-02-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# miniYX

极简解压微信小游戏核心逻辑与渲染层。

## 竖屏与平台集成要求（Story 1.4）

- **竖屏锁定**：`game.json` 中设置 `deviceOrientation: "portrait"`，主场景 `orientation: "portrait"` 与之一致。
- **无挽留弹窗**：用户关闭或切后台时，**禁止**在 `onHide`/退出路径中显示挽留弹窗、确认对话框或失败提示；应静默结束会话。
- **再次进入新会话**：每次启动或 `onShow` 后首次进入主场景时，调用 `createMainScene()` 创建全新会话，**不**恢复旧会话状态（`restore`）。

## 集成渲染层

渲染层（`src/render/`）需在小游戏入口与主循环中接入，才能显示气泡与背景。

### 基本用法

```js
const { createMainScene, handlePinch, handleRelease, getViewState } = require("./src/ui/mainScene");
const { renderMainScene } = require("./src/render/renderMainScene");

// 1. 创建主场景（每次进入/onShow 时调用，不 restore）
let scene = createMainScene({ storageAdapter: wx.getStorageSync ? { getGuideCompleted: () => !!wx.getStorageSync("guideDone"), setGuideCompleted: () => wx.setStorageSync("guideDone", true) } : null });

// 2. 获取 Canvas 2D 上下文（微信小游戏 type='2d'）
const canvas = ...; // wx.createCanvas() 或等效
const ctx = canvas.getContext("2d");

// 3. 主循环：每帧传入同一 gradientCache 以复用渐变
const gradientCache = {};
function render() {
  const viewState = getViewState(scene);
  renderMainScene(ctx, viewState, canvas.width, canvas.height, {
    theme: "dark", // 或 "light"
    gradientCache,
  });
  requestAnimationFrame(render);
}
render();

// 4. 捏合/松手时更新场景
// onTouchMove: scene = handlePinch(scene, strength);
// onTouchEnd: scene = handleRelease(scene);
```

### 关键点

- **gradientCache**：必须在帧间复用同一对象，否则渐变缓存无效，影响性能。
- **getViewState(scene)**：将 `scene` 状态映射为渲染所需的 `viewState`（含 `bubbleScale` 等）。

### 平台集成（PlatformAdapter + InputController）

完整小游戏入口见 `game.js`。使用 `PlatformAdapter` 封装 `onShow`/`onHide`：onShow 时创建新场景，onHide 时静默结束。使用 `InputController` 监听触摸事件，识别双指捏合/松手并计算 strength。

**触摸坐标说明：** 微信小游戏 `wx.onTouchStart` 等返回的坐标（`clientX`/`clientY` 或 `x`/`y`）需与 canvas 坐标系一致。若 canvas 有缩放或偏移，需在 `InputController` 中做坐标转换后再调用 `isPointInBubbleArea`。建议在真机/模拟器上验证捏合命中检测。

## 验证与文档

- **真机验证清单**：`docs/verification-checklist-epic2-haptics.md`（Story 2.2/2.3/2.4 触觉与视觉降级）
- **3–5 分钟会话验证**：`docs/manual-session-verification.md`
- **状态生命周期指南**：`docs/state-lifecycle-guideline.md`（Epic 3+ 开发参考）
- **E2E 测试评估**：`docs/e2e-test-evaluation.md`

## 运行测试

```bash
npm test
```