Gallery

Kiln’s examples live in examples/: a showcase of the whole API, six original scenes, a stress scene, nine ported sketches, seven sound examples, and nine remixes (on their own page). Every one runs with

uv run python examples/<name>.py

and takes --frames N to render N frames and exit. The pictures and videos below were rendered with kiln.testing.render_frames on a pinned clock, with scripted mouse and keys, so they are reproducible. Set KILN_BACKGROUND=1 to run an example without it stealing focus from your terminal.

Showcase

A dark window of twenty panels in a five by four grid: primitives and rect modes, colour, blend modes, transforms, style scopes, winding rules, curves, bulk draws, noise, math helpers, input events, images, an Fbo, a shader, a mesh, TrueType text, a GUI panel tuning a rose, instanced arrows in orbit, GPGPU particles and a flock grazing moss with its predator; under them a wide sound panel with a step sequencer and a spectrum.

The whole of examples/showcase.py in one window: twenty panels and a sound row, one for each part of the API.

examples/showcase.py is Kiln’s own feature map: one live window with twenty panels and a sound row, and every name in the API appears in one of them. Each panel reacts to the mouse while it is over it, and this picture, rendered at pixel ratio 2, was taken after a scripted visit (a click on the style panel, a scroll, a sweep over the text panel, two drags on the GUI panel’s sliders, a drag and a circle over the Fbo, a click on the sound panel). When a feature lands in Kiln, it gets a place here too: the grid is worked out from the number of panels, so it grows to fit.

Panel Shows Learn more
01 primitives circles, ellipses, rectangles, triangles, fill, stroke and lines; RectMode.CORNER and CENTER Shapes
02 color fill, stroke and tint, HSB, hex, named colours Color
03 blend modes the six Blend modes over a two-tone ground Blending and trails
04 transforms with transform(), rotate, scale, shear, a fractal tree Transforms
05 style scopes with style() and style() (click it) Transforms
06 shapes and winding polygon winding rules, holes, union, open and closed paths Custom shapes
07 curves Catmull-Rom curves and beziers, curve resolution Custom shapes
08 bulk numpy draws circles and friends: hundreds of shapes in four calls Performance
09 noise and random noise, signed_noise, seeds, gaussians Noise and randomness
10 math helpers map, clamp, lerp, wrap, normalize and more Noise and randomness
11 input and events mouse, keys, modifiers, scroll, file drops, window events Interaction
12 images and textures Image, draw(source=), texture filters and wrap modes Images, Pixels and screen
13 offscreen Fbo a float Fbo with feedback trails Offscreen drawing
14 shader material one Shader, every pixel; a bad source raises ShaderError Shaders
15 Mesh and Vbo PrimitiveModes, static and streamed Vbos Meshes
16 TrueType text Font: the three Inter weights, an ink box, baseline and metrics, a wrapped paragraph, text on a wave Text
17 kiln.Gui a kiln.Gui of its own, always shown: sliders, a choice and a button tune a rose GUI
18 instancing 2,048 arrows in one instanced draw, each with its own colour and orbit (Vbo.upload_attribute, draw(instances=)); hover to turn them to the mouse Instancing
19 GPGPU particles 8,192 particles stepped on the GPU: ping-pong RGBA32F Fbos, a step material and a raw Shader that draws them from the position texture (hover to stir) GPGPU particles
20 agents kiln.agents: a flock of about 200 and a predator in one Population, steered by separate, align, cohere, evade and pursue; the prey graze a moss Field, pay for living (metabolize), breed (reproduce) and die, and a behaviour tree decides for all of them (hover to see it) Agents: a flock that decides, Ecosystems: fields, life and evolved brains
21 sound silent until clicked: a Synth note (x sets the pitch), a Pluck, and a bar of Kick, Snare and HiHat in a Sequencer with its playhead and a Reverb on the master, with master.spectrum() and master.level() drawn live; needs kiln-gl[sound] Sound, Plucks and sound effects, Drums, Sequencer, Effects, Audio-reactive, Making a track

The header, the footer and the pointer layer cover the app, window, time and input functions.

Run it with uv run python examples/showcase.py.

Key Does
space pause
t / c toggle trails / clear them
b change the background colour
1 2 3 0 30, 60, 120 fps, or uncapped
v toggle vsync
n / e cycle the texture filter / wrap mode
s save a screenshot
f / w fullscreen / windowed
r reset the clock
tab show or hide the control panel, a kiln.Gui (animation speed, reset clock, frame rate)
esc or q quit

The mouse: hover a panel to steer it, click for ripples, drag to paint, scroll to grow the tree, click the style panel to change style, hover the text panel to wrap and wave its type, work the rose’s controls in the GUI panel, and drop a file on the window. python scripts/render_showcase.py regenerates the picture, and the crop of each panel that opens its tutorials.

Scenes

