Merge branch 'master' of http://82.157.175.59:3000/GenarrativeAI/Genarrative

docs/prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md

@@ -151,9 +151,9 @@ Agent 的职责是帮助用户确认可以直接编译 demo 的最小配置：
 
 题材决定后续生成或选择物品素材的方向。用户可以自定义主题，例如水果、玩具、食物、符号等。
 
-首版 demo 不接入真实图片生成。运行态可消除物统一使用纯色几何体表现，不使用透明气泡，也不在图案上放文字标识。题材仍决定后端生成的 `visualKey` 和尺寸比例，但前端首版用差异化颜色与几何造型表现可消除物，例如圆形、三角形、菱形、五角星、梯形、平行四边形等，避免玩家在堆叠状态下难以辨认。
+首版 demo 不接入真实图片生成。当前运行态可消除物统一使用参考图方向的 25 个积木件类型表现，不使用透明气泡，也不在图案上放文字标识。前端首版用差异化颜色、积木造型和 3D 程序化模型表现可消除物，避免玩家在堆叠状态下难以辨认。
 
-水果图形资产需要具备常识可感知的相对大小关系，但不要求真实比例绝对精准。首版固定规则为：西瓜明显大于苹果；苹果、橙子、梨、桃子为中等尺寸；葡萄、李子、青柠等小型水果略小。该尺寸由后端运行态物品 `radius` 下发，前端只按快照表现。
+可消除物尺寸使用五档相对体积规则：XL 型相对体积为 `1.60~2.30`，L 型为 `1.25~1.60`，M 型为 `1.00`，XS 型为 `0.65~0.85`，S 型为 `0.35~0.50`。单局中 XL / L / M / XS / S 按本局使用的消除物类型数的 `20% / 30% / 30% / 15% / 5%` 分配；非整数配额按最大余数补齐，确保总数等于本局使用类型数量。同一关卡内同一个颜色和造型的物品只能对应一个尺寸档位；可存在同尺寸但不同颜色和造型的物品。后端运行态通过 `radius` 下发权威尺寸，前端只按快照表现。
 
 ### 需要消除次数
 
@@ -265,6 +265,16 @@ totalItemCount = clearCount * 3
 
 每种物品数量必须是 `3` 的倍数，避免生成无法通关的局。
 
+生成的消除物类型数由用户填写的需要消除次数决定：
+
+```text
+itemTypeCount = clearCount <= 25 ? clearCount : 25
+```
+
+当 `clearCount <= 25` 时，本局生成的 `itemTypeId` 数量等于 `clearCount`，每种类型默认生成 `3` 件；当 `clearCount > 25` 时，本局最多生成 `25` 种 `itemTypeId`，后续消除组按这 `25` 种类型轮转补齐，且每种类型最终数量仍必须保持 `3` 的倍数。
+
+同一局内这些类型必须分别使用不同的形状和颜色组合，不能出现两个组看起来像同一种物体的情况。
+
 ## 8.4 阶段陆续生成
 
 每局物品允许阶段陆续生成。
@@ -277,8 +287,8 @@ totalItemCount = clearCount * 3
 
 首版 demo 使用 2D 图案素材。
 
-1. demo 至少提供 `10` 种颜色与几何造型组合素材。
-2. 当题材为水果时，后端仍可切换到 `10` 种水果视觉键和尺寸比例，但前端首版必须把这些视觉键映射为无文字的纯色几何体，不能显示为水果图、透明气泡或文字标记。
+1. demo 至少提供 `25` 种彼此不同的颜色与几何造型组合素材，支撑 `clearCount > 25` 时的类型上限。
+2. 当前 demo 使用 25 个积木件视觉键作为默认素材池；前端首版必须把这些视觉键映射为无文字的纯色 2D 图标和程序化 3D 积木模型，不能显示为透明气泡或文字标记。
 3. 后续可以尝试替换为伪 3D 或 3D 模型。
 4. 用户题材主题后续会映射为符合常识预期的物品集合。
 
@@ -310,6 +320,8 @@ totalItemCount = clearCount * 3
 
 飞行动画过程中，物品不再与其他物品产生碰撞。
 
