Files
XericUIActionVessel/Documentation/XChart-RenderFramework.md
T
lrss3 0d9a3d7417 XChart P17 口径修正:序号只读、矢量场按 3 维坐标 + 相邻两条记录一支箭头
按他 2026-10-25 的澄清(规范 §24.5 / §25 已先改对):

- **序号不再是给人设的**:标题行 `R… D…` 改成文本读数(就地刷新);Body 里不再有任何序号输入控件。
  新增 `RenumberDrawOrder()`:任何结构变化(上移/下移/加/删)之后把每个元素的 `m_DrawOrder`
  重写成它在表里的位置 ⇒ **位置更靠后=绘得更晚=盖在上面**,位置是唯一权威;
  注册序由类型定死,只显示。↑↓ 的 tooltip 也改成讲层序。
- **矢量场数据口径改对**:前三维=坐标 x/y/z(与圆柱/散点同一套归一化)、**一支箭头=相邻两条记录**
  (第 i 条起点、第 i+1 条按绝对/相对解释)、**第 4~7 维=颜色**(色相 0..256 色环 / 饱和 / 明度 / 不透明,
  全可选)。需求印**三个数**(需要几个数值维 / 需要几条记录 / 表里各有多少)——
  "记录不够"与"维数不够"在画面上同形,只有这三个数分得清。
- 支数由纯算术 `XChartVectorFieldMath.ArrowCount(记录数, 上限)` 算(N 条 ⇒ N−1 支,上限裁剪,<2 条 ⇒ 0)。
- **两端各自颜色**:杆用起点色、头用终点色(读两条记录各自的颜色维);沿杆逐顶点渐变留给 P18。
- 生成器 `螺旋矢量场` 改成 **7 维**(坐标 + 色相走满一圈 + 饱和/明度/不透明),自己补列。

判据:编译门三臂 + 3 对照绿;探针 **439** 项 0 失败(新增支数一族);
`p4_control` **57/57** 支臂各红在点名断言上(新增两支:一对不再花两条记录、空表不挡而直接进算术);
`p2` / `family` / `generator_gate` / `hierarchy_gate` 在同一棵交付树上复跑全绿。
过程记录:第一版给"一对不再花两条记录"点名的清单里放了一条**被更前面的守卫挡住、这支变异体碰不到**
的判据,`did not go red` 当场抓出来 ⇒ 按实测改清单,并给零/一条记录补了它自己那支变异体(§25.7)。
2026-10-25 21:01:53 +08:00