Six pieces made for Kiln, to show what its pieces do together. Each video is the real example, driven by scripted input.

Abyss

Kunstformen der Tiefe, after Ernst Haeckel’s Kunstformen der Natur (1904): medusae pulse and climb through the dark, trailing tentacles that sway on noise; radiolarians turn slowly, lattice shells cut with holes and crowned with spines; thousands of plankton drift on a noise current and glow where the water is disturbed. Nothing is cleared between frames, only dimmed, so every motion leaves a trace.

The techniques: custom shapes with holes (next_contour) for the lattice shells, noise to sway the tentacles and carry the plankton, additive blending for the glow and the god rays, and bulk numpy draws for the plankton, the marine snow and every tentacle (one lines call each). The mouse stirs the plankton, and a click, halfway through, flashes it with bioluminescence.

Controls. Move the mouse to stir the plankton (the medusae grow curious and follow it), click for a flash of bioluminescence, right-click to release a medusa. space pauses, t toggles the trails, h hides the caption, esc quits.

Run it with uv run python examples/abyss.py. Source: examples/abyss.py.

Pilgrim

Inspired by thatgamecompany’s Journey (2012): a robed figure walks, surfs the slopes and flies on a scarf that holds its energy, across endless dunes toward a mountain of light. Singing wakes the cloth creatures drifting over the sand, and awake they follow you, lift you and refill the scarf. Glyphs hover over the dunes, and each one lengthens the scarf. It is an original piece: it borrows an idea and an atmosphere, no art or code.

The techniques: every dune is a noise ridge drawn as a custom shape, at five parallax depths; the scarf and the cloth are verlet chains drawn as triangles; the sand, its glitter and the wind are bulk numpy draws, the sun and the singing rings are additive blends. The video holds the right arrow to walk, then the up arrow to fly, and sings once.

Controls. Left and right arrows (or a and d) walk, up (or w) jumps, and holding it flies, using up the scarf’s energy. space sings (hold it for a long call). h hides the title, esc quits. With the mouse, hold the left button to walk toward the cursor (above you: fly) and right-click to sing.

Run it with uv run python examples/pilgrim.py. Source: examples/pilgrim.py.

Embers in a draught

Two thousand sparks flock over the kiln floor, after Craig Reynolds’ boids (1987): each keeps clear of its neighbours, flies the way they fly and stays with them, and a slow draught bends the flocks into ribbons. A spark glows hotter the more neighbours crowd it, and white-hot when it runs. The mouse is a threat: every spark that finds it within reach flees, because each spark’s decision is a two-branch behaviour tree, flee the mouse, else flock, drawn on screen by tree.draw.

The techniques: agents (a Population, separate, align and cohere, and a Tree), offscreen drawing for the fading float trails, additive blending for the glow, and a fixed step, so the flight is the same at any frame rate.

Controls. Move the mouse near the sparks. space pauses, t hides the tree, h hides the caption, esc quits.

Run it with uv run python examples/16_flocking.py. Source: examples/16_flocking.py.

Shoal

A shoal of minnows and the embers that hunt it, in one population of two kinds and one behaviour tree. The minnows school and bolt from the nearest ember; an ember chases the nearest minnow, eats it and rests, and the shoal breeds back. A click is the outside world’s say: it writes a goal that every ember without prey in sight goes to, until the goal goes stale. The panel is the tree, with how many agents each node returned SUCCESS, RUNNING and FAILURE for. It is an original piece.

The techniques: agents with a kinds column and is_kind branches, senses.nearest_of to flee and to chase, a speed limit per agent, kill and spawn with the tree following each agent by its id, and an intent field written from a click.

Controls. Click to call the embers to a spot. space pauses, t hides the tree, h hides the caption, esc quits.

Run it with uv run python examples/17_predators.py. Source: examples/17_predators.py.

Meadow

Grazers live, breed and die on a field of moss that grows back where it was eaten, thickest on fertile patches that wander with the seasons. Every grazer carries genes for its size, its top speed and how far it sees, and pays for each of them in energy; a well-fed one has a child with its genes, mutated, and a starved one dies and feeds the moss. Nobody chooses the traits. Here hunters were let in after 20 seconds, and the video picks up 100 seconds in: the histograms at the right show speed climbing away from where it started (the red dashes), which the hunters select for. Size climbs too, but it does that without hunters as well (why). It is an original piece, after John Holland’s genetic algorithms (1975) and Larry Yaeger’s PolyWorld (1994).

The techniques: a moss Field with a fertility map as its cap, a Genome, and metabolize, reproduce and die (ecosystems); two kinds in one population, pursue and flee, and contain for the walls.

Controls. p lets the hunters in or drives them out. space pauses, h hides the caption, esc quits.

Run it with uv run python examples/23_ecosystem.py. Source: examples/23_ecosystem.py.

Neuroevolution