+当前 3D 实验模式下，物品进入备选栏后必须从圆形空间的物理世界移除；备选栏只展示该物品同款 3D 模型的独立预览，固定为斜 `45` 度便于识别，不再参与场内碰撞、重力或堆叠。
+
 前端播放即时反馈的同时，必须向后端提交点击意图。后端确认后固化入槽结果；后端拒绝时，前端恢复物品位置和备选栏表现。
 
 ## 8.9 备选栏
@@ -318,8 +330,9 @@ totalItemCount = clearCount * 3
 
 1. 每次点击进入即时反馈流程后，前端先把物品表现为进入备选栏。
 2. 备选栏中每出现 `3` 个相同物品 id，前端立即播放自动消除效果并腾出格子。
-3. 后端确认后固化真实备选栏和消除结果；若后端返回状态不一致，前端必须以最新后端快照校正。
-4. 如果备选栏满且无法消除，前端可以立即展示失败过渡，最终失败状态以后端确认为准。
+3. 3D 模式下，备选栏格子展示从场内取出的同款 3D 模型预览，视角固定斜 `45` 度，不使用另一套不一致的 UI 图标；托盘预览必须共享一个 WebGL renderer，不能因多个预览上下文导致中心场地模型不可见；WebGL 回退或 `2D` 模式下才使用保留的 2D 图标。
+4. 后端确认后固化真实备选栏和消除结果；若后端返回状态不一致，前端必须以最新后端快照校正。
+5. 如果备选栏满且无法消除，前端可以立即展示失败过渡，最终失败状态以后端确认为准。
 
 ## 8.10 胜利
 

docs/technical/MATCH3D_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-30.md

@@ -518,15 +518,25 @@ totalItemCount = clearCount * 3
 
 每种 `itemTypeId` 的数量必须是 `3` 的倍数。
 
+消除物类型数按创作输入的 `clearCount` 计算：
+
+```text
+itemTypeCount = clearCount <= 25 ? clearCount : 25
+```
+
+当 `clearCount <= 25` 时，运行态快照中的不同 `itemTypeId` 数量必须等于 `clearCount`；当 `clearCount > 25` 时，不同 `itemTypeId` 数量必须等于 `25`。超过 `25` 组的消除目标按这 `25` 种类型轮转生成，确保每种类型的最终数量仍是 `3` 的倍数。
+
+这 `25` 组在同一局内还必须对应 25 套不同的形状和颜色签名，不能有两组视觉上撞型。
+
 ## 9.3 demo 视觉素材
 
-首版使用内置视觉键和前端内置几何图形资产，不接真实图片生成。
+首版使用 25 个内置积木件视觉键和前端内置几何图形资产，不接真实图片生成。
 
-1. 水果题材必须使用 `watermelon-green / apple-red / banana-yellow / grape-purple / melon-green / berry-blue / peach-pink / plum-indigo / lime-lime / orange-orange` 这组内置水果视觉键；前端首版将其映射为纯色几何体，不渲染水果写实图，也不能显示为带文字或透明气泡的小球。
-2. 非水果题材暂使用 `red_circle / yellow_triangle / purple_diamond / green_square / blue_star / orange_hexagon / cyan_capsule / pink_heart / lime_leaf / white_moon` 这组兜底颜色形状视觉键。
-3. `visualKey` 不允许在前端统一兜底为同一个素材；未知 key 至少要有稳定的颜色差异，避免多个不同 `itemTypeId` 被玩家误认为同一种物品。
-4. 运行态图案必须使用实心、高饱和、无文字的几何 SVG，至少覆盖圆形、三角形、菱形、方形、五角星、六边形、胶囊、心形、梯形、平行四边形等多种轮廓；外层命中按钮不得再显示半透明气泡底。
-5. 水果题材的相对尺寸由后端权威半径决定，首版要求西瓜明显大于苹果，苹果、橙子、桃子等中型水果大于葡萄、李子、青柠等小型水果；前端不得自行改写规则半径，只负责按快照表现。
+1. 当前 demo 使用 25 个积木件视觉键作为默认素材池；前端首版将其映射为无文字的 2D 图标和程序化 3D 积木模型，不渲染写实图，也不能显示为带文字或透明气泡的小球。
+2. `visualKey` 不允许在前端统一兜底为同一个素材；未知 key 至少要有稳定的颜色差异，避免多个不同 `itemTypeId` 被玩家误认为同一种物品。
+3. 运行态图案必须使用实心、高饱和、无文字的几何 SVG，并保持与 3D 模型同一批 `visualKey` 对应关系；外层命中按钮不得再显示半透明气泡底。
+4. 每局按使用类型数量分配五档相对体积：XL 型 `1.60~2.30` 占 `20%`，L 型 `1.25~1.60` 占 `30%`，M 型固定 `1.00` 占 `30%`，XS 型 `0.65~0.85` 占 `15%`，S 型 `0.35~0.50` 占 `5%`。非整数配额按最大余数补齐，总数必须等于本局使用类型数量。
+5. 同一局内同一个颜色和造型的 `visualKey` 只能对应一个尺寸档位和一个半径，不能出现同一物品类型三件副本大小不同，也不能出现同一视觉键在复用时被分配到两种大小。前端不得自行改写规则半径，只负责按快照表现。
 6. 后续接入真实题材图片素材前，必须另补资产生成方案。
 
 ## 9.4 难度