1736 lines
151 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# XChart 渲染框架与对象池规范(需求整理)
本文是**实施依据**:先约定职责与流程,再按分期落地。每节末尾的"判据"是必须能机器验证或能明确观察的条目,
不写"应该会更好"这种无法证伪的话。
---
## 0. 现状问题(P0,先修)
### 0.2 一个工具炸掉 = 全部不显示(验收时发现,已修)
`XScatterPointRenderer.SetPoints(positions, colors)` 第一句就读 `positions.Length`,
而散点工具在"没有点"时传了 `null` 表示清空 ⇒ NRE。这个异常发生在 `XChartToolsManager.RenderAll()`
的循环里,**没有隔离**,于是循环中断:排在它后面的所有工具当帧以及之后都不再渲染。
现象就是"我加了一个圆柱元素,所有元素都不显示了"——跟圆柱没关系,是散点先炸了。
修法两半,都要:
1. `null` 表示清空就在渲染器里当清空处理(并在工具侧改用 `ClearAll()`)——**"没有数据"不是一个可以
被解引用的对象**;
2. 渲染/更新循环按工具隔离:一个工具抛异常 ⇒ 报一次带**工具名**的日志,其余工具继续。
隔离但不吞:静默跳过会让更多人变成"不知道为什么没画"。
判据:`grep -rn "SetPoints(null)" Runtime` 为空;`RenderAll` 里每个 `OnRender()` 都在 try 里。
### 0.3 只有最内层能折叠(验收时发现,已修)
`MakeBox` 返回的是带边框的容器,而折叠回调切换的是它内部那个空 `inner`;大分类的内容却直接加在了
外框上 ⇒ 点标题只把空容器藏了,内容照旧显示,看上去"大分类不能折叠,只有最小分组能折"。
约定:**一个可折叠块 = `Root`(描边 + 标题)+ `Body`(内容)**,两件事必须分开——
挂进父级时挂 `Root`,放内容时只放 `Body`。谁往 `Root` 上加内容,谁的折叠就无效。
判据:面板里不存在 `Root.Add(内容)`(只有父 `Body.Add(子 Root)`);`MakeGroup` 一次把 `Root` 与 `Body` 都交出来,
调用点必须显式选一个——选错在面板上立刻能看见(就是这次那样),所以它是个能被一眼证伪的约定。
### 0.1 面板(原 P0)
层级面板在"添加元素"之后:新元素出现在元素板块里,但**其它折叠栏打不开,或打开后没有任何条目**。
根因(机制层面,可核对):
1. 面板用一个挂在**根节点**上的冒泡监听 `RegisterCallback<ChangeEvent<bool/int/float/...>>` 来发现"值变了"。
`Foldout` 本身就是 `INotifyValueChanged<bool>`,所以**点一下分组标题也被当成"值变了"**,进而
`ApplyModifiedProperties()` + (结构签名变化时)`RebuildTree()`。
2. Unity 在带值的元素挂上面板时,会发一次 `isDefaultValue` 的通知(`bool` 的默认值是 `false`)。
我的回调把它当用户操作写进展开状态字典 ⇒ 每次重建后**所有分组的展开状态被打回 false**。
两条叠在一起的表现就是:一次结构性操作之后,展开即重建、重建即全折叠,看上去"打不开/空的"。
判据(修完之后必须成立、修之前必须能红):
- 展开状态只由**用户点击**改变,不由挂起时的默认通知改变;
- 点的/数的值改变**不重建**面板树;只有增删/移动/换类型才重建;
- 折叠栏的开关不触发任何 `serializedObject.ApplyModifiedProperties()`(用一个"操作计数"断言:
纯展开/折叠 100 次 ⇒ 计数为 0)。
---
## 1. 职责划分:chart 管数据,工具只管呈现
- **chart = 数据的所有者与管理者**。所有"这条轴/这个散点显示哪一段数据"的**数据范围**都属于 chart 的基础数据板块,
不属于任何工具。工具只问 chart 要"已经算好的东西",自己不存数据、不解释数据语义。
- **工具(渲染器)= 只呈现**。立方体网格背景、线框、散点、轴线、圆柱、箭头……全部是同一类东西:
拿 chart 给的空间/数据范围/颜色,把自己画出来。
- 面板因此只有两个板块(顺序固定):
1. **基础**:基本变换(四元数姿态、半边长、尺寸口径、中心偏移)、颜色(全局色板)、**数据**(维度、数据范围、
记录/版本统计)、调试(显示节点、重建、回收)。
2. **工具**:图里挂的每个渲染工具一个可折叠块,块内只有该工具的呈现参数。
判据:
- **范围类**字段(手动 min/max)不再出现在任何工具上:它们只有一处主人——chart 数据板块里的**维度行**
(`XChartDimensionDefinition` 的 `OverrideMin` / `OverrideMax` / `ManualRange`,经
`IXChartRenderContext.TryResolveDomain(dimension, out min, out max)` 生效,
工具连范围都不用传)。
- **绑定类**字段("这条轴画哪一维")留在工具上,2026-10-22 验收时他明确选了这一支:
它回答的是"呈现哪一路数据",不是"数据范围多少";散点用它选颜色映射维、箭头用它选起点维,
收归 chart 会让"乘几维"这件事从元素上消失。收归的只有范围。
- 面板顶层只有"基础"和"工具"两个板块;工具块里剩下的全是呈现参数(刻度数、次刻度、标签源、
格式串、颜色、走向…)——没有范围。
- 数据板块里**每个维度一行**:显示名 / 覆盖开关 / 覆盖范围 / 可见,外加一行当前生效范围的说明
(自动值域=该维聚合;这一维没数据就直说"轴这一帧不会出现,勾覆盖可先摆出来")。
---
## 2. 可控绘制流程(谁先画、谁后画、怎么拿数据)
渲染上下文由 chart 建立并持有,工具**不自己 Find 别人**:
```
chart.EnsureInitialized()
→ BuildToolsRoot() 建 [XChartTools] 根(默认:不显示 + 不保存)
→ RegisterTools() ★脚本注册(派生类唯一集中注册点)
→ RebuildElements() 配置注册
→ EnsureSpace() 没有空间工具就补一个默认的
→ RebuildToolPools() §5 的池调度(一次遍历所有脏池)
→ OnChartInitialized() 通用收尾
每帧:
chart.Update() → 刷新判定(数据版本号 / 请求)
chart.LateUpdate() → context.Begin()
→ for each tool: tool.OnRender(context)
→ context.End() 提交本帧申请、回收未用槽位(§5)
```
`IXChartRenderContext`(chart 实现,工具只读)至少开放这些口子:
- `Space` / `ProjectionVersion`:拿投影,`Project(p)`、`Compose(toolTransform)`、`GetFaceFrames()`;
- `GetDomain(dimension)`:该维的**显示范围**(由 chart 的数据板块决定,工具不再自己算 min/max);
- `RequestTextSlots(owner, count)`:见 §5;
- `Palette`:全局颜色(工具自己的颜色是覆盖项,不是唯一来源)。
判据:
- 工具类里不再出现 `FindTool<...>()`(除 chart 自己在初始化时解析空间);
- 散点/轴线的显示范围来自 `context.GetDomain()`,脚本侧改 chart 的数据范围 ⇒ 两类元素同时变(探针断言)。
---
## 3. 作用域纪律:编辑器代码不得渗进运行时
- **运行时命名空间的 `using` 不许落在 `#if UNITY_EDITOR` 里**(2026-10-23 现场):属性参数必须是编译期常量,
而 `[AddComponentMenu(XericRegistrationPaths.Table + "…")]`、`[ContextMenu(…)]` 这些**在玩家编译也要算得出来**。
`using XericUI.Core;` 一旦被守卫住,编辑器那套照样绿、只有玩家编译报 CS0103——他贴的三条就是这个
(`BubbleLayout/BubbleLayoutGroup.cs`、`XTable/Rendering/Component/XericUIActionTable.cs` 与 `.Api.cs`)。
- 这条**由编译门的一支臂强制**:`run_gate.py` 现在除了"运行时(带 UNITY_EDITOR)"和"编辑器"两臂,
还编一支**玩家臂**——同一份 rsp、同一批源码,只把 `-define:` 里的 `UNITY_EDITOR` 剥掉。
它上线第一次跑就复现了那三条(同文件同行),修完转绿;以后这类形状不用靠人想起来。
**盲区记录**:更窄的守卫(`UNITY_EDITOR_WIN` 里用、`UNITY_EDITOR` 里 using)玩家臂也看不见——
那需要第三支"只带平台宏"的臂,等真出现这一类再说,先记在这里别当成已覆盖。
采用仓库里已有的 **partial 分文件** 约定(参考 `XericUIActionTable.cs` / `.Api.cs` / `.Border.cs`):
| 文件 | 内容 | 程序集 |
|---|---|---|
| `XChartRenderToolBase.cs` | 呈现、池槽位访问、脏标记:**纯运行时**,不含 `UnityEditor` | Runtime |
| `XChartRenderToolBase.Editor.cs` | `partial`,编辑器侧调试/检视用的数据导出(只读快照,不画图) | Runtime,整体 `#if UNITY_EDITOR` 包裹 |
| `ChartToolXxx.cs` | 具体工具 | Runtime |
| `XChartPanelEditor.cs` / 池的调试绘制 | 面板与手柄 | **Editor** 程序集,运行时绝不引用 |
规则:
1. Runtime 程序集里**不出现** `using UnityEditor`;需要编辑器行为时只有两种写法:`#if UNITY_EDITOR` 整块包裹,或把
代码放到 Editor 程序集的 `partial` 分文件里。
2. 面板只读运行时暴露的元数据(`[XChartElement]`、字段名、`[Header]`/`[Tooltip]`),不要求运行时提供绘制 API。
3. 调试功能(显示全部节点、强制重建)在运行时暴露**动词**(`RebuildAll()` / `SetGeneratedVisible(bool)`),
编辑器只负责放按钮。
判据:`grep -rn "using UnityEditor" Runtime/XChart` 为空(除 `#if UNITY_EDITOR` 块内)。
---
## 4. 面板呈现规范(box 风格 + 标题纪律)
- 分组一律用**带边框和留白的 box** 包裹:标题行(可折叠)+ 内容缩进。板块(基础/工具)是大 box,工具是嵌套 box。
- box 的**左内边距至少 16px**:折叠小三角是 `Foldout` 自带的 toggle,默认样式带负缩进,
留白不够它就压在左描边上(现象:验收时反馈"box 还是和折叠按钮有冲突,左侧要再往左避让一些")。
嵌套层的左缩进只给 4px——左右两侧各自收紧,否则内层标题会被推出可读宽度。
- **标题一经确定不再改**:标题就是字段的短名,语义写在 `[Tooltip]` 里,浮上去看。
禁止 `标题(一些更新说明)` 这种写法——那是把 changelog 写进 UI。
⇒ 现有需要清理的:`空间(四元数姿态 + 半边长)`、`宿主(立方体的哪个面、往哪个方向走)`、
`填充面(a=前 b=后 …)`、元素行标题 `MeshBg(Cube Mesh Bg Config)` 等,一律改成短标题,说明搬进 Tooltip。
- 元素行的标题只放 `ElementName`;类型名不放标题(放 tooltip 或次级信息行)。
- 判据:面板上所有 `Header` 字符串不含括号;同名字段在两次编译之间标题不变(把标题清单固化进探针/门的一个断言)。
- 折叠的**默认态与开合纪律**(默认全折叠、最深一层互斥)另见 §13——那一节改的就是这一条。
---
## 5. 文本(及同类组件)对象池
**动机**:编辑器阶段组件的任何变换都不会保存 ⇒ 池在域重载后可能整体不存在 ⇒ 没有语言级保证,
只有"每次用之前校验"这一条路。所以:
### 5.1 申请单位是"一批",不是"一个"
- 工具**不能** `var t = pool.Get()` 立刻拿组件。必须先算本帧需要几个:`RequestTextSlots(owner, count)`。
- chart 收到的是"某工具的槽位需求脏了",不是即时分配。
- 派生类通过基类的属性访问已发落的列表:`protected IReadOnlyList<TMP_Text> Texts { get; }`(长度就是申请数),
越界访问要判空并跳过,**不 NRE、不静默画错**。
### 5.2 一次调度:先释放、再补充、顺位优先、池兜底
```
chart.RebuildToolPools() // 帧首或脏标记后调用
1) 收集所有 dirty 的 owner,按申请数排序(先大后小:让先申请者顺位拿到回收件)
2) 对每个 owner:delta = Requested - Current
delta < 0 → 归还 |delta| 个到"本帧回收队列"(先处理释放)
3) 再遍历一次:delta > 0 → 先从"本帧回收队列"取(顺位复用)
队列空 → 从池 get(池里也没有就新建,标记 DontSave/HideInHierarchy)
4) 回收队列仍有剩余 → 才真正 release:setActive(false) 放回池
5) 每个 owner 的列表被换回(换实例而不是原地改长度),并清 dirty
```
要点(就是你的原话的形式化):申请与释放都走"换列表",具体实现层不自己维护实例列表;
组件数变化必须重新申请(换回旧列表 → chart 校验有效性/可见性 → 少了补、多了抽);
抽出来的先给别的 owner 顺位,顺位空了才 get,顺位盈余了才 release。
### 5.3 有效性校验(每次调度都做)
槽位满足下列全部才算可用,否则丢弃并补:`!= null`、`gameObject != null`、`activeSelf` 符合预期、
`transform.parent == 池根`、`(hideFlags & DontSave) != 0`。编辑器域重载后池根可能整个没了——那时
重建池根,而不是抛。
判据(探针可跑,纯 C# 不依赖 Unity 对象也行:把"池"抽象成一个可注入的 `ISlotFactory`):
- 需求 3→5 再 5→2,两轮调度后:顺位复用次数 = 抽取件被别的 owner 用掉的次数,release 次数 = 队列剩余;
- 两个 owner 争抢有限回收件时,先申请者拿到(排序规则生效);
- 任何 `Texts[i]` 都不重复发给两个 owner(同一实例不双主);
- 池根丢失后一次调度能自愈(无异常、数量补齐)。
### 5.4 消费方的三条纪律(写这条是因为雷达那类写法会和校验打架)
1. **不得对发落到的槽位 `SetActive(false)`**:`activeSelf` 是 §5.3 的判据之一,工具自己停用就会
被下一轮调度当无效丢弃、再补新件——每帧丢弃+新建,计数器一直涨。要隐藏内容就**擦文本**
(`text = string.Empty`)或者**少申请几个**。
2. **申请数是总数不是增量**,而且必须在 `OnUpdate` 里申请、在 `OnRender` 里落笔:
chart 的顺序是 `Update → DispatchTextPools → RenderAll`,反了就会出现"这帧申请、下帧才有件"。
3. **只读 `Texts`,不缓存**:池换回列表时旧引用就作废了;取值一律 `i < Texts.Count` 并跳过 null。
**自建文本的残留点(普查口径:`Runtime/XChart` 里 `AddComponent<TextMeshProUGUI>`)**:
只剩 `Pools/XChartTextSlotFactory.cs` 这一处实现。`Axis/ChartToolAxis.cs` 与 `Radar/ChartToolRadarBg.cs`
都已在 P2 迁入池(雷达原先靠逐标签 `SetActive(false)` 隐藏、且数量一变就整数组销毁重建,
按纪律 1 改成"要几个申请几个":关掉标签就是申请 0 个,件直接回池)。
判据:这条 grep 的命中数必须是 1,且命中文件在 `Pools/` 下——多于 1 就说明又有工具自己造标签了。
**离线测不到的一条**(不是"没测到",是没有生产者):`XChartTextSlotFactory.IsAlive` 里
`(hideFlags & HideFlags.DontSave) != 0` 这枚掩码。它要求运行时真有一个 `TMP_Text` 实例,而离线造不出
(在探针里重写一遍同样的表达式=抄自己的实现,一起错也不会红)。它错起来的形状是"每帧都把发落到的
标签当无效丢弃再补新的"⇒ 画面表现为标签闪烁/干脆不见。
**已有现场证人**:§6 的自述报表在编辑器里拍到 684 次调度、`dropped=0`、`idle` 从未为假,
且每次 `hasRange=True` 都 `want==have`——掩码与父子口径在真环境里被反复验过且没判错过。
枚举数值是现测的(引擎自带 mono):`DontSave=52`,编辑器旗标 `DontSaveInEditor|HideInHierarchy=5`,
`5 & 52 = 4 ≠ 0`;运行期 `HideAndDontSave=61`,`61 & 52 = 52 ≠ 0`。
---
## 6. 生命周期、回收与调试
- **chart 下所有生成节点默认:不显示在 Hierarchy + 不保存**。编辑器期 `HideFlags.DontSaveInEditor | HideInHierarchy`,
运行期 `HideAndDontSave`(`CurrentFlags` 统一给)。
- `chart.RebuildAll()`:销毁 chart 生成的**全部**节点(含池根与池内件)→ 校验目录干净(子节点数 == 0)→
走 chart 初始化流程 → 每个工具自己的初始化流程。**重建是"chart + 它的全部工具"一起的**,不把重建丢给某个工具。
- 池也提供 `DestroyAllSlots()`(硬销毁),供 `RebuildAll()` 与调试菜单调用。
**P3 落地形态**:`IXChartSlotFactory.DestroyAll()` + `XChartSlotPool.Dispose()`(调度器只交回列表,
销毁交给认识"件"的实现),`Teardown()` 里先 `DestroyTextPool()` 再拆工具,
并且**现拆现验**——池根挂在 chart 自己下面,`[XChartTools]` 的清理带不走它,
不显式拆就等于每回收重建一次在场景里漏一个 `GeneratedTextPool`(报表会打 `POOL-ROOTS-LEAKED: N`)。
**这条判据上线第一次跑就抓到了真漏**:验收现场 66 次 `POOL-ROOTS-LEAKED`——
漏的不是 `RebuildAll()`(它走 `Teardown`,会把池根拆掉),而是**域重载**:复用旧 `[XChartTools]` 时
只清了 `[XChartTools]` 的子节点,上个域留在 chart 自己下面的池根没人管,新池再建一个就攒一个
(他重启一次 Unity 正好放大)。修法:`BuildToolsRoot()` 里先 `PurgeLeftoverPoolRoots()`。
修完同一条判据在同一套按钮流程下 **66 → 0**。
- 调试动词:`SetGeneratedVisible(bool)`(只改显示,**不改保存位**)。
- **自述报表**(编辑器期,整份文件在 `#if UNITY_EDITOR` 里):工程根存在 `xchart.dump.on` 时,
每 0.4 秒把这张图的关键内部状态追加进 `xchart.dump.txt`——Canvas 在不在、空间版本号与投影尺度、
元素表逐行、池的 owners/acquire/reuse/release/dropped/idle、每个工具的可见性与兄弟序号、
以及每个工具最近一次异常(`LAST-FAILURE`)。开关是文件而不是菜单,是因为面板与渲染同时出问题时
需要同一个时刻两边的读数,而 Console 会滚掉。报表自己炸了就写一条并停下,不每帧抛。
- 判据:`RebuildAll()` 之后工具数、池内件数、生成节点数与首次初始化后一致;显示开关来回切两次 ⇒ 保存位不变(哈希/`hideFlags` 断言)。
---
## 7. 分期实施
| 期 | 内容 | 完成判据 |
|---|---|---|
| P0 | 面板两个根因(默认通知污染展开状态;值改变重建)+ box 风格 + 标题清理 | §0 三条判据;门绿;他看一眼能开能关 |
| P1 | `IXChartRenderContext` 接管:工具不再 `FindTool`;`Space`/`GetDomain` 从 context 拿 | §2 判据;门绿 |
| P2 | 文本池:`ISlotFactory` + 调度算法 + 基类槽位属性;轴线先接入 | §5.3 四条断言在探针里跑(含可红对照)**已达成**:25 项池断言正本全绿,三支变异臂各在指定断言上红;接入方=轴线 + 雷达 |
| P3 | `RebuildAll` / `DestroyAllSlots` / `SetGeneratedVisible` + 调试板块入口 | §6 判据 **已达成**(现场读数):重建前后 `tools/owners/acquire` 逐项一致(池计数器重置回 1、其余不变),`missing-DontSave` 全程 0;池根泄漏 66 → 0;面板行数与表长在正本里恒等 |
| P4 | 数据归属上移:轴/散点的显示范围改由 chart 数据板块给;删工具里的范围字段 | §1 判据:范围字段在工具上只剩绑定;探针 231 项全绿 + p4_control 三支臂红;现场读数(`rangeSource=`)证明范围来自维度行 |
| P5 | 数据窗口:UI Toolkit 虚拟化浏览 + 行文本导出/导入/复制粘贴 | §9;探针含"往返位精确"与"时间非递减被拒"两条 + 各自变异臂;窗口自报绑定次数(灌 1w 条应停在几十) |
| P6 | 圆柱重做:投影从 2D 算起,外轮廓=两片端椭圆的凸包,填充同一多边形,**弧段走曲线渲染器(贝塞尔)**、直线走折线渲染器,可选十字/母线/端面环(=包边的补弧),两端各自法线 | §10(含 10.1–10.5);探针 277 项(圆柱那 15 条各有能红对照,p4_control 共 17 支臂);门三臂 + pool_family + p2/p4 全绿;观感归他 |
每期都要:编译门绿 + 探针绿 + **至少一条能红的对照**(证明新断言在看东西),观感类结论一律归你。
---
## 9. 数据窗口(浏览 / 导入导出 / 复制粘贴)
入口:`Tools/XChart/数据窗口`,或面板"基础 → 数据 → 打开数据窗口"(带着当前图表进去)。
- **虚拟化落在 UI 层**:数据本身仍是 `XChartDataModel` 里那张内存记录表(没有分页、没有懒加载);
虚拟化指"只有滚进可见范围的行才被绑定"。窗口顶部自报 `总行数 / 维度 / 已绑定次数 / 最近绑定行`——
灌一万条后这个次数应停在几十。**把这件事写进窗口里**,免得有人以为数据被分页了。
- **格式只有一份**:导出、导入、复制、粘贴全走 `XChartDataText`(规范 §3)。
行文本而不是 JSON:运行时程序集没有可依赖的 JSON 库,手写解析器等于自己造一个容易错的轮子;
行文本还能直接丢进表格软件、在编辑器里逐行 diff、粘贴替换不需要转义嵌套。
- **数值按往返精度写**(`"R"` + 不变文化):写成 `0.00` 这类格式会在导出→导入之间静默丢精度,
而那种丢失在图上只表现为"点挪了一点点",是最难查的一族——探针有一条断言专门钉这个
(`data text: round trip keeps values bit exact (round-trip precision, not 0.00)`),
并配一支把格式改成 `0.00` 的变异臂证明它会红。
- **导入是全有或全无**:任何一行不合法就整份拒绝并**指出行号**,绝不半途替换掉一半数据
(半份数据比没数据更坏)。注意 `double.TryParse("NaN")` 是**成功**的,所以拒绝必须来自
"值是不是有限"这一步,而不是"能不能解析"——这条也是他现场踩出来的(我第一版期望写错了行号)。
- **破坏性动作**(替换、清空):先弹确认,且**先把当前数据复制到剪贴板**,误操作能捞回来。
---
## 8. 验收时发现、本轮未修的(2026-10-22 记)
1. **数据为空时"什么都不画"是设计,但对使用者不友好**:轴线的自动值域来自该维的聚合 min/max,
图里没写数据时聚合是空的 ⇒ `TryResolve` 两条来源都给不出 ⇒ 轴线整条不出现。
**P4 已修**:数据板块每个维度一行,行内第一句就是当前生效范围——
"自动值域 = 该维聚合 a..b"/"覆盖 a..b(自动值域被忽略)"/
"这一维还没有任何数据 ⇒ 画它的轴这一帧不会出现;勾上覆盖范围并填两个不同的值就能先摆出来"。
范围本身也搬到这一行(`OverrideRange` + `ManualRange`),工具不再各存一份。
**(2026-10-25 更新,§21)**:一个总开关表达不出"只钉最小、最大跟着数据跑",这一行改成
`OverrideMin` / `OverrideMax` 两端各自可钉;而**行本身**从面板搬进了数据窗口的「维度范围」页
——面板的「数据」框整块删除(他:"我们将所有的信息都整合到这个窗口里面去")。
**这一句写错过一次**(P4 验收现场它印的是"自动值域 = 该维聚合 NaN..NaN"):面板自己写了一遍
"聚合存在就算有数据"的判定,而空模型下 `Has(Minimum)` 是**真**、值是 NaN。同一条规则不能有两个实现——
现在"能不能用"一律问 `XChartDomainMath.TryResolve`,面板只负责把结果说成人话;
报表那份 `rangeSource` 同理,改成取本帧的结果(`m_HasRange`)而不是再问一遍聚合。
2. **轴刻度与立方体网格的分格没对齐**:刻度由 nice-step 在数据域里铺,网格分格由 `GridDivisions`
在几何域里铺,两套口径。
3. **立方体网格自身的值域不可调**:背景网格只有分格数,没有"它在数据域里覆盖到哪"的入口。
**第 2、3 条在 P4 的处理(二选一已定)**:**不派生,改成"可见化 + 手动对齐"**。理由:
立方体的网格线画在**几何面**上,它跟数据维度没有天然的一一对应——要让分格从刻度派生,
背景元素就得知道"这个面的 s/t 各对应哪一维",那是把数据绑定塞进背景元素,
与 §1 的归属划分正相反(背景只该知道几何)。
所以:范围一侧已经归到维度行(第 3 条的"值域可调"由此满足——立方体覆盖的就是各维范围,
散点按同一份范围归一化,所以网格与点天然同一尺度);分格那一侧只做"算式可见":
轴元素行下印一句"主刻度 K 条 = K−1 段 ⇒ 把立方体网格的分格数设成 K−1 就逐线对上",
两个旋钮还是各自的旋钮,但对得对不对一眼能算。
**他随后指出"刻度并没有和网格线对齐,两头都没对齐"——查下去是这个原因**:
轴的默认跨度是 `0.08 .. 0.95`(内缩的装饰值),而网格线铺的是整面 `0 .. 1`,
于是两头的刻度必然差着 8% / 5% 的面宽,**改分格数也补不回来**。
P4 已做三件事:① 默认跨度改成 `0 .. 1`(铺满整面);② 已存在的元素仍带着旧序列化值,
所以轴元素行会印"这条轴只铺了 8% .. 95% 的面宽,两头都对不上格线"并给一个**铺满整面**按钮
(一次点击写 0/1,不静默改数据);③ 把前提写在提示句里:对齐要求"铺满整面 **且** 范围能被步长整除"。
**诚实的边界**:聚合出来的范围常常不是"好看"的数(现场就是 `-49.936..49.936`),
这种范围按 nice-step 铺出来的刻度**落不到格线上**——探针把这条也正面钉住了
(`grid alignment: a ragged range … cannot land on grid lines`),
要那种情况也逐线对齐,就得走另一支(网格分格从刻度派生),也就是上面说的"往背景里塞数据绑定"。
**分格数按方向分(P4 尾巴,他选的"现在就把这条做完")**:立方体背景的 `GridDivisions`
变成"统一值 + S/T 各一份"(0=跟随统一值),算式抽成 `XChartGridDivisions`(纯托管,探针钉住
"沿 S 的格线由 T 的分格数决定"这一句最容易写反的话)。轴元素行按它自己的走向给出"把哪个方向设成 K−1",
并把当前值印出来(`现在 S=0 T=0`)——不然让人满面板找旋钮。**同族里还有一处没跟上**:
`ChartToolMeshBg`(网格预览产品那份背景)仍是一份分格数,而且它连边线的画法都不一样,
等它那期一起改;这里如实点名,不假装扫干净了。
**"轴末端差一点点"这条的判定过程(留着给下次省事)**:先给出可分辨的读数——轴工具自己持有的
`span=start..end` 印进报表。现场读数:改起点比例时 `span` 从 `0..1` 走到 `0.5..1` 并稳定
⇒ **值确实到了工具身上**,"值没传下来"这一支被排除。
**映射这一支也被排除**(这是可离线证的,不是猜):线框棱、格线、轴三者共用同一份投影
(线框走 `Space.Project(Vertices[..])`、格线与轴走面帧 `Map`),而"每个面的四角恰落在立方体顶点上"
**早就是探针里的一条断言**(见 `XChartCubeGeometry` 面顶点索引表的注释)——
面帧的 s=0/1 就是该面的两条棱,轴铺满整面时两端必然落在棱上。
换面后仍然"两端都差"这一现象与之一致:他比的是**立方体轮廓**,而轴画在某个面的**对角线**上,
那条对角线的两个端点本来就在轮廓内部(CrossRatio=0 时轴还正好压在面的棱上,容易被相邻面的填充盖住)。
⇒ 归为**观感层待重构项**(他 2026-10-23 的话:"你现在做的框架其实和我想的也有点出入,
如果这个问题的原因主要出在映射上的话,我们后面再重构吧,你先做完这几个目标")。
下次要真判它,得拿像素级证人(把轴的两端、该面四角、以及轮廓六角的像素坐标一起印出来比),
现在是"他说看着短、机器证明两端正好在棱上",**两半并存,不合并结论**。
4. **面板:增删元素之后,Inspector 里的元素行会整批消失**(验收时确认的现象,与渲染无关)。
**数据侧已排除**:684 次采样里 `elements: count` 从没读过 0(最小 2,常见 3),
而且工具清单与元素表逐项对得上("表里有但工具没建"的采样数 = 0)——
所以"行没了"是**面板读数**的问题,不是序列化丢了。
**P3 已按这一条修**:`m_ElementsProp` 字段删掉,改成 `ElementsProp()` 每次现取
(`serializedObject.Update()` 之后旧句柄会作废,而作废的 `SerializedProperty` 不报错,
只安静地报 `arraySize == 0`)。同时面板把自己的读数印进同一份报表:
`panel: rows=N table=M`,两边不等就打 `ROWS-DISAGREE`。
**未证的一半**:这条证人的"能红"要在真编辑器里演一次(把 `ElementsProp()` 临时改成返回 null,
应当看到 `rows=0 table=3 ROWS-DISAGREE`);离线演不了,所以这里记作**待现场取证**,不算已证。
5. **元素重名会串台**(同一批采样拍到 8 次 `Axis,Axis`):默认名按类型给,同类加第二个就撞,
而 `ReapplyElements` 按 `ElementName` 配对 ⇒ 改第二条轴的字段会灌进第一条。
**P3 已修**:登记名由 `chart.ElementNameFor(index)` 给——同名按表内出现次序补序号("Axis"、"Axis 2"),
只由位置决定、不入库,所以重建后还是同一个名字;面板行标题与配对都走这一份。
6. **点"重新生成全部节点"会抛 `MissingReferenceException: m_AtlasTextures of FontAsset`**
(P3 验收第二轮的现场)。栈是 UI Toolkit 的按钮文本测量 → `TextCore.Text.FontAsset.TryAddCharacterInternal`。
**盘上证据**:默认字体资产是 `Assets/Font/OPPO Sans 4.0 SDF.asset`(`TMP Settings.m_defaultFontAsset` 指向它),
它的 `m_AtlasTextures` 列了 8 项、第 8 项是 `{fileID: 0}`,而 `m_AtlasTextureIndex: 6`:
盘上那 7 张都在,**第 8 槽是运行时补进去的动态图集**,域重载之后就是一个失效引用。
所以这不是"重建把资产拆了",而是**任何一次需要新增字形的文本测量**都会撞上它
(面板里的中文标签正好在做这件事,点重建只是让文本重新量一遍)。
**一次一变量的判法**:不动图表,只把 Inspector 关掉再打开(或改一个普通字段触发重建面板)——
若同样报,就与"重建"无关。资产侧处置:把那个字体资产重新 Import 一次(或让它重建动态图集)即可清掉空槽。
这一条**不改我的代码**(我的两条:`SetGeneratedVisible` 只走两层、面板同名分组重复,P3 已修),
只把它记成"资产侧状态",免得下次又绕回"是不是重建的锅"。
**2026-10-23/24 的补充观测(有用的一条)**:它后来又连着报了两轮,栈分别是
`UITKTextHandle.ComputeTextWidth`(P7 期间)与 `InspectorWindow.RedrawFromNative → ComputeTextHeight`,
内层落在 `FontAsset.SetupNewAtlasTexture`/`GetFallbackMaterial`。规律是:
**只要文本测量需要"一个新字形",就会走到那个坏掉的动态图集槽** ⇒ 所以它出现的频率与
**我新加的中文标签**正相关(P3–P7 加了不少新字),而不是与"重建/域重载"正相关。
判据上的意义:**这条会挡住一切"看一眼面板/图"的验收**(Inspector 每次重绘都可能抛),
所以它一旦出现就要优先在资产侧清掉,别把它当成"我的改动没生效"——**它不是渲染、不是数据、也不是插槽的事**。
**2026-10-24 定量补记(他问"面板不是 uGUI 吗,为什么会撞 TMP",并把资产盘开数了一遍)**:
- **面板确实不是 uGUI**:Inspector 走 `CreateInspectorGUI`(VisualElement 树),数据窗口是
`EditorWindow + rootVisualElement`,两处都是 **UI Toolkit**;uGUI+TMP 只有画布上那张图(刻度标签)。
但**编辑器里的 UI Toolkit 文本仍然由 TextCore 排版/光栅化**——引擎为编辑器另带一份同名文本引擎
(`UnityEditor.TextCoreTextEngineModule.dll`,成员与运行时那份一致:`TryAddCharacterInternal` /
`SetupNewAtlasTexture` / `m_AtlasTextures` / `FallbackFontAsset`),栈里的 `UITKTextHandle.ComputeTextWidth`
就是 UIE 到 TextCore 的桥。⇒ **面板中文和图上 TMP 中文共用同一条字形供给链**,所以"上面(ASCII 按钮)
好了、下面(中文按钮)坏了"是同一条路上的两种结果,不是两处不同的 bug。
- **盘上的数字把根因钉住了**(`Assets/Font/OPPO Sans 4.0 SDF.asset`,`TMP Settings.m_defaultFontAsset` 指它):
`m_AtlasWidth/Height = 1024`、`m_PointSize = 90`、`m_AtlasPadding = 9`、`m_AtlasPopulationMode = 1`(Dynamic)、
`m_IsMultiAtlasTexturesEnabled = 1`、`m_ClearDynamicDataOnBuild = 0`,**已烘 742 个字形、图集正好 8 页**。
算术自洽:90pt 的汉字约 `1024/(90+18) ≈ 10` 见方 ⇒ **一页只装得下约 100 个汉字**,742/100 ≈ 8 页。
⇒ 面板每多一句新中文,就要**现场新建一页**,而"新建页"(`TryAddGlyphsToNewAtlasTexture → SetupNewAtlasTexture`)
正是域重载后旧页 `Texture2D` 引用失效的那一步。**所以"重载 TMP 文本"不会有任何效果**——
要动的是这份字体资产的**供给方式**,不是文本资产。
- **另一条同源的放大器**:`TMP Settings.m_fallbackFontAssets` 是**空的** ⇒ 所有中文都往这一份 90pt 的资产里现烤,
没有任何回退字体分担。
- **两条能断掉它的修法(资产侧,归他定)**:① 用 Font Asset Creator 按 `Assets/Font/3500字完整版.txt`
**一次烘全**,并把 **Sampling Point Size 降到 32–40**(90pt 时 3500 字要 30+ 页;40pt 约 6–7 页),
之后运行时不再需要新页;② 或给 TMP/TextCore 配一份**含汉字的 fallback**,让默认资产只负责拉丁字形。
- **离线证不了的一半(如实点名)**:编辑器 UIE 文本**具体取哪一份字体资产**(`TMP Settings` 的默认资产?
TextCore 自己的 settings?还是 `EditorTextElement` 的内建默认?)我没能在离线射程内定死——
`EditorTextElement` 这个类型在 `UnityEditor.dll` 与 `UnityEditor.UIElementsModule.dll` 里都**没反射到**,
`StyleProperties` 也没取到(探针:`.ximage-gate/font_path_probe.cs` / `font_path_probe2.cs`)。
⇒ 因此"我代码侧显式给面板指定字体"这条**尚未证成**,不能当成现成的解法承诺。
**2026-10-24 第二次更正(把上面那条"证不了"收掉一半)**:按名字在**全部**编辑器程序集里扫类型之后:
- **2022.1 里没有 `EditorTextElement` 这个类型**(上面那句"没反射到"的原因不是路径猜错,是它不存在)。
编辑器 UIE 用的就是普通 `UnityEngine.UIElements.TextElement`(成员里带 `uitkTextHandle`),
经 `UITKTextHandle` 桥到 TextCore。
- **TextCore 的默认字体权威是 `UnityEngine.TextCore.Text.TextSettings`**
(`defaultFontAsset` / `defaultFontAssetPath` / `fallbackFontAssets` / `GetCachedFontAssetInternal` /
`m_FontLookup` / `m_FontReferences`),**不是 `TMP Settings`**——TMP 3.0.9 的脚本里一次都没提 TextSettings,
两套默认各管一条路(`TMP_Text` 走 TMP Settings,UIE 走 TextSettings)。
但**项目里没有 TextCore 的 TextSettings 资产**(全项目扫 `m_DefaultFontAsset` = 0 处,编辑器安装目录里
也没有散落的那种 .asset)⇒ "面板取哪一份"这一跳仍未定,留作下面的分岔。
- **代码侧的出口现在确认存在**:既然是 `TextElement`,`style.unityFontDefinition`(`FontReference`,
可指一份 SDF 资产或旧式 `Font`)就是可设的入口 ⇒ 面板可以脱离"默认资产"这条路。
API 存在性能在编译门上自证;**"设了之后出不出字"仍只能他那边看一眼**。
- **字体资产普查(他项目 `Assets/` 下 4 份 SDF)**:
| 资产 | 字形 | 汉字 | 图集 | pointSize | 供给模式 |
|---|---|---|---|---|---|
| `Font/OPPO Sans 4.0 SDF`(= TMP 默认) | 742 | 632 | **8 页** 1024² | **90** | **Dynamic + 多页** |
| `Font/PMZD3` | 3579 | **3489** | **1 页** 2048² | 27 | **Static** |
| `TextMesh Pro/Resources/…/LiberationSans SDF` | 250 | **0** | 1 页 | 86 | Dynamic |
| 同上 `- Fallback` | 22 | **0** | 1 页 | 86 | Dynamic |
⇒ **"换成 Unity 自带的多国通用字体"这条不成立**:TMP 自带那份**一个汉字都没有**(fallback 那份也没有),
换过去中文一律缺字形。**差别不在"哪家的字体",在"要不要现场补页"**——90pt 的汉字一页只装约 100 个,
面板每多一句中文就新建一页,而"新建页"正是坏掉那步;Reimport 把页清回去 ⇒ 当前开着的面板重量一遍就好,
再开新界面又逐字补页 ⇒ 又坏(与他"只救当前面板"的观察对上)。
他项目里**已经有正确形状的样本**:`PMZD3`(静态、单页、3489 汉字)。
7. **P3 之后的显隐判据**:`SetGeneratedVisible` 改成按名字认根(`[XChartTools]` + `GeneratedTextPool`)+ 递归到底,
与 `m_ShowDebug`/`m_HideAllTools` 两个开关接通(这两个字段原先**没有任何读者**——"勾了没反应"就是这么来的)。
现场判据:报表新增 `hideFlags: hidden=N shown=M missing-DontSave=K` 一行——
来回切两次后 `hidden/shown` 互换、而 `missing-DontSave` 必须恒为 0(那才是"没被写进资产")。
8. **UGUI 单个 Graphic 的 65535 顶点上限会让"按记录数长出网格"的元素整块炸掉**(2026-10-23 P6 验收现场):
他那边抛 `ArgumentException: Mesh can not have more than 65000 vertices`(栈:`VertexHelper.FillMesh` ←
`Graphic.OnPopulateMesh` ← … ← `CanvasUpdateRegistry.PerformUpdate`)。这是**每个 Graphic 各自**的上限
(≈16250 个四边形),而我的元素里有几个是**按记录数**长网格的:箭头=一条记录 2 个四边形(杆 + 头),
散点=一个点 1 个四边形 ⇒ 几千条记录就开始逼近,他现场灌过 10000 条 ⇒ 80000 顶点,必然撞上。
**它不是圆柱那一轮引入的**:圆柱的输出是有界的——`SegmentCount ≤ 256` ⇒ 轮廓 ≤ 2×512 点
⇒ 填充 ≤ 1024 个面(4096 顶点)、包边 ≤ 1024 条线,离上限差一个数量级;这一条属于**数据量**这条路。
**本轮不修**(如实点名):正解是按顶点预算把网格**分块**成多个 Graphic(或给每个元素一个显式的"最多画多少"),
那是渲染器层的改动,不是圆柱这一期的事。**先记下来,别让"圆柱验收失败"和"网格上限"混成一件事。**
**他 2026-10-23 批准后已做(本包范围内)**:`XChartMeshFillRenderer` 改成**提交即按预算分块**——
纯算法抽成 `XChartMeshBudget`(`ChunkVertexBudget = 16000`;`Split` 切块、`MaxChunkVertices` 报最大值),
渲染器本体不画、每块一个子 Graphic(`FaceChunk`,只画 `[start,end)` 那么些面,顺序 = 提交顺序,
所以画家序不变)。**判据**:探针 5 条(每块不超预算、覆盖不重不漏且保序、最大值真是最大、单面超预算也自成一块不丢面、
零面零块),对照臂 R「把切块关掉(永远一块)」⇒ 第一条红;**现场读数**:圆柱与箭头两个按记录数长网格的工具
各自在报表里印 `fillChunks=` 与 `fillMaxVerts=`("最大的那个 Graphic 有多少顶点")。
**库侧分块已做一半(2026-10-23)**:`PrimitiveCacheRendererBase`(**散点走它**)与 `CurveCacheRendererBase`
都改成"本体不画、按 `ChunkVertexBudget = 16000` 把条目切块、每块一个子 Graphic",
块内索引按块内顶点起点**重基**(`PopulateSlice`);顺序不变(块按提交顺序、块内也按顺序)⇒ 画家序不动。
块边界用条目自带的 `vertexCount` 累计(和本包 `XChartMeshBudget.Split` 同一口径)。
**仍欠**:`CacheLineRendererBase`(`UILineRendererV2`)**没做分块**,原因是它的索引是"每子段 3 个三角、
且最后一段会引用**上一段**的顶点做转角连接"⇒ 切块要先记录"每个子段的索引起点"才能精确切片,
不是 12 行能改完的;同时它的**当下**提交量本来就小(轴线刻度、圆柱包边),而真正咬人的
**水位泄漏**已经修掉,所以这条按"更重要的事先做"排后。
**(当日已补做)**:线渲染器也切块了 —— 布局是均匀的(每段 `VerticesPerSegment` 个顶点),按段数切即可;
生成索引时顺手记下**每个子段的索引起点**(`m_SegmentIndexStart`,这是精确切片的前提);
**块首多带前一段的顶点**(同一根线里子段的转角连接三角会引用上一段的顶点,不带就在接缝缺角);
切开时丢掉落在窗口外的三角(那是上一段的连接三角)。两棵库树符号对齐:`ChunkCount` 各 9、`ChunkVertexBudget` 各 6。
**平台变体树(`com.lrss3.deconstruction-webGL release/`)的诚实说明**:它同 asmdef 名、本工程没有它的 rsp;
我把改动按**符号名**与 Release 树对齐着同步过去了(`LiveVertexCount` 各 6 处、`ChunkCount` 各 6 处、
`ChunkVertexBudget` 各 4 处),但**没有编译器为它作证**——试过把本工程的 rsp 重指向它,
结果是 5309 条"命名空间已包含定义"(rsp 里路径形式混用,只能重定向一部分 ⇒ 两棵树进了同一次编译)。
那种红的臂分不清"我改坏了"和"路径混用",所以没放进门里;这条改动属**按同形状同步、未经编译验证**,
重放脚本留在 `.ximage-gate/patch_lib_chunks.py`。
**真因找到了(2026-10-23 晚,他一句"是不是顶点推送没有回收"直接点中)**:不是"量太大",是**只增不减**。
库那三个基类(`CacheLineRendererBase` / `PrimitiveCacheRendererBase` / `CurveCacheRendererBase`)的顶点缓存都写成
`while (m_MeshVertexCache.Count < needed) m_MeshVertexCache.Add(new UIVertex());` —— **只 grow、从不收缩**;
而 `OnPopulateMesh` 又是 `vh.AddUIVertexStream(m_MeshVertexCache, m_MeshIndexCache)`,**把整个列表**交给 VertexHelper。
于是提交的顶点数 = **历史最高水位**:任何一次让某个组件画多过(灌大批数据、临时把元素调大)就把水位抬上去,
**之后数据降回来也不落**,一旦越过 65535 就永久报错 —— 这正是他看到的"一直提醒"、"也没看到脚本刷新"、
以及"我们的图例不该有 65000 个顶点"。**它和"按记录数长网格"是两条独立的路**(那条是当下量就超,
这条是历史最高水位),所以分块修不了它,必须让缓存跟着当前内容收缩。
**已修**(两棵库树按符号名对齐:`LiveVertexCount` 各 6 处、`RemoveRange` 各 5 处):重建时把缓存 shrink 到
当前真正需要的顶点/索引数,并暴露 `LiveVertexCount`(**当帧真提交量**,不是水位)。
**报告口径**:每个按数据量长网格的元素都印自己组件的提交量 —— 散点 `points= / pointVerts=`、
箭头 `arrowFaces= / fillChunks= / fillMaxVerts=`、圆柱再加 `curveVerts= / wireVerts=`、轴线 `wireVerts=`。
**跨包编译顺序也补上了**(否则一改库就满屏 `CS1061` 假红):`run_gate_lib.py` 先把库编出来,
`run_gate.py` 再把渲染里指向 dag 旧 `Lrss3.Deconstruction.ref.dll` 的引用重定向到本次产出
(打印 `lib_ref=N`,N 必须 ≥ 1 ——"重定向真的发生了"本身是判据)。
---
## 10. 圆柱:视角下的外轮廓包边(P6,2026-10-23 按他口述重做)
**他指出的错**(原话):"几何扫描图形的含义是在我们视角下这个图形会呈现出一种外轮廓包边的效果。
所以现在你现在的做法就是直接将圆柱端面的几个顶点都连起来的做法是不对的,应该只显示外边轮廓。
而轮廓的识别就是:将一个圆变形后投影到界面上实际上就相当于将圆压扁成椭圆了,所以椭圆就有长边和短边,
所以过圆心一点的长轴用来连接外边框。"
- **旧实现错在哪**:把相邻端面点按角度连成一片片四边形(侧面)+ 盖面三角扇。那画出来的
是"**所有母线都可见**的透视线框",不是包边——它把背面的轮廓线也画了出来。
- **新实现**:外轮廓 = 两片端面椭圆**采样点集的凸包**(`ConvexHull`,Andrew monotone chain,纯数学)。
对凸截面这是**精确解**,而且平行/斜置/两端不同法线/两端不同心**都是同一套代码**:
不必为"斜圆柱"另写切线公式,那两条"过圆心的长轴方向"的桥接线就是凸包自动给出的那两段。
轮廓只画包边;"把两端顶点全连起来"降级成可选元素(`GeneratrixCount`,**默认 0**)。
- **投影从 2D 算起**(他要求"从两个端面的投影换算开始就应该在 2D 上算,最大限度复用结果"):
每片端面只投 **3 次**——圆心 + 盘内两根基(`TryOrthogonalBasis` 取正交基,`TryProjectDisc` 把
基向量的像素像当半轴)。正交投影是**仿射**的 ⇒ `p(θ) = 中心 + U·cosθ + V·sinθ` 正好是椭圆,
此后所有采样(轮廓、十字、母线)都在 2D 上按参数式展开,不再对每个点做 3D 投影。
- **可选项各有开关**:`ShowOutline`(包边)、`ShowFill`(填充=**同一个**凸包多边形,
中心扇形提交给 `XChartMeshFillRenderer`)、`ShowCapCross`(端面十字)、`GeneratrixCount`(内部母线)。
十字用 `CrossPoints` 取的是 +U/+V/−U/−V 这四个**采样顶点**(`right − left = 2U`、`top − bottom = 2V`),
所以它**永远与实际端面对得上**、能看出滚转;若改用椭圆的长短轴,长短轴会随观察方向自己转、把滚转吃掉。
- **两端各自可设法线**(`StartNormal`/`EndNormal`,零向量=沿两端连线,与旧行为一致)。
**我第一版怎么把"矩形"这条判错的(值得留档,因为教训不是"期望写错了")**:
- 需求里写的是"两片同形同向、正面朝观察者 ⇒ 凸包为矩形(四点,两两平行)"。我照着这个**姿态**去写断言
——用两片"盘面平行于屏幕"的圆盘(`U=(10,0)、V=(0,10)`,圆心相距 40)——结果量出来是 **50 点**,不是 4 点。
我一度把它记成"我的期望写错了",并把它改成"真子集 + 四个极值角在包上"。
- 复盘才明白:**错的是我选的姿态,不是那句话**。盘面平行于屏幕时,圆盘投影成整圆,轮廓是**胶囊**:
两段半圆弧本身就在包上(弧上采样点都是凸点),所以点数 = 两段弧 + 两个接点。
而"4 点矩形"要的是**端面看到侧刃**——端面平面包含视线方向时椭圆压成一条线段,
两片平行线段的并集才是**正好 4 个角**的矩形(这才是圆柱从侧面看过去真正的样子)。
- 所以现在两种姿态**都留着**:正面(胶囊,判"真子集 + 四个极值角 + 面积 ≥ 两片之和")与
侧刃(**正好 4 点矩形**,判"count == 4 且对边两两平行等长")。前者还顺手把"点数不是 4"这件事钉住了,
免得下一个人又把"矩形"当普遍规律。
- 顺手的收获:**侧刃这条是"单调链必须剔掉共线点"唯一的可判定形式**。侧刃姿态下所有采样点**精确共线**
(`V` 恰为零 ⇒ 每点 y 精确等于圆心 y),把 pop 条件从 `<= 0` 放松成 `< 0` 就会把它们全留下——臂 M 因此有靶子。
- "**面积 ≥ 单片端面**"这条断言**不可能有能红的对照**:凸包含住某一组点 ⇒ 面积不小于那组点,
于是只要"包住两片"为真,它就永远不能红。**没有能红对照的断言不算门** ⇒ 挪到"两片相距 40"那一对上
判"面积 ≥ 两片之和"(那里才是独立信息),并配一支"只保留下凸链"的变异臂证明它会红。
同一条也删掉了一句只判上界的"仍是多边形"——它的内容已被 `count < 2×采样数` 严格覆盖。
**臂 M 顺手抓出一个真实的容量越界(已修)**:`ConvexHull` 的两条链各自最多 push 一次每个输入点,
写入下标最大到 `2×count−3` ⇒ 包点缓冲要能装下 **2×count**;而原来的契约只要求"装下 count"
(`BuildOutline` 里写的是 `segmentCount * 2`,那正好是**采样数**,不是采样数的两倍)。
平时的输入(胶囊 50 点)离边界很远,所以一直没炸;臂 M 把全部 96 个采样点都留在链里,
当场以 `IndexOutOfRange` 打穿了那道门。现在:`ConvexHull` 自己带容量断言、契约改成"output ≥ 2×count",
工具与探针的缓冲都按这个口径给。**这一条是变异臂第二次抓到"我自己的判据/契约有洞"**。
**判据(离线,全绿)**:门三臂(runtime / player / editor,player 臂剥掉 `-define:UNITY_EDITOR`)
+ 探针 **268** 项 + `pool_family` + `p2_control` 四臂 + `p4_control` **14 支臂**。
圆柱这 7 条断言各有对照:真子集/侧刃矩形/四点/桥接极值/包住两片/两片面积 ← 臂 I(只保留下凸链)、
J(只采一片端面)、L(**不取凸包、把采样点全交回去 = 他否掉的那种画法**)、M(保留共线点);
十字 ← 臂 K(改成按屏幕轴对齐)。
**现场读数**:每帧报表里该工具一行带 `outlinePoints= / fill= / cross= / generatrices= / normals=`,
0 也要能分清"没算"(`built=false`,法线退化)还是"算出来是空"——按 §8 的老规矩,零必须说出它零在哪一层。
**本轮明确不做(别当成已覆盖)**:**端面平面去切立方体网格**。他提到两个端面法线"用于在立方体网格中
设定他们的切面",但本轮他选的是"先只要法线定朝向",所以**只做了朝向,没做切面交线**。
要让端面真在立方体网格里切出交线,是另一件:需要"平面 × 立方体面"的求交与多边形裁剪,
而且它属于**几何**不属于数据(§1 的归属划分),落点应在空间/背景那一侧,不要塞进数据模型。
### 10.1 第二轮验收(2026-10-23 现场):默认法线让两端互为镜像 + 端面圆要能闭合
他现场看出两件事,都对着这一期的实现:
- **"两个端面是旋转了吗,它的连接顺序错了"** —— 这是**真的**,根因在默认法线的取法。原来我让两端各自
"朝另一端"取法线,于是第二片拿到的是**反号**的法线;而 `TryOrthogonalBasis(-n)` 会给出 `u' = -u`
(叉积对第一个参数反号)⇒ 两片的采样角是**镜像**的:同一个采样下标 i 在两片上指向不同方向,
可选元素里"两端对应点相连"的母线就拧成 X 形,端面十字两端也互为镜像。
现在把这条规则抽成纯函数 `XChartCylinderGeometry.ResolveNormals`:**显式法线优先;默认两端都用同一条轴、同向**
⇒ 两片参数化完全一致,下标 i 就是同一个 3D 方向。配了一支把 end 翻成 `-axis` 的对照臂,
它量出的正是 `u (0,-0.24,-0.97)` vs `(0,0.24,0.97)`(`v` 不变)——这条修复的直接证据。
- **"端面圆没有闭合,我想选择闭合"** —— 端面自己的那一圈椭圆**不是**外轮廓的一部分(轮廓只走可见的那一段,
正面看就是胶囊的那两段弧),所以我原先根本没画它。现在按端面各自给了开关
(`ShowStartRing` / `ShowEndRing`,**默认关**,保持包边那套观感):打开就是**首尾相接的整圈**闭合环,
用的是同一套 `PointAtStep` 采样角(所以环、十字、母线三者永远共顶点)。
- 现场读数行相应补上 `ringStart= / ringEnd=` 与两端法线来源(`normals=alongAxis/explicit`),
以后"环没画"和"环画了但看不清"能分开说。
### 10.2 "拉近了有断口"=我一段一段画线(2026-10-23 同一轮)
他放大看图时看到**线条在每个转角处有断口**。根因在我的调用方式,不在渲染器选型:库里
`CacheLineRendererBase` 的网格生成器会给**同一根线内的相邻子段**补"转角连接三角形"
(`LineMeshGenerator` 里的 `hasPrevInLine` 就是这个开关),而我原来对轮廓的每一段各调一次
`DrawLine` ⇒ 每一段都是"一根新线的第一段" ⇒ **每个转角都没有连接三角形** ⇒ N 段就有 N 个断口。
(端面圆环更明显:48 段 = 48 个断口,放大看就是"虚线环"。)
修法就是换调用形式:轮廓、两个端面圆环、十字都改成**一次 `DrawPolyline`**
(闭合的多边形/圆环靠"把首点补到末尾"实现闭合;十字改成"过圆心的三段折线",
这样圆心处也有接缝连接)。母线本来就是各自独立的一段,仍然用 `DrawLine`。
**通用句:折线要用"一次提交整条线"的 API,别用"逐段提交"——接缝三角形是按"同一根线"补的,
逐段调用会把每一段都当成新的一根。**(这一层之后又被 §10.4 推进:**弧**不再用折线,改用曲线渲染器;
这里的"一次提交"继续适用于**直线**——十字与母线。)
### 10.3 单 Graphic 的 65535 顶点上限(下一轮修,他 2026-10-23 批准)
见 §8.8。他同意下一轮按顶点预算把网格**分块**成多个 Graphic。**同一个待定量的读数要一起做**:
他报"圆柱 `ShowFill` 打开即抛 65535",但按代码算填充只有 ~4k 顶点(轮廓 ≤ 1024 面),
两者对不上 ⇒ 要么读数(`outlinePoints=` 与各 Graphic 顶点数)证明我算错,要么溢出的是别的元素
(开关只是触发了整块 canvas 重建)。**没有这个读数就不要下结论**(§8 的老规矩:零要说清零在哪一层)。
### 10.4 弧段改用曲线渲染器(他点名的 `Generation/Curve`,2026-10-23)
先给结论:**"拉近有断口"有两层,第一层是我的调用方式,第二层才是渲染器选型。**
- **第一层(已修)**:库里 `LineMeshGenerator` 的转角连接三角形只给**同一根线内**的相邻子段补
(判据是 `hasPrevInLine`),而我原来对轮廓/端面环**每一段各调一次 `DrawLine`** ⇒ 每段都成了"新线的第一段"
⇒ 每个转角都没连接三角形。端面环 48 段 = 48 个断口,放大就是虚线环。
- **第二层(他指出的正解)**:折线渲染器**本质上**是分段直线,适合直线;**弧要用曲线渲染器**——
`Packages/com.lrss3.deconstruction/Runtime/Generation/Curve`(`UICurveRenderer` / `CurveCacheRendererBase`
+ `CurveMeshGenerator`)内部就是**贝塞尔细分**,我只需要给控制点。他原话:
"你现在用的折线渲染器就是分段的,适合用来显示直线……它的结构中就是使用的贝塞尔细分,完全不需要你自己实现。"
现在的分工:
| 画什么 | 用什么 | 为什么 |
|---|---|---|
| 轮廓的**弧段**、两个端面**圆环** | `UICurveRenderer.AddCurve`(三次贝塞尔,每节 ≤90°) | 弧必须是真曲线;细分交给渲染器,我只算控制点 |
| 轮廓的**桥接段**(跨端面那两条) | 同上,控制点取 1/3、2/3(直线贝塞尔) | 直线用贝塞尔表示就是直线,走同一条提交路径 |
| 端面**十字**、内部**母线** | `UILineRendererV2`(整条 `DrawPolyline`,不是逐段 `DrawLine`) | 他说的"折线渲染器适合显示直线" |
控制点全部由纯几何算,**每条都有能红的对照臂**:
- `TryParameterOf(disc, point) → θ`:解 2×2 反解椭圆参数并验 `cos²+sin²≈1`。**凸包分组**(哪几个点是弧、
哪一段是桥)全靠它。臂 O 让它永远返回 false ⇒ 分组与"每点都有归属"两条断言同时红。
- `BuildArcPiece(disc, a, sweep, pieces, index)`:系数 <c>k = 4/3·tan(Δ/4)</c>(圆弧→贝塞尔的经典值)。
**椭圆是圆的仿射像**,控制点随仿射变换同样变换 ⇒ 同一个 k 对椭圆弧一样成立。臂 P 把 `k` 置 0
⇒ 弧退化成弦,"中点鼓到弧上"那条断言红(这条正是"折线冒充曲线"的失败形状)。
- `ClassifyOutline` + 运行段合并:胶囊应当切成**恰好 2 段弧 + 2 条桥接**(探针钉住 `runs == 2`)。
- `SweepToDirection`:从"段内第二个点"定转向,凸包是逆时针,弧必须顺着走(否则会绕远路画一整圈)。
现场读数行再加一个 `curveEntries=`(这一帧往曲线渲染器提交了几节),
这样"曲线一条都没提交"和"提交了但看不见"能分开说。
### 10.5 端面环=包边的**补弧**(他 2026-10-23 第二轮反馈)
他打开线框检查,报两条:
1. "关闭 `ShowStartRing/EndRing` 之后,消失的是**外侧**的圆环,但实际上我们应该控制的是**内部**的圆环闭合部分";
2. "我们绘制的圆环好像是**重复**的……`showring` 的时候,原本的边框上会出现两次不同的线框"。
两条是同一件事:我把环画成了**整圈椭圆**,而包边已经画了那片端面的**外侧弧** ⇒ 外侧重了(同一位置两条线),
而"内部那半圈"才是这个开关该负责的东西。正解:**环=包边那段弧的补弧**——起点接在可见弧的终点、
方向相反、扫过 `2π − |可见|`。于是外侧由包边画、内侧由环画,合成一整圈端面圆,两边都不重复。
包边整个关掉时,环自己补整圈(不然只剩半圈悬空,那才是"看不见的环")。
**这里我连错两次(都留档,教训比结论值钱)**:
- 第一版把补弧写成"**把两个端点对调、再要求反方向**"。`SweepToDirection` 只会挑"同号里较短的那一条",
所以对调端点后它给出的是**原路返回** ⇒ 环又画回包边那一段,**和 bug 一模一样**。
- 第二版改成"起点接在可见弧终点、方向相反、扫过 2π−|可见|"。这仍然是错的:
**反向走会把同一段弧原路覆盖一遍**(半圆时最直观:反着走一遍正好还是那半个圆),
于是他看到的现象变成了"环补成了**外**半环"。
**正解是同方向**:补弧=从可见弧的终点**接着同方向**走完剩下的那一圈(`2π − |可见|`),
于是可见弧 ∪ 补弧 = 整圈,两者**同号**、绝对值和 = 2π。
**为什么公式断言两次都放过了它**:我写的判据是 `|可见| + |补| = 2π`——**和实现用的是同一个(错误的)信念**
("补弧 = 反向"),所以它两次都绿。真正抓住错误的是那条**几何**判据:
> `cylinder ring: the ring complement lies INSIDE the outline (inner half, not the outer)`
> ——补弧的中点用**点在轮廓内部**来判(可见弧的中点则必须落在边界上)。
> 实测把补弧写错时它报 `inside=True distance=7.9e-08 at (0,-10)`:
> 中点就贴在边界上(那是可见弧自己在的位置)。
**通用句:公式型判据和实现出自同一个念头时,两者会一起错;凡"某段几何属于哪一侧"这种性质,
要用一个**独立的几何量**去判(中点在哪、离边界多远、面积正负),别只比角度和。
** 对照臂 S「让环取可见弧的扫角」⇒ 这条几何判据红;臂 Q「`ComplementSweep` 改成 `return -sweep`」⇒ 公式那两条红。
---
## 11. 网格插槽、值模式、注册分组与绘制顺序(P7-P9,2026-10-23 他口述)
### 11.1 要解决的问题(都对着现行代码)
1. **面是靠枚举钉死的**:轴线存 `CubeFace`(0..5) + `Direction` + 三个比例,用 `m_FaceFrames[(int)Face]`
取面帧(`ChartToolAxis.cs:46-51,191-194`),而面帧由 `XChartCubeGeometry.BuildFaceFrames`
**硬编码六面**产出(`XChartCubeGeometry.cs:238-253`)。`XChartFaceFrame` 自己是通用的
(四边形补丁 → 像素,不认识立方体),**被钉死的是生产者** ⇒ 换成异形网格(非六面、非四边形)就失效。
2. **网格分格与数据范围是两套口径**:分格数是手填 int(`XChartMeshBgConfig.cs:49`),
没有任何东西从维度范围/刻度推出来(`XChartGridDivisions.cs:25-33`)——§8.2 那条"刻度与网格线对不齐"
的根子就在这里。他要的是:**网格线由 chart 的数据范围统一控制**,工具只管自己的风格与细节。
3. **注册顺序与绘制顺序被一个数绑死**:工具平铺在 `[XChartTools]` 下,**sibling 索引就是绘制顺序**,
而 `OrderIndex` 同时决定插入位置(`XChartToolsManager.cs:124-136`)⇒ "轴线要在点的上层"与
"背景要先初始化"共用一个旋钮,互相打架。分组(背景/前景)在代码里不存在。
### 11.2 网格插槽(provider → consumer)
定义网格的**背景工具**在注册时把自己的一组组**标定顶点**开放出来(=插槽);要用这些几何的前景工具
(轴线、标尺、tooltip、可互动元素)按 **id** 取用,不再认"第几个面"。
- **板子**:`IXChartSlotBoard`(由 chart 建立、随 `IXChartRenderContext` 一起交给工具):
`Publish(id, mode, access, values)` / `TryRead(id, out SlotView)` / `Version`(值变了版本号前进,
消费者据此重建)。板子是**几何**的通路,不碰数据(数据仍走 `IXChartDataSource`)。
- **一个 chart 只有一份"定义网格"**:网格工具是**定义工具**(`Definition` 分类,见 11.4),
**在任何统一生命周期里它都第一个跑**——它先算好各维范围、格线与面片,其余工具(轴线、标尺、
tooltip、可互动件)**通过 chart 找网格组件**(唯一网格时也可按 <b>0 号</b>登记,省一次查找)再取插槽。
这不是"背景先画",是**数据先算**:别人要用的东西在它们开跑之前就已就位。
- **一组顶点=一个插槽**;消费者拿到的是只读视图(`ReadOnly`)或可写(`ReadWrite`:例如可拖动手柄
写回去让网格跟随)。
- **异形网格**照样能用:它只要按同一套模式发布插槽;消费者读的是点,不是"面号"。
- **读的时机不绑初始化**:背景先初始化、前景后初始化,但插槽**每帧可读**(`Version` 变了才重建),
所以"前景依赖背景"与"背景依赖前景发布的参数"(见 11.5)都不冲突。
### 11.3 值列表的"模式"声明(他给的四种起步)
模式决定"怎么切值 + 每个参数怎么解释",**并声明读写权限**:
| 模式 | 值布局 | 一组代表 |
|---|---|---|
| `Line2D` | 2 值/点,2 点为一组 | 起点 → 终点(面内) |
| `Line3D` | 3 值/点,2 点为一组 | 起点 → 终点(立方体单位) |
| `Circle2D` | 2 值=圆心,1 值=半径 | 面内圆 |
| `Circle3D` | 3 值=圆心,3 值=法向,1 值=半径 | 空间圆(斜切面) |
| `Quad3D` | 3 值/点,4 点为一组(ST00→ST01→ST11→ST10) | 空间四边形面片(**新增**:轴线要的是"面内 (s,t)→像素"的补丁,用两个 `Line3D` 组表达会依赖组序约定,不如单列一种模式) |
后续要曲线就再加模式(`Arc2D`:圆心 + 半径 + 起止角;`Bezier3D`:4 个控制点…)。
**模式是纯数据描述**:切值与解释都能在没有 Unity 的情况下断言。
每种模式都要能回答三件事(也各是一条判据):**一组几个值**、**写进越界/个数不对时拒收**、**只读槽被写要拒**。
### 11.4 注册分组:初始化顺序 ≠ 绘制顺序
- **分类**:`XChartToolCategory { Background, Foreground }`(空间工具另算,它最先)。
- **初始化**:`Space → Background(按 RegistrationOrder)→ Foreground(按 RegistrationOrder)`;
`RegistrationOrder` **默认=注册先后**(没写也不会出现"顺序不确定"),显式值只用于同组插队。
- **绘制**:单独的 `DrawOrder`(默认=注册先后),只决定 `[XChartTools]` 下的 sibling 顺序。
"轴线的线画在点上面"=调 axis 的 `DrawOrder`;而轴线**依然依赖网格发布的插槽**——两件事不再互相牵连。
- **统一调度**:管理器持有"按组 + 按 RegistrationOrder"的列表与"按 DrawOrder"的总表;
`UpdateAll / RenderAll / Teardown / 报表` 一律**遍历列表**,不再逐个手调;新增工具=进列表。
### 11.5 网格线由数据范围控制(11.1 第 2 条的落法,2026-10-23 他定的方向)
**定义权在网格,不在轴线**:网格是定义工具、最先跑,它
1. 从 chart 的数据板块**读各维范围**(`IXChartRenderContext.TryResolveDomain`;范围本身仍归维度行,§1 不动),
2. 由范围推**格线**(nice-step;`XChartGridDivisions` 那套按方向分格的算式保留),
3. 把**格线与面片**发布成插槽(`Quad3D` 面片 + `Line3D` 格线),
轴线**跟随**:读同一条格的插槽来定自己的刻度位置 ⇒ **"网格线与刻度逐条对齐"由构造成立**,
不再是"看着齐 + 手填分格数"(§8.2)。轴线原有的 `MajorCount` 变成"跟随网格"的默认 + 显式覆盖
(覆盖即放弃对齐,这是明说的取舍,不是静默)。读不到插槽时回落自己的分格数——
**并把这个回落印进报表**(零要说清零在哪一层)。
### 11.6 分期与完成判据
| 期 | 内容 | 完成判据 |
|---|---|---|
| P7 | 插槽板:`IXChartSlotBoard` + 五种模式(含新增 `Quad3D`)+ 值视图;网格(定义工具)读各维范围 → 推格线 → 发布面片/格线插槽;轴线**只按插槽 id 定位**(**面枚举删掉**) | 纯数据断言:每种模式各配能红对照(错切值 ⇒ 红、越界/个数不对 ⇒ 拒收、只读槽被写 ⇒ 拒);轴线在无插槽时回落并发声 |
| P8 | 分组与顺序:`Category{Definition, Background, Foreground}` + `RegistrationOrder` / `DrawOrder` 分离;管理器按列表调度四类调用 | 断言:两者可分别设置(把 axis 的 DrawOrder 调到最后 ⇒ 绘制序变、初始化序不变);**定义工具在任何生命周期里都第一个跑**(把它注册在最后一个也照样第一);报表每工具印 `category/regOrder/drawOrder`;对照臂:两个 order 混用 ⇒ 红 |
| P9 | 网格线由数据范围控制(定义权在网格,轴线跟随) | 断言:同一份数据下"网格线与主刻度**逐条坐标相等**"(不是"看着齐");数据范围变了仍逐条相等;读不到插槽时回落被**印进报表**;对照臂:分格数写回手填 ⇒ 红 |
三期都要:编译门(本包 + 库)绿 + 探针全绿 + 每期至少一条能红对照 + 调度改动后 `p2/p4` 臂仍全红。
### 11.7 P7 落地记录(2026-10-23/24)
**已完成**(都带判据):
1. **插槽板**:`Runtime/XChart/Space/XChartSlotBoard.cs` —— `XChartSlotMode{Line2D,Line3D,Circle2D,Circle3D,Quad3D}`
+ `XChartSlotAccess{ReadOnly,ReadWrite}` + `XChartSlotView`(取点/取线/取圆/取面片 + `CanWrite`;**只读槽与过期视图都不许写**,
写成功推板子版本 ⇒ 别的消费者重建)。`XChartRenderContext.Slots` 由 chart 的上下文持有(空板非 null)。
2. **发布**:`ChartToolMeshBg`(网格背景)与 `ChartToolCubeBg`(立方线框)**都**把六个面发布成 `Quad3D`
(`mesh.face.0..5`)。发布的是**单位立方体的四角**而不是像素——所以"谁投影"仍只有一条路,
而"哪个面在哪儿"由定义者说了算。*两个元素都发布是必须的*:只放线框的图若没人发布,轴线会静默回落。
3. **消费**:轴线的宿主面改成 **`SlotId` 字符串**(`CubeFace` 枚举已从工具与配置里删除),
`ResolveFaceFrame` 先读插槽、用**自己的**矩阵投影四角并 `XChartFaceFrame.FromCorners` 组装面帧;
读不到就回落:把同一个 id 按 `mesh.face.<n>` 解释成面号自己推(解释不出来返回无效帧 ⇒ 清空绘制)。
**`frame=`**(`slot|cube`)进报表 —— 两条路画出来一样时更要印,否则"跟随网格"没有生产者。
4. **判据**:探针 +5 条 —— 五种模式的切值/解释、只读拒写、过期拒写、可写写通、
**插槽角点与面帧角逐点对拍**("改走插槽后画面不变"的离线证明)、id 约定稳定且互不相同、回落解析器只认 `mesh.face.<n>`。
对照臂 **T**(不查权限)、**U**(放行截断组)、**V**(交换两个侧角 ⇒ 角序错)各红在指名的格子上。
**P7 还差**:① 网格发布**格线** `Line3D`(P9 对齐要用);② `Teardown` 时 `Slots.Clear()`(避免脏槽);
③ 面板上给 `SlotId` 一个"已发布插槽"的下拉提示(现在是文本输入)。
---
## 12. 界面串的语言:**回到中文**(试过英文,他 2026-10-24 当场否掉)
**先记结论**:界面串(按钮、字段名、分组标题、读数句、窗口正文)**保持中文**。
**为什么试了英文**:TMP/TextCore 的默认字体资产有一个坏掉的图集槽(§8.6),而**任何"需要新字形"的文本测量都会抛**
—— 面板/窗口/Inspector 每次重绘都可能撞。当时的想法是"界面串全 ASCII ⇒ 结构上不再需要新字形"。
**为什么否掉**(他原话):"你的界面上的有些说明太长了,而且报错的都是一些按钮、字段,或者纯 UGUI 上的
labeltext,我感觉你还是用中文吧,不然界面塞不下。" ⇒ 英文在这些位置**装不下**(中文一个词 = 英文 2–4 个词),
而报错位置恰好就是这些**短**控件文本。**语言不是这条问题的解法**。
**由此确认的三件事**:
1. 那条图集问题**只能在资产侧修**(Reimport / 删空槽 / 换默认字体,见 §8.6)——它是**资产导入状态**,
不是渲染、不是数据、也不是插槽的事。
2. **图表自己的标签文本不归我管**:轴线刻度标签、维度显示名、格式化串都是**用户数据**,
本来就可能是任何字符,不可能靠"我写 ASCII"绕开。
3. **留下的经验**:新 UI 文案**要短**(面板宽度有限;这次是英文暴露了长度问题,中文也一样别写长句)。
**留档**:三张映射表 `ui_locale.py`(配置与菜单)/`ui_locale_window.py`(数据窗口)/`ui_locale_panel.py`(面板)
是"试过英文"的完整记录(含 205 条对照),`revert_locale.py` 可一键回滚(幂等);
按"界面串必须 ASCII"写的 `locale_check.py` **已删除**——它编码的是**已被否掉的规则**,
留着会变成一道"逼人做错事"的常驻门。
### 12.1 最后的落法(2026-10-24,他给了精确证据)
他给的证据是决定性的:**只有顶部那几个按钮抛**(添加元素/全部展开/全部折叠),
其余按钮、字段名、纯 Label 都不抛 ⇒ 触发的不是"整个面板",而是**恰好含有"图集里没有的那个字"的控件**
(添加/元素/展开/折叠/…)⇒ 那些字要走 `TryAddCharacterInternal` → `SetupNewAtlasTexture` ⇒ 撞坏槽。
于是落法是**两条规则**,都不动整体语言:
1. **会抛的那几个控件改成 ASCII 短词**:`Add` / `Expand` / `Collapse`(他选"换更短的词")。
ASCII ⇒ 不需要新字形 ⇒ 不再触发;短 ⇒ 装得下(他指"装不下"的是**长说明**,不是这几个词)。
**判据/规矩**:以后哪个控件开始抛,就单独把它换成 ASCII 短词;不需要全仓英文化。
2. **长说明一律"面板一句 + 完整进日志"**:面板塞不下、又没法复制的长文本改走 `Debug.Log`,
并且**按 key 只打一次**(`LogDetailOnce`——面板随数据重建,不去重就刷屏)。
已改三处:报表状态(`报表:开/关` + 完整路径与字节数进日志)、`Capacity` 说明、网格对齐提示、
轴"只铺了 8%..95%"的警告(面板只留百分比,整句进日志)。
**规矩**:新加的面板文案先问"这句话在面板里能不能看全、能不能复制",不能就拆成一句 + 日志。
---
## 13. 折叠层级:默认全折叠 + 最深一层自动互斥(2026-10-24 他口述)
他的要求,逐条照做:
1. 所有折叠板块**默认处于折叠状态**;
2. "里面的一层折叠层"共用**一个排斥标记**——一次只想展开一个详细板块("折叠太多了我看不到");
3. 要有**统一的标记**:先折叠所有被标记的,只留用户刚点开的那个;
4. 这个标记**只在最深的那一层**,"不是所有层级都需要这个东西";
5. 层级本身要由**程序化的流程**生成,chart 自身和各组件都走同一套,互斥标记由流程自动补上。
### 13.1 落法
- **默认折叠**:`MakeGroup` 在没有历史记录时 `expanded = false` ⇒ 面板一打开只有「基础」「工具」两行。
- **层级不由调用方报数**(第 5 条的实质):`MakeGroup` / `GroupFor` 只**登记**块,把 key 钉在盒子根的
`userData` 上;整棵树灌完后 `FinalizeHierarchy` 把这一轮的块交给 `XChartPanelHierarchy.Compute`,
现算 **父级 / 深度 / 是否最深**。**为什么不能传参**:一块挂在谁的 Body 里由 `GroupFor` 的合并规则
决定(同名合并、跨父级不合并),传进来的层级会和真实挂接位置分叉——而第 4 条要的就是真实层级。
- **"最深"= 叶子块**:它下面再没有折叠块,也就是**真正装字段的那一层**。
⚠️ 这**不是**"全局最大深度":一条分支只有一层(基础 → 调试),另一条有两层(基础 → 数据 → 维度 0),
两边的叶子都算"它那条分支里最深的一层",都要打标记;按全局深度挑会把「调试」漏成自由块,
于是又能同时开两个详细面板了。这一条有专门的变异臂(M1)。
- **互斥只有一条**(第 2、3 条):所有叶子块共用一组标记,展开任意一个 ⇒ 其余开着的一律收起;
中间层(基础 / 工具 / 某个元素 / 数据)**不受管**——它们是导航,想开几个开几个。
- **「Expand」是显式例外出口**:`SetAllExpanded` 期间 `m_BulkFold` 屏蔽互斥。不屏蔽的话"全部展开"
会**逐个开、逐个被收**,按下去只剩最后一个开着(等于没展开)。之后点任意叶子块,规则立刻回到"只开一个"。
### 13.2 机器看得见的与看不见的
- **看得见**:那套算术。`.ximage-gate/hierarchy_gate.py` 把实现文件**和探针一起编译**(不是抄一份),
47 条断言:正本全绿,5 支变异臂各红在它指认的那条
(M1 按全局深度 / M2 认生 `userData` / M3 一块不打 / M4 深度不累加 / M5 块块都打)。
每支臂的 `WITNESS` 行印的是**它自己那份文件的字节与 sha**—— mutant 的身份不会被正本冒充。
- **看不见**:控件那一层。引擎的 mono **造不出真 `VisualElement`**(静态构造要绑
`UIElementsRuntimeUtilityNative::VisualElementCreation`,实测 `SMOKE=THREW TypeInitializationException`),
所以"假树"能验规则、验不了 `parent`/`userData` 到底接没接上。
- **因此面板自己印读数**:调试块一行「层级:块 N 最深 M 深 D ⇒ 判决」,报表的 `panel:` 行追加
`groups= deepest= depth= hierarchy=`。两个判决名不是装饰:
`HIERARCHY-NO-PARENT` = 块多于一个却没有任何块认到父级(往上爬那一格没爬到东西,互斥会连导航层一起管);
`HIERARCHY-NO-LEAF` = 一块最深都没有。这两条**不会**以"没打印所以没事"的形式蒙过去。
### 13.3 他侧验收(只需按一次 Ctrl+R)
1. 选中图表 ⇒ Inspector 只有「基础」「工具」两行(默认全折叠)。
2. 开「基础」⇒ 里面「基本信息」「数据」「调试」:开「调试」会把「基本信息」收掉(**它们同是叶子层**),
开「数据」不影响它们(**它是导航层**)。
3. 「数据」下开「维度 0」⇒「维度 1」自动收起。
4. 再去开某个元素的「外观」⇒「维度 0」也收起 ⇒ 全面板任何时候只有一个详细块开着。
5. 按「Expand」⇒ 全开(横向比对的出口);再点任意叶子块 ⇒ 回到"只开一个"。
6. 开「自述报表」后,报表里 `panel:` 行应看到 `hierarchy=OK` 且 `deepest < groups`。
---
## 14. 参数来源(P10)与桶采样虚拟化(P11)(2026-10-24 他口述的要求)
他的原话拆成四件可实施的事:
1. **每个工具的参数要能配"从哪个维度来"**——现在只有两种来源:配置里的常量,或硬编码的维度下标。
需要一层统一的东西,把"工具要的参数 ← 数据维"配上,chart 才能真正驱动渲染。
2. 同一层要能和数据虚拟化结合:**折线按桶采样**,桶内算最大/最小/平均/中位数……,
把一个范围的记录简化成**一个点**,取"我们认为最有意义"的那个统计量。
3. 有些渲染器要**复合数据**:一个项跨多个维度拼接(圆柱=3 维 × 2 个值=起点/终点;
矢量场=位置 3 维 + 方向 3 维)⇒ **渲染器按它实际需要的通道数创建项**,不由 chart 预设。
4. 65535 那条上限:折线靠**桶采样**解决;其他渲染器用**硬上限**或别的策略限制。
**同时改口径**:圆柱/散点/折线这些工具的数据来源与几何驱动**都基于 chart 的数据源**;
散点按当前维度定义给形态(2 维=2D 散点、3 维=3D 散点);**"数据维数"不是"chart 是二维还是三维"的判据**
(以后可能上来四元数或别的表示)。chart 一般 3 维够用,但接口不该把它焊死。
### 14.1 P10 已落:几何来源=常量 / 数据(先落圆柱)
- **纯算术单独一支** `XChartBindingMath`:三维取值、值域归一化,以及**记录编组**。
四条"拒绝"分支都在渲染路径里,眼睛分不出"这一帧没画"和"画的是上一帧",所以它们必须离线判:
下标/维度越界、空数据、NaN 一律 false——**宁可这一帧不画,也不往几何里塞 NaN**。
- **顺序只留一个权威**(他 2026-10-24 的现场,问题是他改第 1 条而圆柱不动):记录下标 `0` = 最早、
`n-1` = 最新,**与数据窗口的行号同一套下标**;`XChartBindingMath` **不提供**"往回数第几条"这种相对量
(第一版就是它:默认"上一条→最新",于是同一份数据在窗口里是第 1 条、在工具里成了第 n-2 条,
而末两条相等时圆柱两端直接合并)。API 是 `CompleteGroupCount` / `TryResolveGroup(recordCount, groupIndex, groupSize)` /
`TryResolvePosition(data, recordIndex, …)`,全部**绝对下标**。
- **归一化是必须的一步**:常量坐标是立方体单位(±1),数据值是数据口径(可能上千)。
`TryNormalize` 把值域映射到 ±1,**值域退化(min==max)时返回 false**(那一刻没有"数据在哪儿"),
**超范围不裁剪**——超出盒子的值是数据的事实,裁了就看不出来了。
- **圆柱=一组记录一根**(他纠正过一次:不是"最近两条",也不是"n 条记录 n-1 根,而是两两一组 16 根"):
组 `g` 覆盖 `[g*size, g*size+size-1]`,两端取**组首与组尾**,组与组**严格不重叠、也不把上一组并进来**,
凑不满一组的尾巴**不画**(记进 `groupsSkipped`)⇒ 32 条记录、组大小 2 = **16 根圆柱**(记录 0-1、2-3…30-31)。
常量模式仍是配置里那两个坐标(`m_Start`/`m_End` 字段名与类型都没动,老预制体绑定不变);
新增字段只加在几何组里:`m_DriveByData` / `m_DimensionX|Y|Z` / `m_GroupSize`(默认 2)/ `m_MaxCylinders`(默认 64)。
- **多根的画家序**:三个渲染器(填充/曲线/折线)都只按**提交顺序**画,所以每帧把圆柱按深度
**远→近**排一次(`ChartToolSpace.DepthOf` 越大越近)再提交;不排就会让近的被远的盖住。
工具内部因此改成"各清一次 → 每根追加 → 最后统一提交"。
- **拿不到几何时的行为是明确的**:清空三个渲染器(**不能走绘制路径**——端面圆环吃的是上一帧的圆盘,
会留下一个没有壳的环),并且**不退回常量几何**(那会假装数据在动)。
- **脏判定**把数据版本算进来:数据模式下图随数据变,只比 `ProjectionVersion` 会漏。
- **报表读数**:`geometry=literal | data(groups 16/16, size 2, rec 0->31, capped/skip 可选) | data-skipped(<原因>)`
与 `cylinders=<这一帧真画了几根>`。理由是他那条老规矩:`skipped`、`literal`、"截断了多少"
在画面上长得一样,只有印出来才分得清。
**离线证据**:探针 **323 项**(分组断言:32→16 组、组 0 = 记录 0-1、组 15 = 记录 30-31、
奇尾不成组、组大小 4 跨 0..3/4..7、负组号与组大小 <2 拒绝;下标断言:记录 0 / 记录 2(最新)/
越界与负下标拒绝;加上 NaN、归一化端点、退化值域、超范围不裁剪);
`p4_control` 新增两支对照臂——「组多含一条记录」(`last = first + groupSize`)与
「尾巴组被放行」(`if (last >= recordCount)` 短路成 false),各红在点名断言;编译门三臂全绿。
**过程记录(值得留着)**:上一版探针首跑红在 `binding: a value outside the domain is NOT clamped`——
**是我手算的期望值错了**(`30` 在 `[-10,10]` 里映射到 `unit = 3`,我写了 `>3.9`),实现是对的。
期望值凡是手打的,都要对着真数据核一遍再写进判据。
### 14.2 P11 设计(未做,先记清楚再动手)
- **桶采样**:复用已有的 `XChartMultiResolutionSeries`(多分辨率桶,`XChartAggregateBucket` 已带
First/Last/Min/Max/Mean + 版本号增量重建),**补 Median**(桶内样本少,排序即可);
chart 侧已有 `XChartAggregateKind`(9 种)与 `XChartDataModel.TryGetAggregates` 可对齐命名。
- **"最有意义"的默认值按渲染器定**:折线取 `Last`(最新值,监看场景要的就是它;要包络就给 Min/Max 两条),
圆柱/矢量场这类"复合项"取窗口 `Mean`(平均位置/平均方向),散点不聚合(抽稀即可)。
- **上限=预算,不是常数**:每渲染器声明"每项顶点数",`XChartMeshBudget.ChunkVertexBudget` 是每个
Graphic 的预算 ⇒ 项数上限=预算 ÷ 每项顶点数;超限按策略降采样(桶加大)或截断,
**并在报表点名**("截了多少"必须能被读到,才有资格叫上限)。
- **待他定的两条**:① 折线默认聚合是不是 `Last`;② 复合项要不要再加一种"每条记录一个项"的模式
(今天圆柱是"两条记录一个项",箭头是"一条记录的 6 个通道一个项")。
---
## 15. Undo 删除时的原生崩溃:销毁窗口里不能再拆子孙(2026-10-24 现场)
**他报的**:删掉 chart 后撤回不了——一按 Ctrl+Z 就整个编辑器崩掉;之前界面上也看不到任何渲染内容。
**日志给出的因果**(`%LOCALAPPDATA%\Unity\Editor\Editor.log`,崩溃点在 482139 行),崩溃前 Unity 连报**两次**:
```
Child GameObject 'LineChunk0' was not registered into undo system and became dangling during an undo operation.
Use Undo.RecordCreatedObject to correctly add a child GameObject which can be handled by the undo system
[StructureUndoBase.cpp line 600]
```
紧接着 `Received signal SIGSEGV`,56 层栈里关键那几层:
```
Object_CUSTOM_DestroyImmediate ← UnityEngine.Object.DestroyImmediate
← XChartToolBase.Dispose (XChartToolBase.cs:88)
← XChartToolsManager.RemoveAllTools (XChartToolsManager.cs:166)
← XChartToolsManager.Dispose (XChartToolsManager.cs:264)
← XChartBase.Teardown (XChartBase.cs:509)
← XChartBase.OnDestroy (XChartBase.cs:498)
← MonoBehaviour::WillDestroyComponent / GameObject::WillDestroyGameObject / PreDestroyRecursive
← ObjectUndo::ApplyUndo ← UndoManager::Undo ← Ctrl+Z(快捷键派发)
```
**机制**:Ctrl+Z 正在**应用撤销**(那条撤销就是把这个层级递归销毁)。Unity 在递归销毁途中回调我们的
`OnDestroy → Teardown`,而 Teardown 又对**同一棵子树的子孙**(工具根 → 池根 → `[XChartTools]` 根)逐个
`DestroyImmediate`——在 Unity 自己的销毁遍历**中途**再进一次销毁是重入,直接原生段错误。
`LineChunk0`(分块线渲染器建的子节点)没有登记进 undo system、成了 "dangling",正是它把一条警告变成崩溃。
**修法(本轮已落)**:`OnDestroy` 先把 `m_HierarchyBeingDestroyed` 置真;Teardown 在这个窗口里
**一个 `Destroy*` 都不调**——生成物全是本对象的子孙,跟着一起没:
- `ToolManager.ReleaseBookkeeping()`:`RemoveAllTools(false)` → `tool.Dispose(false)`(该注销的账照记:
先 `ForgetTextOwner` 再从列表里拿掉,只是不拆自己的根)+ 池只丢引用(`TextPool = null`)。
- `ToolsRoot` 只置空;"池根现拆现验"那条判据在销毁窗口里跳过(整棵子树都在被销毁,没有"漏一个"可言)。
- `XChartToolBase.Dispose(bool destroyRoot)` 与 `XChartToolsManager.Dispose(bool) / RemoveAllTools(bool) /
RemoveTool(tool, bool)` 都带上了这个开关,**默认 `true`** ⇒ 非销毁路径(面板重建、「重新生成全部节点」)
行为完全不变,`POOL-ROOTS-LEAKED` 那条判据继续有效。
**仍然开着的一条(警告,不再崩)**:生成物(`LineChunk*` / `FillChunk*` / `TextSlot_*` / 工具根 / 池根)
都没登记进 undo system,所以每次 undo 仍会印那句 "became dangling"。
要消掉就得在创建处 `Undo.RegisterCreatedObjectUndo`——但那会把生成节点塞进他的 undo 历史
(能一步步撤回出半死的图),**所以这条留给他定**,本轮不擅自改。
**恢复现场的事实(离线能查的都查了)**:
- **盘上的场景没坏**:`Assets/Scenes/Main_金塘.unity` 是完整 text YAML(71.9 MB、mtime 13:11)——
崩溃发生在 Undo 中途,没来得及写盘。
- 但那份场景里**没有任何图表组件**(370 个 distinct guid 全扫过,`XChartBase` / `XMeshPreviewChart` /
`XPseudo3DScatterChart` 三个脚本 guid 都不在),全 `Assets/` 的预制体里也没有 ⇒ 他那个 chart
从来没被保存到盘上(是内存对象),"恢复"没有可恢复的源。
- `Temp/__Backupscenes/0.backup`(13:19,**二进制**):我**判不了**它有没有那个 chart——
guid 探针在这份备份上拿场景里 6 个真 guid 做对照也全是 0 命中,说明**这个仪器对二进制备份不可用**,
不能把"没命中"读成"里面没有"(如实记档)。
- `Library/EditorInstance.json` 里留着死掉的 pid 38624:不用手删,Unity 启动时会重写。
**判据**:编译门三臂 + 探针 317 项全绿(离线只能证到"编得过、纯逻辑没回归");
**"点 Ctrl+Z 不再崩"与"删了重建后界面有内容"这两条归他在现场判**——离线跑不了编辑器的销毁路径。
---
## 16. 数据窗口改造成表(2026-10-24 他口述)
他的清单(逐条落):
1. **表头行**:`#`(记录下标)/ 时间 / 每个维度(可就地改名)/ `+`(加一列)/ 标签。
表头与行里的格子**共用同一组列宽常量**(`kIndexWidth`/`kTimeWidth`/`kCellWidth`/`kAddColumnWidth`),
否则表头和数据会错位。
2. **第一列是什么**(他问的):那是**记录下标**——0 = 最早、n-1 = 最新,**所有工具按这个顺序取值**
(圆柱就是按它两两分组:0-1、2-3…)。它**不是数据、不可改**;列标题的 tooltip 直接写这句。
3. **加行**:列表最后一行专门放「+ 添加一行」(列表项数 = 记录数 + 1;绑定那一行时把格子整组隐藏、
只显示按钮——两种布局互斥,不能挤在一层)。
4. **加列**:表头最右的 `+` 新增一个数值维(默认 key `d<n>`、名 `D<n>`,随即可在表头改名);
老记录这一维补 0(`SetDimensions` 会重排每行的值数组)。
5. **改名**:只改**显示名**——新增 `XChartDimensionDefinition.DisplayName` 可写 + 模型
`TryRenameDimension(index, name)`(空名拒收)。维度序号与 key 不动:序号是工具绑定的依据。
6. **工具栏用 Toolbar 族控件**(`ToolbarMenu` / `ToolbarButton` / `ToolbarToggle` / `ToolbarSpacer`),
并把功能**按组收进下拉**:`导出▾[到剪贴板, 到文件…]`、`导入▾[从剪贴板替换/追加, 从文件替换/追加…]`、
`清空▾`、`测试▾[螺旋 32, 平方和金字塔 30]`;面板那种"一排裸 Button"不再出现。
7. **底部状态栏**:`总行 / 维度 / 已丢弃` + **缓冲上限的就地输入框**(改它只影响之后的写入,
到顶才从最旧的开始丢;改小不裁剪、改大找不回)+ 最近一条消息。
8. **顶部"强制刷新"**:改完数据直接 `ForceRefresh()`,不用回界面乱点(测试时最需要的就是它)。
9. **测试数据生成器搬进窗口并抽成一支**:`Editor/XChart/XChartDataGenerators.cs`
——`AppendSpiral(32)`(就是原来那圈正弦/余弦)与 `AppendSquarePyramid(4)`(1+4+9+16 = 30 个顶点)。
面板里的「生成 32 条示例」「灌 10000 条」删掉(数据相关的事集中到窗口),
「追加一条」也改走同一个 `TryAppend3`(不再两处各写一份)。
10. **长说明搬到 tooltip**:窗口底部不再占一整段说明文字("只有滚进可见范围的行会被绑定…"),
改挂在列表的 tooltip 上——要看的浮一下就有,不用天天占屏幕。
**金字塔的口径**(与他核对过):第 `k` 层有 `k×k` 个顶点,层内 x/y 铺满 `[-(k-1)/2, +(k-1)/2]`,
**z = k 逐层升高** ⇒ 层数越高、点越多、位置越高。
**判据**:新增 `.ximage-gate/generator_gate.py`(探针 `generator_probe.cs` 直接**编译源码本身**,
不信 dll 副本):11 条断言(四层恰好 30 个顶点、层 1 是 (0,0,1)、层 2/3/4 的 x-y 跨度 ±0.5/±1/±1.5、
每层各占一个 z、时间戳从 0 起非递减、螺旋 32 条且 x 从 -100 到 +100、数值维不足 3 时只喂前几维、
无数值维时不写)**正本全绿**;2 支变异臂(层数多一层、层内跨度平移)各红在点名断言。
WITNESS 印的是**那段源码的字节与 sha**(变异臂印变异副本),所以"判的是哪棵树"有据。
窗口的观感/手感(表头对不对齐、下拉顺不顺手)**归他现场判**——离线看不到控件。
---
## 17. P11:桶采样(把一个范围简化成一个点)(2026-10-24)
他的原话:"linechart 渲染时需要以桶采样数据,每个桶里面还要最大、最小、平均、中位数……目的是把一个范围内的数据
简化为一个点,这个点则需要取一个我们认为最有意义的值去呈现。"
**落法**:新增纯算术 `XChartBucketMath`(`Runtime/XChart/XChartBucketMath.cs`):
- `BucketCount(recordCount, targetPoints)`:目标点数 ≤0 或 ≥ 记录数=**不聚合**(桶数=记录数,
于是"没开桶采样"的行为与以前逐字节相同);记录数为 0 时 0 个桶。
- `TryBucketRange(recordCount, bucketIndex, bucketCount, out first, out endExclusive)`:
整数均分(`recordCount * i / bucketCount` 的整数算术),**桶与桶严丝合缝、不留缝不重叠、
并起来正好覆盖整表**。
- `TryReduce(data, dimension, first, end, reduce, scratch, out value)`:桶内归约,
直接复用数据层已有的 `XChartAggregateKind`(Count/First/Last/Min/Max/Sum/Mean/**Rms**/**Median**),
不再造第二套枚举。NaN/Inf 一律跳过;整桶坏值返回 false——**宁可少画一个点,也不塞一个假位置**;
中位数要么给够 `scratch`、要么拒收(渲染路径里不偷偷分配)。
**"最有意义"的默认值按元素定**:散点默认 `Last`(**抽稀**:取桶内最后一条真实记录,不造新值),
要看趋势就把桶内归约换成 `Mean`/`Median`、要看包络换成 `Minimum`/`Maximum`。
圆柱那条路是**记录编组**(§14.1:一组一根,端点取组首组尾),不是桶归约——两种不同的问题:
"把一段压成一个点"用桶,**"一段里取两端"用编组**。
**接进散点**(`ChartToolScatterPoints`):`BucketTargetPoints`(0=不聚合)与 `BucketReduce` 两个参数,
配置里在"数据来源"组;`BuildPointsFromDataSource` 改成"算桶数 → 逐桶归约三路(+颜色维)→ 归一化"。
两个必须说清的细节:
- **归约不等于抽稀**:`Mean/Median` 得到的点**不在原始数据里**(是这段数据的中心),
这是刻意的选择("取一个我们认为最有意义的值"),默认给 `Last` 就是为了"不造新值"。
- **算完要裁掉尾巴**:渲染器**按数组长度**提交,桶数变少时不 `Resize` 就会画出上一轮的旧点
(`TrimPoints` 干这件事)。
**上限这件事(他说的"65535 已经由上游分页解决了")**:不再新造一套全局"预算÷每项顶点数"的换算——
上游分页兜住总量,剩下的**每渲染器上限就表达成它自己的参数**:圆柱是「最多几根」(默认 64)、
散点是「桶目标点数」(0=不限)。两者都会**在报表里印实际值**:
散点 `points= buckets= records= reduce=`、圆柱 `cylinders=` 与 `geometry=data(groups …, capped/skip …)`。
**判据**:探针 **343 项**(新增 20 条 `bucket:` 断言:桶数四态、7 桶切 100 条必须严丝合缝且覆盖末尾、
越界桶/桶多于记录数拒收、以及 5 种归约 + 中位数(偶数取中间两个的平均)+ 无 scratch 拒收 +
只读自己那段范围 + 空段/越界段拒收)**正本全绿**;`p4_control` 新增三支对照臂,**每条断言各有自己的生产者**:
「桶之间留缝」(首记录整体平移一格 ⇒ 红在 `contiguous`)、
「末桶早停一条」(只把最后一个 end 减一 ⇒ 红在"覆盖末尾",而**留缝那条看不见它**)、
「Last 归约答成 First」(红在 `reduce Last … = 3`)。
**过程记录**:我第一版把"留缝"这条臂同时要求红两条,结果**覆盖末尾那条根本没红**——
末桶的 `end` 在那改法里根本没动,它看不到缝。**同一条结论的两半要各有各的变异体**,
不能拿一个变异体去担保两个不同机制。
**"桶采样的观感"(点够不够、`Mean` 是否比 `Last` 好看)归他在现场判**——离线只知道算术对。
---
## 18. P7 收尾:格线插槽 + 面板的"已发布插槽"(2026-10-24)
P7 原本还欠三条,这轮结清(其中一条**判定为不需要做**):
1. **网格发布格线 `Line3D` 插槽**(P9 要用):
- id 约定 `mesh.face.<面号>.grid.S`(沿 S 的等 t 线)/ `.grid.T`(沿 T 的等 s 线),
模式 `Line3D`、只读,值是**单位立方体端点**——与 `mesh.face.<n>` 的四角同一口径,
所以"谁投影"仍只有一条路。
- **值由纯算术填**(`XChartCubeGeometry.FillGridLineValues`:比例 `i/(lineCount-1)`、**含两条边**、
沿 S = 等 t 线),两个定义网格的工具(元素框架的网格背景、Pseudo3D 的立方体背景)各自按
**自己画出来的那一套**条数发布(前者统一分格数、后者按方向拆)——
**"发布的线 = 画出来的线"**是 P9"刻度落在格线上"的前提。
2. **`Teardown` 里的 `Slots.Clear()`:判定为空操作,不写**。理由:插槽板归 `XChartRenderContext` 所有,
Teardown 把 `ToolManager`(连着 context)一起丢掉,下一次 `EnsureInitialized` 会新建 context ⇒ 新板子;
全仓只有两个消费者(轴线、网格背景)且都每帧从 `Context.Slots` 现取,没有第三方持有。
写它只会在代码里留一条**永远走不到的守卫**("判据没有生产者=测不了"那一族的反面:没人能从它变红里学到东西)。
记录在案:将来若出现"context 跨重建复用",这条才需要补。
3. **面板的"宿主面"改成选清单**:轴的宿主面新增 `已发布插槽` 下拉(列**当前板上真有的** id)+手填框,
并在 `AppendHeaderGroups` 里跳过那条裸 `m_SlotId` 字段(同一件事不做两个入口)。
板子为此加了**索引式**的 `TryGetSlotAt(index, out id, out mode)`(不返回集合 ⇒ 面板每帧取不分配);
面板上只留"已发布插槽 N 个",完整 id 清单走日志(长文本不进面板,他 §12.1 的规矩)。
**判据**:探针 **355 项**(新增 12 条:3 条线占 18 个 float、写回条数、发布后 `groupCount==3`、
第 0/中/末条分别落在 t=0 / 0.5 / 1 的边界与中线上、沿 T 那组是等 s 族、三组 id 互不相同、
缓冲太小拒收、`TryGetSlotAt` 走到末尾且越界拒收);`p4_control` 新增「格线不到远边」臂
(`i/(lineCount-1)` 改成 `i/lineCount` ⇒ 红在"最后一条是 t=1 边")。
面板观感(下拉顺不顺手)**归他现场判**。
**过程记录(我自己踩的坑,已修)**:第一版里**立方体背景两个方向共用一个"按最大值开的"缓冲**
(沿 S 的条数由 T 的分格数决定、沿 T 的由 S 的,按方向拆就必然不同),而插槽板是
**按数组长度算组数**的(`Array.Copy(values, entry.Values, values.Length)`)⇒ 条数少的那一组会把
缓冲尾巴上的残留当成额外的格线发布出去,板子上凭空多出几条不存在的线(轴线对齐时被引到错位置)。
修法:**两个方向各一个缓冲,且长度必须与这一组的条数精确相等**(不是"够大就行")。
网格背景同源形态也一起改了(分格数从大变小时,旧的长缓冲同理)。
并把这条**板子契约**钉进语料:`slot board: the group count comes from the ARRAY length
(publishers must pass an exact-length buffer)`——哪天板子改成"组数另有来源",这条会先红。
---
## 19. P8:注册分组 + 注册序与绘制序分离(2026-10-24)
他 2026-10-23 的口径:"定义一个值列表……需要一个 order 表示每个组件的刷新顺序……可以简化为直接使用
特定的类型标记,比如背景(背景网格),前景(参数点位、轴线标尺、tooltip、其他可互动元素);
使用列表统一调度;这个 order 只是注册 order,**不是绘制顺序 order**,比如我希望轴线的线可以绘制在点的上面"。
**落法**(把"谁先算"和"谁盖谁"彻底分开):
- **`XChartToolCategory{Definition, Background, Foreground}`**(`Runtime/XChart/XChartToolOrder.cs`):
定义组 = 空间、网格背景、立方体背景(它们算范围、发布插槽)⇒ **最先跑**;
前景 = 散点/箭头/圆柱/轴线;`Background` 目前没有工具落在这里(位置留给"只画背景、不定义几何"的第三类)。
分组是**类型标记**(工具 override `Category`),不入序列化——省一个要调的旋钮。
- **`XChartToolBase.DrawOrder`**(绘制序,小者先画)与 `OrderIndex`(注册序,小者先建/先算)**各管一件事**。
配置里对应 `m_OrderIndex`(语义改为注册序)与新增的 `m_DrawOrder`;面板元素行现在是「注册序 / 绘制序」两个格子。
- **顺序规则只有一处**:`XChartToolOrder.Compare/Sort`(分组 → 数值 → **注册序**)。
最后那一级是稳定性的来源——少了它,"值相同"的两个工具谁在前就看运气,画面上就是"有时点在上面、有时轴在上面"。
- **统一调度**:`XChartToolsManager.ApplyOrder()` 一次落两件事——
**更新序**(分组→注册序,`m_Dispatch`)与**绘制序**(分组→绘制序 ⇒ 写进兄弟序,UGUI 按兄弟序画家序)。
`UpdateAll` 走 `m_Dispatch`(所以定义组当帧先算完范围/发完插槽);`RenderAll` 仍按注册表遍历(画家序由兄弟序决定,与遍历序无关)。
- **三个读数分开印**:每个工具的调试行有 `category= reg= draw= sibling=`——"谁先算"和"谁盖谁"必须能分开看,
否则调错了也读不出来。
**同轮修的一处旧账**:`pnpm` 的时代里 `AddTool` 直接把兄弟序设成注册序的位置,于是"注册序 = 绘制序"被焊死;
现在兄弟序只由 `ApplyOrder` 按(分组、绘制序)写。
**判据**:探针新增 `tool order:` 断言(分组压过任何数值、背景夹在两者之间、同组比数值、
同组同值按注册序、自反相等、一次真实排序的置换、已有序时报"没动过");`p4_control` 新增两支臂
「先比值再分组」「丢掉注册序这一级」,各红在点名断言。
---
## 20. P9:网格线由数据范围定、轴线跟随(2026-10-24)
他 2026-10-23 的原话:"立方体网格上的分割线也都统一通过 chart 上的数据范围控制",以及
"在任意的统一更新生命周期中,网格都是最先刷新数据的,比如网格要计算数据各个维度的范围"。
分两半落地,**前一半(定义权在网格)已完成**:
**20.1 网格按数据范围布线(已完成)**
- 新增纯算术 `XChartGridLines`:
`BuildUniformRatios(count, ratios)`(等分:比例 `i/(count-1)`、含两条边——旧行为);
`BuildRatios(min, max, scale, strength, targetCount, manualStep, autoStep, ratios, scratch)`
(**用该维的值域** + `XChartAxisMath.BuildTicks/NiceStep` 求刻度值,再经 `ToParameter` 折成面参数比例,
夹到 [0,1]、丢掉 NaN/Inf)。**与轴线刻度同源**——"逐条坐标相等"的前提就在这。
- `XChartCubeGeometry.FillGridLineValues` 改成"**比例 → 端点**"(比例由上面那支算):
"格线在哪儿"只有一个实现、两个背景共用。沿 S 的线 = 等 t 线(写反就是整片网格转 90°)。
- 网格元素新增两个绑定:`沿 S 的格线绑哪一维` / `沿 T 的格线绑哪一维`(默认 −1=不绑、等分)。
绑了就用该维数据范围算线位置;**那一维没有数据时退回等分而不是不画**(网格整片消失比"线回到等分"难查)。
- 立方体背景(Pseudo3D 旧产品)目前仍走等分,代码与文档都写明了:数据驱动那条路先落在元素框架的网格背景上。
**20.2 轴线吸附跟随(已完成)**
- **纯算术**:`XChartCubeGeometry.GetFaceParameter(face, point, out s, out t)`(面参数反解,与
`GetFacePoint3D` 互为逆)与 `XChartGridLines.TrySnapToGrid(ratios, count, ratio, maxDistance, out snapped)`
(取**最近**的一条;距离超过上限就**不吸**——宁可不对齐,也不把刻度扭到老远)。
- **轴线**新增 `AlignToGrid`:开启后在**面参数**上吸附(格线发布的就是面参数位置),再折回轴上的比例——
所以"刻度落在格线上"是几何意义,不是数值凑。轴沿 S 走读 `grid.T` 那组(等 s 线)、沿 T 走读 `grid.S`;
吸附上限=**相邻两条线最小间距的一半**。取不到槽(无网格元素 / 网格没发布 / 手填 id 不是 `mesh.face.<n>`)
就不吸,并把原因写进 `align=` 读数:`off | grid(n/m, snapMax=…) | no-board | no-slot | no-lines | unknown-face`
——"没吸上"和"没开对齐"在画面上一样,只有这一行分得清。
- 配置:轴元素多了「对齐格线」一项。
**过程记录(探针当场抓到我实现里的错)**:`GetFaceParameter` 第一版只写了点积,**忘了面轴长度是 2**
(面轴是"整条边",不是单位向量)⇒ 参数被整整放大 4 倍;断言"往返 (0.25,0.75) 解回来还是它"一次就红
(实得 `s=1 t=3`)。修成"除以 |轴|²"并留了注释。⇒ 这是"手写公式先写期望、让机器算"的又一次收益。
对照臂也随实现更新:「面参数反解**忘掉轴长**」——它红在同一条断言上。
**判据(20.1)**:探针新增 `grid lines:` 断言(−100..100 域、目标 5 ⇒ 恰好 0/0.25/0.5/0.75/1;
产出的比例一律有限且在 [0,1];值域退化时不许产出 NaN/Inf;等分含两条边);
`p4_control` 新增/改派两支臂——「格线不到远边」(等分处 `count-1` → `count`,红在"最后一条是 t=1 边")与
「网格比例用错映射」(把 `ToParameter` 换成"除以跨度"⇒ 下半截线全挤到边上,红在点名断言)。
## 21. P12:数据的删、每列的范围,都收进数据窗口(2026-10-25 他口述)
他的原话要点(决定落在哪儿的是这些,不是我的排序):
- "我想单独去操作删除某一个数据项目" ⇒ 数据窗口要能**删一行**;"我在数据窗口里只能添加,没办法删除…
应该添加个标签,可以去删除这一最外面那一列数据项目" ⇒ 还要能**删一列**。
- "数据窗口工具栏里的图标引用字段可以改到底部的状态栏中,放到右侧" ⇒ 「图表」ObjectField 搬家。
- "Chart 面板的这个数据分类下…它只有三个是吗?如果我想添加一个新的维度,它也并没有去创建新的标签出来" ⇒
面板那批维度行是按**建面板时的数组长度**摊开的,新加的列不会长出新行;而根子上是"范围这件事不该在面板里摊"。
- "我们需要一个额外的字段来表示当前这一个维度下这个数据范围是多少…通过数据窗口调整的话,我们也可以立刻看到这个数据范围的变化"
- "转念一想,我们需要保留现在这个数据窗口的精简样式,可以在窗口的下面开一个新的分类出来…我们要切到新的这个分类标签页下"
⇒ **表不动**,在窗口下面加第二页(不是我原来打算做的"表底下再加三行统计")。
- "每一列下面都会有一一个计算值,就是当前统计的一个最小值、最大值、平均值…然后后面才是我们手动可以覆盖的值…
每个可以手动覆盖的值,前面有个勾选框…这个手动覆盖值默认应该就是 0";"它是两个字段,就是两行。我单独去巡视它们"
⇒ 统计只读、覆盖可写,**各占一行**,每个覆盖值前面一个勾选框(他举的形状就是后期处理的 Volume)。
- "勾选之后呢,就会启动这个维度上的对应的字段的限制。比方说,我想限制某个轴,它的最小值就必须得是 0,
最大值可以让它自由发挥…最小值低于 50 的我们就看不到了,这个轴就会突破这个网格范围" ⇒ **两端各自可钉**。
- "包括像你上面写的那个记录维度版本是321启用,然后还有追加记录这些都可以不需要了…你直接在这儿保留一个按钮,
一个打开数据窗口的按钮,在基础分类下就可以了。我们将所有的信息都整合到这个窗口里面去";"数据面板不要搞太深了"。
**21.1 一维范围:从"两端一起"改成"两端各问各的"**
- `XChartDimensionDefinition` 新增 `m_OverrideMin` / `m_OverrideMax`。`m_ManualRange` 的两个分量**总是留着**——
没钉住的那端存的数不参与解析,但下一次勾上时格子不该是空的("先填数再勾选"和"先勾选再改数"两条路都不能丢数据)。
- 旧的 `m_OverrideRange` 保留,含义="两端一起钉",而且**只在两个分量确实不相等时**才算数(`LegacyBothPinned`):
"勾了但没填(0/0)不算覆盖"这条从 P4 起就在,它保护的是"默认状态凭空造出一段范围",留在定义层,臂 A 仍能把它打掉。
- 分侧开关一旦写过就把主开关清零(`SetDomainOverride`)。不清就会留一个死状态:勾选框读出来是"勾着"(因为主开关),
取消勾选却取消不掉——两个来源表达同一件事时必然出现的形状。
- 唯一的读取出口是 `DomainOverride`(`XChartDomainOverride{HasMin,Min,HasMax,Max}`)。**`EffectiveManualRange` 删除**:
同一件事不留两个视图,否则"面板说的范围"和"工具用的范围"可以各自成立。
- 解析规则(`XChartDomainMath.TryResolve`,顺序就是优先级):① 钉住的那端用填的数;② 没钉的那端用该维聚合;
③ 只钉一端而另一端连聚合都没有 ⇒ 以钉住的那端为中心展开 ±`DegeneratePad`;④ 两端都钉成同一个值 ⇒ 同样展开,
而不是画一条零宽的轴;⑤ 手填把两端写反(或钉到聚合之外)⇒ **自动排序**,与旧规则同一处理;
⑥ 什么都没钉、聚合也没有 ⇒ `false`,调用者这一帧什么都不画(不是画在 0 上)。
- **入口收成一扇门**:`TryResolve(IXChartDataSource, dimension, out min, out max)` 自己读维度行 + 该维聚合;
`XChartRenderContext.TryResolveDomain` 现在只是转发它,数据窗口的范围页与轴线的 `rangeSource=` 读数也走同一扇。
以前"面板自己算一遍、上下文再算一遍"就是两处规则会分岔的地方(P4 现场那条 `NaN..NaN` 的读数就是这么来的)。
- 轴线的报表读数跟着改口径:`override[0..auto]` 表示"只钉了最小端",`auto` 明确印出来——
"这一端的数是谁给的"在画面上看不出来,只能在这行分。
**21.2 记录表:删一行、删一列**
- `TryRemoveRecord(index, out reason)`:越界就拒绝并报"现在一共 N 行"。**时间非递减不会被破坏**
(去掉有序序列的一个元素还是有序的),所以时间窗的二分定位照旧——这条写在方法注释里,并有判据。
- `TryRemoveDimension(index, out reason)`:删定义 + 从每条记录的值数组里摘掉对应那一格。
值数组的下标口径是**"第几个数值维"**而不是维度表里的行号——中间夹一个 Time 维时两者会错开,
这条专门有判据(Time 在前、删第一个数值维)和一支把它按"维度表行号"算的对照臂。
- 删列**不回改工具绑定**(轴的 `Dimension`、圆柱的 X/Y/Z 都按序号绑):这里只把数据的事实做对,
序号前移的连带影响由窗口的消息点名("后面的列号整体前移…要重新对一遍")。
- 删列是破坏性动作 ⇒ 先把整表复制进剪贴板(和"清空"同一张安全网)再要一次确认;删一行不打断——
一行就在眼前,且随时能整表导出。
- 范围覆盖的写入口是 `model.TrySetDomainOverride(...)` 而不是裸字段:**非有限数在门口就拒**
(NaN/Inf 当范围端点=整条轴安静地什么都不画,那是最难查的一族),写完 `Publish()`,
于是按版本缓存聚合的工具下一帧就看到新域。
**21.3 数据窗口:两页 + 状态栏**
- 顶栏只剩动作:`导出 / 导入 / 清空 / 测试 / 强制刷新 / 绑定读数`。
- 中部两页(同一时刻只显示一页):**数据表**(保持原来的精简样子)与**维度范围**;切换条是一条 `Toolbar`
放在**窗口下面**(他说"在窗口的下面开一个新的分类出来",不是把表变复杂)。
- 范围页一列一框、三层:① 列名 + **生效范围**(钉了哪端、没钉的那端跟数据);② **统计**(样本数 / 最小 / 最大 /
平均 / 中位 / RMS,全部来自 `TryGetAggregates`,与桶归用同一套聚合口径);③ `钉住最小`+格子、`钉住最大`+格子(默认 0)。
统计只读、覆盖可写,**各占一行**(他的原话"它是两个字段,就是两行,我单独去巡视它们")。
- 每列那一框**不是折叠块**:范围页再套一层折叠没有任何东西可省("数据面板不要搞太深了")。
- 行的格子引用改挂在 `RowWidgets`(`cells.userData`)上,不再按 `cells[childCount - 1]` 数——
加一列之后按位置数会把"标签"格当成数值格填。列表回收来的行控件如果格子数不对就**整条重造**(`EnsureWidgets`)。
- 每行末尾一个"删",表头每列一个"×",两者都占固定列宽(表头同一位置留空一格,否则列会错位)。
(**P14 起**行末按钮改写作 `-`,见 §23;固定列宽那条不变)
- 状态栏右侧是「图表」引用字段;`EnsureChart` 的提示语跟着改成"底部状态栏右侧"(说错位置比不说更坏)。
- 范围页的统计**只在这一页真的露出来时算**:中位数要排序,在表格页每敲一下格子就为看不见的一页扫一遍全表是白付的代价。
**21.4 面板**
- 「数据」框整块删除:记录/维度/版本/已丢弃的读数、追加一条、清空、以及每维一行的显示名/可见/覆盖范围——
全部进数据窗口。那些读数窗口状态栏里本来就有,两处各印一份迟早各说各话。
- 「基础」下只留一个按钮 `打开数据窗口` 加一句"数据的事都在窗口里",面板不再有第三层数据导航。
- §13 的层级/互斥判据不受影响(删掉的只是叶子块,互斥标记仍按"树上现算的最深层"打)。
**21.5 文本格式升到第 2 版**
- `XCHART-DATA 2` 的 DIM 行带 `覆盖标记(0/1) 覆盖标记(0/1) 最小值 最大值` 四个字段。
第 1 版只带两个数,靠"相等=没覆盖"表达"两端一起",**分侧覆盖带不走**——导出再导回来会把
"只钉最小"读成"两端都钉",于是那一端被静默冻住。
- 第 1 版仍**读得动**,但版本只能来自表头:两种布局字段含义不同,v1 的 `-3` 落在 v2 的标记位上会被读成"没钉"。
判据成对:v1 文件导入后两端仍是钉住的;v2 表头配 v1 的 7 字段行必须**报错**而不是静默少带一段覆盖。
- 顺手补两处门口:覆盖端点写 `NaN`/`Infinity` 直接拒;DIM 行字段数只接受 4 / 5 / 全套,"少一截"不再静默忽略。
后一条原本是个**真崩溃**:老代码用 `fields.Length >= 6` 做守卫却去读 `fields[6]`,一条被截断的 6 字段行会
`IndexOutOfRangeException`(探针以前只用 4 字段行测这条路,所以一直没撞)。
**21.6 两套下标:维度表的行号 与 值数组的下标**
写范围页时撞出来的另一件事:**"这一维"和"这一列"不是同一个号**。
- 维度表 `m_Dimensions` 一行=一列(键、种类、显示名、范围覆盖都在那一行上)。
- 每条记录的值数组只装**数值列**(`NumericDimensionCount` 个格子)。表里全是 Number 时两个号重合;
夹进一个 Label/Time 列(导入的文本、雷达那种带标签的维度都可能带)就**错开**。
三条规则收进一个纯函数文件 `Runtime/XChart/XChartColumnMath.cs`(`ValueCount` / `ValueSlot` /
`DefinitionOfValueSlot`),模型与窗口都调它:
- `XChartDataModel.NumericDimensionCount` = `ValueCount(表)`(原来自己数一遍)。
- `TryGetDimension(dimension)` / `TrySetDomainOverride(dimension, …)` 的入参是**值下标**——
与 `GetValueAt` / `TryGetAggregates` 同一个口径,因为工具绑的就是这一个数。
按表行号回答会在混合种类的表上把"第 1 维"答成 `tag` 那一列,于是钉住的范围落到一个工具根本不读的列上。
- `TryRemoveDimension(tableIndex)` 的入参是**表行号**(窗口"×"按钮就在那一列上),
它内部用 `ValueSlot` 决定要不要摘一格——非数值列返回 −1,本来就没有格要摘。
窗口的两处跟着改:**范围页一列一框**,标题同时印出两个号(`列 2 · Y(值下标 1)`;**P14 起收成 `Y [1]`**,见 §23),
非数值那一列印"这一列不占值格"并把两个勾选框禁掉;**表里的格子**记住自己对应的值下标
(`RowWidgets.Slots` 是这套分布的签名,行控件回收时签名不对就整条重造——只看列数的话,
换一张同列数、种类不同的图会把不可编辑的格子当成能改的)。
判据:`column maths:` 5 条(值下标 1 在 `[x, tag, y]` 上找到的是 `y`;不占值的行报 −1;
门用第二列自己的聚合解范围;钉第二列的最小端只动第二列;第一列不被第二列的钉影响),
配 4 支臂:值计数把非数值列也算进去、门按表行号答维度、表行号的"值下标"就是行号本身、
以及"每个值下标都答第一个数值列"。
`data cut:` 删行删列 7(含 Time 维夹在中间那条)、`column maths:` 下标口径 5、`data text:` 格式形状 4 + 往返 2 改写)。
`p4_control` **47** 支臂每支红在自己点名的断言上,本轮新增/改派 13 支:主开关的等值规则被删、门不读维度行、
解析器不走"没钉"分支、没钉的一端仍取手填值、无限聚合当可用、非有限覆盖值被收、删行没真删、
删列留着被删的那一格、值下标按维度表行号算、导出丢掉最大端标记、v1 文件按 v2 布局读、截断的 DIM 行被放行、
值计数把非数值列也算进去。门三臂(runtime / player / editor)绿;`p2_control`、`pool_family`、
`generator_gate`、`hierarchy_gate` 同轮复跑。
**判据的判据(本轮抓到的两条,属于同一族)**
1. **`Expect(label, cond, detail)` 的 detail 是无条件求值的。** 我在一条说明串里直接写了
`numericOnly.Records[0].Values.Count`——"值计数把非数值列也算进去"那支臂恰好让那张表的记录
**一条都没进去**(值个数与数值维个数对不上 ⇒ `TryAddRecord` 拒绝),于是取 `[0]` 当场抛
`ArgumentOutOfRangeException`:探针死掉,**既没有红也没有判**。mono 后面那段
"class libraries are out of sync" 是崩溃的余波,不是环境问题(同一份 dll 在别的臂上跑得好好的)。
⇒ 凡是碰 `Records[i]` 的判据都**先查条数**,说明串里用三目表达式兜住。
2. **"能红"不等于"红在该处"。** `every value slot answers with the first numeric column` 那支臂
让我原本点名的那条("钉第二列的最小端只动第二列")**碰巧过了**——两列都答同一列时,
"钉的那一列"和"解的那一列"错得一致,于是自洽。真正红的是"第一列不该被第二列的钉影响"那条。
⇒ 点名清单按实测改到能红的那条上;一支只红在"顺带后果"上的臂指认不出具体规则。
**证据链自己的一次事故(记在这里因为它影响"臂表可信吗"这个问题)**:`p4_control.py` 被一次
read-modify-write 的失败写入截成 0 字节(写入前先编码、编码抛异常 ⇒ 文件已被清空)。重建没有靠记忆重写,
而是按盘上的证据还原:`p4_p12.txt` 给出臂名与 `*.p4ctrlN.cs` 的对应关系,每份变异副本与**当前**源码逐行
diff 得到 (锚点, 替换),`p4_ctrlN.out.txt` 里那一轮真报红的断言名就是该臂的点名清单——所以清单是
**证据而不是记忆**。脚本:`.ximage-gate/rebuild_p4.py` + `install_p4.py`(候选文件先编译、每条锚点必须
在当前源码里命中恰好一次,全部通过才覆盖正式文件)。两处重建暴露的问题也顺手修了:相邻两行互换被
diff 拆成两组 ⇒ 锚点命中 4 次;FAIL 行的标签自己含冒号(`domain ownership: …`),按第一个冒号切会把
一整族断言压成一个词 ⇒ 改成拿探针里的断言名表做最长前缀匹配。
## 22. P13:立方体那几件搬进「工具」,格线只有一个作者(2026-10-25 他口述)
### 22.1 现场报的四条,逐条要对得上机制
1. 「显示网格线」勾选后网格线**反而消失**,不勾反而在;默认是"勾着 + 看得见"。
2. 保持它关闭,**再去操作别的**(转一转让表刷新)网格线又不见了/回来再点又显示出来——"总之有 bug"。
3. 「立方体外观」这一组还挂在 `基础` 下;而且面板说"另有脚本注册的工具 3 个"却**不说是哪三个**。
他的要求原话:既然是工具就要放在工具下面,chart 本身应该只留 `基础`。
4. 添加的 `Mesh BG` 元素里**填充面改了没作用**(Nothing/Everything 一模一样),网格面有效,
但它和图上那两个开关**互相冲突**,"逻辑上就很冲突,很割裂"。另外名字要改成描述性的
(`BG Cube Grid`),因为后面还有平面坐标系网格、雷达图网格、神经图谱网格。
### 22.2 根因:同一件事有两个作者
`ChartToolCubeBg`(线框)当年不只画 12 条棱,还画**面内格线**,并且把格线发布成
`mesh.face.<n>.grid.S/.T` 插槽;`ChartToolMeshBg` 也画格线、也发布**同一批 id**。两件事由此发生:
- 插槽板按 id 覆盖 ⇒ **谁后跑谁说了算**。轴线"跟随网格"跟的是最后发布那一家。
- 两家的条数算式不一样:线框那侧画 `i/(N-1)`(含两条边共 N 条),网格那侧画 `d/divisions` 的**内部线**
(N−1 条)。于是关掉一边,另一边把那批位置**用另一套条数**画回来 ⇒ 看上去就像复选框接反了(症状 1)。
- 图上还有一个 `m_ShowGridLines`(只管线框那半),元素上另有一份 `GridFaces` 掩码(只管网格那半)。
一个开关只能管半个作者,另一半在别的时机(刷新、重投影)亮回来 ⇒ 症状 2 的"状态会跳"。
- 面板上「基础 → 立方体外观」那组字段与元素表里那份配置**存的是同一件事**,两处各一份、
谁后灌谁赢 ⇒ 症状 3、以及症状 4 的"割裂"。
本项目里这类死法已经出现过好几轮,形状都一样:**两处存同一件事**。这轮的处置不是给某个开关补个取反,
而是把"谁画格线"这件事变成**结构上只有一个作者**。
### 22.3 现在的分工(一件渲染活只有一个作者)
| 元素(面板上的名字) | 画什么 | 发布什么插槽 | 手里有哪些旋钮 |
| --- | --- | --- | --- |
| `Space` | 不画 | — | 四元数、半边长、尺寸口径、中心偏移(**唯一投影权威**) |
| `BG Cube Wire` | 12 条棱(前向/后向两套色) | `mesh.face.<n>` 四角 | 前/后棱颜色、棱宽、显示后向棱 |
| `BG Cube Grid` | 面填充 + 面内格线(+可选面轮廓) | `mesh.face.<n>` 四角、`…grid.S/.T` | 填充面掩码与双色、网格面掩码、格线色/宽、分格数(统一 + S/T)、绑定的维度、只画可见面 |
| `ChartTool_ScatterPoints` | 点 | 刻度插槽 | 形状、大小、描边、颜色映射 |
三条硬约束:
- **线框没有"格线"这条代码路径**(字段、渲染器、发布全删了)。不是"默认关着",是**不写它就无法画**——
两个作者的形状从此表达不出来。
- 网格元素**画上去的线**用的就是**发布给轴线的那份比例数组**(`PublishGridSlots` 算完留在
`m_RatioScratchS/T`,`DrawGrid` 直接读),不再各按各的条数算第二遍。
- **"哪些面有格线"也只有一个判据**:发布侧与绘制侧共用 `DrawsGridOnFace(face)`
(掩码 ∧ 面帧有效 ∧(开了"只画可见面"时)朝向观察者)。此前发布是**六面全发**的,
于是掩码筛掉的面照样有插槽,轴线会去吸一条画面上一条都不存在的线——同一个病换到了插槽那一层。
等式现在由工具自己判:报表印 `faces=画上/发出`、`retracted=`(这一轮撤掉了几个面的格线插槽)与
`linesCheck=ok|DIFF drawn=… want=…`(期望值 = 发布的条数 + 描轮廓的面数 × 4;轮廓那 4 条只画不发)。
- **板子因此多了"撤下"这一面**(`IXChartSlotBoard.Unpublish(id)`):只有 <c>Publish</c>(同 id 覆盖)的话,
定义者说得出"这里的线换成这一批",却说不出"<b>这里不再有线</b>"——上一轮那批值会一直挂在板上被轴线吸走。
掩码筛掉的面、以及整个网格元素被 Dispose 时,都会把它发过的 12 个格线插槽撤干净
(**只撤自己发的**:`mesh.face.<n>` 那批四角是立方体本身的几何,线框元素也在发,动它就是拆别人的定义)。
空数组发布是拒的(组数必须为正,§11.2),所以"撤下"只能是一个显式动作而不是一次空写。
- 分格数按方向分(统一值 + S/T 各一份,0=跟随统一值),因为两条轴的刻度数通常不同;
等分时"沿 S 的线由 **T** 的分格数决定"(算式只在 `XChartGridDivisions` 里,探针钉着)。
### 22.4 渲染参数搬进元素表:预设自己声明默认元素
他给的方向是"chart 默认情况下就是个网格、纯数据,所有的渲染都是基于工具的;创建脚本时就该带上特定工具,
注册可以直接在配置里注册"。落法:
- `XChartBase.DeclareDefaultElements()`:派生类在这里声明"这张图默认带哪些元素"(规范意义上的**配置注册**)。
`XPseudo3DScatterChart` 在这里给出 `Space` / `BG Cube Wire` / `BG Cube Grid` 三件。
- `AddDefaultElement<T>()` **按类型去重**(`XChartElementTable.IndexOfKind`,纯函数、离线可验)。
图表初始化会跑很多遍(域重载、预制体开合、进 Play),不去重就是每遍多一个背景 ⇒ 格线画两遍、
边越描越粗,现象只会被描述成"图越来越糊"。
- 只在**第一次读到这张表**时补(`m_ElementsSeen` 标记):他把某个元素删掉就是意愿,之后不再自动补回来。
老场景的表里往往只有轴线/散点(立方体那几件当时还是图上的字段),第一次进来会把缺的补上——
否则这次改动就变成"升级完背景整块没了"。
- 图上那组「立方体外观」字段**删除**。`CubeHalfSize` / `Rotation` / `ApplyViewPreset` / `FrontEdgeColor` /
`GridDivisionsS` / `ShowGridLines` … 保留为**转发属性**:读写的是元素表里那份配置本身
(`ElementOf<XChartSpaceConfig>()` 等),写完立刻 `ReapplyElements() + ForceRefresh()`。
属性还在(外部脚本不必修),但**状态只有一份**了。元素被删掉时 getter 给中性值、setter 静默不做——
不抛,也不背着他造一个元素回来。
- `ShowGridLines` 的真身是 `BG Cube Grid` 的 `GridFaces` 掩码:开=六面都画,关=一面都不画。
只画后墙那种"部分面"直接用掩码,别再用布尔。
- 网格元素的默认值就是旧「立方体外观」的默认行为:不填面、六面都画格线但只画朝向观察者的那几面、
不描面轮廓(轮廓归线框那 12 条棱,描两遍只会让边变粗)。
**代价要说明白**:字段被删 ⇒ 场景/预制体里存过的那组立方体外观值会静默回到默认(Unity 按字段名恢复序列化)。
姿态、半边长、格线颜色要重拧一遍。这是"两处存同一件事"必须付的一次性账。
### 22.5 命名按"画的是什么几何",不按"是不是网格"
- 显示名:`MeshBg` → **`BG Cube Grid`**;线框元素的显示名 → **`BG Cube Wire`**。
- 注册 id:`cube-grid` / `cube-wire`(id 是稳定标识;这里是**新增**的 id,没有改名迁移问题)。
- 元素 `ElementName` 同时是 ToolsRoot 下的节点名与 `FindTool` 的配对键 ⇒ 面板行、层级树、报表行**三名一致**。
- 理由(他点名的):后面还有平面坐标系网格、雷达图网格、神经图谱网格,`Mesh/背景` 分不开它们;
名字要能并列:`BG Cube Grid` / 将来的 `BG Plane Grid` / `BG Radar Grid`。
### 22.6 面板:`基础` 只剩图自己,`工具` 把话说全
- `基础` 里不再出现任何渲染参数(那组字段没了,分组自然消失)。图=基本变换 + 颜色 + 数据 + 调试。
- 「工具」下**脚本注册的工具逐个点名**:`名字 · 类型 组=… 注册=… 绘制=…`,一行一个;
一个都没有时也说明是"没有"还是"工具管理器还没建"。只报数量等于没报(他 2026-10-25:
"你并没有显示出来这几个工具是什么东西?")。
- 轴线块里"与网格对齐"的提示语**当场从元素表里那份网格配置读** S/T 现值,位置写成
`工具 → <那块网格的元素名>`。写死"基础 → 立方体外观"不会报错,只会把人引到一个已经不存在的块上;
图里没有网格元素时明说"没有格线可对",而不是留一句空话。
- 预设(`XChartCreateMenu` 那几条右键菜单)不需要额外登记工具:组件第一次初始化就会补出默认元素,
所以"创建出来就带着特定工具"由 `DeclareDefaultElements` 保证,面板上立刻看得见、能改。
显示名这一处**故意与其余元素不同**(`轴线`/`散点`/`圆柱` 是中文,这两个是英文):
`ElementName` 同时是 ToolsRoot 下的节点名、`FindTool` 的配对键、以及报表里那一行的名字,
而他给的字面就是 `BG Cube Grid`(§22.1 第 4 条)。这两个名字进的是**层级与配对**,不是 TMP 文本,
所以不撞 §12.1 那条字形问题。
### 22.8 只有现场能判的(他侧验收清单)
报表开关:面板 `基础 → 调试 → 自述报表 开`,跑几帧后文件在项目根 `xchart.dump.txt`。
本轮每个元素自己那一行带上了分层的读数,症状不再需要靠"看起来像"来归因。
1. **面板形状**:`基础` 下再无「立方体外观」;`工具` 下出现 `Space` / `BG Cube Wire` / `BG Cube Grid` 三块
(散点图预设),以及「脚本注册的工具」一块**逐行列出**工具(散点图应当只点出 `ChartTool_ScatterPoints`)。
2. **网格开关不再反**:`BG Cube Grid → 网格面` 改成 `Nothing` ⇒ 线消失;改回 `Everything` ⇒ 线出现;
**然后**再转一下视角 / 灌一次数据 ⇒ 线**还在**(旧形状下这两步会把状态翻过去)。
这条是本轮的核心判据:开关只有一个作者之后,"再操作别的"没有第二个作者能把线画回来。
3. **线框不再抢格线**:`BG Cube Wire` 那块里**找不到**任何格线旋钮(不是"关着",是没有这一行)。
4. **报表等式**:`BG Cube Grid` 那一行自带判决 `linesCheck=ok`(红了会写 `DIFF drawn=… want=…`),
旁边 `faces=画上/发出` 两个数也应当相同;`lines=S/T` 是两族各自的条数,
`fillFaces=/gridFaces=` 印的是**掩码字母**(`a=前 b=后 c=上 d=下 e=左 f=右`,按面号升序;空集印 `-`,
例如"后墙三面"印 `bed`)。
5. **填充面**(本轮**没有结论**的一条,如实记着):他报"Nothing/Everything 都没作用"。
我从代码里找不到"必然看不见"的确定成因,只能保证下一轮报表能一句话定位在哪一层:
- `fillFaces=-` ⇒ 面板的值没落到工具上(传输那一层)
- `fillFaces=…` 有字母而 `filled=0` ⇒ 落到工具了但一面都没提交(面帧无效/被可见性筛掉)
- `filled=3 chunks=1 renderers=ok/ok` ⇒ 提交了,那么"看不见"就是**外观**那一层(颜色、alpha、被谁盖住)
- `renderers=fill-NULL/…` ⇒ 子物体根本没建出来
注意默认预设里 `填充面` 是 `Nothing`(旧图本来就没有面填充)——要看填充先把这块的掩码打开,
或者在 `工具 → Add` 里另加一块 `BG Cube Grid`。
6. **老场景的一次性代价**:图上那组「立方体外观」字段删了 ⇒ 存过的姿态/半边长/格线颜色回到默认,要重拧;
元素表里已有的配置不受影响。
### 22.7 判据与证据链(本轮新增的那些)
本轮新落下来的**纯逻辑**只有两小块,所以离线判据只钉这两小块;其余(谁画、谁盖谁、发没发出去)
都在 Unity 对象图上,只能靠元素自己印的读数判(见 22.8)。
- `face mask letters:` 5 条 —— 报表的证人词汇。空集印 `-` 而不是空串;六面印 `abfecd`
(**面号升序 × 语义字母**,不是 a..f);每面 `letter → face → mask → letter` 往返;不属于六面的位
不许凭空印出字母。"字母跟着内部枚举顺序漂"是这条判据要拦的那件事。
- `element table:` 6 条 —— 默认元素判重的唯一查找。空表/空类型答 −1 而不是抛;同类找自己那条;
**线框不算网格**(把两者认成同一类,先建的线框就会把网格挡在门外:格线整块没了、一句错都不报);
空槽跳过而不是命中;基类匹配任何元素;同类两条时第一条是权威。
- `slot board:` 5 条(新增)—— `Unpublish` 撤得掉、撤完读方拒绝、真空撤不动(返回 false 且不推版本)、
撤后还能重新发、"发空数组"仍然是拒的(所以"这里不再有线"只有 `Unpublish` 一个说法)。
- 等式类判据(`linesCheck=`、`faces=画上/发出`、`retracted=`)**由被测元素自己印**,
不写在文档里等人手算(§21 那条"文档里的数字门槛要有产出判决的读数器")。
**本轮终态读数**(都对着一棵跑完就再没动过的树;`gate` 与探针在套件收口后又复跑一次确认):
编译门三臂(runtime / player / editor)绿 + 3 支对照各红在指名的错上;离线探针 **424** 项 **0** 失败;
`p4_control` **52** 支臂每支红在自己点名的断言上(本轮新增 5 支:空槽算命中、字母跟着枚举序漂、
报表读裸位、插槽撤不掉、撤下不算变更);`p2_control` 4 臂、`pool_family`、`generator_gate` 2 变异、
`hierarchy_gate` 5 变异同轮复跑。产物:`.ximage-gate/` 下 `gate_p13final.txt`、`probe_p13final.txt`、
`p4_p13full.txt`、`chain_p13full.txt`(每套一个 rc 行)。
**我这一轮自己踩的两处,如实记在这里**:
1. 六面的字母串我手打成 `afecd`(漏了 `b`),是离线探针当轮就红的——又一次"手打的格式常量必须有
对着真数据的断言",不是我先想对了再写测试。
2. `retracting what is not there` 那条我拿"整段开始前的版本"当基线,中间那次 `Publish` 自己就把版本推了
⇒ 判据恒红。**基线要贴着被测动作取**,否则量到的是自己前面那几步。
——同一轮里这个错我**连犯两次**:改完第一条的基线之后,新加的"真撤才推版本"那条还是拿
`board2.Version` 在 `Publish` 之前取的,于是那支臂"红 0 条"、`CONTROL FAILED`。
一条规则我只在挨打的时候才认,下一次写判据时它并不会自己长回来 ⇒ 规则要写在取基线那一行旁边。
3. 两支新臂第一次根本没编译:`(mask & (1 << i))` —— 枚举与 `int` 不能相与(CS0019)。
`SETUP FAILED: mutated runtime did not compile` 与 `did not go red` 是两种**不同的自证失败**,
两种都不许被"其余 49 支都红了"掩盖;前者还额外说明一件事:变异体没编译 ⇒ 它压根没判过任何东西。
另有一条流程账:这轮三次启动长套件、三次中途发现还要改代码(P13b 的过滤、`FirstOfKind`、`Unpublish`),
每次都**当场停掉重跑**而不是让它跑完拿一份"树已经不是那棵树"的绿。停三次比留一份过期证据便宜。
**第四次是反向的**:定版那一跑已经在跑,我顺手改了一段注释(`PushCubeLook` 的 doc 摆错位置),
改完立刻意识到"注释也是树"⇒ 当场按逆操作还原,并把这件事留在这里——该文件不是任何臂的锚点,
行为也没有任何一路经过它,但"这一跑描述的是哪棵树"这个问题我不能替自己回答。
⇒ 规矩补一条:**跑起来了就一个字都不动**,包括看起来人畜无害的注释;实在想改就写进下一条任务。
## 23. P14:数据窗口的界面收敛(2026-10-25 他现场三条)
他对着窗口截图点的三条,都是"界面上话太多、而话多的地方还压掉了该看的行":
1. **行末删除按钮**:`删` → **`-`**(固定列宽那套不变;表头同一位置仍留空一格)。
2. **范围页的号**:`列 2 · Y(值下标 1)` → **`Y [1]`**。行的**位置**已经是表里的列号,
括号里再报一遍号只是把同一件事说两次;`[n]` 就是工具真正使用的那个数。
不占值格的列印 `tag [-]` +一行 `不占值格`。统计行去掉 `统计:` 前缀;
生效行不再复述"哪一端被钉住"(**下面那两个勾自己就是读数**)。
状态栏的回执从"我改了什么"改成**结果**:`Y [1] 生效 -100 .. 100`。
3. **说明文字退回 tooltip**:`kListHint` / `kRangeHint` 都只浮着不占界面。范围页那段可见的长说明删掉,
其中"这正是“原点必须留在 0”那类要求的做法"这类句子**是开发时我们俩的对话,不是界面文案**——
它对着当时的我,不对着下一次打开这个窗口的他。要么写成一句操作帮助(tip),要么就别写。
**第一列挤成一行的真机制**:不是"少写了一行",是**那一整页的容器允许收缩**。
UI Toolkit 里 `flexShrink` 默认为 1,窗口矮了,被压扁的就是**最上面那一行**——三行的框塌成两行、
文字叠着画;后面几列因为剩余空间够才看起来正常(所以他看到的是"只有第一列坏了")。
⇒ 修法是从 `ScrollView.contentContainer` → body → 每列的框 → 框里每一行**整条链 `flexShrink = 0`**,
标签一律 `NoWrap`:装不下宁可截断,也不许和邻行叠在一起。表头那一行同样补 `flexShrink = 0`
(它被压一次就会整表错位)。
**判据与账**:编译门三臂绿(编辑器程序集里 `XChartDataWindow.cs` 是点名源,"门绿"包含它编过了)。
但这三条**全是观感,离线判不了**(引擎 mono 造不出真 `VisualElement`,§13.2 那条实测仍然成立)
⇒ 布局是否真的不再叠行、文案是否够短,**归他现场判**;P14 没有任何一条绿可以替"界面已经对"说话。
## 24. P15:元素块收成一行状态;默认元素让不让删(2026-10-25 他给的格式)
### 24.1 一行状态:`▼ √ Cylinder (R1, D4) [↑][↓][-]`
- 落法:新增 `MakeHeaderRow` 把那块折叠板的 `Foldout` 搬进一个横排行,右边依次是
**√**(写 `m_Enabled`)、**R**、**D** 两个格子、`↑` `↓` `-` 三个动作键(一个字符,中文说明进 tooltip)。
Body 里原来那一行「启用 / 注册序 / 绘制序 / 上移 / 下移 / 删除」**整行删掉** ⇒ 同一个写入口只有一处。
- **"注册序/绘制序的字段我在界面上没看到"的原因**:控件一直都在,只是它们在**折叠着的 Body 里**
(面板默认全折叠,§13)。所以这不是"没做",是"做了但放在看不见的地方"——这一类要按位置查,不按存在查。
- ~~**R/D 用可编辑格子**~~ **→ 改成文本读数**(2026-10-25 他第二轮澄清,见 §24.5):
第一版我做成了两个窄输入框,他当场否掉——**他根本不想设这两个序号**(注册序是类型定好的、
绘制序跟位置走)。顺带两个现场依据:输入框会露出拖拽光标("露馅"),而且窄到数字都看不见。
文本读数要**就地刷新**(面板树在值变化时不重建,静态文本会停在旧值上——"改了没反应"的又一种形状),
这一条由 `RefreshOrderReadouts` 负责。
- **顺手拆掉一个藏着的第二入口**:`m_Enabled` / `m_OrderIndex` / `m_DrawOrder` 是基类字段、没有 `[Header]`,
`AppendHeaderGroups` 会把它们整组塞进元素 Body 的「其它」里 ⇒ 标题行有了 √ R D 之后,同一个写入口
就出现两次。现在这三个名字在元素分组时被跳过(与 `m_SlotId` 同一条规矩:同一件事不做两个入口)。
**P17 追加**:`m_OrderIndex`/`m_DrawOrder` 也不再在 Body 里留输入控件(§24.5 的政策)。
### 24.2 默认元素(`Space` / `BG Cube Wire` / `BG Cube Grid`)**让删,也让关**
删掉就是"这张图我不要它",那是他的意愿,面板不该拦(同 §22.4:预设只在第一次读到这张表时补齐缺的那几件,
之后不再自动补回来)。三个各删掉会怎样,逐条说清,不留"删了会怎样?"这种没答案的格子:
| 删 / 停用 | 结果 | 为什么不会连锁 |
| --- | --- | --- |
| `BG Cube Wire` | 没有 12 条棱 | 面四角仍由网格元素发布 ⇒ 轴线照旧有宿主面 |
| `BG Cube Grid` | 没有填充、没有格线 | 面四角由线框发布 ⇒ 轴线照旧;`AlignToGrid` 回落,报表 `align=` 说原因 |
| `Space` | 回到默认姿态 | 见 24.3:不变量补全之后,删掉它不等于图没了 |
⇒ `[-]` 与 `√` 对**每一个**元素都保持可用,不做"某几行不许删/不许关"的特例;他问的"如果不能删就把 `-` 禁用掉"
这一支因此不落地,理由就写在 `-` 的 tooltip 里。
### 24.3 顺带补全一条不变量:`EnsureSpace()` 现在**每次重建后**都跑
它原来只在初始化那一次跑。把「空间(基变换)」删掉或停用之后,表里没有空间元素、也没人再补一个
⇒ 投影权威为 null,线框/网格/散点全部不画,现象是**"整张图突然空了"**——而这只是点了一下"删"。
补上之后:删掉空间元素=回到默认姿态继续画(旋钮没了,重新 Add 一条 `空间(基变换)` 就回来)。
这条**离线判不了**(要真 `GameObject` + `ToolManager`),判法归现场:删掉或停用 `Space` 那一行 ⇒ 图还在。
### 24.4 判据与账
编译门三臂绿(`XChartBaseEditor.cs`/`XChartDataWindow.cs` 都在点名源里);`hierarchy_gate` 5 变异臂绿
——层级是沿 `Box` 往上认父级的,把 `Foldout` 搬进横排行不动它的身份(key 仍钉在盒子根上)。
`p4_control` / `p2_control` / `pool_family` / `generator_gate` 在**这棵交付树**上复跑,终态补记在下面。
**界面那一层照例离线判不了**(mono 造不出真 `VisualElement`,§13.2)⇒ 一行排不排得下、
窄格子能不能改数,归他现场判。
### 24.5 序号的政策:注册序**只读**,绘制序**跟着位置走**(2026-10-25 他第二轮澄清)
他原话(意译后按代码语言记档):**"我根本不想给它设置这两个序号"**——
- **注册序**:由**类型**定好的(定义几何的那一类天然靠前,数据呈现那一类天然靠后)。
它对人只在"看"的意义上存在:面板**只显示、不可编辑**。用户手填注册序没有意义,
写错了还会把"谁先算"这件事弄乱;所以它不进任何输入控件。
- **绘制序**:**绑定元素在表里的位置**——调上移/下移不仅仅是改层级顺序,**它就是改绘制顺序**。
于是不再有第二个手填的绘制序号,也就不存在"位置和序号各说一套"。
⇒ 落法(面板侧):标题行上的 `R… D…` 是**文本读数**(他第一轮就是这么要求的,我第一轮理解成输入框,
错了);`m_OrderIndex` 在面板上**不再出现输入控件**(从"其它"组里跳过,原因见 24.1 那条备注);
`m_DrawOrder` 同样不出现——上移/下移按钮直接把它写进去,面板只把结果印成 `D…`。
**为什么这比"可编辑"更强**:序号一旦能手填,就会出现两条口径(位置 vs 数字)指向不同的事实,
"上移之后绘制顺序到底变没变"这个问题就没人回答得了。绑定之后**位置是唯一权威**。
**落法(代码侧,2026-10-25 同日)**:面板的 `AfterStructureChange()` 里调 `RenumberDrawOrder()`——
任何结构变化(上移/下移/加/删)之后把表内每个元素的 `m_DrawOrder` 重写成它的位置(0,1,2…)。
于是"位置更靠后=绘得更晚=盖在上面"。面板上 `R… D…` 只是这两个数的**读数**(`RefreshOrderReadouts` 就地刷新)。
**终态(2026-10-25,交付树上复跑那一跑)**:`p4_control` **52/52** 支臂各红在自己点名的断言上;
探针 **424** 项 **0** 失败;`p2_control` 4 臂、`pool_family`、`generator_gate` 2 变异、`hierarchy_gate` 5 变异全绿;
编译门三臂 + 3 支对照绿。产物:`.ximage-gate/` 下 `gate_p15b.txt`、`probe_p15.txt`、`p4_p15.txt`、
`chain_p15.txt`(每套一个 `*VERDICT rc=` 行)。
**注意这份绿覆盖的是什么**:它覆盖的是**算术与协议那一层**(`EnsureSpace` 那条不变量在不在,
它一句都看不见)——那条只有现场"删掉 Space 那一行,图还在不在"能判。
**覆盖范围要说准**(这一轮收口后又动过一次文件):52 支臂 / 探针 / p2 / family / generator / hierarchy
那一次复跑覆盖的是"标题行 + `EnsureSpace`"那棵树;之后为拆掉「其它」里的第二入口又改了一次
`XChartBaseEditor.cs`,改完**编译门三臂 + 探针 424 项**再跑一次绿(`gate_p15c.txt`、`probe_p15b.txt`)。
那六套为什么不必再跑:逐脚本查过,`XChartBaseEditor` 这个文件名只出现在 `run_gate.py` 的点名源里,
其余套件一个都不读它(`grep` 结果:`run_gate.py` 与一条早已不用的 `ui_locale_panel.py`)。
⇒ 报"全绿"时必须同时报**哪一份绿是哪棵树**,不然一句"全绿"就把两次改动混成一次了。
## 25. P17:矢量场(箭头)——数据口径(**2026-10-25 他澄清后定稿**)、相对/绝对、连续绘制、颜色
> **口径修正(同一天,先听他澄清)**:本节初版把矢量场写成"一条记录装两组三维(6 维)",那是照着
> 旧实现/旧文档推的,**不对**。他给的正确口径是:**三维就是坐标本身(跟圆柱一样用 x/y/z),
> 一支箭头由相邻两条记录构成;颜色接在第 4~7 维**。代码随后按这一版改(改前它仍按旧口径跑)。
### 25.1 现场:加了箭头一条都不画,根因是"形状不够时静默返回"
他加了「向量箭头」元素、数据也在,一条都没出现。原因是一行判断:
`if (NumericDimensionCount < OriginDimension + 6) return;`——算完 0 支、提交 0 个面,
画面上与"工具没注册 / 空间是 null / 渲染器没建"**完全同形**,报表里也只是几个 0。
⇒ 处置不是改那行判断,而是**让这件事说得出来**:
- 元素配置报出自己的需求(`RequiredNumericDimensions`),面板印一对数:
`需要 N 个数值维,表现在有 M 个 ⇒ 一条都不画(报表里 dims=N/M)`;
- 报表里该元素自己印 `dims=有/需要 arrows=算了几支 mode=… colors=…`。
- 需求由**元素自己的配置**报,面板不写特例——下一个元素不用再写一遍,两边也不会分叉。
### 25.2 数据口径(定稿)
一条记录 **7 个数值维**,前三维与圆柱同义:
| 维 | 含义 | 必填 |
| --- | --- | --- |
| 0,1,2 | **坐标 x/y/z**(立方体单位,与圆柱、散点同一套归一化) | 是 |
| 3,4,5 | **颜色**:色相(**0..256 色环**)、饱和度(0..1)、明度(0..1) | 否 |
| 6 | **不透明度**(0..1) | 否 |
**一支箭头 = 相邻两条记录**(第 i 条与第 i+1 条)。他原话:"我们是 0 和 1,一个代表坐标,
一个代表它的矢量的方向"——即两条记录一组,而不是一条记录里塞两组三维。
- 为什么相邻而不是像圆柱那样"严格不重叠分组":圆柱要的是**一段一段的杆**(组与组不共享端点),
矢量场要看的是**相邻两点之间的关系**(首尾相接才连得起来)。
- 颜色是**每条记录自带**的 ⇒ 一支箭头的起点色与终点色可以不同(沿杆渐变)。
这是他说"两个分量都可以独立设置颜色,从而组成七维信息"的落点。
### 25.3 两种读法:相对 / 绝对
| 读法 | 第二条记录怎么用 | 算式 | 螺旋数据画出来 |
| --- | --- | --- | --- |
| `Absolute`(默认) | 它的**坐标**当作方向矢量 | 起点 + 方向×倍率 | 每根朝"下一点的坐标方向"散开=一片**刺猬** |
| `Relative` | 它是**第二个点** | 起点 + (第二点−起点)×倍率 | 一串**首尾相接**、顺着螺旋转 |
算式收进纯算术 `XChartVectorFieldMath.Tip(mode, first, second, scale)`,离线探针钉住
(含"同一份数据两种读法必须给不同的末端"——这条要能红,否则两种读法等于同一种)。
### 25.4 连续绘制,以及"勾一个、藏一片"
`Continuous`:把每条记录的坐标**按顺序连成折线**(只有最后一段带箭头)。
这时"相对/绝对"没有意义——连起来的本来就是空间里的一条路径 ⇒ 面板上那两个选项**隐藏**。
互斥显示的判据写在配置自己身上(`XChartElementConfig.IsFieldHidden(fieldName)`),
面板只负责"照着藏/放"。**藏而不是不建**:面板树在值变化时不重建,勾回来必须立刻可见。
### 25.5 颜色(可选维)
第 4~7 维 `[色相, 饱和度, 明度, 不透明度]`:
- 色相走 **0..256 的色环**(256 与 0 同色,128 是半圈);其余三个按 0..1 夹住。
- **不透明度那一维不算硬需求**:多给就多读、没给退回单色 alpha。算进门槛的话,
勾一下"有不透明度"会让整个元素因维数不够突然消失——那是一个开关变成了总闸。
- 不是有限数**门口就拒**(退回单色,不画成黑):NaN 经取模 + HSV 换算会变成一块"看着像黑"的东西,
那是我们替数据编的颜色。
- 换算**自己写**(`HsvToRgb`)而不是调 `Color.HSVToRGB`:后者是引擎侧静态调用,离线探针跑不起来,
而这条换算正是要离线钉住的。
### 25.6 示例数据("点一下就能看到东西")
测试数据 `螺旋矢量场`:一圈正弦/余弦点,每条记录 7 维(坐标 + 色相 0→256 走满一圈 + 饱和度/明度 1)。
**它自己会把列补到 7 个**——测试数据的判据是"能用",不是"提示他先去加四列"。
### 25.7 判据与账(初版实现随 25 小节口径一起改)
- 探针:`vector field` / `vector field colour` 一族(末端算式、两种读法必须分开、色环 0..256、门口拒 NaN,
以及**支数** `ArrowCount`:N 条记录 N−1 支、上限裁剪、0/1 条记录⇒0 支)。
- `p4_control`:新增五支臂(相对被读成绝对、色环按 0..1 读、颜色门口放 NaN 进来、
一对不再花两条记录、空表不挡而直接进算术)各红在点名断言上。
- 编译门三臂绿;`p2` / `family` / `generator_gate` / `hierarchy_gate` 在交付树上复跑。
- **终态(2026-10-25,口径修正后的交付树那一跑)**:探针 **439** 项 **0** 失败;`p4_control` **57/57** 支臂
各红在自己点名的断言上;`p2_control` 4 臂 / `pool_family` / `generator_gate` 2 变异 /
`hierarchy_gate` 5 变异全绿;编译门三臂 + 3 支对照绿。产物:`.ximage-gate/chain_p17fix.txt`(每套一行 rc)。
- **覆盖不到什么**:箭头在画面上长什么样、两种读法看起来是不是"刺猬/首尾相接"、互斥那一项藏没藏对——
离线一条都判不了(mono 造不出真 `VisualElement`,§13.2),归他现场判。
**判据的判据(本轮第三次同类现形)**:我给"一对不再花两条记录"那支臂点名的清单里放了两条,
其中"一条记录⇒0 支"这条**在这支变异体下根本碰不到**——它被更前面的 `recordCount < 2` 守卫挡住了,
于是 `did not go red` 当场把这条假点名抓了出来。⇒ 规矩不变:**点名清单按实测改**;
给每条判据配**它自己那支**变异体(这次补了"空表不挡而直接进算术"那一支专门管零/一条记录)。
### 25.8 他侧验收(Ctrl+R 后)
1. `工具 → Add → 向量箭头`,数据窗口 `测试 → 螺旋矢量场`:立刻看到箭头。
2. 切 `相对 / 绝对`:一幅"刺猬"、一幅首尾相接的旋转链。
3. 勾 `连续绘制`:`相对/绝对`那一项**消失**,图上变成一条折线(末端一个箭头);取消勾选 ⇒ 回来。
4. 打开颜色维:颜色取自色环;起点色与终点色不同时沿杆渐变(见 25.2 的颜色归属)。
### 25.9 还没做的(如实点名)
- **曲线渲染器**:现在是直线段(他给的默认)。库里那个带矢量标签的曲线渲染器 + "箭头位置可调"
排下一轮(`UICurveRenderer`,注意 §10.4:整条一次提交,别逐段 `DrawLine`)。
- **两端各自颜色**的渲染侧支持:**现在杆用起点色、头用终点色**(读第 i 与第 i+1 两条记录各自的颜色维)
⇒ 两条记录颜色不同时,一支箭头上就能看到两种颜色。真正的"沿杆逐顶点渐变"要等填充渲染器支持
逐顶点双色(P18,模板已有"径向渐变"那一档可参照)。