240 foragers, each steered by a tiny neural network whose weights are its genes: 16 ray readings in, toward food and toward hunters, 12 hidden, and a turn and a speed out. Nobody trains them. Each generation lives 20 seconds and scores a point for each piece of food it eats; then the next is bred from the best. The first generation spins and wanders; the video joins the thirteenth halfway through its life and runs four times faster than real time, into the fourteenth, with the best forager ringed and its rays drawn, and every generation’s best and mean score on the right. They learn to eat, not yet to dodge the hunters. It is an original piece, after David Montana and Lawrence Davis (1989) and John Holland (1975).

The techniques: rays, Brains, drive and next_generation, all batched over the population.

Controls. f fast-forwards, space pauses, h hides the caption, esc quits.

Run it with uv run python examples/24_neuroevolution.py. Source: examples/24_neuroevolution.py.

Stress

Another example, examples/stress.py, drives every part of Kiln as hard as it goes and times each layer. It belongs with the numbers, in the Performance tutorial.

Remixes

Nine well-loved sketches, from classic example sets, Generative Design and the classics, read again through the kiln: fire, clay, glaze, glass and ash, with one shared palette and a pyrometric heat ramp. They have their own page, with a video or a picture of each.

Ported examples

Nine sketches that began as another framework’s examples, each linked below (the licence is in examples/NOTICE). These are ports in spirit: where Kiln has a clearer way to do something, they use it. They keep the mouse and keyboard interaction of the originals. Each runs with uv run python examples/0X_name.py.

Graphics

A port of graphicsExample: circles, 200 random rectangles, transparency and a fan of lines. Press s to toggle thick lines. Source: examples/01_graphics.py.

Polygons

A port of polygonExample: winding rules, a star that follows the mouse, a spiral, a Catmull-Rom curve with draggable points, a bezier, holes and constructive-solid-geometry-style contours. Source: examples/02_polygon.py. Here the mouse sits over the star and one curve point has been dragged. The picture was rendered with a fixed 60 fps clock, so it is reproducible.

Blending

A port of blendingExample: a rainbow follows the mouse and mixes with the text behind it. Keys 1 to 5 pick alpha, add, multiply, subtract and screen. The original uses an image and a TrueType font. This port predates Kiln’s images and Font, so the rainbow is drawn from rectangles and the text is bitmap text. Here is the Screen mode. Source: examples/03_blending.py.

Noise field

A port of noiseField2dExample: 4096 particles of pollen blown by a 2D slice of a 3D noise field, leaving faint trails. Click to reset, press any key for the debug view of the wind. Source: examples/04_noise_field.py.

Image loader

Inspired by imageLoaderExample and imageSubsectionExample. One picture, a Ming porcelain jar painted with a dragon in cobalt blue (The Met, public domain), used four ways: drawn as it is, read back as pixels and turned into a halftone of 3,600 circles in one call (the grey backdrop gets none), shrunk to grayscale and tinted, and faded in and out. Move the mouse over the original for a loupe (draw(source=)), press c to colour the halftone. Source: examples/05_image_loader.py.

Fbo trails

A port of fboTrailsExample: two Fbos fade a little every frame and get a turning cube, the mouse and a sweeping bar drawn on top. The left Fbo has 8 bits per channel, the right one is floating point. Both fade by the same small amount (hold 2), but the left one cannot store steps that small, so its dim trails stop fading and stay as a grey haze. Source: examples/06_fbo_trails.py.

Shader

Inspired by shaderExample. The original’s noise vertex shader (every point shaken by noise and pushed away from the mouse) is run on the Ming jar laid over a grid of triangles, and the fragment shader keeps the screen-fixed pattern of the original as smooth lines whose width follows how dark the jar is. Press s to turn the shader off. Source: examples/07_shader.py.

Vbo

A port of vboExample: a relief built from the jar’s darkness (its cobalt dragon stands up from the white glaze), drawn 25 times, swaying and leaning (here with a key held, so it is the Vbo). Kiln has no camera, so the vertex shader does the 3D and the copies are drawn back to front. Hold any key to draw the Vbo (data already on the GPU) instead of the Mesh (sent again at every draw): 1.4 million vertices a frame take about 8 ms as a Mesh and about 1 ms as a Vbo on an M-series Mac. Source: examples/08_vbo.py.

GUI

Inspired by guiExample: a panel of controls shapes a circle. The radius, colour and resolution (the circle’s sides: three is a triangle) sliders, “filled” and “two circles” toggles, a button, two labels and a folder of rings are all kiln.Gui controls, and the panel draws itself on top of the sketch. A click off the panel moves the circle. Here the resolution is down to seven sides and a second circle is on. Source: examples/09_gui.py. Learn more in the GUI tutorial.

Sound

These examples need the sound extra (pip install "kiln-gl[sound]") and play through your speakers, so the page cannot show them running. Each has a tutorial with the sound on it.