@@ -646,9 +656,10 @@ src/components/match3d-runtime/
 
 1. 圆形空间占据主要区域。
 2. 备选栏固定 `7` 格。
-3. 倒计时清晰但不遮挡物品。
-4. 物品点击区域稳定，不因动画造成布局跳动。
-5. 胜利/失败结算使用独立面板，不在当前面板下方展开。
+3. 3D 模式下，备选栏格子使用与圆形空间内一致的程序化 3D 模型预览，固定斜 `45` 度视角，且不接入场内物理碰撞；托盘预览必须共享一个 WebGL renderer，不能每格创建独立 renderer；仅 WebGL 回退或 `2D` 模式使用 2D 图标。
+4. 倒计时清晰但不遮挡物品。
+5. 物品点击区域稳定，不因动画造成布局跳动。
+6. 胜利/失败结算使用独立面板，不在当前面板下方展开。
 
 ## 11.5 本地 mock 口径
 

docs/technical/MATCH3D_RUNTIME_3D_GEOMETRY_EXPERIMENT_2026-05-02.md

@@ -19,7 +19,7 @@
 1. 现有 `Match3DVisualIcon`、`Match3DToken` 和托盘 2D 图案渲染代码必须保留。
 2. 新增 3D 表现层只作为运行态棋盘的可选渲染分支。
 3. 当浏览器不支持 WebGL、3D 依赖加载失败或实验开关关闭时，运行态必须自动回到现有 2D 图案表现。
-4. 托盘继续使用当前 2D 图标，便于玩家识别已选物品，也便于实验失败时快速回滚。
+4. 3D 模式下，托盘直接复用场内同一套程序化 3D 模型，以固定斜 `45` 度识别视角展示已选物品；托盘内物品不进入物理世界，不参与碰撞。WebGL 不可用或实验回退时，托盘继续使用当前 2D 图标。
 
 ## 3. 工程落点
 
@@ -50,7 +50,7 @@ cannon-es
 
 3D 分支只读取后端快照中的物品坐标、层级、可点击状态和视觉键。物理碰撞、轻微堆叠和几何体姿态只作为前端表现层，不改变消除规则、备选栏规则、胜负判定或最终权威快照。
 
-`match3dVisualAssets.tsx` 保留 2D 纯色几何图案映射，运行态托盘继续使用该 2D 图标；`match3dRuntimePresentation.ts` 收口显示层坐标和状态兼容，避免异常旧坐标把 2D 或 3D 物体推到圆形边界外。
+`match3dVisualAssets.tsx` 保留 2D 纯色几何图案映射，运行态托盘在 3D 模式下通过 `Match3DTrayPreviewBoard` 使用单个共享 WebGL 预览层复用 `createMatch3DItemMesh` 生成同款 3D 模型，不能为每个托盘格单独创建 `WebGLRenderer`。WebGL 不可用或 2D 回退时继续使用该 2D 图标；`match3dRuntimePresentation.ts` 收口显示层坐标和状态兼容，避免异常旧坐标把 2D 或 3D 物体推到圆形边界外。
 
 ## 4. 验收口径
 
@@ -58,8 +58,10 @@ cannon-es
 2. 3D 几何体保持在圆形区域内，不被圆形边界裁切到不可点。
 3. 物体进入场景后有轻微物理碰撞和堆叠稳定过程。
 4. 点击 3D 物体后仍执行原有乐观入槽、后端确认、三消反馈和结算。
