Packages

A package is a domain of reusable capability with a stable interface. The repository’s packages/ holds 19 standard packages, each with a README and its own tests.

Layout

image.entpkg/
├── package.esn      // its name and the least language and IR it needs
├── kernels/         // the Kernels and functions it uses (kernels/<topic>.ent)
├── graphs/          // presets a scene places as sub-graphs (graphs/<product>.esn)
├── data/  assets/   // as needed: tables and files
├── tests/           // <topic>.esn + <topic>.replay, run on every backend
└── README.md

A scene, example or package uses a package whole — use "…/name.entpkg"; — never a file inside it, so the manifest’s versions hold. A preset, table or asset is reached by its path inside:

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

or by name, when ENTELECHY_PACKAGES lists the directory it is in:

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

use "image.entpkg";

A scene reaches one package of a name: two editions of one are refused, naming both.

Four layers of words

A package speaks in functions, Kernels, graph presets and data. (docs/DECISIONS.md)

1. A function composes inside a Kernel, on one element. Whatever can be said of one element alone is said as a function first.
2. A Kernel is a node of the Graph only where its work cannot be one element’s (its neighbors, the last frame, another size, a pass a scene places on its own); its body calls the package’s functions.
3. A graph preset (graphs/*.esn) is a way the package recommends to compose its Kernels — a recipe, not an interface. A scene replaces any part with its own node.
4. Data is a look or setting as rows (Grade, Film, Dof), made by a node and carried by the Graph.

A package holds no person’s input (that is controls’), no switch between two looks, and no content one program alone holds.

The standard packages

Package	Domain	Kernels	Functions	Presets
animation	A skeleton, the clips that pose it and the mesh that follows: sampling and blending clips, walking, aiming, and skinning by the joint palette.	10	4	1
audio	Sound’s atoms, a block of stereo samples a frame: the clock, the cues a program’s events set going, noise, a tone and an envelope, and the filters and delay…	7	35	0
controls	What a person’s hands do, read for a program, and the one package that reads them: a game’s actions from the keyboard, the mouse and a pad alike, from a table…	5	15	0
geometry	Rotations as quaternions and rigid transforms as matrices; a camera’s matrices and the ways between the world, clip space and the picture; curves through…	0	70	0
image	What Entelechy does to a picture, knowing nothing of the world it shows: color spaces, blending and masks, two pictures compared, filters, tone and its curves,…	39	52	10
mesh	Triangle meshes as two rows, points and faces: lattices that make the torus, the sphere and the plane, midpoint subdivision, and the surface where a field…	11	13	2
music	Music’s words, not a program’s music: scales and chords (the modes and the semitones of their degrees, a note’s pitch, the chords stacked on a degree), an…	0	27	0
navigation	Ways over a grid: how far each cell is from a seed by what each costs to enter, relaxed a pass at a time, and the step a walk takes toward it.	1	6	0
parallel	The data-parallel algorithms other packages build on: a stable sort of integer keys, the compaction of flagged rows, runs of entries laid out by owner, and the…	16	2	6
physics	Rigid circles and boxes in the plane that fall, collide, rest, slide and bounce: pairs found through a grid, manifolds solved all at once over substeps.	23	42	2
random	Randomness a Kernel can repeat: hashes of whole numbers, the same bits on every backend, the value, gradient, fractal, cellular and curl noise built on them,…	0	24	0
raster	Triangles turned into the surface a camera sees, drawn alike on every backend: plain, tiled and through a cutout mask; and translucent triangles over it, in…	17	19	10
signal	Fast Fourier transforms of complex numbers in rows 1 << bits long (at most 256), each row a group of lanes running every round of butterflies in place: rows…	4	5	4
terrain	Ground as heights on a grid of cells: read back as a smooth surface, its normal, where a ray first meets it (crossing blocks it passes over) and how open the…	3	7	0
text	Text: glyph rows laid out and drawn from a program’s font atlas, text decoded into rows of letters, the wide glyphs a project’s words use drawn into an atlas,…	20	26	5
texture	What a surface is drawn with, point by point as a shader asks: patterns, the ways a pattern is laid on a surface, layers and normals. Each is a function a…	0	21	0
ui	A screen drawn per pixel: rectangles laid out, shapes painted, text written, and navigation through a list by the hands controls reads. What a program’s…	3	63	0
vector	Drawings filled pixel by pixel: the shapes entelechy import reads from SVG, their fill rules, paints and gradients, drawn whole or tiled.	15	23	2
voxel	Worlds of voxels drawn by walking rays through them: boxes of voxels placed in the world, a place shaded from the sun, shapes as data, and bodies posed by…	4	21	0

geometry, music, random and texture offer functions only (called inside a Kernel), no Kernels. Every package’s Kernels, functions, types, presets and tests are in Class reference · Packages.

Packing and inspecting

entelechy package packages/image.entpkg     # print what it holds
entelechy pack packages/image.entpkg        # carry it as one .entpkg file
entelechy unpack image.entpkg image2.entpkg # open it again into a new directory

Rules for a package

From packages/README.md, held by cargo xtask packages (run by cargo xtask verify):

• Name: one lower-case English noun naming its domain (image, raster, physics); no verbs, abbreviations or utils. A project’s own packages take two words or more (game_music) so they never meet these.
• Layer: a package uses packages of its own layer or below, and no two use each other.
• Kernel ids begin with the package’s name and say what they make: raster.cover@4, parallel.sort_place@1, image.blur@1.
• Names: functions snake_case verbs or noun phrases, structs and types PascalCase; no name declared twice among all packages. Qualify on a clash: random::fbm2.
• Spelling: American English (color, center, gray).
• Tests: tests/<topic>.esn + <topic>.replay, reaching every Kernel the package declares, so a package carried alone is proved alone.
• Entry: a word enters only when a probe finds it missing.