Naming

How Kiln’s names are chosen, so you can guess the ones you haven’t met.

Kiln’s names follow a few rules. Learn them once and you can guess most of the API: the test for every name is what a Python programmer, or a model writing Kiln code, would type first. Its vocabulary started from openFrameworks’ and was redesigned for Python.

1. Name what it is, not how to fetch it

State that reads like data is a property, with no get_ or set_:

img.texture          # not img.get_texture()
color.hue = 128      # not color.set_hue(128)
mesh.vertex_count
fbo.allocated

2. Live state lives on four small objects

kiln.mouse, kiln.keys, kiln.clock and kiln.window hold what changes while the sketch runs. They stay live after from kiln import mouse, where a plain module value would be a snapshot taken at import.

kiln.mouse.x, kiln.mouse.y, kiln.mouse.pressed
kiln.Key.LEFT in kiln.keys
kiln.clock.time, kiln.clock.dt, kiln.clock.frame, kiln.clock.fps
kiln.window.width, kiln.window.height
kiln.window.title = "Orbits"

3. One name per setting; None means off

A style setting has one name, used as its function, its Style field, its style() keyword and, where it has one, its run() keyword. There are no on/off pairs: None turns a setting off (tint is never off: white is no tint).

kiln.fill(255, 120, 60)            # shapes are filled...
kiln.stroke("white", width=2)      # ...and outlined, each in its own colour
kiln.fill(None)                    # no fill
kiln.tint(255, 128)                # pictures, Fbos and meshes take a tint
kiln.blend(kiln.Blend.ADD)

4. Scopes are with blocks

Anything that must be undone is a context manager, so a block can’t be left unbalanced:

with kiln.transform():
    kiln.translate(200, 150)
    kiln.rotate(angle)
    kiln.rect(-20, -20, 40, 40)

with kiln.style(fill=None, stroke="red"):
    kiln.circle(200, 150, 60)

with kiln.shape(close=True):
    for x, y in points:
        kiln.vertex(x, y)

with fbo:                          # also: with shader:, with texture:, with image:
    kiln.background(0)

5. Shapes are nouns; plurals are the numpy bulk form

Drawing functions are nouns: circle, ellipse, rect, line, triangle, bezier, curve, text. Their plurals (circles, ellipses, rects, lines) take numpy arrays and draw thousands in one call. On objects, .draw() is the only drawing verb, and variants are keywords: img.draw(x, y, w, h, source=...), mesh.draw(wireframe=True), vbo.draw(instances=n).

Round things take a radius: circle(x, y, r), and ellipse(x, y, rx, ry) takes two radii. rect(x, y, w, h, radius=8) rounds the corners.

6. Modes are enums that also take strings

Each mode is a StrEnum named after the setting it fills (Blend, RectMode, Winding, TextureFilter), so kiln.blend(kiln.Blend.ADD) and kiln.blend("add") are the same call. An unknown string raises a ValueError that lists the valid ones.

7. Configuration goes to run()

run()’s keywords are the starting values of the runtime properties of the same name:

kiln.run(Sketch(), 800, 600, title="Orbits", fps=60, auto_clear=False)
kiln.window.title = "Still orbiting"     # changed while it runs

8. Units: radians, seconds, points, 0–255

rotate(angle) takes radians (math.radians converts), clock.time is in seconds, sizes are in logical points, and colour channels run from 0 to 255.

9. Python-familiar names, words spelled out

Kiln keeps names Python programmers already know, such as kiln.map and kiln.random, even where they match a builtin, and doesn’t duplicate what Python has. Other words are spelled out (Key.ESCAPE, next_power_of_two); common idioms (pos, dt, fps, xy) stay short. Write import kiln and call kiln.<name>: a star import would hide map, exit and the random module.

10. Classes follow the same rules

Kind of member Rule Examples
Cheap state a property img.pixels, mesh.vertices, tex.mipmaps
Work a method with a specific verb upload, write, read, allocate, release
Booleans a bare adjective or has_x allocated, loaded, pressed, playing
Keyed state subscription shader["time"] = t, mesh.attributes["age"], grid.patterns["kick"]
Counts <thing>_count vertex_count, instance_count
Variants keywords draw(wireframe=True)

Domain words stay as their fields write them: GL (Fbo, Vbo, Shader, draw_elements), MIDI (note_on), behaviour trees (Sequence, Selector) and synthesis (cutoff, resonance).

Naming something new

  1. Write the line a Python programmer would type first.
  2. State is a property of its owner; an action is a method with a specific verb; drawing is a noun at module level, or .draw() on an object.
  3. No get_, set_, enable_, disable_ or toggle_: use None for off.
  4. A setting has one name everywhere, and its enum is named after it.
  5. Plurals for numpy bulk forms; radians, seconds, points and 0–255; round things take a radius.
  6. Keep domain terms, spell out the rest, and say in the docstring when a familiar name means something different in Kiln.