-5. 单元测试仍覆盖 2D 回退图案，确保回退路径没有被删除。
-6. 390px 移动端与桌面端均不能出现横向溢出，顶部状态、圆形棋盘和 7 格备选栏都要完整可见。
+5. 被取出的 3D 物体必须立即从棋盘物理世界移除；备选栏展示的是无碰撞、固定角度的独立预览模型，不允许继续受场内碰撞、重力或堆叠影响。
+6. 托盘 3D 预览必须共享一个 renderer，避免多个 WebGL 上下文导致中心棋盘上下文被浏览器回收；中心棋盘监听 `webglcontextlost`，丢失时自动回退 2D 表现，禁止出现模型不可见但仍可点击的状态。
+7. 单元测试仍覆盖 2D 回退图案，确保回退路径没有被删除。
+8. 390px 移动端与桌面端均不能出现横向溢出，顶部状态、圆形棋盘和 7 格备选栏都要完整可见。
 
 ## 5. 锅型容器优化
 
@@ -72,3 +74,88 @@ cannon-es
 3. 物理世界使用同一个锅内半径作为水平活动边界，所有可消除物体的初始位置和运行中位置都必须被约束在圆形锅内。
 4. 物体受到重力后只允许在锅内碰撞、滑动、翻滚和向上堆叠，不能因为碰撞或初始坐标散落到圆形区域外。
 5. 该优化仍只属于前端 3D 表现层，不改变后端运行态坐标、点击权威判定、备选栏、消除和胜负规则。
