包

包是一个领域的可复用能力，带有稳定接口。仓库 packages/ 下有 19 个标准包，每个都有 README 和自己的测试。

包的结构

image.entpkg/
├── package.esn      // 包名与所需的最低 language/IR 版本
├── kernels/         // 包 use 的 Kernel 与函数（kernels/<topic>.ent）
├── graphs/          // 场景可作为子图放置的预设（graphs/<product>.esn）
├── data/  assets/   // 按需：数据表与资源文件
├── tests/           // <topic>.esn + <topic>.replay，在每个后端上运行
└── README.md

场景、示例或其他包总是整体使用一个包——use "…/name.entpkg";——而不是包里的某个文件，这样清单中的版本约束才成立。预设、数据表和资源按包内路径引用：

use "../../packages/image.entpkg";
node soft: graph "../../packages/image.entpkg/graphs/blur.esn" { ... }
input font: Grid<Float> = "text.entpkg/assets/font.png";

或者在 ENTELECHY_PACKAGES 列出包所在目录时按名字引用：

ENTELECHY_PACKAGES=/path/to/entelechy/packages entelechy run scene.esn

use "image.entpkg";

一个场景只能使用某个名字的一个包：同一包的两个版本会被拒绝，并指出两者。

四层词汇

包用函数、Kernel、图预设和数据说话。（docs/DECISIONS.md）

1. 函数：在 Kernel 内部、对一个元素组合。凡是能只就一个元素说的，先写成函数。
2. Kernel：只有当工作不能是单个元素的（读取邻居、上一帧、另一种尺寸，或场景要单独放置的一遍）时才是 Graph 的节点；其主体调用包的函数。
3. 图预设（graphs/*.esn）：包推荐的组合方式——一份配方，不是接口。场景可以用自己的节点替换其中任何部分。
4. 数据：以行表示的外观或设置（Grade、Film、Dof），由节点产生、由 Graph 传递。

包不持有人的输入（那是 controls 的事），不在两种外观之间切换，不包含只属于某个程序的内容。

标准包

包	领域	Kernel	函数	预设
animation	骨骼、驱动它的动画片段与跟随的网格：片段采样与混合、行走、瞄准、蒙皮。	10	4	1
audio	声音的基本单元：每帧一块立体声采样；时钟、事件触发、噪声、音调、包络、滤波与延迟线。	7	35	0
controls	读取人的操作：键盘、鼠标、手柄统一映射为游戏动作，以及指针；唯一读取输入的包。	5	15	0
geometry	四元数旋转与刚体变换矩阵、相机矩阵、曲线、有符号距离场（SDF）及其组合、空间扭曲。	0	70	0
image	对图片的处理：色彩空间、混合与遮罩、对比、滤波、色调曲线、缩放锐化、抗锯齿、直方图、距离场、mipmap、像素画。	39	52	10
mesh	三角网格（点与面两排数据）：圆环、球、平面网格，中点细分，等值面提取。	11	13	2
music	音乐词汇：音阶与和弦、音高、乐器音符（音色、包络、颤音、合唱）。	0	27	0
navigation	网格上的寻路：按代价逐遍松弛的距离场，以及朝目标走的下一步。	1	6	0
parallel	其他包依赖的数据并行算法：整数键稳定排序、压缩、按所有者布局、连通分量。	16	2	6
physics	平面上的刚体圆与盒子：下落、碰撞、静止、滑动、弹跳；网格宽相与子步求解。	23	42	2
random	可重复的随机：整数哈希（各后端位级一致）、值噪声、梯度噪声、分形、细胞、旋度噪声、正态分布等。	0	24	0
raster	三角形光栅化：在各后端上一致绘制，支持分块、遮罩与半透明；native.rasterize 是它的快速路径。	17	19	10
signal	复数快速傅里叶变换（FFT），每行最长 256，按组在 lane 中原地蝶形运算。	4	5	4
terrain	网格高度场地形：平滑表面、法线、射线求交、天空可见度、侵蚀、生成网格。	3	7	0
text	文字：字形排版与绘制、文本解码、字体图集、数字格式化、模板填充、写文件。	20	26	5
texture	表面着色用的纹理函数：图案、映射方式、图层与法线。	0	21	0
ui	逐像素绘制的界面：矩形布局、形状、文字，以及由 controls 驱动的列表导航。	3	63	0
vector	矢量图形逐像素填充：从 SVG 导入的形状、填充规则、颜料与渐变。	15	23	2
voxel	体素世界的光线步进渲染：体素盒、阳光着色、形状数据、按关节摆姿态的身体。	4	21	0

geometry、music、random、texture 只提供函数（在 Kernel 内调用），没有 Kernel。每个包的 Kernel、函数、类型、预设和测试见类参考 · 包。

打包与查看

entelechy package packages/image.entpkg     # 打印包的内容
entelechy pack packages/image.entpkg        # 打成单个 .entpkg 文件
entelechy unpack image.entpkg image2.entpkg # 重新展开到新目录

编写包的规范

摘自 packages/README.md，由 cargo xtask packages 检查（cargo xtask verify 会运行它）：

• 命名：一个小写英文名词表示领域（image、raster、physics），不用动词、缩写或 utils。项目自己的包用两个以上的词（game_music），避免与标准包冲突。
• 分层：包只使用同层或更低层的包，两个包不能互相使用。
• Kernel id 以包名开头并说明它做什么：raster.cover@4、parallel.sort_place@1、image.blur@1。
• 名字：函数用 snake_case 动词或名词短语，struct/type 用 PascalCase；所有包中没有重复声明的名字。冲突时用 random::fbm2 限定。
• 拼写：美式英语（color、center、gray）。
• 测试：tests/<topic>.esn + <topic>.replay，必须覆盖包声明的每个 Kernel，使包可以单独被证明。
• 准入：一个词只有在探针（probe）发现它缺失时才进入包。