+
+## 6. 中心引力优化
+
+2026-05-02 追加中心引力，用来解决高消除次数下 3D 物体过于松散、贴边后被圆形场地裁切的问题。体验后发现默认向心力会让模型过度挤压成团，因此当前先关闭默认引力，只保留代码开关，后续如需再尝试可重新调参。
+
+编码口径：
+
+1. 中心引力默认系数为 `0`，默认不对物理 body 施加水平向心力。
+2. 引力只作用在 X/Z 平面，不改变垂直重力，物体仍会自然落到锅底或堆叠在其他物体上。
+3. 引力在越靠近锅边时越明显，避免大量物体碰撞后形成稀疏外环；靠近中心时力度收敛，避免所有物体被吸成单点。
+4. 锅内活动边界继续作为硬约束；高数量物体应被锅边挡住并向上堆叠，不允许散落到圆形场地外。
+5. `/match3d?clearCount=100` 可作为本地直达压力测试入口，用于验证 300 个物体时仍在锅内聚拢。
+
+## 7. 正交俯视与真实场地边界
+
+2026-05-02 针对高堆叠时 3D 物体被 DOM 圆形裁切的问题，明确中心圆形区域不是裁切蒙版，而是游戏实际游玩场地。
+
+编码口径：
+
+1. 3D 棋盘使用正交俯视相机，避免高处物体因为透视放大而投影到圆形场地外。
+2. 圆形场地的内圈圆环对应 3D 世界里的锅内空气墙，物体范围由物理约束控制，不再依赖 DOM `overflow-hidden` 裁切。
+3. 外层圆形 UI 只负责显示锅沿和场地外观，不能把物体裁成半截；如果物体看起来越界，优先修正相机、物理半径和空气墙。
+4. 高数量压力测试以 `/match3d?clearCount=100` 为基准，物体可以在场地内向上堆叠，但不能被圆形边缘压住或切掉。
+
+## 8. 类型数量与样式池历史口径
+
+2026-05-03 曾调整消除物类型生成规则，解决 3D 关卡中可消除物类型和样式过少的问题。该节为历史口径，后续实际实现以第 11 节 25 个积木件资源池为准。
+
+编码口径：
+
+1. 历史版本曾使用 20 类形状颜色组合。
+2. 当前版本已替换为 25 个积木件，旧 20 类上限不再作为编码依据。
+3. 3D 与 2D 回退仍共用视觉键映射，新增样式不能破坏 `?match3dRender=2d` 回退路径。
+
+## 9. 特殊形状 3D 可读性修正
+
+2026-05-03 针对 20 组关卡中看不到十字、圆环、盾形、闪电、月牙、箭头等新形状的问题，补充 3D 几何体渲染口径。
+
+编码口径：
+
+1. 数据层仍使用 `visualKey` 决定类型，不新增贴图素材或文本标识。
+2. 十字、心形、星形、圆环、盾形、闪电、月牙、箭头、V 形等特殊形状不能继续使用普通盒子、球体或锥体代理，必须生成俯视角可辨认的 3D 轮廓。
+3. 特殊形状使用 Three.js 程序化轮廓挤出生成，保持当前 3D 实验可快速回退，不影响现有 2D 图案分支。
+4. 特殊形状的物理碰撞可以继续使用近似碰撞体，但显示网格需要固定为俯视可读姿态，避免落地翻滚后又变成长方块或普通三角体。
+5. 当前特殊形状已被 25 个积木件资源池替换；不能为了让玩家开局肉眼看到全部类型而改动初始层级、物理堆叠、遮挡、边界或可点击规则。
+
+## 10. 15 组中档局面的类型唯一性修正
+
+2026-05-03 针对 `clearCount=15` 时可消除物类型不足 15 种的问题，补充中档局面的规则验收口径。
+
+编码口径：
+
+1. `clearCount=15` 时，运行态数据中必须生成 `15` 种不同 `itemTypeId`，且首个 `15` 个 `visualKey` 必须分别对应不同几何形状。
+2. 每种 `itemTypeId` 在 `clearCount=15` 时只对应 1 次消除目标，即恰好生成 `3` 件物体；同一种视觉模型在同局中不应出现超过 3 件。
+3. 不为了展示 15 种而修改初始层级、物理堆叠、遮挡、边界或可点击规则；被盖住、堆叠和局部不可见是正常玩法效果。
+4. 当前版本已改为第 11 节的 `itemTypeCount = clearCount <= 25 ? clearCount : 25` 规则。
+
+## 11. 25 个积木件资源池替换
+
+2026-05-03 根据新的参考图，把可消除物体替换为 25 个积木件类型，并调整本局类型抽取规则。
+
+编码口径：
+
+1. 默认 `visualKey` 资源池改为 25 个积木件，覆盖长条、短条、2x2、2x3、2x4、1x1、光板、斜坡、圆柱、透明圆环、拱门和锥形件等差异化模型。
+2. 前端 3D 表现继续使用 Three.js 程序化几何体生成，不引入外部贴图或 GLB；托盘和 2D 回退继续使用同一批 `visualKey` 的简化图标。
+3. `clearCount <= 25` 时，本局从 25 个类型中按确定性随机顺序抽取 `clearCount` 种类型，不允许同局刷新重复类型。
+4. `clearCount > 25` 时，本局最多使用 25 种类型，额外消除组在这 25 种中轮转复用；每种类型最终数量仍必须是 3 的倍数。
+5. 该随机抽取只决定本局使用哪些类型和使用顺序，不改变物理堆叠、遮挡、边界、可点击判定、备选栏和胜负规则。
+6. 前端本地试玩、创作后试玩和后端权威运行态必须使用同一套 `itemTypeCount = clearCount <= 25 ? clearCount : 25` 口径。
+
+## 12. 五档体积规则
+
+2026-05-03 追加可消除物模型大小规则，把每局可消除物按五档相对体积分配。
+
+编码口径：
+
+1. M 型作为标准体积 `1.00`。
+2. XL 型相对体积范围为 `1.60~2.30`，占本局可消除类型数的 `20%`。
+3. L 型相对体积范围为 `1.25~1.60`，占本局可消除类型数的 `30%`。
+4. M 型相对体积固定为 `1.00`，占本局可消除类型数的 `30%`。
+5. XS 型相对体积范围为 `0.65~0.85`，占本局可消除类型数的 `15%`。
+6. S 型相对体积范围为 `0.35~0.50`，占本局可消除类型数的 `5%`。
+7. 本局使用类型数仍按第 11 节计算，即 `clearCount <= 25 ? clearCount : 25`。比例遇到非整数时按最大余数补齐，确保五档数量之和等于本局使用类型数。
+8. 体积档位分配绑定到本局选中的 `visualKey`，同一局内同一个颜色和造型只能有一个尺寸档位和一个半径；当 `clearCount > 25` 轮转复用类型时，复用的同一 `visualKey` 继续沿用同一尺寸。
+9. 前端本地试玩、创作后试玩和后端权威运行态必须使用同一套五档体积分配口径。